DocumentatieEngagement Platform API
Sign inGet started
Guides
API

Update a contact

PATCH
/workspaces/{workspaceId}/contacts/{contactId}
Update the specified contact given its ID. This endpoint allows you to update the contact's attributes, lists, and identifiers.
Verzoek-payload
allowWritingReadOnly
boolean
Whether to allow writing to read-only attributes. (this is only allowed if the request origin is from flows or journeys)
strategy
string
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.
Possible values: strict_alias, first_alias, first
attributes
object
A map of key-value pairs, where the values are boolean, number, or string, or a non-empty array of those, or null
addIdentifiers
array of object
The list of identifiers to add to the contact.
Onderliggende parameters tonen
addIdentifiers.key
string
verplicht
The identifier key.
addIdentifiers.value
string
verplicht
The identifier value.
addIdentifiers.properties
object
Object with key-value pairs, where the key is up to 64 characters, only letters and digits. This can be used to store additional information about the identifier.
removeIdentifiers
array of object
The list of identifiers to remove from the contact.
Onderliggende parameters tonen
removeIdentifiers.key
string
verplicht
The identifier key.
removeIdentifiers.value
string
verplicht
The identifier value.
addToLists
array of string
The list of list ids to add the contact to.
removeFromLists
array of string
The list of list ids to remove the contact from.
listIds
array of string
The list of list ids for the contact.
addToAccounts
array of string
The list of account ids to add the contact to.
removeFromAccounts
array of string
The list of account ids to remove the contact from.
accountIds
array of string
The list of account ids for the contact.
identifiers
array of object
Use "addIdentifiers" instead
Onderliggende parameters tonen
identifiers.key
string
verplicht
The identifier key.
identifiers.value
string
verplicht
The identifier value.
identifiers.properties
object
Object with key-value pairs, where the key is up to 64 characters, only letters and digits. This can be used to store additional information about the identifier.
addCompanyRefs
array of string
The list of company references to add to the contact.
removeCompanyRefs
array of string
The list of company references to remove from the contact.
companyRefs
array of string
The list of company references for the contact.
Antwoord-payload
accountIds
array of string
The list of account ids for the contact.
attributes
object
A map of key-value pairs, where the values are boolean, number, or string, or a non-empty array of those, or null
companyRefs
array of string
The list of company references for the contact.
computedDisplayName
string
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.
createdAt
string
verplicht
featuredIdentifiers
array of object
The list of identifiers for the contact.
Onderliggende attributen tonen
featuredIdentifiers.key
string
verplicht
The identifier key. This can be from your custom identifier key or one of the built-in keys.
featuredIdentifiers.value
string
verplicht
The identifier value. This represents the actual value for the identifier.
id
string
verplicht
The unique identifier for the contact.
identifierCount
integer
The number of identifiers for the contact.
isAnonymous
boolean
Whether the contact is anonymous. A contact is anonymous if it has no identifiers, or only has visitorid identifiers.
listIds
array of string
The list of list ids for the contact.
updatedAt
string
verplicht
workspaceId
string
Your workspace identifier.
Codevoorbeeld
curl -X PATCH 'https://api.bird.com/workspaces/{workspaceId}/contacts/{contactId}' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

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.
Codevoorbeeld
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": "contacts@example.com"
    }
  ]
}'

Update contact's attributes

In this example, we're updating a contact providing attributes. To know more about attributes, please refer to this documentation.
Codevoorbeeld
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"
  }
}'

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

Update contact's details

In this example, we're creating a contact providing all the examples above.
Codevoorbeeld
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": "contacts@bird.com"
    }
  ]
}'