# IntegratelyをGenderAPI.io V2に接続する

> Mailchimpのレコード向けにIntegratelyをGenderAPI.io V2に接続します。適切なコネクターを選び、typeとvalueを送信して、data、meta、クレジット、エラーを処理します。

Canonical HTML: https://www.genderapi.io/ja/blog/integrately-gender-api-integration

Last reviewed: 2026-09-29

## API契約に合ったIntegratelyの接続方法を選ぶ

このガイドのHTTP手順では、https://api.genderapi.io/api/v2/genderでGenderAPI.io V2を呼び出します。JSONボディでtypeとvalueを送信します。推定結果はdataに、リクエストと課金の情報はmetaに含まれます。ネイティブコネクターには独自の契約があり、その内容を以下で説明します。

IntegratelyのGenderAPI.io公式掲載ページはgenderapi.ioにリンクしており、名前、メールアドレス、メールアドレスからの名の抽出のためのアクションを提供しています。基盤となるAPIのバージョンや出力の完全なスキーマは示されていません。アクション名だけでは、V2との互換性を確認できません。

Integratelyでは、Webhook/APIが外部に送信するPOSTアクションとして説明されています。現在のヘッダー設定とJSONエディターの機能は、このガイドのために個別に検証されていません。以下のV2のHTTP仕様は、使用するアクションがAuthorizationヘッダーと入れ子のJSONボディを送信できることを確認してから適用してください。既存のネイティブアクションは、それぞれ独自のフィールド仕様を保ちます。

