이 개발자 문서는 현재 영어로만 제공됩니다. 코드 및 API 동작은 모든 지역에서 동일합니다.

Contacts API

The Contact Finder service lets you search a B2B warehouse, reveal contact PII, verify deliverability, enrich records, run bulk discovery, and look up companies. All routes are served under /v1/contacts and backed by module-H.

Authentication

Every request must carry a tenant API key as a Bearer token:

Authorization: Bearer ai92_live_<key>     # production
Authorization: Bearer ai92_test_<key>     # sandbox

OAuth 2.0 access tokens (Authorization: Bearer eyJ…) are also accepted. Mutating requests support the Idempotency-Key header.

Credit costs at a glance

Endpoint	Cost
`GET /v1/contacts/search`	Free
`POST /v1/contacts/reveal`	3 cr (email) / 5 cr (email+phone)
`POST /v1/contacts/verify`	1 cr (free if inconclusive)
`POST /v1/contacts/enrich`	11 cr
`POST /v1/contacts/bulk`	300 cr per 100 (rounded up)
`GET /v1/contacts/{company_id}`	2 cr

GET /v1/contacts/search

Cost: Free

Free warehouse search across the contact database, scoped to a brand.

Auth: Bearer (tenant key or OAuth token)

Parameter	In	Type	Required	Description
`brand_id`	query	string	No	Restrict results to a brand. Verified against the account.
`tags`	query	string	No	Comma-separated tag filter.
`email`	query	string	No	Filter by exact email.
`limit`	query	integer	No	Page size. Default `50`.
`offset`	query	integer	No	Page offset. Default `0`.

Request

bash

curl https://api.ai92.ai/v1/contacts/search?brand_id=acme&limit=25 \
  -H "Authorization: Bearer ai92_test_51a9c0de…"

Response 200 OK

json

{
  "total": 1284,
  "limit": 25,
  "offset": 0,
  "contacts": [
    {
      "person_id": "p_8f21a6",
      "full_name": "Jordan Vega",
      "title": "VP Marketing",
      "company": "Acme Corp",
      "tags": ["decision-maker", "saas"]
    }
  ]
}

POST /v1/contacts/reveal

Cost: 3 credits (mode=email) · 5 credits (mode=email_phone)

Reveal a contact's PII by person_id. email mode returns the email only; email_phone adds phone. Credits are deducted only after a successful reveal.

Auth: Bearer

Field	Type	Required	Description
`person_id`	string	Yes	The warehouse person id to reveal.
`mode`	string	No	`email` (default, 3 cr) or `email_phone` (5 cr).
`include_phone`	boolean	No	Legacy alias for `mode=email_phone`. Default `false`.

Request

bash

curl https://api.ai92.ai/v1/contacts/reveal \
  -H "Authorization: Bearer ai92_test_51a9c0de…" \
  -H "Content-Type: application/json" \
  -d '{"person_id": "p_8f21a6", "mode": "email_phone"}'

Response 200 OK

json

{
  "person_id": "p_8f21a6",
  "email": "[email protected]",
  "phone": "+1-415-555-0173",
  "full_name": "Jordan Vega",
  "title": "VP Marketing",
  "company": "Acme Corp"
}

Errors

Status	Code	When
`422`	`INVALID_REVEAL_MODE`	`mode` is not `email` or `email_phone`.
`402`	`INSUFFICIENT_CREDITS`	Balance below the reveal cost.

POST /v1/contacts/verify

Cost: 1 credit — free when the verdict is inconclusive (status=unknown)

Email deliverability check (ZeroBounce via module-H). Charged 1 credit only for a definitive verdict.

Auth: Bearer

Field	Type	Required	Description
`email`	string	Yes	The email address to verify.

Request

bash

curl https://api.ai92.ai/v1/contacts/verify \
  -H "Authorization: Bearer ai92_test_51a9c0de…" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Response 200 OK

json

{
  "email": "[email protected]",
  "status": "deliverable",
  "sub_status": "none",
  "credits_consumed": 1
}

When the verdict is inconclusive, status is "unknown" and credits_consumed is 0.

Errors

Status	Code	When
`402`	`INSUFFICIENT_CREDITS`	Balance below 1 credit.

POST /v1/contacts/enrich

Cost: 11 credits

Full contact enrichment (email + phone + firmographics) via module-H.

Auth: Bearer

Field	Type	Required	Description
`person_id`	string	Yes	The person id to enrich.
`fields`	string[]	No	Specific fields to enrich. Defaults to all.

Request

bash

curl https://api.ai92.ai/v1/contacts/enrich \
  -H "Authorization: Bearer ai92_test_51a9c0de…" \
  -H "Content-Type: application/json" \
  -d '{"person_id": "p_8f21a6", "fields": ["email", "phone", "company_size"]}'

Response 200 OK

json

{
  "person_id": "p_8f21a6",
  "email": "[email protected]",
  "phone": "+1-415-555-0173",
  "company": "Acme Corp",
  "company_size": "201-500",
  "industry": "Software",
  "linkedin_url": "https://linkedin.com/in/jvega"
}

Errors

Status	Code	When
`402`	`INSUFFICIENT_CREDITS`	Balance below 11 credits.

POST /v1/contacts/bulk

Cost: 300 credits per 100 requested records (rounded up per 100)

Bulk contact discovery via module-H. filters must include the discovery keys the backend requires (e.g. vertical, geography). Cost = ceil(limit / 100) * 300.

Auth: Bearer

Field	Type	Required	Description
`filters`	object	Yes	Discovery filter keys (e.g. `vertical`, `geography`).
`limit`	integer	No	Records to discover. Default `100`. Range `10`–`10000`.

Request

bash

curl https://api.ai92.ai/v1/contacts/bulk \
  -H "Authorization: Bearer ai92_test_51a9c0de…" \
  -H "Content-Type: application/json" \
  -d '{"filters": {"vertical": "fintech", "geography": "US"}, "limit": 200}'

Response 200 OK

json

{
  "discovered": 200,
  "contacts": [
    { "person_id": "p_aa01", "full_name": "Lee Park", "title": "CFO", "company": "Northwind" }
  ],
  "credits_charged": 600
}

Errors

Status	Code	When
`402`	`INSUFFICIENT_CREDITS`	Balance below the computed cost.

GET /v1/contacts/{company_id}

Cost: 2 credits

Look up a company by id from the module-H warehouse.

Auth: Bearer

Parameter	In	Type	Required	Description
`company_id`	path	string	Yes	Warehouse company id.

Request

bash

curl https://api.ai92.ai/v1/contacts/co_4521 \
  -H "Authorization: Bearer ai92_test_51a9c0de…"

Response 200 OK

json

{
  "company_id": "co_4521",
  "name": "Acme Corp",
  "domain": "acme.com",
  "industry": "Software",
  "employee_count": 420,
  "hq_location": "San Francisco, CA"
}

Errors

Status	Code	When
`402`	`INSUFFICIENT_CREDITS`	Balance below 2 credits.