Integrately를 GenderAPI.io V2에 연결하기

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 편집기 기능은 이 가이드를 위해 독립적으로 확인하지 않았습니다. 사용하는 액션이 Authorization 헤더와 중첩된 JSON 본문을 보낼 수 있음을 확인한 뒤에만 아래의 V2 HTTP 규격을 사용하세요. 기존 기본 제공 액션은 각자의 필드 규격을 유지합니다.

계정과 원본 레코드 준비하기

이 예시는 이름을 기준으로 Mailchimp 레코드를 보강합니다. 원본 앱과 대상 앱에 대한 접근 권한, GenderAPI.io 계정 API 키, HTTP 액션에 필요한 플랫폼 기능이 필요합니다. 이 가이드에는 실제로 작동하는 로그인 정보나 연결된 계정이 들어 있지 않습니다.

V1과 V2는 같은 계정 API 키와 같은 잔액을 사용합니다. 과금되는 요청을 설정하기 전에 GET /api/v2/usage로 키를 확인하고, 이 엔드포인트의 응답에서 meta.access.mode 값이 api_key인지 확인하세요. 키가 없거나 인식되지 않으면 공유 IP 체험으로 대체될 수 있습니다. 운영 중인 자동화가 이를 모르는 채로 IP 체험에 의존해서는 안 됩니다.

설정하는 동안에는 워크플로를 비활성화해 두세요. 테스트 추정 요청에도 일반 크레딧이 차감됩니다. 이 가이드는 공개 문서와 V2 규격을 기준으로 검토했습니다. 이번 게시를 위해 어떤 플랫폼에서도 인증된 워크플로를 처음부터 끝까지 실행하지는 않았습니다.

인증과 무료 사용량 확인

Integrately에서 GenderAPI.io V2 요청 설정하기

Mailchimp 구독자 트리거를 선택하고 테스트 레코드 하나를 확인하세요. 업데이트에 사용할 대상 그룹(Audience)과 구독자의 ID를 유지하고, 실제 이름 필드를 선택하며, 이름이 없는 레코드는 건너뛰세요.
Webhook/API와 URL로 데이터를 보내는 액션을 찾으세요. 계속하기 전에 사용 가능한 설정을 확인하세요. 아래 규격에는 인증 헤더와 중첩된 JSON 본문이 필요하며, 현재 편집기 기능은 여기서 독립적으로 확인하지 않았습니다.
액션이 이 요구 사항을 충족한다면 POST와 아래의 V2 엔드포인트를 선택하세요. 계정에서 사용할 수 있는 설정 항목을 사용해, 보내는 요청에 Authorization: Bearer YOUR_API_KEY와 Content-Type: application/json이 포함되도록 하세요.
type = name, value = 매핑한 이름, ai_mode = off를 담은 options로 JSON 본문을 만드세요. 선택한 액션의 요청 미리보기를 확인하세요. 평탄한 양식 페이로드는 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 단계 확인하기

액션 하나를 의도적으로 테스트하고, 이후 단계의 필드를 선택하기 전에 반환된 본문을 확인하세요. 원본 고객이 같더라도 기본 제공 GenderAPI.io 단계와 Webhook/API 단계는 서로 다른 필드 레이블을 표시할 수 있습니다.

키는 연결 또는 요청 인증을 위한 설정 항목에 보관하고, 자동화를 보거나 공유할 수 있는 사람을 제한하세요. 이 공개 가이드에는 작동하는 키, 내보낸 연결, 미리 구성된 고객 업데이트가 포함되어 있지 않습니다.

identified 결과, 알 수 없는 결과, 실패를 따로 처리하기

대상 시스템의 업데이트를 선택하기 전에 응답 본문을 파싱하세요. 아래 JSON 경로는 V2 응답 본문을 기준으로 합니다. 플랫폼에 따라 본문을 감싸거나 평탄화할 수 있습니다. 의도적으로 실행한 테스트로 실제 반환 구조를 확인하고, 결과를 원본 레코드 ID와 연결해 두세요.

추정 결과는 사람의 정체성이나 본인이 밝힌 성별을 확정하지 않습니다. 본인이 제공한 정보와 분리해 저장하세요. 수용 기준은 자신의 사용 사례를 대표하는 데이터에 근거해 정하고, 데이터셋의 신뢰도와 AI의 신뢰도는 따로 평가하세요.

확인 항목	예상 값 또는 유형	워크플로에서의 판단
`meta.access.mode`	계정을 사용하는 이 워크플로에서는 api_key	값이 ip_trial이면 워크플로를 중지하고 키를 바로잡으세요. IP 체험에서 성공한 응답은 계정 인증을 증명하지 않으며, 이미 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를 반환합니다. 최종 차감으로 잔액이 0 아래로 내려가더라도 시작 잔액이 0보다 크면 요청을 시작할 수 있습니다.

별명 모드는 name: null과 함께 성별을 반환할 수 있으며, 알 수 없는 결과를 반환할 수도 있습니다. 일반 AI 폴백도 별명 추정도 정확하거나 null이 아닌 답을 보장하지 않습니다.

요청 옵션	동작	성공한 조회의 크레딧
options.ai_mode: off	데이터셋만 사용합니다.	1(알 수 없는 결과 포함)
options.ai_mode: fallback	먼저 데이터셋을 조회하고, 성별이 반환되지 않으면 일반 AI를 사용합니다. 단일 요청의 기본값입니다.	총 1(AI 폴백 포함)
options.ai_mode: always	AI에 직접 요청합니다.	2
forceToGenderize: true	먼저 데이터셋을 조회한 다음, 실제 이름이 없어도 AI가 개인의 별명이나 별칭을 해석할 수 있게 합니다.	데이터셋에서 결과를 얻으면 1, AI를 사용하면 총 2

처리량을 늘리기 전에 워크플로 검증하기

실제로 직렬화된 JSON, 파싱된 결과 경로, API 키 접근, 확정된 과금을 의도적인 테스트로 확인하세요. 알 수 없는 결과와 실패의 처리는 가능하면 예시 응답으로 테스트하세요.
워크플로의 어느 단계가 재시도하는지, 어떤 고객 필드가 변경되는지 확인하세요. 원본 레코드 ID, 완료된 응답, 요청 참조값을 보관해 두면 나중에 대상 시스템에서 실패가 발생해도 새 요청을 보낼 필요가 없습니다.
먼저 소규모로 통제된 실행만 활성화하고, 병렬 처리를 늘리기 전에 레코드와 크레딧을 확인하세요. GenderAPI의 크레딧과 자동화 플랫폼이 부과하는 작업(task) 또는 오퍼레이션 비용은 별개입니다.
일괄 요청에는 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월 30일에 검토한 것은 번역 확인이며, 계정을 사용한 새로운 테스트가 아닙니다. 운영 환경에서 업데이트를 활성화하기 전에, 선택한 액션의 현재 필드, 인증, 본문, 응답, 재시도를 본인 계정으로 테스트하세요.

출처와 문서

한국어판은 2026년 9월 30일에 마지막으로 검토했습니다. 각 플랫폼에 관한 정보는 2026년 9월 26일에 확인한 공개 문서를 바탕으로 합니다. 이 검토는 연결된 계정으로 새로 실행한 테스트가 아닙니다. 현재 설정 방법과 제공 여부는 각 플랫폼의 공식 문서에서 확인하세요.