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ボディを送信できることを確認してから適用してください。既存のネイティブアクションは、それぞれ独自のフィールド仕様を保ちます。
アカウントと元のレコードを準備する
この例では、名前をもとにMailchimpのレコードを拡充します。連携元と連携先のアプリへのアクセス、GenderAPI.ioアカウントのキー、HTTPアクションで使うプラットフォームの機能が必要です。このガイドには、有効な認証情報や接続済みのアカウントは含まれていません。
V1とV2は、同じアカウントのキーと同じ残高を使用します。課金対象のリクエストを設定する前に、GET /api/v2/usageでキーを確認し、このエンドポイントのレスポンスでmeta.access.modeがapi_keyになっていることを確認してください。キーがない場合や認識されない場合は、共有のIPトライアルに切り替わることがあります。本番の自動化が、気付かないうちにこれに依存する状態にしてはいけません。
設定中はワークフローを無効にしておいてください。テストで送信した推定にも通常どおりクレジットが消費されます。この手順は、公開ドキュメントとV2の仕様に照らして確認したものです。この公開にあたり、どのプラットフォームでも認証済みのワークフローを最初から最後まで実行してはいません。
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は、信頼できるコンテキストがある場合にのみ追加してください。このフィールドは任意であり、居住国を調べるものではありません。
{
"type": "name",
"value": "Alice",
"options": {
"ai_mode": "off"
}
}更新を有効にする前にHTTPステップを確認する
後続のフィールドを選ぶ前に、アクションを意図的に1回テストし、返されたボディを確認してください。ネイティブのGenderAPI.ioステップとWebhook/APIのステップでは、元の顧客が同じでも、表示されるフィールドのラベルが異なることがあります。
キーは、接続またはリクエスト認証用の所定の設定に保存し、自動化を表示または共有できる人を制限してください。この公開ガイドには、有効なキー、エクスポートされた接続、あらかじめ設定された顧客の更新は含まれていません。
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または完全なレスポンスなし | 更新を一時停止し、エラーと課金ステータスを確認してください。タイムアウトは、サーバーが何も処理しなかったことを証明するものではありません。 |
Mailchimpでは対応するレコードだけを更新する
保存したMailchimpのオーディエンス（Audience）と購読者のIDを使って、送信先のレコードを選択します。推定値専用のフィールドや承認済みのタグに書き込む前に、結果のステータスと、上記のアクセスと課金の確認に関する条件を追加してください。性別がない場合やnullの場合に、それをコンタクトの既定のカテゴリーに変換しないでください。
更新を有効にする前に、identifiedの結果、不明な結果、エラーの各分岐をテストします。架空のサンプルレスポンスを使えば、新しい推定を送信せずに分岐の条件を確認できます。連携先アプリでの更新は上記の確認に基づいて行い、関係のないフィールドやタグを上書きしないようにしてください。
再試行と重複課金を管理する
Integratelyでは、会社全体に適用される設定を含む、自動再試行の動作が説明されています。この自動化を有効にする前に、ポリシーとタスクの履歴を確認し、共有の設定を変更する前にほかのワークフローへの影響を評価してください。繰り返されたHTTPリクエストは、それぞれ独立した課金対象のリクエストです。成功した出力を保存しておけば、後続のMailchimpでの失敗を、もう一度リクエストを送らずに修正できます。
GenderAPIへの新しいリクエストは、それぞれが独立した操作です。送信前に、保存した連携元のIDと処理ステータスを使って、ワークフロー内で繰り返された連携元イベントの重複を除いてください。連携元レコードのIDは、サーバー側で重複を防ぐキーではありません。
成功した不明な結果は、完了した課金対象の結果です。タイムアウトやレスポンスが不完全な場合は、結果も課金も分からないことがあります。リクエストの参照情報があれば保存し、リクエストを再送する前に課金を確認してください。レート制限のレスポンスにRetry-Afterヘッダーが含まれている場合は、それに従ってください。
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 |
量を増やす前にワークフローを確認する
- 意図的に実行する1回のテストで、実際にシリアライズされたJSON、解析された結果のパス、APIキーによるアクセス、課金の確認を検証してください。可能であれば、不明な結果とエラーの処理をサンプルレスポンスでテストしてください。
- ワークフローのどのステップが再実行され、顧客のどのフィールドが変更されるかを明確にしてください。元のレコードのID、受け取ったレスポンス、リクエストの参照を保存しておけば、後で送信先で失敗しても、もう一度リクエストを送る必要はありません。
- まず小規模で管理された実行を有効にし、レコードとクレジットを確認してから並列度を上げてください。GenderAPIのクレジットと、自動化プラットフォームが課金するタスクや操作は、別々のコストです。
- バッチにはPOST /api/v2/gender/batchを使用します。APIキーによるアクセスでは最大50項目、IPトライアルでは最大10項目です。items配列には名前、メールアドレス、ユーザー名を混在させることができ、各項目に明示的なオプションと一意のidを指定します。各結果を確認してください。HTTP 200のレスポンスにも、個々の項目のエラーが含まれることがあります。ネイティブコネクターがバッチに対応しているかどうかは、別途確認が必要です。
よくある質問
古いネイティブアクションの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日のレビューは翻訳の確認であり、アカウントを使った新しいテストではありません。本番の更新を有効にする前に、選択したアクションの現在のフィールド、認証、リクエストボディ、レスポンス、再試行の動作をご自身のアカウントで確認してください。
出典とドキュメント
日本語版の最終確認日はです。各プラットフォームに関する情報は、2026年9月26日に確認した公開ドキュメントに基づいています。この確認は、接続済みのアカウントを使った新しいテストではありません。現在の設定方法と提供状況は、各プラットフォームの公式ドキュメントで確認してください。