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.

Create a Job

POST/v1/jobs

typestring*

Job type: validate or find.

dataarray*

Array 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_urlstring

Optional URL to receive a POST when the job completes.

Create Validate Job

curl -X POST https://api.gtmdata.co/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/gtmdata"
  }'

Create Find Job

curl -X POST https://api.gtmdata.co/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"}
    ]
  }'

Response

{
  "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}

Request

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

Response

{
  "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"
}

Status	Description
`pending`	Job is queued and waiting to start
`processing`	Job is actively being processed
`completed`	All items have been processed
`failed`	Job 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.

pageinteger

Page number (default: 1).

per_pageinteger

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

Request

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

Response

{
  "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.

Request

curl https://api.gtmdata.co/v1/jobs \
  -H "Authorization: Bearer gtm_live_your_key"

Response

{
  "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, GTMData will send a POST request to that URL when the job completes.

Webhook POST Body

{
  "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. GTMData will retry failed deliveries up to 3 times with exponential backoff.