API reference

The document is OpenAPI 3.1: request bodies, query parameters, error responses, an operationId per operation (createCampaign, launchCampaign…), named schemas, and every event under webhooks with its payload. The offline copy is a snapshot of the live document, for tools that can't reach the API. When they differ, the live one wins.

Authentication

Send Authorization: Bearer <token> on every request. The token is an API key (ov_…, scoped to one workspace, shown once when created; only a hash is stored) or a console session (the JWT POST /auth/sign-in returns, valid 8 hours). Revoked keys stop working at once and stay listed as revoked.

A few actions need a person, not a key: creating, listing and revoking API keys, redeeming a licence, starting a checkout, the billing portal or the extra LinkedIn accounts add-on, exporting the whole workspace and deleting it. With an API key they answer 403 SESSION_REQUIRED_ERROR, so a leaked key can't mint its own replacement. A missing or invalid token answers 401 UNAUTHORIZED, never with a WWW-Authenticate header. Sign-in and sign-up allow 20 attempts per IP every 10 minutes, then answer 429 TOO_MANY_ATTEMPTS_ERROR.

Responses

Every success is 200 OK with a JSON body { "data": … }; lists add "meta". Creating something answers 200 too, with the created object in data.

Pagination

Lists take ?cursor= and ?limit= (1–100, default 50; preview defaults to 25). Pass meta.nextCursor back as cursor for the next page; it is absent on the last page. Cursors are opaque strings.

GET /v1/leads?listId=list_xWOp0Icf&limit=2

{
  "data": [
    { "id": "lead_0vnrCpdo", "firstName": "Paul", "lastName": "Murphy", "company": "Quanta Billing", ... },
    { "id": "lead_1wjEHuX9", "firstName": "Amelia", "lastName": "Brown", "company": "Initech", ... }
  ],
  "meta": { "nextCursor": "lead_1wjEHuX908nyQUu45grRA" }
}

The events feed is a cursor feed: ?after=<event id> returns what happened since, oldest first, and meta.nextCursor is always set (an empty page means nothing new yet). Without after you get the latest page; ?before=<meta.prevCursor> reads further back. POST /v1/search/people pages with a cursor field in the body and also returns meta.total when LinkedIn reports it.

Errors

Errors use HTTP status codes and one body shape: { errorCode, message, details? }. errorCode is stable and safe to branch on; message is for people; details carries structure when there is some, such as the issues that block a launch.

HTTP/1.1 422 Unprocessable Entity

{
  "errorCode": "CAMPAIGN_LAUNCH_BLOCKED_ERROR",
  "message": "The campaign can't launch: The campaign has no senders: add at least one to senderIds; The sequence has no steps; ...",
  "details": {
    "issues": [
      { "code": "no_senders", "blocking": true, "message": "The campaign has no senders: add at least one to senderIds" },
      { "code": "no_steps", "blocking": true, "message": "The sequence has no steps" },
      { "code": "no_leads", "blocking": true, "message": "No leads: add leads to its lists or straight to the campaign (POST /v1/campaigns/{id}/leads)" }
    ]
  }
}

Validation failures answer 422 UNPROCESSABLE_CONTENT: message names the first problem in a sentence, and details.issues lists every one as { path, message, code }. Every body, query string and MCP argument object is strict: a field the API doesn't know is refused, never silently dropped, so a typo in an optional field fails loudly instead of changing what runs.

POST /v1/campaigns
{ "name": "Bad", "steps": [{ "type": "invite", "after": "1d" }] }

HTTP/1.1 422 Unprocessable Entity

{
  "errorCode": "UNPROCESSABLE_CONTENT",
  "message": "steps.0.after: Unknown field \"after\"",
  "details": {
    "issues": [
      { "path": "steps.0.after", "message": "Unknown field \"after\"", "code": "unrecognized_keys" }
    ]
  }
}

Idempotency

Every write (POST, PATCH, DELETE) accepts an Idempotency-Key header (at most 200 characters). The first successful answer for a key is stored for 24 hours, per caller, method and path, together with a hash of the body, and replayed for every retry with the same key and body, with an Idempotent-Replayed: true header. The same key with a different body is refused with 422 IDEMPOTENCY_KEY_REUSED_ERROR, so use a value that is unique per intended object, such as campaign-revops-de. Failed answers aren't stored: retrying after an error runs the request again.

Ids and times

Ids are prefixed strings, so you can tell what an id points to: org_ workspace, user_ user, key_ API key, snd_ sender, list_ list, lead_ lead, imp_ import, blk_ blocklist entry, cmp_ campaign, enr_ enrollment, act_ action, cnv_ conversation, msg_ message, evt_ event, whk_ webhook endpoint, whd_ webhook delivery, exp_ workspace export. Times are ISO 8601 in UTC (2026-10-28T12:51:07.282Z).

Endpoints

Paths are relative to https://api.getoutvoy.com. Every /v1 route accepts an API key or a session unless it says session only.

Account and workspace

Your data: export and deletion

The whole workspace leaves in one ZIP: a JSON file per kind of record (leads, lists and memberships, campaigns with their steps, enrollments, every action the engine took, conversations and messages, senders, blocklist, events, webhook endpoints, imports, API key names, billing, users), CSV copies of leads, lists and memberships, and a README.json that describes every file. Secrets are never in it: no password or key hashes, no webhook signing secrets, no LinkedIn sessions. Exporting everything and deleting the workspace are for workspace owners in a console session; agents read each resource through its own endpoint. To erase one contacted person, use DELETE /v1/leads/{leadId} (keys work).

Senders

Search

Lists, leads and imports

Blocklist

Campaigns and enrollments

Inbox

Events and webhooks

Outside /v1