Create or update a contact by identifier

Create or Update Contact by Identifier

PATCHhttps://api.bird.com/workspaces/{workspaceId}/contacts/identifiers/{identifierKey}/{identifierValue}

Path parameters

workspaceId*string (uuid)

Your workspace identifier.

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

identifierKey*string

The identifier key of you contact.

Example: "emailaddress"

identifierValue*string

The identifier value of your identifier key.

Example: "[e-mail]"

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

200201404409422

Updated

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/identifiers/{identifierKey}/{identifierValue}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200201404409422

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "computedDisplayName": "John Doe",
  "createdAt": "2025-01-02T12:28:01.009Z",
  "updatedAt": "2025-01-02T12:28:01.009Z",
  "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/identifiers/emailaddress/[e-mail]" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "addIdentifiers": [
    {
      "key": "phonenumber",
      "value": "[phone]"
    }
  ]
}'

Response (200 OK)

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

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/[e-mail]" \
-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)

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