email-contacts

Get a contact

Returns a single contact, including its custom data values and the channels it can be reached on. To find a contact's ID by email address or external_id, use List contacts.

get/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 fetch.

Headers

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.

Response

The 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.