# Yhdistä Zapier ja GenderAPI.io V2

> Yhdistä Zapier GenderAPI.io V2:een Mailchimp-tietueita varten. Valitse oikea yhteys, lähetä type ja value ja käsittele sitten data, meta, krediitit ja virheet.

Canonical HTML: https://www.genderapi.io/fi/blog/zapier-gender-api-integration

Last reviewed: 2026-09-30

## Valitse Zapier-yhteys, joka vastaa API-määrittelyäsi

Tämän oppaan HTTP-määritys kutsuu GenderAPI.io V2:ta osoitteessa https://api.genderapi.io/api/v2/gender. Lähetä type ja value JSON-rungossa. Ennuste luetaan kentästä data ja pyynnön sekä laskutuksen tiedot kentästä meta. Valmiilla liittimillä on omat määrittelynsä, jotka kuvataan alla.

Zapier tarjoaa GenderAPI.io-toiminnot sukupuolen päättelyyn nimestä tai sähköpostiosoitteesta. Julkinen sivu ei vahvista endpointin versiota eikä V2:n vastausmäärittelyä. Olemassa olevien valmiiden toimintojen tulosteet on tarkistettava ennen kuin muutat myöhempien vaiheiden kenttien yhdistämistä.

Alla oleva V2-ohje käyttää Webhooks by Zapier -toimintoa ja jäsenneltyä POST-hyötykuormaa. Webhooks-toiminnon saatavuus riippuu maksullisesta Zapier-tilauksesta. GenderAPI-tilin saldo ja Zapier-palvelun oma tehtävien kulutus ovat erillisiä.

