REST API reference

The public REST API includes authenticated account, finder, probe, and background job routes.

Use the interactive reference at /api/reference when you want the exact schema. Use this page when you want the practical rules for deciding which endpoint to call and how to handle the response.

All requests use bearer authentication.

Authorization: Bearer relid_pat_...

SDKs

Official SDKs are generated from the same OpenAPI document that powers the interactive reference.

• Node: @relentlessidentity/sdk
• Python: relentless-identity
• Ruby: relentless_identity
• Go: go.relentlessidentity.com/sdk
• Rust: relentless-identity

Account

Inspect the current bearer token, usage, request history, and background jobs.

GET https://api.relentlessidentity.com/client/token
GET https://api.relentlessidentity.com/client/usage
GET https://api.relentlessidentity.com/client/history
GET https://api.relentlessidentity.com/client/jobs
GET https://api.relentlessidentity.com/client/jobs/{job_id}
GET https://api.relentlessidentity.com/client/jobs/{job_id}/inputs.txt

• GET /client/token: confirm which user and scopes the current bearer token resolves to.
• GET /client/usage: show current free-tier windows or paid usage balance, including any reserved paid value held by queued jobs.
• GET /client/history: return recent completed direct requests.
• GET /client/jobs: list queued, running, completed, failed, or canceled background jobs.
• GET /client/jobs/{job_id}: inspect one job plus paginated item results.
• GET /client/jobs/{job_id}/inputs.txt: download the original submitted inputs while retained payload is still available.

Finder

Use Finder when you have a person's full name and company domain.

POST https://api.relentlessidentity.com/client/attempt

{
  "full_name": "Jane Doe",
  "email_domain": "acme.com"
}

Finder request fields:

• full_name: the real person's full name.
• email_domain: the company's public website or mailbox domain.

Finder returns the shared compact result envelope:

• state: deliverable or undeliverable
• outcome: found, not_found, or error
• address: resolved work email when one is found

Use Finder when the target email address is not known yet.

Probe

Use Probe when you already have a specific email address.

POST https://api.relentlessidentity.com/client/probe

{
  "email": "jane.doe@acme.com"
}

Probe request fields:

• email: the exact mailbox you want to verify.

Use Probe when you already know the exact email address and want a compact deliverability verdict.

Probe batch

Use Probe Batch when you already have many specific email addresses and want compact per-email identity results in one call.

POST https://api.relentlessidentity.com/client/probe/batch

{
  "emails": [
    "jane.doe@acme.com",
    "john.smith@acme.com"
  ]
}

The response uses a { results, summary } wrapper. Each item in results uses the compact probe shape, and any item that returns outcome: "error" is treated as a free operational failure and is not billed.

Probe batch request fields:

• emails: one or more exact mailbox addresses.

Probe batch is the synchronous path for many known identities at once.

Background jobs

Use background jobs when you need deadline-driven asynchronous execution plus callback delivery.

POST https://api.relentlessidentity.com/client/jobs/finder
POST https://api.relentlessidentity.com/client/jobs/probe-batch

{
  "deadline": "2027-01-02T00:00:00Z",
  "callback_url": "https://example.com/callbacks/relentless",
  "inputs": [
    {
      "full_name": "Jane Doe",
      "email_domain": "acme.com"
    }
  ]
}

{
  "deadline": "2027-01-02T00:00:00Z",
  "emails": [
    "jane.doe@acme.com",
    "john.smith@acme.com"
  ]
}

Completed jobs are retrieved from GET /client/jobs/{job_id}. Original inputs remain downloadable as plain text from GET /client/jobs/{job_id}/inputs.txt while the retained payload is still available.

Background job rules:

• Jobs are accepted with 202 Accepted and then run asynchronously.
• Finder jobs take inputs, where each item looks like a normal Finder request.
• Probe batch jobs take emails plus an optional provider and callback_url.
• deadline is required. If the requested deadline is too tight even with immediate execution, the API returns 422.
• Job creation can still succeed while synchronous verification is temporarily busy. Queueing is the preferred path for larger or deadline-driven workloads.
• Completed payload rows are retained for a limited time. Job headers remain available longer than the raw item payload.

Job detail responses include:

• job status and counts
• reserved and actual paid usage values
• paginated item results
• callback delivery status

For large original input sets, prefer the plain-text download route instead of rendering every item inside your own UI.

Capacity And 429

The synchronous client endpoints may return 429 Too Many Requests when real-time verification capacity is already fully occupied.

Current behavior:

• POST /client/attempt
• POST /client/probe
• POST /client/probe/batch

These public synchronous endpoints intentionally keep the request shape minimal. Provider overrides and other internal routing controls are not part of the public client contract.

When that happens:

• the response is temporary, not permanent
• retrying later is valid
• background jobs are the preferred fallback for larger workloads or deadline-sensitive work

Typical response shape:

{
  "detail": {
    "error": "service_busy",
    "message": "Synchronous verification is temporarily at capacity. Retry shortly or use a background job instead.",
    "details": {
      "suggestion": "Schedule the work with POST /client/jobs/probe-batch."
    }
  }
}

Important:

• a 429 on a synchronous client request does not mean jobs are unavailable
• queued background jobs wait for capacity instead of failing for this reason
• internal dashboard traffic may follow different operational rules than public client endpoints

Response Handling

Handle these cases first:

• state=deliverable and outcome=found: success
• state=undeliverable and outcome=not_found: negative result
• outcome=error: operational failure, not a confirmed negative

For batch and job responses, treat per-item outcome=error as a retry or review case rather than a valid mailbox verdict.

Interactive reference

For the same public routes in Scalar, open /api/reference. That page also exposes the generated OpenAPI document used for SDK generation.