API reference

Batch Processing

Validate or find emails in bulk with a single API call. Batch endpoints process requests synchronously and return all results at once.

Batch Validate

Validate up to 500 emails in a single request.

POST/v1/validate/batch

Parameters

ParameterTypeDescription
emailsreq
string[]Array of email addresses to validate. Maximum 500 per request.

Request

curl -X POST https://api.gtmcli.com/v1/validate/batch \
  -H "Authorization: Bearer gtm_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "ceo@example.com",
      "nobody@fake.com",
      "info@catchall-corp.com"
    ]
  }'

Response

200 OKjson
{
  "results": [
    {
      "email": "ceo@example.com",
      "status": "valid",
      "provider": "google"
    },
    {
      "email": "nobody@fake.com",
      "status": "invalid",
      "provider": "other"
    },
    {
      "email": "info@catchall-corp.com",
      "status": "catchall",
      "provider": "other"
    }
  ],
  "total": 3,
  "credits_used": 0.25
}

INFO

Maximum of 500 emails per batch validate request. For larger lists, use the async Jobs API.

Batch Find

Find emails for up to 50 contacts in a single request.

POST/v1/find/batch

Parameters

ParameterTypeDescription
contactsreq
object[]Array of contact objects. Maximum 50 per request.
contacts[].first_namereq
stringContact's first name.
contacts[].last_namereq
stringContact's last name.
contacts[].domainreq
stringCompany domain to search.

Request

curl -X POST https://api.gtmcli.com/v1/find/batch \
  -H "Authorization: Bearer gtm_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {"first_name": "Tim", "last_name": "Cook", "domain": "apple.com"},
      {"first_name": "Satya", "last_name": "Nadella", "domain": "microsoft.com"},
      {"first_name": "Fake", "last_name": "Person", "domain": "norealdomain.com"}
    ]
  }'

Response

200 OKjson
{
  "results": [
    {
      "email": "tcook@apple.com",
      "status": "valid",
      "provider": "other",
      "convention": "flast",
      "confidence": 1
    },
    {
      "email": "satya.nadella@microsoft.com",
      "status": "valid",
      "provider": "microsoft",
      "convention": "first.last",
      "confidence": 1
    },
    {
      "email": null,
      "status": "not_found",
      "provider": "other",
      "convention": null,
      "confidence": 0
    }
  ],
  "total": 3,
  "credits_used": 2
}

INFO

Maximum of 50 contacts per batch find request. For larger lists, use the async Jobs API.

Credit Usage

Batch requests follow the same credit rules as single requests. Only valid results are charged for validation (0.25 credits each), and only valid or valid_catchall results are charged for finds (1 credit each). The response includes a credits_used field showing the total credits consumed.

TIP

You only pay for results. Invalid, not-found, and catch-all results are always free.