---
title: "Forms API"
description: "Forms in the OneSend API: 9 endpoints. Hosted signup forms with double opt-in, embed code and submissions."
url: https://onesend.email/docs/api-reference/forms/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/docs/api-reference/)

# Forms

Hosted signup forms with double opt-in, embed code and submissions.

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 signup forms

GET `/v1/forms`

Each form includes submission and confirmation counts and its public URLs.

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

### Responses

`200` Success

```
{
  "data": [{
    "id": string,
    "object": "form",
    "name": string,
    "status": "active" | "disabled",
    "fields": [{ … }],
    "listIds": [string],
    "consentText": string or null,
    "consentVersion": number,
    "doubleOptIn": boolean,
    "successMessage": string or null,
    "redirectUrl": string or null,
    "fromName": string or null,
    "fromEmail": string or null,
    "replyTo": string or null,
    "confirmation": {
      "subject": string,
      "heading": string,
      "body": string,
      "buttonLabel": string
    },
    "welcomeTemplateId": string or null,
    "style": {
      "primary": string,
      "background": string,
      "text": string,
      "font": string,
      "logoUrl": string,
      "title": string,
      "description": string,
      "buttonLabel": string,
      "useBrand": boolean
    },
    "allowedOrigins": [string],
    "stats": {
      "submissions": number,
      "confirmations": number,
      "pending": number,
      "confirmationRate": number or null
    },
    "urls": {
      "hosted": string,
      "submit": string,
      "script": string
    },
    "createdAt": string,
    "updatedAt": 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`)

## Create a signup form

POST `/v1/forms`

Double opt-in is on unless `doubleOptIn: false`. The response includes the hosted page URL; `GET /v1/forms/{id}/embed` returns the embed code.

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `name`required | `string` |  |
| `status` | `"active" \| "disabled"` |  |
| `fields` | `array of object` | At most 20 items. |
| `fields[].key`required | `string` | Contact attribute key (`first_name`, `company`, …). `email` is always present and is not listed here. |
| `fields[].label`required | `string` |  |
| `fields[].type` | `"text" \| "number" \| "date" \| "boolean" \| "category" \| "email"` | Default "text". |
| `fields[].required` | `boolean` |  |
| `fields[].placeholder` | `string or null` |  |
| `fields[].options` | `array of string or null` | Choices for `category` fields. At most 50 items. |
| `listIds` | `array of string` | Lists a contact is added to when they subscribe (after confirming, with double opt-in). At most 20 items. |
| `consentText` | `string or null` | Shown next to a required checkbox. Changing it starts a new consent version. |
| `doubleOptIn` | `boolean` | Default true: new contacts stay `pending` until they confirm by email. |
| `successMessage` | `string or null` |  |
| `redirectUrl` | `string (uri) or null` | After a successful submit, go here instead of showing the success message (http or https). |
| `fromName` | `string or null` |  |
| `fromEmail` | `string (email) or null` | Sender of the confirmation and welcome email. Defaults to no-reply@ your first verified domain. |
| `replyTo` | `string (email) or null` |  |
| `confirmation` | `object or null` |  |
| `confirmation.subject` | `string` |  |
| `confirmation.heading` | `string` |  |
| `confirmation.body` | `string` | Plain text; blank lines separate paragraphs. `{{ form_name }}` and `{{ workspace_name }}` are available. |
| `confirmation.buttonLabel` | `string` |  |
| `welcomeTemplateId` | `string or null` | Template sent once the contact is subscribed. |
| `style` | `object` |  |
| `style.primary` | `string` |  |
| `style.background` | `string` |  |
| `style.text` | `string` |  |
| `style.font` | `string` |  |
| `style.logoUrl` | `string` |  |
| `style.title` | `string` |  |
| `style.description` | `string` |  |
| `style.buttonLabel` | `string` |  |
| `style.useBrand` | `boolean` | Use the workspace brand (logo, colors, font) for values not set here. Default true. |
| `allowedOrigins` | `array of string` | Websites allowed to post this form (for example `https://www.example.com`). Empty: any site. At most 20 items. |

### Responses

`201` Success

```
{
  "id": string,
  "object": "form",
  "name": string,
  "status": "active" | "disabled",
  "fields": [{
    "key": string,
    "label": string,
    "type": "text" | "number" | "date" | "boolean" | "category" | "email",
    "required": boolean,
    "placeholder": string or null,
    "options": [string] or null
  }],
  "listIds": [string],
  "consentText": string or null,
  "consentVersion": number,
  "doubleOptIn": boolean,
  "successMessage": string or null,
  "redirectUrl": string or null,
  "fromName": string or null,
  "fromEmail": string or null,
  "replyTo": string or null,
  "confirmation": {
    "subject": string,
    "heading": string,
    "body": string,
    "buttonLabel": string
  },
  "welcomeTemplateId": string or null,
  "style": {
    "primary": string,
    "background": string,
    "text": string,
    "font": string,
    "logoUrl": string,
    "title": string,
    "description": string,
    "buttonLabel": string,
    "useBrand": boolean
  },
  "allowedOrigins": [string],
  "stats": {
    "submissions": number,
    "confirmations": number,
    "pending": number,
    "confirmationRate": number or null
  },
  "urls": {
    "hosted": string,
    "submit": string,
    "script": string
  },
  "createdAt": string,
  "updatedAt": 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`)

