Docs / API reference

Conversions

Credit purchases, sign-ups and other goals to the email that drove them.

Base URL https://your-server.example (your OneSend server). Authentication and errors are described in the overview.

List conversions

GET /v1/conversions

Authentication: Authorization: Bearer with an API key or a session token.

Parameters

NameInTypeDescription
cursorquerystring
limitqueryintegerDefault 50. 1 to 200.
campaignIdquerystring

Responses

200 Success

{
  "data": [{
    "id": string,
    "goal": string,
    "value": number or null,
    "currency": string or null,
    "contactId": string or null,
    "email": string or null,
    "campaignId": string or null,
    "messageId": string or null,
    "attributedBy": "token" | "message" | "email" | "none",
    "occurredAt": string
  }],
  "nextCursor": string or null
}
Errors: 400, 401, 403, 404, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Record a conversion

POST /v1/conversions

Attribution: token (the os_ct query parameter added to tracked links) → messageId → email (the most recent campaign click by that address within the attribution window, 7 days by default). Send idempotencyKey (e.g. your order id) to make retries safe.

Authentication: Authorization: Bearer with an API key or a session token.

Request body

application/json, required.

FieldTypeDescription
tokenstringThe os_ct query parameter added to tracked links. Best attribution.
messageIdstringCredit a specific email.
emailstring (email)Credit the most recent campaign click by this address within the attribution window.
campaignIdstringWith email: only consider this campaign.
goalstringWhat happened, for example purchase or signup. Default "conversion".
valuenumberRevenue, at most 1,000,000,000. 0 to 1000000000.
currencystringISO currency, for example USD.
occurredAtstringWhen it happened (ISO 8601). Defaults to now.
idempotencyKeystringFor example your order id: a retry with the same key is not counted twice.

Responses

201 Success

{
  "id": string,
  "goal": string,
  "value": number or null,
  "currency": string or null,
  "contactId": string or null,
  "email": string or null,
  "campaignId": string or null,
  "messageId": string or null,
  "attributedBy": "token" | "message" | "email" | "none",
  "occurredAt": string
}
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)