---
title: "Contacts API"
description: "Contacts in the OneSend API: 13 endpoints. Contacts and their attributes. Emails are unique per workspace (stored lowercased)."
url: https://onesend.email/docs/api-reference/contacts/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/docs/api-reference/)

# Contacts

Contacts and their attributes. Emails are unique per workspace (stored lowercased).

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 contact attributes

GET `/v1/contact-attributes`

System attributes (email, first\_name, last\_name, phone) are always present.

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

### Responses

`200` Success

```
{
  "data": [{
    "key": string,
    "label": string,
    "type": "text" | "number" | "date" | "boolean" | "category",
    "options": [string],
    "system": boolean
  }]
}
```

**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 contact attribute

POST `/v1/contact-attributes`

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `key`required | `string` |  |
| `label`required | `string` |  |
| `type`required | `"text" \| "number" \| "date" \| "boolean" \| "category"` |  |
| `options` | `array of string` |  |

### Responses

`201` Success

```
{
  "key": string,
  "label": string,
  "type": "text" | "number" | "date" | "boolean" | "category",
  "options": [string],
  "system": boolean
}
```

**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 contact attribute

DELETE `/v1/contact-attributes/{key}`

Values already stored on contacts are kept.

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

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `key`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`)

## List contacts

GET `/v1/contacts`

`cursor` is a row offset: pass back `nextCursor` unchanged. `total` is the number of matching contacts.

**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. |
| `q` | query | `string` |  |
| `listId` | query | `string` |  |
| `segmentId` | query | `string` |  |
| `status` | query | `string` |  |
| `quality` | query | `string` | Comma separated address quality values (ok, invalid, typo, no\_mx, disposable, role, unchecked). |

### Responses

`200` Success

```
{
  "data": [{
    "id": string,
    "object": "contact",
    "email": string,
    "firstName": string or null,
    "lastName": string or null,
    "phone": string or null,
    "attributes": object,
    "listIds": [string],
    "status": "subscribed" | "unsubscribed" | "bounced" | "complained" | "pending" | "inactive",
    "source": "import" | "api" | "form" | "manual" | null,
    "engagement": {
      "lastOpenedAt": string or null,
      "lastClickedAt": string or null,
      "campaignsReceived": number,
      "opens": number,
      "clicks": number
    },
    "quality": "ok" | "invalid" | "typo" | "no_mx" | "disposable" | "role" | null,
    "qualitySuggestion": string or null,
    "sunsetState": "reengage_sent" | "inactive" | null,
    "consent": {
      "method": "double_opt_in" | "single_opt_in" | "import" | "api",
      "formId": string or null,
      "submissionId": string or null,
      "importId": string or null,
      "submittedAt": string or null,
      "confirmedAt": string or null,
      "ipHash": string or null,
      "userAgent": string or null,
      "consentText": string or null,
      "consentVersion": number or null,
      "confirmedElsewhere": boolean
    },
    "createdAt": string,
    "updatedAt": string
  }],
  "nextCursor": string or null,
  "total": number
}
```

**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 or update a contact (by email)

POST `/v1/contacts`

Attributes are merged; `null` removes one. `listIds` are added to existing memberships.

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `email`required | `string (email)` | Unique per workspace; stored lowercased. Creating an existing email updates that contact. |
| `firstName` | `string or null` | Available in templates as `{{first_name}}`. |
| `lastName` | `string or null` | Available in templates as `{{last_name}}`. |
| `phone` | `string or null` |  |
| `attributes` | `object` | Custom attributes by key, for example `{ "plan": "pro" }`. Available in templates as `{{plan}}` or `{{contact.plan}}`. Keys you have not created under contact attributes are stored, but not exported or offered in the segment builder. |
| `listIds` | `array of string` | Lists to add the contact to. |
| `status` | `"subscribed" \| "unsubscribed" \| "bounced" \| "complained" \| "pending" \| "inactive"` | Defaults to `subscribed`. |

### Responses

`201` Success

```
{
  "id": string,
  "object": "contact",
  "email": string,
  "firstName": string or null,
  "lastName": string or null,
  "phone": string or null,
  "attributes": object,
  "listIds": [string],
  "status": "subscribed" | "unsubscribed" | "bounced" | "complained" | "pending" | "inactive",
  "source": "import" | "api" | "form" | "manual" | null,
  "engagement": {
    "lastOpenedAt": string or null,
    "lastClickedAt": string or null,
    "campaignsReceived": number,
    "opens": number,
    "clicks": number
  },
  "quality": "ok" | "invalid" | "typo" | "no_mx" | "disposable" | "role" | null,
  "qualitySuggestion": string or null,
  "sunsetState": "reengage_sent" | "inactive" | null,
  "consent": {
    "method": "double_opt_in" | "single_opt_in" | "import" | "api",
    "formId": string or null,
    "submissionId": string or null,
    "importId": string or null,
    "submittedAt": string or null,
    "confirmedAt": string or null,
    "ipHash": string or null,
    "userAgent": string or null,
    "consentText": string or null,
    "consentVersion": number or null,
    "confirmedElsewhere": boolean
  },
  "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`)

## Bulk actions on contacts

POST `/v1/contacts/bulk`

Actions: `add_to_list` / `remove_from_list` (with `listId` or `listIds`), `unsubscribe`, `resubscribe` (only contacts that unsubscribed, never bounced or complained ones), `delete`.

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

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `ids`required | `array of string` | At most 10000 items. |
| `action`required | `"add_to_lists" \| "remove_from_lists" \| "add_to_list" \| "remove_from_list" \| "unsubscribe" \| "resubscribe" \| "delete"` |  |
| `listIds` | `array of string` |  |
| `listId` | `string` |  |

### Responses

`200` Success

```
{
  "updated": number,
  "affected": number
}
```

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

## Export contacts as CSV (streamed)

GET `/v1/contacts/export`

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

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `format` | query | `"csv"` | Default "csv". |
| `listId` | query | `string` |  |
| `segmentId` | query | `string` |  |
| `status` | query | `string` |  |
| `q` | query | `string` |  |

### Responses

`200` Success (text/csv)

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

## Get a contact

GET `/v1/contacts/{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": "contact",
  "email": string,
  "firstName": string or null,
  "lastName": string or null,
  "phone": string or null,
  "attributes": object,
  "listIds": [string],
  "status": "subscribed" | "unsubscribed" | "bounced" | "complained" | "pending" | "inactive",
  "source": "import" | "api" | "form" | "manual" | null,
  "engagement": {
    "lastOpenedAt": string or null,
    "lastClickedAt": string or null,
    "campaignsReceived": number,
    "opens": number,
    "clicks": number
  },
  "quality": "ok" | "invalid" | "typo" | "no_mx" | "disposable" | "role" | null,
  "qualitySuggestion": string or null,
  "sunsetState": "reengage_sent" | "inactive" | null,
  "consent": {
    "method": "double_opt_in" | "single_opt_in" | "import" | "api",
    "formId": string or null,
    "submissionId": string or null,
    "importId": string or null,
    "submittedAt": string or null,
    "confirmedAt": string or null,
    "ipHash": string or null,
    "userAgent": string or null,
    "consentText": string or null,
    "consentVersion": number or null,
    "confirmedElsewhere": boolean
  },
  "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 contact

PATCH `/v1/contacts/{id}`

Attributes are merged (`null` removes one). `listIds`, when given, replaces the contact’s list memberships. Setting `status: "subscribed"` resubscribes an unsubscribed contact.

**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` | `string (email)` | Unique per workspace; stored lowercased. Creating an existing email updates that contact. |
| `firstName` | `string or null` | Available in templates as `{{first_name}}`. |
| `lastName` | `string or null` | Available in templates as `{{last_name}}`. |
| `phone` | `string or null` |  |
| `attributes` | `object` | Custom attributes by key, for example `{ "plan": "pro" }`. Available in templates as `{{plan}}` or `{{contact.plan}}`. Keys you have not created under contact attributes are stored, but not exported or offered in the segment builder. |
| `listIds` | `array of string` | Lists to add the contact to. |
| `status` | `"subscribed" \| "unsubscribed" \| "bounced" \| "complained" \| "pending" \| "inactive"` | Defaults to `subscribed`. |

### Responses

`200` Success

```
{
  "id": string,
  "object": "contact",
  "email": string,
  "firstName": string or null,
  "lastName": string or null,
  "phone": string or null,
  "attributes": object,
  "listIds": [string],
  "status": "subscribed" | "unsubscribed" | "bounced" | "complained" | "pending" | "inactive",
  "source": "import" | "api" | "form" | "manual" | null,
  "engagement": {
    "lastOpenedAt": string or null,
    "lastClickedAt": string or null,
    "campaignsReceived": number,
    "opens": number,
    "clicks": number
  },
  "quality": "ok" | "invalid" | "typo" | "no_mx" | "disposable" | "role" | null,
  "qualitySuggestion": string or null,
  "sunsetState": "reengage_sent" | "inactive" | null,
  "consent": {
    "method": "double_opt_in" | "single_opt_in" | "import" | "api",
    "formId": string or null,
    "submissionId": string or null,
    "importId": string or null,
    "submittedAt": string or null,
    "confirmedAt": string or null,
    "ipHash": string or null,
    "userAgent": string or null,
    "consentText": string or null,
    "consentVersion": number or null,
    "confirmedElsewhere": boolean
  },
  "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 contact

DELETE `/v1/contacts/{id}`

Removes the contact and its list memberships. Suppressions are kept, so a deleted address that bounced stays blocked. With `erase=true` (GDPR erasure), the address is also removed from messages, events, campaign recipients, clicks, conversions, form submissions and received mail, and a suppression keyed by a hash of the address keeps the person from being mailed again. See docs/privacy.md.

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

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |
| `erase` | query | `"true" \| "false"` |  |

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

## Contact activity timeline

GET `/v1/contacts/{id}/activity`

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

### Parameters

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

### Responses

`200` Success

```
{
  "data": [{
    "type": "sent" | "delivered" | "opened" | "clicked" | "bounced" | "unsubscribed" | "complained" | "converted" | "added_to_list" | "imported",
    "campaignId": string or null,
    "campaignName": string or null,
    "messageId": string or null,
    "detail": string or null,
    "occurredAt": 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`)

## Automations a contact went through

GET `/v1/contacts/{id}/journeys`

Runs (newest first) with each step the contact passed, and the contact's recent tracked events.

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

### Parameters

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

### Responses

`200` Success

```
{
  "data": [{
    "id": string,
    "object": "automation_run",
    "automationId": string,
    "automationName": string or null,
    "version": number,
    "contactId": string,
    "email": string or null,
    "status": "active" | "waiting" | "completed" | "exited" | "failed" | "canceled",
    "stepId": string or null,
    "waitingFor": "wait" | "event" | "quiet_hours" | "frequency_cap" | null,
    "nextRunAt": string or null,
    "exitReason": string or null,
    "lastError": string or null,
    "test": boolean,
    "emailsSent": number,
    "goalReachedAt": string or null,
    "enteredAt": string,
    "completedAt": string or null,
    "steps": [{ … }]
  }],
  "events": [{
    "id": string,
    "name": string,
    "properties": object,
    "occurredAt": 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`)

## Export a contact's data (GDPR)

GET `/v1/contacts/{id}/export`

Everything stored about one person in this workspace, as JSON: the contact, lists, suppression, campaign deliveries, messages, events, clicks, conversions, form submissions and mail received from the address. To erase the person, use DELETE /v1/contacts/{id}?erase=true.

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

### Parameters

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

### Responses

`200` Success

```
object
```

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