## Preview a form

POST `/v1/forms/preview`

The hosted page HTML for unsaved settings (for a live preview). Nothing is stored.

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `name` | `string` |  |
| `status` | `"active" \| "disabled"` |  |
| `fields` | `array of object` | At most 20 items. |
| `fields[].key`required | `string` | Contact attribute key (`first_name`, `company`, …). `email` is always present and is not listed here. |
| `fields[].label`required | `string` |  |
| `fields[].type` | `"text" \| "number" \| "date" \| "boolean" \| "category" \| "email"` | Default "text". |
| `fields[].required` | `boolean` |  |
| `fields[].placeholder` | `string or null` |  |
| `fields[].options` | `array of string or null` | Choices for `category` fields. At most 50 items. |
| `listIds` | `array of string` | Lists a contact is added to when they subscribe (after confirming, with double opt-in). At most 20 items. |
| `consentText` | `string or null` | Shown next to a required checkbox. Changing it starts a new consent version. |
| `doubleOptIn` | `boolean` | Default true: new contacts stay `pending` until they confirm by email. |
| `successMessage` | `string or null` |  |
| `redirectUrl` | `string (uri) or null` | After a successful submit, go here instead of showing the success message (http or https). |
| `fromName` | `string or null` |  |
| `fromEmail` | `string (email) or null` | Sender of the confirmation and welcome email. Defaults to no-reply@ your first verified domain. |
| `replyTo` | `string (email) or null` |  |
| `confirmation` | `object or null` |  |
| `confirmation.subject` | `string` |  |
| `confirmation.heading` | `string` |  |
| `confirmation.body` | `string` | Plain text; blank lines separate paragraphs. `{{ form_name }}` and `{{ workspace_name }}` are available. |
| `confirmation.buttonLabel` | `string` |  |
| `welcomeTemplateId` | `string or null` | Template sent once the contact is subscribed. |
| `style` | `object` |  |
| `style.primary` | `string` |  |
| `style.background` | `string` |  |
| `style.text` | `string` |  |
| `style.font` | `string` |  |
| `style.logoUrl` | `string` |  |
| `style.title` | `string` |  |
| `style.description` | `string` |  |
| `style.buttonLabel` | `string` |  |
| `style.useBrand` | `boolean` | Use the workspace brand (logo, colors, font) for values not set here. Default true. |
| `allowedOrigins` | `array of string` | Websites allowed to post this form (for example `https://www.example.com`). Empty: any site. At most 20 items. |

### Responses

`200` Success

```
{
  "html": 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`)

## Get a signup form

GET `/v1/forms/{id}`

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

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success

```
{
  "id": string,
  "object": "form",
  "name": string,
  "status": "active" | "disabled",
  "fields": [{
    "key": string,
    "label": string,
    "type": "text" | "number" | "date" | "boolean" | "category" | "email",
    "required": boolean,
    "placeholder": string or null,
    "options": [string] or null
  }],
  "listIds": [string],
  "consentText": string or null,
  "consentVersion": number,
  "doubleOptIn": boolean,
  "successMessage": string or null,
  "redirectUrl": string or null,
  "fromName": string or null,
  "fromEmail": string or null,
  "replyTo": string or null,
  "confirmation": {
    "subject": string,
    "heading": string,
    "body": string,
    "buttonLabel": string
  },
  "welcomeTemplateId": string or null,
  "style": {
    "primary": string,
    "background": string,
    "text": string,
    "font": string,
    "logoUrl": string,
    "title": string,
    "description": string,
    "buttonLabel": string,
    "useBrand": boolean
  },
  "allowedOrigins": [string],
  "stats": {
    "submissions": number,
    "confirmations": number,
    "pending": number,
    "confirmationRate": number or null
  },
  "urls": {
    "hosted": string,
    "submit": string,
    "script": string
  },
  "createdAt": string,
  "updatedAt": string
}
```