- [IntegratelyのGenderAPI.io公式掲載ページ](https://integrately.com/integrations/genderapi-io)
- [既存のV1ドキュメント](https://www.genderapi.io/ja/api-documentation/v1)

## アカウントと元のレコードを準備する

この例では、名前をもとにMailchimpのレコードを拡充します。連携元と連携先のアプリへのアクセス、GenderAPI.ioアカウントのキー、HTTPアクションで使うプラットフォームの機能が必要です。このガイドには、有効な認証情報や接続済みのアカウントは含まれていません。

V1とV2は、同じアカウントのキーと同じ残高を使用します。課金対象のリクエストを設定する前に、GET /api/v2/usageでキーを確認し、このエンドポイントのレスポンスでmeta.access.modeがapi_keyになっていることを確認してください。キーがない場合や認識されない場合は、共有のIPトライアルに切り替わることがあります。本番の自動化が、気付かないうちにこれに依存する状態にしてはいけません。

設定中はワークフローを無効にしておいてください。テストで送信した推定にも通常どおりクレジットが消費されます。この手順は、公開ドキュメントとV2の仕様に照らして確認したものです。この公開にあたり、どのプラットフォームでも認証済みのワークフローを最初から最後まで実行してはいません。

- [認証と無料の使用状況確認](https://www.genderapi.io/ja/docs/v2/authentication#environment-setup)

## IntegratelyでGenderAPI.io V2のリクエストを設定する

- Mailchimpの購読者トリガーを選び、テストレコードを1件確認します。更新のためにオーディエンス（Audience）と購読者のIDを保存し、実際の名のフィールドを選んで、名前のないレコードはスキップしてください。
- Webhook/APIと、URLにデータを送信するためのアクションを見つけます。先に進む前に、利用できる設定を確認してください。以下の仕様には認証付きのヘッダーと入れ子のJSONボディが必要ですが、現在のエディターの機能はここでは個別に検証されていません。
- アクションがこれらの要件を満たしている場合は、POSTと以下のV2エンドポイントを選択します。アカウントで利用できる設定を使って、送信するリクエストにAuthorization: Bearer YOUR_API_KEYとContent-Type: application/jsonが含まれるようにしてください。
- type = name、ai_mode = offを含むoptionsを持ち、valueにマッピングした名を指定したJSONボディを作成します。選択したアクションのリクエストのプレビューを確認してください。Content-Typeヘッダーが設定されていても、フラットなフォームのペイロードはV2のJSONボディではありません。
- 動的な名前には、プラットフォームのJSONマッピングまたはシリアライズの機能を使用してください。選択したアクションで入れ子のJSONや認証付きのヘッダーを保持できない場合は、キーやJSONをクエリパラメーターに入れるのではなく、HTTPに対応したステップを使用してください。

| HTTP設定 | 値 | 目的 |
| --- | --- | --- |
| `Method` | `POST` | 推定のリクエストを1件送信します。 |
| `URL` | `https://api.genderapi.io/api/v2/gender` | 単一の推定に使うGenderAPI.io V2のエンドポイントです。 |
| `Authorization` | `Bearer YOUR_API_KEY` | プラットフォームの認証設定またはヘッダー設定で、このプレースホルダーを置き換えます。 |
| `Content-Type` | `application/json` | フォームのフィールドではなく、ネストされたoptionsオブジェクトを含むオブジェクトを送信します。 |
| `options.ai_mode` | `off` | 最初のテストは意図的にデータセットのみで行います。通常の課金は1クレジットで、不明な結果でも同じです。 |

## 送信前にJSONボディを確認する

この例は固定の入力を示したもので、推定結果ではありません。まずリクエストの構造を確認し、次に正しいJSONシリアライズを使ってvalueをマッピングした元のフィールドに置き換えてください。プラットフォームのマッピング式を、文字列のままAPIに送信しないでください。

ほかの入力では、typeをname、email、usernameのいずれかに設定し、対応する値をvalueに指定します。countryは、信頼できるコンテキストがある場合にのみ追加してください。このフィールドは任意であり、居住国を調べるものではありません。

**Integrately用のV2 JSONリクエスト**

```json
{
  "type": "name",
  "value": "Alice",
  "options": {
    "ai_mode": "off"
  }
}
```

- [リクエストのフィールド、型、既定値](https://www.genderapi.io/ja/docs/v2/request-parameters)

## 更新を有効にする前にHTTPステップを確認する

後続のフィールドを選ぶ前に、アクションを意図的に1回テストし、返されたボディを確認してください。ネイティブのGenderAPI.ioステップとWebhook/APIのステップでは、元の顧客が同じでも、表示されるフィールドのラベルが異なることがあります。

キーは、接続またはリクエスト認証用の所定の設定に保存し、自動化を表示または共有できる人を制限してください。この公開ガイドには、有効なキー、エクスポートされた接続、あらかじめ設定された顧客の更新は含まれていません。

- [IntegratelyのWebhook/APIアクション](https://integrately.com/integrations/webhook-api)
- [Integratelyのドキュメント](https://integrately.com/docs)

## identifiedの結果、不明な結果、失敗を分けて処理する

送信先の更新を選ぶ前に、レスポンスボディを解析してください。以下のJSONパスはV2のボディを指します。プラットフォームによっては、ボディがラップされたりフラット化されたりすることがあります。意図的に実行する1回のテストで実際に返される構造を確認し、結果を元のレコードのIDと結び付けて保存してください。

推定は、本人の身元や本人が申告した性別を確定するものではありません。本人から提供された情報とは分けて保存してください。受け入れ基準は自社のユースケースを代表するデータに基づいて決め、データセットの信頼度とAIの信頼度は別々に評価してください。

| 確認項目 | 想定される値または型 | ワークフローでの判断 |
| --- | --- | --- |
| `meta.access.mode` | このアカウント用ワークフローではapi_key | ip_trialの場合はワークフローを止め、キーを修正してください。IPトライアルで成功したレスポンスは、アカウントが認証されたことを証明するものではなく、すでにトライアルのクレジットを消費している可能性があります。 |
| `meta.usage.billing_status` | confirmedまたはunconfirmed | unconfirmedの場合は、リクエストIDを保存し、再試行や処理の続行の前に課金を照合してください。 |
| `data.result_status / data.gender` | identifiedとmaleまたはfemale、unknownとnull | 受け入れたidentifiedの結果は、推定値専用のフィールドに保存してください。不明な結果は、既定のカテゴリーを割り当てずにそのまま保持してください。 |
| `data.confidence / data.confidence_kind` | 0から1の数値またはnull、根拠の種類またはnull | observed_frequencyとmodel_reportedは別々に解釈してください。どちらも全般的な正確性を保証するものではありません。 |
| `data.source / data.sample_count` | dataset、ai、none／整数またはnull | 推定の取得元を保存してください。AIには保存されたサンプル数がありません。データセットのサンプル数は、製品の正確性を示す指標ではありません。 |
| `meta.request_id / meta.usage` | リクエストの参照／使用状況オブジェクト | 両方をワークフローのレコードと結果とあわせて保存してください。APIキーや不要な個人データを通常のログに書き込まないでください。 |
| `HTTPの失敗／レスポンスなし` | Problem Detailsまたは完全なレスポンスなし | 更新を一時停止し、エラーと課金ステータスを確認してください。タイムアウトは、サーバーが何も処理しなかったことを証明するものではありません。 |

- [V2レスポンスの完全なリファレンス](https://www.genderapi.io/ja/docs/v2/responses)
- [エラー、タイムアウト、再試行の判断](https://www.genderapi.io/ja/docs/v2/errors-and-retries)

## Mailchimpでは対応するレコードだけを更新する

保存したMailchimpのオーディエンス（Audience）と購読者のIDを使って、送信先のレコードを選択します。推定値専用のフィールドや承認済みのタグに書き込む前に、結果のステータスと、上記のアクセスと課金の確認に関する条件を追加してください。性別がない場合やnullの場合に、それをコンタクトの既定のカテゴリーに変換しないでください。

更新を有効にする前に、identifiedの結果、不明な結果、エラーの各分岐をテストします。架空のサンプルレスポンスを使えば、新しい推定を送信せずに分岐の条件を確認できます。連携先アプリでの更新は上記の確認に基づいて行い、関係のないフィールドやタグを上書きしないようにしてください。

- [レスポンスフィールドと不明な結果](https://www.genderapi.io/ja/docs/v2/responses)
- [精度と信頼度の説明](https://www.genderapi.io/ja/accuracy-methodology)
- [データソースと日付付きのデータベース概要](https://www.genderapi.io/ja/data-provenance)

## 再試行と重複課金を管理する

Integratelyでは、会社全体に適用される設定を含む、自動再試行の動作が説明されています。この自動化を有効にする前に、ポリシーとタスクの履歴を確認し、共有の設定を変更する前にほかのワークフローへの影響を評価してください。繰り返されたHTTPリクエストは、それぞれ独立した課金対象のリクエストです。成功した出力を保存しておけば、後続のMailchimpでの失敗を、もう一度リクエストを送らずに修正できます。

GenderAPIへの新しいリクエストは、それぞれが独立した操作です。送信前に、保存した連携元のIDと処理ステータスを使って、ワークフロー内で繰り返された連携元イベントの重複を除いてください。連携元レコードのIDは、サーバー側で重複を防ぐキーではありません。

成功した不明な結果は、完了した課金対象の結果です。タイムアウトやレスポンスが不完全な場合は、結果も課金も分からないことがあります。リクエストの参照情報があれば保存し、リクエストを再送する前に課金を確認してください。レート制限のレスポンスにRetry-Afterヘッダーが含まれている場合は、それに従ってください。

- [クレジットと課金ステータス](https://www.genderapi.io/ja/docs/v2/credits-and-usage)

## AIを使うタイミングを選ぶ

forceToGenderizeは、名前、メールアドレス、ユーザー名のいずれでも任意で使用できます。有効にする場合は、ai_modeを省略するかfallbackを使用してください。offとalwaysは併用できず、422が返ります。最終的な課金で残高がマイナスになる場合でも、開始時の残高がプラスであればリクエストを開始できます。

ニックネームモードでは、name: nullのまま性別が返ることがあります。不明な結果になることもあります。通常のフォールバックもニックネームの推定も、正しい回答やnullでない回答を保証するものではありません。

| リクエストのオプション | 動作 | 成功した検索1件あたりのクレジット |
| --- | --- | --- |
| options.ai_mode: off | データセットのみを使用します。 | 1（不明な結果を含む） |
| options.ai_mode: fallback | まずデータセットを確認し、性別が返らない場合に通常のAIを使用します。単一リクエストのデフォルトです。 | 合計1（AIフォールバックを含む） |
| options.ai_mode: always | 直接AIに問い合わせます。 | 2 |
| forceToGenderize: true | まずデータセットを確認し、その後、実名がなくても個人のニックネームやエイリアスをAIが解釈できるようにします。 | データセットで推定できた場合は1、AIを使った場合は合計2 |

- [AIオプションとニックネームの推定](https://www.genderapi.io/ja/docs/v2/ai-options)
- [クレジットと使用状況](https://www.genderapi.io/ja/docs/v2/credits-and-usage)

## 量を増やす前にワークフローを確認する

- 意図的に実行する1回のテストで、実際にシリアライズされたJSON、解析された結果のパス、APIキーによるアクセス、課金の確認を検証してください。可能であれば、不明な結果とエラーの処理をサンプルレスポンスでテストしてください。
- ワークフローのどのステップが再実行され、顧客のどのフィールドが変更されるかを明確にしてください。元のレコードのID、受け取ったレスポンス、リクエストの参照を保存しておけば、後で送信先で失敗しても、もう一度リクエストを送る必要はありません。
- まず小規模で管理された実行を有効にし、レコードとクレジットを確認してから並列度を上げてください。GenderAPIのクレジットと、自動化プラットフォームが課金するタスクや操作は、別々のコストです。
- バッチにはPOST /api/v2/gender/batchを使用します。APIキーによるアクセスでは最大50項目、IPトライアルでは最大10項目です。items配列には名前、メールアドレス、ユーザー名を混在させることができ、各項目に明示的なオプションと一意のidを指定します。各結果を確認してください。HTTP 200のレスポンスにも、個々の項目のエラーが含まれることがあります。ネイティブコネクターがバッチに対応しているかどうかは、別途確認が必要です。

- [バッチと項目ごとのエラー](https://www.genderapi.io/ja/docs/v2/batch)
- [Pythonでの実装ガイド](https://www.genderapi.io/ja/integrations/python)
- [Node.jsでの実装ガイド](https://www.genderapi.io/ja/integrations/javascript)

## 古いネイティブアクションのprobabilityフィールドを、V2のconfidenceにマッピングできますか？

まずレスポンスの仕様を確認してください。V2を直接使うと、data.confidenceがdata.confidence_kindとともに、0から1の尺度またはnullで返されます。ネイティブコネクターのフィールドのラベルや尺度が、これらのパスと一致するとは限りません。

## HTTPを直接使う例ではAIが使われますか？

最初のリクエストのボディでは、options.ai_modeをoffに設定しています。通常のAIフォールバックを使う場合は、意図的に値をfallbackに変更してください（合計1クレジット）。直接AIを使う場合はalwaysに変更します（2クレジット）。forceToGenderizeは最初にデータセットを参照します。データセットで解決した場合は1クレジット、AIが使われた場合は合計2クレジットです。

## 不明な結果は無料で、自動的に再送しても安全ですか？

いいえ。成功した不明な結果は完全な結果であり、課金されます。再試行は新しい検索です。通信エラーや課金が未確認の場合は、返された使用状況のデータとリクエストの参照を確認してから、再送するかどうかを判断してください。

## このワークフローは、接続したアカウントで実行されましたか？

いいえ。各プラットフォームの設定手順は、2026年9月26日に公開ドキュメントに基づいて確認しました。GenderAPI.io V2のリクエストとレスポンスの説明は、2026年9月27日に確認しました。この日本語版の2026年9月29日のレビューは翻訳の確認であり、アカウントを使った新しいテストではありません。本番の更新を有効にする前に、選択したアクションの現在のフィールド、認証、リクエストボディ、レスポンス、再試行の動作をご自身のアカウントで確認してください。

## 出典とドキュメント

- [IntegratelyのGenderAPI.io公式掲載ページ](https://integrately.com/integrations/genderapi-io)
- [IntegratelyのWebhook/APIアクション](https://integrately.com/integrations/webhook-api)
- [Integratelyのドキュメント](https://integrately.com/docs)
- [GenderAPI.io V2のリクエスト仕様](https://www.genderapi.io/ja/docs/v2/request-parameters)
- [GenderAPI.io V2のレスポンス仕様](https://www.genderapi.io/ja/docs/v2/responses)
- [GenderAPI.io V2の課金とクレジット](https://www.genderapi.io/ja/docs/v2/credits-and-usage)