---
title: "Conversions API"
description: "Conversions in the OneSend API: 2 endpoints. Credit purchases, sign-ups and other goals to the email that drove them."
url: https://onesend.email/docs/api-reference/conversions/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/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](https://onesend.email/docs/api-reference/#authentication) and errors are described in the [overview](https://onesend.email/docs/api-reference/).

## List conversions

GET `/v1/conversions`

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

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `cursor` | query | `string` |  |
| `limit` | query | `integer` | Default 50. 1 to 200. |
| `campaignId` | query | `string` |  |

### 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.

| Field | Type | Description |
|---|---|---|
| `token` | `string` | The `os_ct` query parameter added to tracked links. Best attribution. |
| `messageId` | `string` | Credit a specific email. |
| `email` | `string (email)` | Credit the most recent campaign click by this address within the attribution window. |
| `campaignId` | `string` | With `email`: only consider this campaign. |
| `goal` | `string` | What happened, for example `purchase` or `signup`. Default "conversion". |
| `value` | `number` | Revenue, at most 1,000,000,000. 0 to 1000000000. |
| `currency` | `string` | ISO currency, for example USD. |
| `occurredAt` | `string` | When it happened (ISO 8601). Defaults to now. |
| `idempotencyKey` | `string` | For 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`)
