Submit Email Check

POST

api

public

verify

curl -X POST "https://app.gethuntd.com/api/v1/public/verify" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: hntd_abc12345_yoursecretkey" \
  -d '{"email": "dana@acme.com", "sources": ["gong", "extend"]}'

const response = await fetch('https://app.gethuntd.com/api/v1/public/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.HUNTD_API_KEY
  },
  body: JSON.stringify({ email: 'dana@acme.com', sources: ['gong', 'extend'] })
});

const job = await response.json();
console.log('Job ID:', job.job_id, 'poll after:', job.poll_after);

import requests
import os

response = requests.post(
    'https://app.gethuntd.com/api/v1/public/verify',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': os.environ['HUNTD_API_KEY']
    },
    json={'email': 'dana@acme.com', 'sources': ['gong', 'extend']}
)

job = response.json()
print(f"Job ID: {job['job_id']}, poll after: {job['poll_after']}")

{
  "success": true,
  "job_id": "8f4c2a90-6c1e-4b58-9a2f-1d3e5b7c9011",
  "email": "dana@acme.com",
  "sources": ["gong", "extend"],
  "status": "queued",
  "poll_after": "2026-09-15T09:00:00.000Z"
}

{
  "success": true,
  "job_id": "8f4c2a90-6c1e-4b58-9a2f-1d3e5b7c9011",
  "email": "dana@acme.com",
  "sources": ["gong", "extend"],
  "status": "completed",
  "poll_after": null
}

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "`email` is not a valid address."
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is missing, invalid, or has been revoked."
  }
}

{
  "success": false,
  "error": {
    "code": "SOURCE_NOT_ALLOWED",
    "message": "Your organization does not have access to source `gong`."
  }
}

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly cap reached for source `gong` (10000 of 10000 checks this month)."
  }
}

Availability: Agency plan, on https://app.gethuntd.com. Other plans receive 403 ENDPOINT_NOT_ON_PLAN. Counts against your monthly checks per source. Contact Huntd to enable it.

curl -X POST "https://app.gethuntd.com/api/v1/public/verify" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: hntd_abc12345_yoursecretkey" \
  -d '{"email": "dana@acme.com", "sources": ["gong", "extend"]}'

const response = await fetch('https://app.gethuntd.com/api/v1/public/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.HUNTD_API_KEY
  },
  body: JSON.stringify({ email: 'dana@acme.com', sources: ['gong', 'extend'] })
});

const job = await response.json();
console.log('Job ID:', job.job_id, 'poll after:', job.poll_after);

import requests
import os

response = requests.post(
    'https://app.gethuntd.com/api/v1/public/verify',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': os.environ['HUNTD_API_KEY']
    },
    json={'email': 'dana@acme.com', 'sources': ['gong', 'extend']}
)

job = response.json()
print(f"Job ID: {job['job_id']}, poll after: {job['poll_after']}")

{
  "success": true,
  "job_id": "8f4c2a90-6c1e-4b58-9a2f-1d3e5b7c9011",
  "email": "dana@acme.com",
  "sources": ["gong", "extend"],
  "status": "queued",
  "poll_after": "2026-09-15T09:00:00.000Z"
}

{
  "success": true,
  "job_id": "8f4c2a90-6c1e-4b58-9a2f-1d3e5b7c9011",
  "email": "dana@acme.com",
  "sources": ["gong", "extend"],
  "status": "completed",
  "poll_after": null
}

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "`email` is not a valid address."
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is missing, invalid, or has been revoked."
  }
}

{
  "success": false,
  "error": {
    "code": "SOURCE_NOT_ALLOWED",
    "message": "Your organization does not have access to source `gong`."
  }
}

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly cap reached for source `gong` (10000 of 10000 checks this month)."
  }
}

Overview

Check whether one email address is a user of up to 20 products. In this API a product is called a source, named by a slug such as gong or extend. This is an async operation:

Submit an email and a list of sources
Receive a job_id and a poll_after time immediately (202 Accepted)
Once poll_after has passed, poll Get Email Check Result until status is completed
Read sources[slug].is_user: true, false, or null

The response is always 202 with a job, even when every answer is already cached (then status is completed and poll_after is null), so your client only needs one code path.

Timing

Checks only run Monday to Friday, 09:00 to 18:00 in your account’s timezone. A job submitted on Friday evening starts on Monday morning, and its poll_after says so.
A fresh check takes minutes, not seconds. A cached answer is instant.
poll_after can be days away. In production, save job_id and poll_after and check back from a scheduled job instead of keeping a process asleep.

Which Sources You Can Check

A source slug is accepted only when all three are true. Each failure has its own error:

Rule	If it fails
Your organization has access to the source	`403 SOURCE_NOT_ALLOWED`
The source can check individual people (company-level and demo-only sources can’t)	`422 SOURCE_NOT_VERIFIABLE`
The source isn’t paused for maintenance	`423 SOURCE_UNAVAILABLE`

Access is checked first, so you never learn about sources you haven’t bought. The sources you have access to are listed in the Huntd dashboard.

Limits

