Async Validation Jobs

Create, list, inspect, and download asynchronous email validation jobs

Async Validation Jobs

Use asynchronous validation jobs for larger email lists that should be processed in the background. Jobs are Product Control Plane-owned public API workflows: the API authenticates with X-API-Key, reserves credits for unique submitted emails, validates asynchronously, finalizes charges for High-Value Validations, and refunds unused reserved credits.

Endpoints

Method	Endpoint	Purpose
POST	https://api.gtmapis.com/v1/validate/batch	Create an asynchronous validation job.
POST	https://api.gtmapis.com/v1/csv/prepare-upload	Create a signed upload URL for CSV validation files.
POST	https://api.gtmapis.com/v1/csv/start-processing	Start parsing and validation for a signed CSV upload.
GET	https://api.gtmapis.com/v1/csv/jobs	List validation jobs for the API key account.
GET	https://api.gtmapis.com/v1/csv/jobs/{id}	Get status, progress, summary counts, and download handoff metadata for one job.
GET	https://api.gtmapis.com/v1/csv/jobs/{id}/download	Get a signed results CSV download URL.

Required Scope

Scoped API keys need email:validate:bulk. Legacy unrestricted keys retain compatible access until rotated.

Create Job

Use this JSON endpoint for scripts and SDKs that already have an array of emails. It accepts up to 500,000 submitted emails; valid duplicates are deduplicated before credit reservation.

cURL

curl -X POST https://api.gtmapis.com/v1/validate/batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gtm_test_1234567890abcdef1234567890abcdef" \
  -d '{
    "emails": ["[e-mail]", "[e-mail]"],
    "webhook_url": "https://example.com/gtmapis-webhook"
  }'

Signed CSV Upload

Use this flow for large CSV files so the file body goes directly to Storage instead of through the API proxy.

cURL

curl -X POST https://api.gtmapis.com/v1/csv/prepare-upload \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gtm_test_1234567890abcdef1234567890abcdef" \
  -d '{ "filename": "leads.csv" }'

Upload the CSV file to the returned upload_url, then start processing:

cURL

curl -X POST https://api.gtmapis.com/v1/csv/start-processing \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gtm_test_1234567890abcdef1234567890abcdef" \
  -d '{
    "batch_id": "job_123",
    "email_column": "email"
  }'

List Jobs

cURL

curl "https://api.gtmapis.com/v1/csv/jobs?limit=20" \
  -H "X-API-Key: gtm_test_1234567890abcdef1234567890abcdef"

Get Job Status

cURL

curl https://api.gtmapis.com/v1/csv/jobs/job_123 \
  -H "X-API-Key: gtm_test_1234567890abcdef1234567890abcdef"

Status responses include job state, progress, summary counts, credits reserved, credits consumed, credits refunded, effective credits per High-Value Validation, and download handoff metadata without exposing internal validation batch table shape.

{
  "id": "job_123",
  "status": "completed",
  "progress": { "processed": 1000, "total": 1000, "percent": 100 },
  "results": {
    "total_rows": 1200,
    "unique_emails": 1000,
    "valid": 350,
    "valid_role_based": 250,
    "invalid": 150,
    "risky": 200,
    "unknown": 50,
    "role_based": 250,
    "high_value": 350,
    "catch_all": 200,
    "credits_reserved": 1000,
    "credits_charged": 350,
    "credits_consumed": 350,
    "credits_refunded": 650,
    "credits_per_high_value_validation": 1
  },
  "credit_reservation": {
    "reserved": true,
    "reserved_credits": 1000,
    "credits_charged": 350,
    "credits_consumed": 350,
    "refunded_credits": 650,
    "credits_per_high_value_validation": 1,
    "finalized": true
  }
}

Get Download URL

cURL

curl "https://api.gtmapis.com/v1/csv/jobs/job_123/download?mode=url" \
  -H "X-API-Key: gtm_test_1234567890abcdef1234567890abcdef"

Agents and scripts should use mode=url and follow the signed URL instead of pulling raw CSV content through MCP.

Credit Behavior

• Credits are reserved up front for unique submitted emails.
• Only High-Value Validations are charged when processing completes.
• Role-based, catch-all, invalid, risky, and unknown results are refunded from the reservation.
• Failed-job recovery should refund unused reservations idempotently.
• Use results.high_value, results.credits_consumed, and results.credits_per_high_value_validation to measure cost per usable lead instead of raw cost per lookup.