Skip to documentation
Dashboard
Contacts

Update a contact

Change selected fields on a contact in your workspace.

PATCH/api/v1/contacts/{contactId}
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.

Path parameters

Path parameters
NameTypeRequirementDescription
contactIdUUIDRequiredID of the contact in your workspace.

Request body

Request fields
NameTypeRequirementDescription
emailstringOptionalValid email address, up to 320 characters.
consent_sourcestringWhen granting consentSource of the consent or subscription status, 3 to 240 characters. Required when subscribing or changing the email address of a subscribed contact.
first_name, last_namestringOptionalUp to 120 characters each. Use an empty string to clear a name.
statestringOptionalsubscribed, unsubscribed, or archived.
list_idsUUID[]OptionalUp to 100 workspace list IDs. Replaces existing memberships when supplied.
propertiesobjectOptionalUpdates supplied registered custom field values. Omit a key to retain its value or send null to clear it.

Response

Response fields
NameTypeRequirementDescription
objectstringAlwaysAlways contact.
idUUIDAlwaysThe contact ID.
emailstringAlwaysThe stored email address.
statestringAlwaysThe stored subscription state.

Partial updates

Supply at least one field to update. Omitted fields and list memberships keep their current values. Send an empty string to clear a name or an empty list_ids array to remove all memberships. A supplied list_ids array replaces the full membership set.

Adding a new list membership can trigger active Automations and real email delivery. Supply a fresh consent_source when subscribing a contact or changing the email address of a contact who will remain subscribed.

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.
404CONTACT_NOT_FOUNDThe contact does not exist in this workspace.Check the ID using List contacts.
422CONTACT_CONSENT_REQUIREDThe update needs a fresh source of consent.Supply consent_source documenting consent for the resulting subscription.