- [GenderAPI.io-sovelluksen sivu Zapier-palvelussa](https://zapier.com/apps/gender-api/integrations)
- [Nykyinen V1-dokumentaatio](https://www.genderapi.io/fi/api-documentation/v1)

## Valmistele tili ja lähdetietue

Tämä esimerkki rikastaa Mailchimp-tietueita sähköpostiosoitteen perusteella. Tarvitset pääsyn lähde- ja kohdesovellukseen, GenderAPI.io-tilin API-avaimen sekä ne alustan ominaisuudet, joita HTTP-toiminto käyttää. Opas ei sisällä toimivia tunnistetietoja eikä yhdistettyjä tilejä.

V1 ja V2 käyttävät samaa tilin API-avainta ja samaa saldoa. Tarkista avain pyynnöllä GET /api/v2/usage ennen kuin määrität veloitettavan haun, ja varmista, että kentän meta.access.mode arvo on tämän endpointin vastauksessa api_key. Puuttuva tai tunnistamaton avain voi siirtyä käyttämään yhteistä IP-kokeilua, eikä tuotannon automaation pidä huomaamatta toimia sen varassa.

Pidä työnkulku poissa käytöstä sen määrittämisen ajan. Myös testiennusteen lähettäminen kuluttaa tavallisia krediittejä. Nämä ohjeet on tarkistettu julkista dokumentaatiota ja V2:n määrittelyä vasten; tätä julkaisua varten ei ajettu todennettua työnkulkua alusta loppuun millään alustalla.

- [Todennus ja maksuton käytön tarkistus](https://www.genderapi.io/fi/docs/v2/authentication#environment-setup)

## Määritä GenderAPI.io V2 -pyyntö Zapier-palvelussa

- Aloita Mailchimp-käynnistimellä, joka tuottaa oikean tilaajatietueen. Säilytä sen yleisön (Audience) ja yhteystiedon tunnisteet ja lisää ennen HTTP-toimintoa suodatin, joka ohittaa tyhjät sähköpostiosoitteet.
- Valitse Webhooks by Zapier ja sen POST-toiminto. Aseta alla oleva URL-osoite ja Payload Type -asetukseksi JSON. Lisää datakentät type = email, value = yhdistetty tilaajan sähköpostiosoite ja options__ai_mode = off.
- Zapier-palvelun kaksoisalaviivamerkintä muuttaa kentän options__ai_mode JSON-rungossa sisäkkäiseksi kentäksi options.ai_mode. Alla oleva koodilohko näyttää tuloksena syntyvän API-rungon, ei neljättä kenttää, joka pitäisi liittää toimintoon.
- Lisää kohtaan Headers otsake Authorization, jonka arvo on Bearer YOUR_API_KEY. Käytä Content-Type-arvona application/json. Pidä avain poissa käynnistimen kentistä, kyselymerkkijonoista ja esimerkkivastausten tiedoista.

| HTTP-asetus | Arvo | Tarkoitus |
| --- | --- | --- |
| `Method` | `POST` | Lähettää yhden ennustepyynnön. |
| `URL` | `https://api.genderapi.io/api/v2/gender` | GenderAPI.io V2:n endpoint yksittäisille ennusteille. |
| `Authorization` | `Bearer YOUR_API_KEY` | Korvaa paikkamerkki alustan todennus- tai otsakeasetuksissa. |
| `Content-Type` | `application/json` | Lähettää objektin, jonka sisällä on options-objekti, ei lomakekenttiä. |
| `options.ai_mode` | `off` | Tarkoituksellinen ensimmäinen testi pelkällä tietoaineistolla. Tavallinen veloitus on 1 krediitti, vaikka tulos olisi tuntematon. |

## Tarkista JSON-runko ennen lähettämistä

Tämä on kiinteä esimerkkisyöte, ei ennustettu tulos. Tarkista ensin pyynnön rakenne ja korvaa sitten kentän value arvo yhdistetyllä lähdekentällä, joka on sarjallistettu oikein JSON-muotoon. Älä lähetä alustan kenttien yhdistämislausekkeita API:lle kirjaimellisina merkkijonoina.

Jos syöte on toisenlainen, aseta type arvoon name, email tai username ja anna vastaava value. Lisää country vain, kun luotettava konteksti on saatavilla; kenttä on valinnainen eikä selvitä henkilön asuinmaata.

**Zapier-pyyntö GenderAPI.io V2:een**

```json
{
  "type": "email",
  "value": "alex@example.com",
  "options": {
    "ai_mode": "off"
  }
}
```

- [Pyynnön kaikki kentät, tyypit ja oletusarvot](https://www.genderapi.io/fi/docs/v2/request-parameters)

## Tarkista HTTP-vaihe ennen päivitysten käyttöönottoa

Webhooks-otsakkeet eivät ole erillinen kenttä salaiselle yhteystiedolle: muokkaajat, joilla on pääsy Zap-työnkulkuun, näkevät ne. Rajoita käyttöoikeuksia äläkä jaa Zap-työnkulkua, kuvakaappausta tai vientiä, joka sisältää tunnistetiedon. Zapier tarjoaa myös API by Zapier -toiminnon tallennetuilla tunnistetiedoilla; sen pyynnön rungon määritys poikkeaa tästä jäsennellystä POST-ohjeesta.

Älä kääri runkoa: lähetä yksi objekti, ei luetteloa tai taulukkoa. Käytä yhdistetyille asiakastiedoille mieluummin jäsenneltyä JSON-toimintoa; Custom Request lähettää raakatekstiä eikä koodaa lisättyjä arvoja automaattisesti (escaping).

- [Zapier-palvelun jäsennellyt Webhooks-pyynnöt ja sisäkkäinen JSON](https://help.zapier.com/hc/en-us/articles/8496326446989-Send-webhooks-in-Zap-workflows)
- [Tunnistetietoyhteydet API by Zapier -työkalussa](https://help.zapier.com/hc/en-us/articles/44391660158733-How-to-get-started-with-API-by-Zapier)
- [Uudelleentoiston käyttäytyminen Zapier-palvelussa](https://help.zapier.com/hc/en-us/articles/19220226086797-What-is-replay)

## Käsittele tulokset identified ja unknown sekä virheet erikseen

Jäsennä vastauksen runko ennen kuin valitset päivityksen kohdesovellukseen. Alla olevat JSON-polut viittaavat V2:n vastausrunkoon; alustasi voi kääriä tai litistää sen. Varmista todellinen palautettu rakenne harkitulla testillä ja pidä tulos liitettynä lähdetietueen tunnisteeseen.

Ennuste ei vahvista henkilön henkilöllisyyttä eikä hänen itse ilmoittamaansa sukupuolta. Säilytä se erillään tiedoista, jotka henkilö on itse antanut. Valitse hyväksymisehdot oman käyttötapauksesi näytön perusteella ja arvioi tietoaineiston ja tekoälyn luottamusarvot erikseen.

| Tarkistus | Odotettu arvo tai tyyppi | Päätös työnkulussa |
| --- | --- | --- |
| `meta.access.mode` | api_key tämän tilin työnkulussa | Pysäytä, jos arvo on ip_trial, ja korjaa avain. Onnistunut kokeiluvastaus ei todista tilin todennusta, ja se on voinut jo kuluttaa kokeilun krediittejä. |
| `meta.usage.billing_status` | confirmed tai unconfirmed | Jos arvo on unconfirmed, säilytä pyynnön tunniste ja pyydä laskutuksen täsmäytystä ennen uudelleenyritystä tai jatkamista. |
| `data.result_status / data.gender` | identified ja male tai female; unknown ja null | Ohjaa hyväksytyt identified-tulokset erilliseen päätellyn tiedon kenttään. Säilytä unknown-tulokset antamatta niille oletusluokkaa. |
| `data.confidence / data.confidence_kind` | luku väliltä 0–1 tai null; näytön tyyppi tai null | Tulkitse arvot observed_frequency ja model_reported erikseen; kumpikaan ei ole yleinen tarkkuustakuu. |
| `data.source / data.sample_count` | dataset, ai tai none / kokonaisluku tai null | Säilytä tieto siitä, miten ennuste saatiin. Tekoälytuloksella ei ole tallennettua otoskokoa, eikä tietoaineiston otoskoko ole tuotteen tarkkuuspistemäärä. |
| `meta.request_id / meta.usage` | pyynnön tunniste / käyttötietojen objekti | Tallenna ne työnkulun tietueen ja tuloksen yhteyteen. Pidä API-avaimet ja tarpeettomat henkilötiedot poissa tavallisista lokeista. |
| `HTTP-virhe / puuttuva vastaus` | Problem Details tai ei täydellistä vastausta | Keskeytä päivitys ja tarkista virhe ja laskutuksen tila. Aikakatkaisu ei todista, ettei palvelin tehnyt mitään työtä. |

- [API V2:n JSON-vastaukset ja luottamusarvot](https://www.genderapi.io/fi/docs/v2/responses)
- [Virheitä ja uudelleenyrityksiä koskevat päätökset](https://www.genderapi.io/fi/docs/v2/errors-and-retries)

## Päivitä vain oikea Mailchimp-tietue

Tarkista testitoiminnon jäsennetty vastaus ja valitse kentät, jotka vastaavat polkuja data.gender ja data.result_status sekä muita alla olevia V2:n polkuja. Zapier-palvelun kenttävalitsin voi litistää sisäkkäisten kenttien nimet; käytä havaittua arvoa ja sen yläpolkua äläkä oleta, että valmiin liittimen vanhempi probability-kenttä pätee.

Testaa tuloksen identified, tuntemattoman tuloksen ja virheen haarat ennen päivitysten käyttöönottoa. Keksittyjen esimerkkivastausten avulla voit testata haarojen ehdot lähettämättä uutta ennustepyyntöä. Kohdesovelluksen päivitys saa tapahtua vain, kun yllä olevat tarkistukset täyttyvät, eikä se saa korvata muita kenttiä tai tunnisteita.

- [Vastauskentät ja tuntemattomat tulokset](https://www.genderapi.io/fi/docs/v2/responses)
- [Tarkkuus ja luottamusarvo selitettynä](https://www.genderapi.io/fi/accuracy-methodology)
- [Tietolähteet ja päivätty tietoaineistoprofiili](https://www.genderapi.io/fi/data-provenance)

## Hallitse uudelleenlähetyksiä ja toistuvia veloituksia

Tarkista Zapier-palvelun Autoreplay-asetus ja manuaalisen uudelleentoiston (Replay) asetukset ennen kuin otat Zap-työnkulun käyttöön. Epäonnistuneen webhook-toiminnon uudelleentoisto lähettää uuden haun; onnistunutta hakua ei pidä ajaa uudelleen vain myöhemmän Mailchimp-vaiheen korjaamiseksi. Tallenna alkuperäiset tilaajan tunnisteet ja hakutulos yhdessä.

Jokainen uusi GenderAPI-pyyntö on itsenäinen toiminto. Poista päällekkäiset lähdetapahtumat omassa työnkulussasi ennen lähettämistä tallennetun lähdetunnisteen ja käsittelytilan avulla. Lähdetietueen tunniste ei ole palvelinpuolen avain, joka estäisi uudelleenlähetykset.

Onnistunut tuntematon tulos on valmis tulos, josta veloitetaan. Aikakatkaisun tai keskeneräisen vastauksen jälkeen sekä tulos että veloitus voivat olla epäselviä. Säilytä pyynnön tunniste, jos se on saatavilla, ja täsmäytä veloitus ennen uutta lähetystä. Noudata pyyntörajoitusvastauksen Retry-After-otsaketta, jos se on mukana.

- [Krediitit ja laskutuksen tila](https://www.genderapi.io/fi/docs/v2/credits-and-usage)

## Päätä, milloin tekoälyä käytetään

forceToGenderize on valinnainen nimille, sähköpostiosoitteille ja käyttäjänimille. Kun se on käytössä, jätä ai_mode pois tai käytä arvoa fallback; off ja always ovat ristiriidassa sen kanssa ja palauttavat 422-virheen. Positiivinen alkusaldo riittää pyynnön aloittamiseen, vaikka lopullinen veloitus painaisi saldon negatiiviseksi.

Lempinimitila voi palauttaa sukupuolen, vaikka tuloksessa on name: null. Se voi myös palauttaa tuntemattoman tuloksen. Tavallinen tekoäly varalla ja lempinimipäättely eivät takaa oikeaa vastausta eivätkä muuta kuin null-arvoista vastausta.

| Pyynnön asetus | Toiminta | Krediitit onnistuneesta hausta |
| --- | --- | --- |
| options.ai_mode: off | Käyttää vain tietoaineistoa. | 1, myös tuntemattomasta tuloksesta |
| options.ai_mode: fallback | Hakee ensin tietoaineistosta ja käyttää tavallista tekoälyä, jos sukupuolta ei saada. Tämä on yksittäisen pyynnön oletus. | Yhteensä 1, tekoäly varalla mukaan lukien |
| options.ai_mode: always | Käyttää suoraan tekoälyä. | 2 |
| forceToGenderize: true | Hakee ensin tietoaineistosta ja sallii sitten tekoälyn tulkita henkilökohtaisen lempinimen tai aliaksen myös ilman todellista etunimeä. | 1 tietoaineistosta ratkaistusta tuloksesta; yhteensä 2, jos tekoälyä käytetään |

- [Tekoälyasetukset ja lempinimipäättely](https://www.genderapi.io/fi/docs/v2/ai-options)
- [Krediitit ja käyttö](https://www.genderapi.io/fi/docs/v2/credits-and-usage)

## Varmista työnkulku ennen määrän kasvattamista

- Tarkista yhdellä harkitulla testillä todellinen sarjallistettu JSON, jäsennetyn tuloksen polut, API-avaimella tapahtuva käyttö ja vahvistettu laskutus. Testaa unknown-tulosten ja virheiden ohjaus mahdollisuuksien mukaan valmiilla testivastauksilla.
- Varmista, mitkä työnkulun vaiheet yrittävät uudelleen ja mitkä asiakkaan kentät muuttuvat. Säilytä lähdetietueen tunniste, valmis vastaus ja pyynnön tunniste, jotta myöhempi virhe kohdesovelluksessa ei vaadi uutta hakua.
- Ota käyttöön pieni, valvottu ajo ja tarkista sen tietueet ja krediitit ennen kuin lisäät rinnakkaisuutta. GenderAPI-krediitit ja automaatioalustan tehtävä- tai toimintoveloitukset ovat erillisiä.
- Käytä eräpyyntöön reittiä POST /api/v2/gender/batch: enintään 50 kohdetta API-avaimella tai 10 kohdetta IP-kokeilussa. Taulukossa items voi yhdistää nimiä, sähköpostiosoitteita ja käyttäjänimiä, ja jokaisella kohteella on erikseen määritetyt asetukset ja yksilöllinen id. Tarkista jokainen tulos; HTTP 200 -vastaus voi sisältää osittaisia virheitä. Valmiin liittimen eräpyyntötuki on tarkistettava erikseen.

- [Eräpyynnöt ja osittaiset virheet](https://www.genderapi.io/fi/docs/v2/batch)
- [Python-toteutusopas](https://www.genderapi.io/fi/integrations/python)
- [Node.js-toteutusopas](https://www.genderapi.io/fi/integrations/javascript)

## Miksi Zapier-määrityksessä käytetään kenttää options__ai_mode?

Jäsennelty Webhooks POST -toiminto luo kaksoisalaviivoilla sisäkkäisen JSON-rakenteen. API vastaanottaa options: {ai_mode: off}, jossa off on merkkijono. Se ei vastaanota kirjaimellista ylätason kenttää options__ai_mode.

## Salliiko suora HTTP-esimerkki tekoälyn käytön?

Ensimmäisen pyynnön runko asettaa kentän options.ai_mode arvoksi off. Vaihda arvo harkiten arvoon fallback, jos haluat tavallisen tekoälyn varalla yhteensä 1 krediitillä, tai arvoon always, jos haluat käyttää tekoälyä 2 krediitillä. forceToGenderize hakee ensin tietoaineistosta ja maksaa 1 krediitin, jos tulos ratkeaa siellä, tai yhteensä 2 krediittiä, kun tekoälyä käytetään.

## Onko tuntematon tulos maksuton, tai onko sitä turvallista yrittää automaattisesti uudelleen?

Ei. Onnistunut tuntematon tulos on valmis ja veloitettava. Uusi yritys on uusi toiminto. Siirtovirheissä tai vahvistamattomassa laskutuksessa tarkista palautetut käyttötiedot ja pyynnön tunniste ennen kuin päätät lähettää pyynnön uudelleen.

## Ajettiinko tämä työnkulku yhdistetyllä tilillä?

Ei. Alustojen määritysohjeet tarkistettiin julkista dokumentaatiota vasten 26. syyskuuta 2026. GenderAPI.io V2:n pyyntöä ja vastausta koskevat selitykset tarkistettiin 27. syyskuuta 2026. Tämän suomenkielisen version tarkistus 30. syyskuuta 2026 on käännöksen tarkistus eikä uusi testi tilillä. Testaa valitun toiminnon nykyiset kentät, todennus, runko, vastaus ja uudelleenyritykset omalla tililläsi ennen kuin otat päivitykset käyttöön tuotannossa.

## Lähteet ja dokumentaatio

- [GenderAPI.io-sovelluksen sivu Zapier-palvelussa](https://zapier.com/apps/gender-api/integrations)
- [Zapier-palvelun jäsennellyt Webhooks-pyynnöt ja sisäkkäinen JSON](https://help.zapier.com/hc/en-us/articles/8496326446989-Send-webhooks-in-Zap-workflows)
- [Tunnistetietoyhteydet API by Zapier -työkalussa](https://help.zapier.com/hc/en-us/articles/44391660158733-How-to-get-started-with-API-by-Zapier)
- [Uudelleentoiston käyttäytyminen Zapier-palvelussa](https://help.zapier.com/hc/en-us/articles/19220226086797-What-is-replay)
- [GenderAPI.io V2:n pyyntömäärittely](https://www.genderapi.io/fi/docs/v2/request-parameters)
- [GenderAPI.io V2:n vastausten määrittely](https://www.genderapi.io/fi/docs/v2/responses)
- [GenderAPI.io V2:n laskutus ja krediitit](https://www.genderapi.io/fi/docs/v2/credits-and-usage)