Create or update a contact by identifier

Create or Update Contact by Identifier

patch

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

Authorizations

Path parameters

workspaceIdstring · uuidrequired

Your workspace identifier.

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

identifierKeystring · min: 1 · max: 250required

The identifier key of you contact.

Example: emailaddress

identifierValuestring · min: 1 · max: 500required

The identifier value of your identifier key.

Example: contacts@bird.com

Body

attributesobject | nullable

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

Example: {"firstName":"John","lastName":"Smith","rating":9.6,"cookiesAccepted":false,"labels":["A","B","C"]}

addIdentifiersobject[]

removeIdentifiersobject[]

addToListsstring · uuid[] · max: 10

removeFromListsstring · uuid[] · max: 10

listIdsstring · uuid[] · max: 10

addToAccountsstring · uuid[] · max: 10

removeFromAccountsstring · uuid[] · max: 10

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

identifiersobject[] | nullableDeprecated

Other propertiesany

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.bird.com/workspaces/{workspaceId}/contacts/identifiers/{identifierKey}/{identifierValue}' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "attributes": {
      "firstName": "John",
      "lastName": "Smith",
      "rating": 9.6,
      "cookiesAccepted": false,
      "labels": [
        "A",
        "B",
        "C"
      ]
    },
    "addIdentifiers": [
      {
        "key": "secondaryEmailAddress",
        "value": "contacts-secondary@bird.com",
        "properties": {
          "countryCode": "US",
          "isGmail": true
        }
      }
    ],
    "removeIdentifiers": [
      {
        "key": "secondaryEmailAddress",
        "value": "contacts-secondary@bird.com"
      }
    ],
    "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"
    ],
    "identifiers": [
      {
        "key": "secondaryEmailAddress",
        "value": "contacts-secondary@bird.com",
        "properties": {
          "countryCode": "US",
          "isGmail": true
        }
      }
    ],
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }'

200

201

404

409

422

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "computedDisplayName": "John Doe",
  "createdAt": "2025-02-28T01:52:33.507Z",
  "updatedAt": "2025-02-28T01:52:33.507Z",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "attributes": {
    "firstName": "John",
    "lastName": "Smith",
    "rating": 9.6,
    "cookiesAccepted": false,
    "labels": [
      "A",
      "B",
      "C"
    ]
  },
  "identifierCount": 2,
  "featuredIdentifiers": [
    {
      "key": "emailaddress",
      "value": "contacts@bird.com"
    }
  ],
  "accountIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "listIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

Updated

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.

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

{
  "id": "12bd0e40-9361-4e32-8b26-99b4ab7eae09",
  "computedDisplayName": "John",
  "featuredIdentifiers": [
    {
      "key": "emailaddress",
      "value": "contacts@example.com"
    },
    {
      "key": "phonenumber",
      "value": "+31412345678"
    }
  ],
  "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.

curl -X PATCH "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/contacts/identifiers/emailaddress/contacts@example.com" \
-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": "contacts@example.com"
    }
  ],
  "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.

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

{
  "id": "12bd0e40-9361-4e32-8b26-99b4ab7eae09",
  "computedDisplayName": "John",
  "featuredIdentifiers": [
    {
      "key": "emailaddress",
      "value": "contacts@example.com"
    },
    {
      "key": "phonenumber",
      "value": "+31412345678"
    }
  ],
  "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"
}

Last updated 2 months ago

Was this helpful?