**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`)

## Update a signup form

PATCH `/v1/forms/{id}`

Changing `consentText` increases `consentVersion`; consent proof records the version each contact agreed to.

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

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `name` | `string` |  |
| `status` | `"active" \| "disabled"` |  |
| `fields` | `array of object` | At most 20 items. |
| `fields[].key`required | `string` | Contact attribute key (`first_name`, `company`, …). `email` is always present and is not listed here. |
| `fields[].label`required | `string` |  |
| `fields[].type` | `"text" \| "number" \| "date" \| "boolean" \| "category" \| "email"` | Default "text". |
| `fields[].required` | `boolean` |  |
| `fields[].placeholder` | `string or null` |  |
| `fields[].options` | `array of string or null` | Choices for `category` fields. At most 50 items. |
| `listIds` | `array of string` | Lists a contact is added to when they subscribe (after confirming, with double opt-in). At most 20 items. |
| `consentText` | `string or null` | Shown next to a required checkbox. Changing it starts a new consent version. |
| `doubleOptIn` | `boolean` | Default true: new contacts stay `pending` until they confirm by email. |
| `successMessage` | `string or null` |  |
| `redirectUrl` | `string (uri) or null` | After a successful submit, go here instead of showing the success message (http or https). |
| `fromName` | `string or null` |  |
| `fromEmail` | `string (email) or null` | Sender of the confirmation and welcome email. Defaults to no-reply@ your first verified domain. |
| `replyTo` | `string (email) or null` |  |
| `confirmation` | `object or null` |  |
| `confirmation.subject` | `string` |  |
| `confirmation.heading` | `string` |  |
| `confirmation.body` | `string` | Plain text; blank lines separate paragraphs. `{{ form_name }}` and `{{ workspace_name }}` are available. |
| `confirmation.buttonLabel` | `string` |  |
| `welcomeTemplateId` | `string or null` | Template sent once the contact is subscribed. |
| `style` | `object` |  |
| `style.primary` | `string` |  |
| `style.background` | `string` |  |
| `style.text` | `string` |  |
| `style.font` | `string` |  |
| `style.logoUrl` | `string` |  |
| `style.title` | `string` |  |
| `style.description` | `string` |  |
| `style.buttonLabel` | `string` |  |
| `style.useBrand` | `boolean` | Use the workspace brand (logo, colors, font) for values not set here. Default true. |
| `allowedOrigins` | `array of string` | Websites allowed to post this form (for example `https://www.example.com`). Empty: any site. At most 20 items. |

### Responses

`200` Success

```
{
  "id": string,
  "object": "form",
  "name": string,
  "status": "active" | "disabled",
  "fields": [{
    "key": string,
    "label": string,
    "type": "text" | "number" | "date" | "boolean" | "category" | "email",
    "required": boolean,
    "placeholder": string or null,
    "options": [string] or null
  }],
  "listIds": [string],
  "consentText": string or null,
  "consentVersion": number,
  "doubleOptIn": boolean,
  "successMessage": string or null,
  "redirectUrl": string or null,
  "fromName": string or null,
  "fromEmail": string or null,
  "replyTo": string or null,
  "confirmation": {
    "subject": string,
    "heading": string,
    "body": string,
    "buttonLabel": string
  },
  "welcomeTemplateId": string or null,
  "style": {
    "primary": string,
    "background": string,
    "text": string,
    "font": string,
    "logoUrl": string,
    "title": string,
    "description": string,
    "buttonLabel": string,
    "useBrand": boolean
  },
  "allowedOrigins": [string],
  "stats": {
    "submissions": number,
    "confirmations": number,
    "pending": number,
    "confirmationRate": number or null
  },
  "urls": {
    "hosted": string,
    "submit": string,
    "script": string
  },
  "createdAt": string,
  "updatedAt": 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`)

## Delete a signup form

DELETE `/v1/forms/{id}`

Contacts who signed up are kept. Pending confirmation links stop working.

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

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`204` No content

**Errors: 400, 401, 403, 404, 409, 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`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Embed code for a form

GET `/v1/forms/{id}/embed`

`html` is a plain HTML form that works without JavaScript. Add `script` after it to show the result in place instead of on the hosted page.

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

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`200` Success

```
{
  "hostedUrl": string,
  "html": string,
  "script": string,
  "htmlWithScript": string
}
```

**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`)

## List form submissions

GET `/v1/forms/{id}/submissions`

Newest first. Filter by `status` (comma-separated): `pending`, `confirmed`, `subscribed`, `already_subscribed`, `rejected`.

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

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |
| `status` | query | `string` |  |
| `limit` | query | `integer` | Default 100. 1 to 500. |

### Responses

`200` Success

```
{
  "data": [{
    "id": string,
    "object": "form_submission",
    "formId": string,
    "contactId": string or null,
    "email": string,
    "status": "pending" | "confirmed" | "subscribed" | "already_subscribed" | "rejected",
    "consentVersion": number or null,
    "createdAt": string,
    "confirmedAt": string or null,
    "confirmationError": {
      "code": string,
      "message": string,
      "at": 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`)

## Submit a form from your server

POST `/v1/forms/{id}/submissions`

Same rules as the hosted form: with double opt-in the contact is `pending` until they confirm by email. Pass the subscriber’s `ip` and `userAgent` to include them in the consent proof (the IP is stored only as a hash).

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

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `email`required | `string (email)` |  |
| `firstName` | `string` |  |
| `lastName` | `string` |  |
| `attributes` | `object` | Values for the form fields, by attribute key. |
| `consent` | `boolean` | Required (true) when the form has consent text. |
| `ip` | `string` | The subscriber’s IP address, stored only as a hash in the consent proof. |
| `userAgent` | `string` |  |

### Responses

`202` Success

```
{
  "status": "pending" | "subscribed" | "already_subscribed" | "ignored",
  "submissionId": string or null
}
```

**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`)