Limit	Value	Error
Sources per request	20	`400 INVALID_PARAMETER`
Request body	64 KB	`413 INVALID_BODY`
Requests per source	5 per minute, per organization	`429 RATE_LIMITED`
Requests per API key	60 per minute by default, polls included	`429 RATE_LIMIT_EXCEEDED`
Checks per source per month	10,000 by default (20,000 and 30,000 tiers available)	`429 QUOTA_EXCEEDED`

The per-source limit is all-or-nothing: if any source in the request is over its limit, the whole request is refused and nothing is used up.
Monthly checks reset at the start of each UTC calendar month and count cached answers too. Ask your account manager to change tier.
RATE_LIMITED and RATE_LIMIT_EXCEEDED carry Retry-After (seconds); QUOTA_EXCEEDED doesn’t, because it lasts until the next month.

Errors

HTTP	Error Code	Description
400	`INVALID_PARAMETER`	`email` missing or malformed, or `sources` empty, not an array, over 20 entries, or containing a non-string
400 / 413 / 415	`INVALID_BODY`	Body isn’t JSON, is over 64 KB, or has an unsupported content type or charset
401	`INVALID_API_KEY`	API key is missing, invalid, or has been revoked
403	`ENDPOINT_NOT_ON_PLAN`	Your plan doesn’t include email checks
403	`SOURCE_NOT_ALLOWED`	Your organization doesn’t have access to one of the sources
403	`SUBSCRIPTION_INACTIVE`	Your workspace has no active subscription. Contact your account manager.
422	`SOURCE_NOT_VERIFIABLE`	One of the sources can’t check individual people. Remove it.
423	`SOURCE_UNAVAILABLE`	A source is paused for maintenance. Retry later.
429	`RATE_LIMITED`	Over 5 requests per minute for one of the sources. Wait `Retry-After` seconds.
429	`RATE_LIMIT_EXCEEDED`	Over your API key’s per-minute limit. Wait `Retry-After` seconds.
429	`QUOTA_EXCEEDED`	Monthly checks used up for one of the sources
500	`INTERNAL_ERROR`	Something broke on our side. Safe to retry.
503	`ORG_KIND_UNAVAILABLE`	Your plan briefly couldn’t be confirmed. Retry.

A request that returns an error created no job and used no monthly checks, so it’s always safe to retry.

Authorizations

X-API-Key

string

header

required

API key in format: hntd_{id}_{secret}. Create one in Settings → API & webhooks. Authorization: Bearer is also accepted.

Body

application/json

string<email>

required

The one address to check. Lowercased and trimmed for you.

Maximum string length: 320

Example:

"dana@acme.com"

sources

string[]

required

Source slugs to check the address against (1 to 20). A source is a product such as gong or extend. Duplicates are ignored.

Required array length: 1 - 20 elements

Example:

["gong", "extend"]

Response

Job accepted. Always 202, even when every answer came from cache.

success

enum<boolean>

Available options:

true

job_id

string<uuid>

Pass to Get Email Check Result. Opaque: don't parse it.

Example:

"8f4c2a90-6c1e-4b58-9a2f-1d3e5b7c9011"

string

The address as it will be checked, after lowercasing and trimming.

Example:

"dana@acme.com"

sources

string[]

The sources this job covers, duplicates removed.

Example:

["gong", "extend"]

status

enum<string>

queued if at least one source needs a fresh check; completed if every answer came from cache.

Available options:

queued,

completed

poll_after

string<date-time> | null

Earliest moment work can start (UTC). Don't poll before it. null when every answer came from cache.

curl -X POST "https://app.gethuntd.com/api/v1/public/verify" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: hntd_abc12345_yoursecretkey" \
  -d '{"email": "dana@acme.com", "sources": ["gong", "extend"]}'

const response = await fetch('https://app.gethuntd.com/api/v1/public/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.HUNTD_API_KEY
  },
  body: JSON.stringify({ email: 'dana@acme.com', sources: ['gong', 'extend'] })
});

const job = await response.json();
console.log('Job ID:', job.job_id, 'poll after:', job.poll_after);

import requests
import os

response = requests.post(
    'https://app.gethuntd.com/api/v1/public/verify',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': os.environ['HUNTD_API_KEY']
    },
    json={'email': 'dana@acme.com', 'sources': ['gong', 'extend']}
)

job = response.json()
print(f"Job ID: {job['job_id']}, poll after: {job['poll_after']}")

{
  "success": true,
  "job_id": "8f4c2a90-6c1e-4b58-9a2f-1d3e5b7c9011",
  "email": "dana@acme.com",
  "sources": ["gong", "extend"],
  "status": "queued",
  "poll_after": "2026-09-15T09:00:00.000Z"
}

{
  "success": true,
  "job_id": "8f4c2a90-6c1e-4b58-9a2f-1d3e5b7c9011",
  "email": "dana@acme.com",
  "sources": ["gong", "extend"],
  "status": "completed",
  "poll_after": null
}

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "`email` is not a valid address."
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is missing, invalid, or has been revoked."
  }
}

{
  "success": false,
  "error": {
    "code": "SOURCE_NOT_ALLOWED",
    "message": "Your organization does not have access to source `gong`."
  }
}

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly cap reached for source `gong` (10000 of 10000 checks this month)."
  }
}

​Overview

​Timing

​Which Sources You Can Check

​Limits

​Errors

Authorizations

Body

Response

Overview

Timing

Which Sources You Can Check

Limits

Errors