email-contacts

Update a contact

Updates a contact. Supplied fields are changed and omitted fields are left unchanged; set first_name, last_name, or external_id to null to clear them. Custom values in data are merged: keys you supply are set, keys set to null are removed, and keys you omit are unchanged.

Changing the email address, phone number, or external_id to a value already used by another contact returns a conflict error. A contact always keeps at least one identifier. Clearing both email and phone in the same contact is rejected.

patch/v1/contacts/{contact_id}

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/contacts/{contact_id}
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Path parameters

contact_idstring required
Example:con_01krdgeqcxet5s7t44vh8rt9mg

ID of the contact to update.

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Request body

emailstring email nullable

New email address for the contact. Trimmed and lowercased before it is stored and checked for uniqueness. Must not be in use by another contact in the workspace. Omit to keep the current address; set to null to remove it, as long as the contact keeps at least one identifier.

phone_numberstring nullable

New phone number for the contact, in E.164 format with the leading + and country code. Spaces and punctuation are accepted and stripped. Stored in its canonical form, which may differ from what you send, and unique within the workspace. Omit to keep the current number; set to null to remove it, as long as the contact keeps at least one identifier. An empty string behaves as null.

first_namestring nullable

The contact's first name. Set to null to clear.

last_namestring nullable

The contact's last name. Set to null to clear.

external_idstring nullable

Your own identifier for this contact. Unique within the workspace when set. Set to null to clear.

dataobject

Custom property values to merge into the contact's existing data. Supplied keys are set, keys with a null value are removed, and omitted keys remain unchanged. Each key must be a registered contact property, including an archived one. Each value must match the property's declared type: string, number, boolean, or RFC 3339 datetime. Strings can contain up to 500 characters. An unregistered key returns a validation error. The serialized result is limited to 2 KB.

Example request

{
  "first_name": "Alice",
  "last_name": "Anderson"
}

Response

The updated contact.

idstring required
emailstring email nullable required

The contact's email address, in its stored form, trimmed and lowercased before uniqueness is checked. Unique within the workspace. null when the contact has no email address.

phone_numberstring nullable required

The contact's phone number in normalized international form: a leading + and four to 15 digits. We normalize formatting but do not verify the number against numbering-plan metadata. The number is unique within the workspace. Because carriers recycle disconnected numbers, use external_id as the durable key for your own records. null when the contact has no phone number.

first_namestring nullable

The contact's first name. Available in broadcast templates as bird.contact.first_name.

last_namestring nullable

The contact's last name. Available in broadcast templates as bird.contact.last_name.

external_idstring nullable

Your own identifier for this contact, such as a user ID in your system. Unique within the workspace when set.

dataobject

Custom property values for this contact, available in broadcast templates as bird.contact.<key>. Each key is a property created via the contact properties API, and each value is a string, number, boolean, or RFC 3339 datetime matching the property's declared type (strings up to 500 characters). Total size is capped at 2 KB serialized. Values stored under a property that was later archived remain readable here.

created_atstring date-time required
updated_atstring date-time required

Example response

{
  "id": "con_01krdgeqcxet5s7t44vh8rt9mg",
  "email": "alice@acme.com",
  "phone_number": "+31612345678",
  "audiences": [
    {
      "id": "adn_01krdgeqcxet5s7t44vh8rt9mg",
      "name": "Newsletter subscribers"
    }
  ],
  "created_at": "2026-05-20T09:14:52Z",
  "updated_at": "2026-05-25T16:42:01Z"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.