API Endpoints Reference

Base URL and Versioning

All API endpoints are under the base URL https://api.trustleads.ai/v1/. The API is versioned with a v1 prefix. Breaking changes are introduced in new major versions (v2, v3) — existing v1 integrations will continue to work for a minimum of 12 months after a new version is released.

All responses are JSON with UTF-8 encoding. All timestamps are in ISO 8601 format (UTC). Pagination uses cursor-based pagination with a next_cursor field in list responses.

Jobs Endpoints

The /jobs endpoints allow you to submit enrichment jobs, check their status, and retrieve results. Job submission accepts either a file URL (for files hosted on your own storage) or a direct file upload via multipart form data.

# Submit a new enrichment job (Pro/Agency only)
POST /v1/jobs
Content-Type: application/json
{ "file_url": "https://storage.example.com/leads.csv" }

# List all jobs (newest first)
GET /v1/jobs?limit=20&cursor=<next_cursor>

# Get a single job by ID
GET /v1/jobs/{job_id}

# Download enriched results (returns redirect to signed file URL)
GET /v1/jobs/{job_id}/download

# Response example for a completed job
{
  "id": "job_a1b2c3d4",
  "status": "complete",
  "rows_processed": 1543,
  "rows_failed": 7,
  "quota_consumed": 1543,
  "credits_consumed": 0,
  "created_at": "2024-01-15T10:23:45Z",
  "completed_at": "2024-01-15T10:25:12Z"
}

Usage Endpoint

The /usage endpoint returns current quota consumption and credit balance. This is useful for building dashboards, quota-aware job schedulers, or alerting systems in your own infrastructure.

# Get current usage stats
GET /v1/usage

Response:
{
  "quota_total": 10000,
  "quota_used": 6732,
  "quota_remaining": 3268,
  "credits_remaining": 500,
  "reset_date": "2024-02-01T00:00:00Z",
  "plan": "pro"
}

Webhooks

Trust Leads can POST a webhook to your endpoint when a job completes or fails. Configure webhook URLs at /app/api-keys in the Webhooks section. All webhook payloads are signed with HMAC-SHA256 using your webhook signing secret — verify the X-TrustLeads-Signature header on every incoming webhook to prevent forged payloads.

Webhook events are delivered with at-least-once semantics — your endpoint may receive the same event more than once during network retries. Use the event.id field for idempotency. Events are retried up to 5 times with exponential backoff on non-2xx responses.

# Webhook payload for job.complete event
{
  "event": "job.complete",
  "event_id": "evt_x9y8z7w6",
  "job_id": "job_a1b2c3d4",
  "status": "complete",
  "rows_processed": 1543,
  "download_url": "https://api.trustleads.ai/v1/jobs/job_a1b2c3d4/download",
  "timestamp": "2024-01-15T10:25:12Z"
}