Update a contact

Update a contact

patch

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

/workspaces/{workspaceId}/contacts/{contactId}

Update the specified contact given its ID. This endpoint allows you to update the contact's attributes, lists, and identifiers.

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

contactIdstringRequired

The ID of a contact.

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

Query parameters

attributestring[]Optional

The set of attribute keys to return for the contact besides all non-empty attributes.

Example: ["age","company"]

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

The contact was updated successfully.

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.

404

The contact or workspace was not found.

application/json

409

The HTTP could not be completed because of a conflict with the current state of the resource.

application/json

422

The HTTP request is well-formed but was unable to be processed. The HTTP response should include details about the error.

application/json

patch

/workspaces/{workspaceId}/contacts/{contactId}

HTTPcURLJavaScriptPython

PATCH /workspaces/{workspaceId}/contacts/{contactId} 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-02-20T09:41:36.084Z",
  "updatedAt": "2026-02-20T09:41:36.084Z",
  "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/12bd0e40-9361-4e32-8b26-99b4ab7eae09" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "addIdentifiers": [
    {
      "key": "emailaddress",
      "value": "[email protected]"
    }
  ]
}'

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/12bd0e40-9361-4e32-8b26-99b4ab7eae09" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "attributes": {
    "countryCode": "US"
  }
}'

Response (200 OK)

Update contact's lists

In this example, we're updating a contact providing list IDs. To knoe more about lists, please refer to this documentation.

Request

curl -X PATCH "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/contacts/12bd0e40-9361-4e32-8b26-99b4ab7eae09" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "addToLists": ["12bd0e40-9361-4e32-8b26-99b4ab7eae09"]
}'

Response (200 OK)

Update contact's details

In this example, we're creating a contact providing all the examples above.

Request

curl -X PATCH "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/contacts/12bd0e40-9361-4e32-8b26-99b4ab7eae09" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "addToLists": [
    "12bd0e40-9361-4e32-8b26-99b4ab7eae09"
  ],
  "attributes": {
    "countryCode": "US"
  },
  "addIdentifiers": [
    {
      "key": "emailaddress",
      "value": "[email protected]"
    }
  ]
}'

Response (200 OK)