Contacts
Create a contact
Create a new contact in your workspace.
POST
/api/v1/contactsOn this page
Authentication
Send a RouteKite API key as a Bearer token. This endpoint requires the audience:write scope.
| Name | Type | Requirement | Description |
|---|---|---|---|
Authorization | string | Required | Bearer rk_ API key. The key determines the workspace. |
Content-Type | string | Required | application/json |
Idempotency-Key | string | Required | 8 to 200 characters. Reuse only when retrying the same operation with the same input. |
Request body
| Name | Type | Requirement | Description |
|---|---|---|---|
email | string | Required | Valid email address, up to 320 characters. |
consent_source | string | Required | Source of the consent or subscription status, 3 to 240 characters. |
first_name, last_name | string | Optional | Up to 120 characters each. Defaults to empty. |
state | string | Optional | subscribed, unsubscribed, or archived. Defaults to subscribed. Set the intended state explicitly. |
list_ids | UUID[] | Optional | Up to 100 workspace list IDs. Defaults to an empty array. |
properties | object | Optional | Values for registered custom fields when enabled. |
Response
| Name | Type | Requirement | Description |
|---|---|---|---|
object | string | Always | Always contact. |
id | UUID | Always | The contact ID. |
email | string | Always | The stored email address. |
state | string | Always | The stored subscription state. |
Create behavior
Creating a contact requires an email address and a consent source. If the workspace already has a contact with the same normalized email address, the request returns 409.
A new list membership can trigger active Automations and real email delivery.
Writes and retries
The API key must have been created by a current workspace member. Use a unique Idempotency-Key for each intended write. Reuse it only when retrying the same operation with the same input.
Errors
| Status | Code | What it means | What to do |
|---|---|---|---|
| 400 | INVALID_REQUEST | One or more request fields are invalid. | Correct the request and retry. |
| 401 | UNAUTHORIZED | The API key is missing or invalid. | Send a valid Bearer API key. |
| 403 | FORBIDDEN | The key does not have the required scope. | Use a key with the scope shown above. |
| 429 | RATE_LIMITED | The API key or workspace has reached its request limit. | Wait for the Retry-After interval before retrying. |
| 503 | RATE_LIMIT_UNAVAILABLE | RouteKite could not check request limits. | Retry shortly. |
| 500 | INTERNAL_ERROR | RouteKite could not complete the contact operation. | Retry shortly. Reuse the same Idempotency-Key for write retries. |
| 400 | IDEMPOTENCY_KEY_REQUIRED | The write needs a stable idempotency key. | Send an Idempotency-Key of 8 to 200 characters. |
| 403 | API_KEY_ACTOR_UNAVAILABLE | The API key has no current workspace member as its creator. | Use a key created by a current member. |
| 409 | IDEMPOTENCY_CONFLICT | This idempotency key was used with different input. | Reuse the original input for a retry. Use a new key for a new write. |
| 409 | OPERATION_IN_PROGRESS | An identical write is already in progress. | Retry shortly with the same key and input. |
| 503 | OPERATION_UNAVAILABLE | RouteKite could not complete the write. | Retry with the same key and input. |
| 400 | INVALID_JSON | The request body could not be read as JSON. | Send a valid JSON object. |
| 409 | CONTACT_EMAIL_CONFLICT | A contact in this workspace already uses the email address. | Use another address or update the existing contact by ID. |
| 413 | PAYLOAD_TOO_LARGE | The JSON body exceeds the 128,000-byte request size limit. | Reduce the request size. |
| 409 | PLAN_CONTACT_LIMIT_REACHED | The operation would exceed the account's marketing contact limit. | Review your current contact usage and plan allowance. |
| 403 | BILLING_ACCOUNT_RESTRICTED | The billing account cannot increase its marketing contact usage. | Review the account status before retrying. |
| 422 | CONTACT_SAVE_FAILED | The contact could not be saved. | Check the contact values, list IDs, and custom fields. |
| 503 | FEATURE_UNAVAILABLE | Custom contact fields are unavailable for this workspace. | Retry without properties or check workspace availability. |