Skip to documentation
Dashboard
Contacts

Create a contact

Create a new contact in your workspace.

POST/api/v1/contacts
On this page

Authentication

Send a RouteKite API key as a Bearer token. This endpoint requires the audience:write scope.

Required headers
NameTypeRequirementDescription
AuthorizationstringRequiredBearer rk_ API key. The key determines the workspace.
Content-TypestringRequiredapplication/json
Idempotency-KeystringRequired8 to 200 characters. Reuse only when retrying the same operation with the same input.

Request body

Request fields
NameTypeRequirementDescription
emailstringRequiredValid email address, up to 320 characters.
consent_sourcestringRequiredSource of the consent or subscription status, 3 to 240 characters.
first_name, last_namestringOptionalUp to 120 characters each. Defaults to empty.
statestringOptionalsubscribed, unsubscribed, or archived. Defaults to subscribed. Set the intended state explicitly.
list_idsUUID[]OptionalUp to 100 workspace list IDs. Defaults to an empty array.
propertiesobjectOptionalValues for registered custom fields when enabled.

Response

Response fields
NameTypeRequirementDescription
objectstringAlwaysAlways contact.
idUUIDAlwaysThe contact ID.
emailstringAlwaysThe stored email address.
statestringAlwaysThe 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

StatusCodeWhat it meansWhat to do
400INVALID_REQUESTOne or more request fields are invalid.Correct the request and retry.
401UNAUTHORIZEDThe API key is missing or invalid.Send a valid Bearer API key.
403FORBIDDENThe key does not have the required scope.Use a key with the scope shown above.
429RATE_LIMITEDThe API key or workspace has reached its request limit.Wait for the Retry-After interval before retrying.
503RATE_LIMIT_UNAVAILABLERouteKite could not check request limits.Retry shortly.
500INTERNAL_ERRORRouteKite could not complete the contact operation.Retry shortly. Reuse the same Idempotency-Key for write retries.
400IDEMPOTENCY_KEY_REQUIREDThe write needs a stable idempotency key.Send an Idempotency-Key of 8 to 200 characters.
403API_KEY_ACTOR_UNAVAILABLEThe API key has no current workspace member as its creator.Use a key created by a current member.
409IDEMPOTENCY_CONFLICTThis idempotency key was used with different input.Reuse the original input for a retry. Use a new key for a new write.
409OPERATION_IN_PROGRESSAn identical write is already in progress.Retry shortly with the same key and input.
503OPERATION_UNAVAILABLERouteKite could not complete the write.Retry with the same key and input.
400INVALID_JSONThe request body could not be read as JSON.Send a valid JSON object.
409CONTACT_EMAIL_CONFLICTA contact in this workspace already uses the email address.Use another address or update the existing contact by ID.
413PAYLOAD_TOO_LARGEThe JSON body exceeds the 128,000-byte request size limit.Reduce the request size.
409PLAN_CONTACT_LIMIT_REACHEDThe operation would exceed the account's marketing contact limit.Review your current contact usage and plan allowance.
403BILLING_ACCOUNT_RESTRICTEDThe billing account cannot increase its marketing contact usage.Review the account status before retrying.
422CONTACT_SAVE_FAILEDThe contact could not be saved.Check the contact values, list IDs, and custom fields.
503FEATURE_UNAVAILABLECustom contact fields are unavailable for this workspace.Retry without properties or check workspace availability.