Ctrlk

Update a contact

Update a contact

patch

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

Authorizations

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

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

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}

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.

Update contact's attributes

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

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.

Update contact's details

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

Last updated 1 year ago

Was this helpful?

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": "2025-12-15T23:14:59.416Z",
  "updatedAt": "2025-12-15T23:14:59.416Z",
  "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
}

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]"
    }
  ]
}'

{
  "id": "12bd0e40-9361-4e32-8b26-99b4ab7eae09",
  "computedDisplayName": "John",
  "featuredIdentifiers": [
    {
      "key": "emailaddress",
      "value": "[email protected]"
    }
  ],
  "identifierCount": 1,
  "attributes": {
    "firstName": "John",
    "initialReference": "32d6f4f9-7e9c-4271-bd83-9d6976808f2f",
    "lastName": "Doe",
    "timezone": "America/Sao_Paulo"
  },
  "createdAt": "2024-11-26T15:00:00.000Z",
  "updatedAt": "2024-11-26T15:00:00.000Z"
}

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"
  }
}'

{
  "id": "12bd0e40-9361-4e32-8b26-99b4ab7eae09",
  "computedDisplayName": "John",
  "featuredIdentifiers": [
    {
      "key": "emailaddress",
      "value": "[email protected]"
    }
  ],
  "identifierCount": 1,
  "attributes": {
    "firstName": "John",
    "initialReference": "32d6f4f9-7e9c-4271-bd83-9d6976808f2f",
    "lastName": "Doe",
    "timezone": "America/Sao_Paulo",
    "countryCode": "US"
  },
  "createdAt": "2024-11-26T15:00:00.000Z",
  "updatedAt": "2024-11-26T15:00:00.000Z"
}

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"]
}'

{
  "id": "12bd0e40-9361-4e32-8b26-99b4ab7eae09",
  "computedDisplayName": "John",
  "featuredIdentifiers": [
    {
      "key": "emailaddress",
      "value": "[email protected]"
    }
  ],
  "identifierCount": 1,
  "attributes": {
    "firstName": "John",
    "initialReference": "32d6f4f9-7e9c-4271-bd83-9d6976808f2f",
    "lastName": "Doe",
    "timezone": "America/Sao_Paulo"
  },
  "listIds":["12bd0e40-9361-4e32-8b26-99b4ab7eae09"],
  "createdAt": "2024-11-26T15:00:00.000Z",
  "updatedAt": "2024-11-26T15:00:00.000Z"
}

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]"
    }
  ]
}'

{
  "id": "12bd0e40-9361-4e32-8b26-99b4ab7eae09",
  "computedDisplayName": "John",
  "featuredIdentifiers": [
    {
      "key": "emailaddress",
      "value": "[email protected]"
    }
  ],
  "identifierCount": 1,
  "attributes": {
    "firstName": "John",
    "initialReference": "32d6f4f9-7e9c-4271-bd83-9d6976808f2f",
    "lastName": "Doe",
    "timezone": "America/Sao_Paulo",
    "countryCode": "US"
  },
  "listIds":["12bd0e40-9361-4e32-8b26-99b4ab7eae09"],
  "createdAt": "2024-11-26T15:00:00.000Z",
  "updatedAt": "2024-11-26T15:00:00.000Z"
}