Update a contact

Update a contact

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

PATCHhttps://api.bird.com/workspaces/{workspaceId}/contacts/{contactId}

Path parameters

workspaceId*string (uuid)

Your workspace identifier.

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

contactId*string

The ID of a contact.

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

Query parameters

Body

application/json

attributesnullable Contacts_AttributesObject (object)

A map of key-value pairs, where the values are boolean, number, or string, or a non-empty array of those, or null

addIdentifiersarray of Contacts_CreateIdentifier (object)

The list of identifiers to add to the contact.

removeIdentifiersarray of Contacts_DeleteIdentifier (object)

The list of identifiers to remove from the contact.

addToListsarray of string (uuid)

The list of list ids to add the contact to.

removeFromListsarray of string (uuid)

The list of list ids to remove the contact from.

listIdsarray of string (uuid)

The list of list ids for the contact.

addToAccountsarray of string (uuid)

The list of account ids to add the contact to.

removeFromAccountsarray of string (uuid)

The list of account ids to remove the contact from.

accountIdsarray of string (uuid)

The list of account ids for the contact.

Other propertiesany

Response

200404409422

The contact was updated successfully.

Body

application/json

id*string

The unique identifier for the contact.

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

computedDisplayNamestring

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"

createdAt*string (date-time)

updatedAt*string (date-time)

workspaceIdstring

Your workspace identifier.

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

featuredIdentifiersarray of IdentifierRef

The list of identifiers for the contact.

attributesnullable Contacts_AttributesObject (object)

A map of key-value pairs, where the values are boolean, number, or string, or a non-empty array of those, or null

identifierCountinteger

The number of identifiers for the contact.

Example: 2

accountIdsarray of string

The list of account ids for the contact.

listIdsarray of string

The list of list ids for the contact.

Request

JavaScriptCurlPython

const response = await fetch('https://api.bird.com/workspaces/{workspaceId}/contacts/{contactId}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200404409422

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "computedDisplayName": "John Doe",
  "createdAt": "2024-12-03T15:00:13.820Z",
  "updatedAt": "2024-12-03T15:00:13.820Z",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "featuredIdentifiers": [
    {
      "key": "emailaddress",
      "value": "[e-mail]"
    }
  ],
  "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"
  ]
}

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": "[e-mail]"
    }
  ]
}'

Response (200 OK)

{
  "id": "12bd0e40-9361-4e32-8b26-99b4ab7eae09",
  "computedDisplayName": "John",
  "featuredIdentifiers": [
    {
      "key": "emailaddress",
      "value": "[e-mail]"
    }
  ],
  "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"
}

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)

{
  "id": "12bd0e40-9361-4e32-8b26-99b4ab7eae09",
  "computedDisplayName": "John",
  "featuredIdentifiers": [
    {
      "key": "emailaddress",
      "value": "[e-mail]"
    }
  ],
  "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"
}

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)

{
  "id": "12bd0e40-9361-4e32-8b26-99b4ab7eae09",
  "computedDisplayName": "John",
  "featuredIdentifiers": [
    {
      "key": "emailaddress",
      "value": "[e-mail]"
    }
  ],
  "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"
}

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": "[e-mail]"
    }
  ]
}'

Response (200 OK)

{
  "id": "12bd0e40-9361-4e32-8b26-99b4ab7eae09",
  "computedDisplayName": "John",
  "featuredIdentifiers": [
    {
      "key": "emailaddress",
      "value": "[e-mail]"
    }
  ],
  "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"
}