Create or update a contact by identifier
Your workspace identifier.
b4e02c85-c6d2-4b15-8885-e09671799c61
The identifier key of you contact.
emailaddress
The identifier value of your identifier key.
[email protected]
The list of list ids to add the contact to.
123e4567-e89b-12d3-a456-426614174000
The list of list ids to remove the contact from.
123e4567-e89b-12d3-a456-426614174000
The list of list ids for the contact.
123e4567-e89b-12d3-a456-426614174000
The list of account ids to add the contact to.
123e4567-e89b-12d3-a456-426614174000
The list of account ids to remove the contact from.
123e4567-e89b-12d3-a456-426614174000
The list of account ids for the contact.
123e4567-e89b-12d3-a456-426614174000
PATCH /workspaces/{workspaceId}/contacts/identifiers/{identifierKey}/{identifierValue} HTTP/1.1
Host: api.bird.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 718
{
"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"
],
"ANY_ADDITIONAL_PROPERTY": "anything"
}
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"computedDisplayName": "John Doe",
"createdAt": "2025-06-22T18:54:18.740Z",
"updatedAt": "2025-06-22T18:54:18.740Z",
"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"
]
}
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/[email protected]" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
"addIdentifiers": [
{
"key": "phonenumber",
"value": "+31412345678"
}
]
}'
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/[email protected]" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
"attributes": {
"countryCode": "US"
}
}'
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/[email protected]" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
"attributes": {
"firstName": "John",
"lastName": "Doe",
"countryCode": "US"
},
"addIdentifiers": [
{
"key": "phonenumber",
"value": "+31412345678"
}
]
}'
Last updated
Was this helpful?