Get started

Revor AI API v2 provides prospect discovery, public-web and contact search, customs trade data, Connect account lookup, and one-off outreach. Long-running operations use asynchronous jobs: submit a request, then retrieve its result through the unified jobs endpoint.

Make your first request

After creating an API key, check your credit balance to verify authentication and account status:

cURLCopy
curl "https://revor.ai/api/v2/credits" \
  -H "Authorization: Bearer sk-revor-REPLACE_ME"

Choose a capability

Current paths and fields use websets / webset for prospect discovery. A webset is a prospect list that is generated over time and can be read page by page; callers do not need to know its internal implementation.

Base URL

https://revor.ai/api/v2

API v1 Connect and Outreach endpoints remain temporarily compatible. Both versions can use the same API key, but new integrations should use v2 paths and ensure the key has the corresponding permissions.

Authentication

Use the Authorization: Bearer header:

cURLCopy
curl "https://revor.ai/api/v2/credits" \
  -H "Authorization: Bearer sk-revor-REPLACE_ME"

You may also use x-api-key:

cURLCopy
curl "https://revor.ai/api/v2/credits" \
  -H "x-api-key: sk-revor-REPLACE_ME"

Never put an API key in a URL, frontend code, public repository, or log.

Membership limits and concurrency

The API and MCP share account-wide allowances. Multiple API keys or protocols do not receive separate allowances.

Normal reads, job polling, data-task creation, and outreach actions have separate request limits. Credits, requests per minute, and active-job concurrency are independent controls. See Rate limits, concurrency, and retries for plan limits, headers, errors, and retry behavior.

Common response format

Successful responses contain ok: true and request_id. Lists generally return items; single resources and asynchronous jobs generally return item.

JSONCopy
{ "ok": true, "request_id": "req_xxx", "item": {} }

Error responses contain a stable public error code. Keep request_id when contacting support or troubleshooting.

JSONCopy
{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "invalid_request",
    "request_id": "req_xxx"
  }
}

Idempotency keys

Idempotency-Key is an optional reliable-retry mechanism. Ordinary requests can omit it. If a caller may retry automatically after a network timeout, generate a unique value for the same business operation:

HttpCopy
Idempotency-Key: 2d1ed06a-4e63-4e36-9e88-53784bb61b0b

• Same path, key, and body: returns the first result without creating a duplicate job.
• Same path and key with a different body: returns 409.
• Generate a new key for a genuinely new operation; reuse the original key after a network timeout.
• Without a key, every POST is independent. Duplicate submissions may create, run, and bill multiple jobs.

Asynchronous jobs and Prefer wait

Research and customs endpoints normally return HTTP 202 Accepted. Save item.id, then poll:

HttpCopy
GET /api/v2/jobs/{id}

To wait briefly during creation, include:

HttpCopy
Prefer: wait=20

If the job finishes during the wait window, the creation endpoint returns HTTP 200 with the terminal job. Otherwise it still returns HTTP 202. A wait timeout does not mean the job failed; continue polling its ID.

Job status versus business-resource status

Jobs and prospect lists have separate statuses:

TextCopy
POST /websets
  ├─ preparation_job: queued → running → succeeded
  └─ prospect list: generating_criteria → searching → verifying → completed

The job reports whether one asynchronous operation finished. The prospect-list status reports the stage of discovery. Therefore, preparation_job.status=succeeded only means the list started successfully, not that discovery is complete.

Endpoint reference

Detailed documentation:

• Credit balance
• Rate limits, concurrency, and retries
• Connect accounts
• Send one outreach message
• Find and like a LinkedIn post
• Asynchronous jobs
• Prospect discovery
• Public-web and company-contact search
• Customs trade data

Recommended workflows

One-off outreach

1. Call GET /connect/accounts?can_send=true and select an account_id.
2. Call POST /outreach/dispatches or the LinkedIn-like endpoint. Send Idempotency-Key when safe retries are needed.
3. Save item.id and poll GET /jobs/{id}.
4. For succeeded, read item.result; for failed, read item.error.code.

Prospect discovery

1. Call GET /credits to confirm available credits.
2. Call POST /websets, then save webset.id.
3. Poll GET /websets/{id} until completed, failed, or cancelled.
4. Page through GET /websets/{id}/items?detail=compact&limit=10.

preparation_job.id only confirms whether the list started; it does not mean prospect discovery is complete.

Research and customs jobs

1. Submit the creation request, using Idempotency-Key if safe retries are needed.
2. Read item.id.
3. If item.status is not terminal, poll GET /jobs/{id}.
4. On succeeded, read item.result and item.billing.

Common errors