Create or update a contact by identifier

Create or Update Contact by Identifier

patch

https://api.bird.comhttp://localhost:3000https://api.bird.ai

/workspaces/{workspaceId}/contacts/identifiers/{identifierKey}/{identifierValue}

Authorizations

MessageBird_userMessageBird_accessKey

AuthorizationstringRequired

An access token issued to a user.

Path parameters

workspaceIdstring · uuidRequired

Your workspace identifier.

Example: b4e02c85-c6d2-4b15-8885-e09671799c61

identifierKeystring · min: 1 · max: 250Required

The identifier key

Example: emailaddress

identifierValuestring · min: 1 · max: 500Required

The identifier value

Example: [email protected]

Body

application/json

allowWritingReadOnlybooleanOptional

Whether to allow writing to read-only attributes. (this is only allowed if the request origin is from flows or journeys)

Default: false

strategystring · enumOptional

Strategy for resolving contact conflicts when identifiers match multiple contacts:

• strict_alias: All identifiers must match a single contact, otherwise an error is returned. All non-matching identifiers will be added to the contact that was found (default).
• first_alias: Uses priority-based filtering to find the first matching identifier. When a contact is found, all other identifiers are tried to be added to that contact, but that is allowed to fail.
• first: Uses priority-based filtering to find the first matching identifier. No other identifiers are added when a contact is found. When nothing is found, a contact will be created using only the first provided identifier.

Default: strict_aliasPossible values:

addToListsstring · uuid[] · max: 10Optional

The list of list ids to add the contact to.

Example: 123e4567-e89b-12d3-a456-426614174000

removeFromListsstring · uuid[] · max: 10Optional

The list of list ids to remove the contact from.

Example: 123e4567-e89b-12d3-a456-426614174000

listIdsstring · uuid[] · max: 10Optional

The list of list ids for the contact.

Example: 123e4567-e89b-12d3-a456-426614174000

addToAccountsstring · uuid[] · max: 10Optional

The list of account ids to add the contact to.

Example: 123e4567-e89b-12d3-a456-426614174000

removeFromAccountsstring · uuid[] · max: 10Optional

The list of account ids to remove the contact from.

Example: 123e4567-e89b-12d3-a456-426614174000

accountIdsstring · uuid[] · min: 1 · max: 10Optional

The list of account ids for the contact.

Example: 123e4567-e89b-12d3-a456-426614174000

addCompanyRefsstring[]Optional

The list of company references to add to the contact.

removeCompanyRefsstring[]Optional

The list of company references to remove from the contact.

companyRefsstring[]Optional

The list of company references for the contact.

Other propertiesanyOptional

Responses

200

Updated

application/json

idstringRequired

The unique identifier for the contact.

Example: 123e4567-e89b-12d3-a456-426614174000

computedDisplayNamestringOptional

The computed display name for the contact. It can be derived, in the following order if available, from the displayName attribute, the firstName attribute, the emailaddress identifier, or the phonenumber identifier.

Example: John Doe

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

workspaceIdstringOptional

Your workspace identifier.

Example: 123e4567-e89b-12d3-a456-426614174000

identifierCountintegerOptional

The number of identifiers for the contact.

Example: 2

accountIdsstring[]Optional

The list of account ids for the contact.

Example: 123e4567-e89b-12d3-a456-426614174000

listIdsstring[]Optional

The list of list ids for the contact.

Example: 123e4567-e89b-12d3-a456-426614174000

companyRefsstring[]Optional

The list of company references for the contact.

isAnonymousbooleanOptional

Whether the contact is anonymous. A contact is anonymous if it has no identifiers, or only has visitorid identifiers.

201

Created

application/json

404

Contact or workspace not found

application/json

409

Duplicate identifier

application/json

422

Invalid contact

application/json

patch

/workspaces/{workspaceId}/contacts/identifiers/{identifierKey}/{identifierValue}

HTTPcURLJavaScriptPython

PATCH /workspaces/{workspaceId}/contacts/identifiers/{identifierKey}/{identifierValue} HTTP/1.1
Host: api.bird.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 851

{
  "allowWritingReadOnly": false,
  "strategy": "strict_alias",
  "attributes": {
    "firstName": "John",
    "lastName": "Smith",
    "rating": 9.6,
    "cookiesAccepted": false,
    "labels": [
      "A",
      "B",
      "C"
    ]
  },
  "addIdentifiers": [
    {
      "key": "secondaryEmailAddress",
      "value": "[email protected]",
      "properties": {
        "countryCode": "US",
        "isGmail": true
      }
    }
  ],
  "removeIdentifiers": [
    {
      "key": "secondaryEmailAddress",
      "value": "[email protected]"
    }
  ],
  "addToLists": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "removeFromLists": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "listIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "addToAccounts": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "removeFromAccounts": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "accountIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "addCompanyRefs": [
    "text"
  ],
  "removeCompanyRefs": [
    "text"
  ],
  "companyRefs": [
    "text"
  ],
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "computedDisplayName": "John Doe",
  "createdAt": "2026-03-12T00:39:49.374Z",
  "updatedAt": "2026-03-12T00:39:49.374Z",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "featuredIdentifiers": [
    {
      "key": "emailaddress",
      "value": "[email protected]"
    }
  ],
  "attributes": {
    "firstName": "John",
    "lastName": "Smith",
    "rating": 9.6,
    "cookiesAccepted": false,
    "labels": [
      "A",
      "B",
      "C"
    ]
  },
  "identifierCount": 2,
  "accountIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "listIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "companyRefs": [
    "text"
  ],
  "isAnonymous": true
}

Examples

Let's establish some of our data that will be used in the following examples:

• Workspace ID: a1405560-c8d3-4b1a-877d-3f449ad95352

• AccessKey: abcd

• Contact ID: 12bd0e40-9361-4e32-8b26-99b4ab7eae09

Update contact's identifiers

In this example, we're updating a contact providing identifiers. To know more about identifiers, please refer to this documentation.

Request

curl -X PATCH "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/contacts/identifiers/emailaddress/[email protected]" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "addIdentifiers": [
    {
      "key": "phonenumber",
      "value": "[phone]"
    }
  ]
}'

Response (200 OK)

Update contact's attributes

In this example, we're updating a contact providing attributes. To know more about attributes, please refer to this documentation.

Request

curl -X PATCH "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/contacts/identifiers/emailaddress/[email protected]" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "attributes": {
    "countryCode": "US"
  }
}'

Response (200 OK)

Create a new contact

In this example, we're creating a new contact because the provided identifier is not being used by any existing contacts.

Request

curl -X PATCH "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/contacts/identifiers/emailaddress/[email protected]" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "attributes": {
    "firstName": "John",
    "lastName": "Doe",
    "countryCode": "US"
  },
  "addIdentifiers": [
    {
      "key": "phonenumber",
      "value": "[phone]"
    }
  ]
}'

Response (201 Created)