API reference

Async Jobs

For large lists (up to 100K contacts), use the async Jobs API. Submit a job, poll for status or receive a webhook, then download paginated results.

TIP

Jobs bypass per-minute rate limits. Submit your list once and retrieve results when ready - no need to manage individual API calls.

Create a Job

POST/v1/jobs

ParameterTypeDescription

typereq

stringJob type: validate or find.

datareq

arrayArray of items to process. For validate jobs, each item has an email field. For find jobs, each item has first_name, last_name, and domain.

webhook_url

stringOptional URL to receive a POST when the job completes.

Request

Create Validate Job

curl -X POST https://api.gtmcli.com/v1/jobs \
  -H "Authorization: Bearer gtm_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "validate",
    "data": [
      {"email": "ceo@example.com"},
      {"email": "test@fake.com"}
    ],
    "webhook_url": "https://your-app.com/webhooks/gtmcli"
  }'

Create Find Job

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

Responsejson

{
  "id": "job_abc123",
  "type": "validate",
  "status": "pending",
  "total": 2,
  "completed": 0,
  "created_at": "2026-04-05T12:00:00Z"
}

Get Job Status

GET/v1/jobs/{id}

Check status

curl https://api.gtmcli.com/v1/jobs/job_abc123 \
  -H "Authorization: Bearer gtm_live_your_key"

Responsejson

{
  "id": "job_abc123",
  "type": "validate",
  "status": "completed",
  "total": 2,
  "completed": 2,
  "credits_used": 0.25,
  "created_at": "2026-04-05T12:00:00Z",
  "completed_at": "2026-04-05T12:00:05Z"
}

Job statuses

pendingJob is queued and waiting to start

processingJob is actively being processed

completedAll items have been processed

failedJob encountered an error

Get Job Results

GET/v1/jobs/{id}/results

Results are paginated. Use page and per_page query parameters to navigate through results.

ParameterTypeDescription

page

integerPage number (default: 1).

per_page

integerResults per page (default: 100, max: 1000).

Get results

curl "https://api.gtmcli.com/v1/jobs/job_abc123/results?page=1&per_page=100" \
  -H "Authorization: Bearer gtm_live_your_key"

Responsejson

{
  "results": [
    {"email": "ceo@example.com", "status": "valid", "provider": "google"},
    {"email": "test@fake.com", "status": "invalid", "provider": "other"}
  ],
  "page": 1,
  "per_page": 100,
  "total": 2,
  "total_pages": 1
}

List Jobs

GET/v1/jobs

Retrieve a list of all your jobs, ordered by most recent first.

List jobs

curl https://api.gtmcli.com/v1/jobs \
  -H "Authorization: Bearer gtm_live_your_key"

Responsejson

{
  "jobs": [
    {
      "id": "job_abc123",
      "type": "validate",
      "status": "completed",
      "total": 2,
      "completed": 2,
      "created_at": "2026-04-05T12:00:00Z"
    }
  ]
}

Webhook Payload

If you provide a webhook_url when creating a job, GTMCLI will send a POST request to that URL when the job completes.

Webhook POST Bodyjson

{
  "event": "job.completed",
  "job_id": "job_abc123",
  "type": "validate",
  "status": "completed",
  "total": 2,
  "completed": 2,
  "credits_used": 0.25,
  "completed_at": "2026-04-05T12:00:05Z"
}

TIP

Your webhook endpoint should return a 200 status code within 10 seconds. GTMCLI will retry failed deliveries up to 3 times with exponential backoff.