Create a contact
The contact creation endpoint allows adding a new contact with multiple identifiers, attributes, and lists, specifying their details and associations during the creation process.
Your workspace identifier.
b4e02c85-c6d2-4b15-8885-e09671799c61
The display name for the contact.
John Doe
The list of account ids for the contact.
123e4567-e89b-12d3-a456-426614174000
The list of list ids for the contact.
123e4567-e89b-12d3-a456-426614174000
POST /workspaces/{workspaceId}/contacts HTTP/1.1
Host: api.bird.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 416
{
"displayName": "John Doe",
"identifiers": [
{
"key": "secondaryEmailAddress",
"value": "[email protected]",
"properties": {
"countryCode": "US",
"isGmail": true
}
}
],
"accountIds": [
"123e4567-e89b-12d3-a456-426614174000"
],
"listIds": [
"123e4567-e89b-12d3-a456-426614174000"
],
"attributes": {
"firstName": "John",
"lastName": "Smith",
"rating": 9.6,
"cookiesAccepted": false,
"labels": [
"A",
"B",
"C"
]
},
"ANY_ADDITIONAL_PROPERTY": "anything"
}
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"computedDisplayName": "John Doe",
"createdAt": "2025-06-22T23:15:44.552Z",
"updatedAt": "2025-06-22T23:15:44.552Z",
"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
Create a contact with identifiers
In this example, we're creating a contact providing identifiers. To know more about identifiers, please refer to this documentation.
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/contacts" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
"identifiers": [
{
"key": "emailaddress",
"value": "[email protected]"
}
],
"displayName": "John Doe"
}'
Create a contact with attributes
In this example, we're creating a contact providing attributes. To know more about attributes, please refer to this documentation.
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/contacts" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
"displayName": "John Doe",
"attributes": {
"firstName": "John",
"lastName": "Doe"
}
}'
Create a contact with lists
In this example, we're creating a contact providing list IDs. To knoe more about lists, please refer to this documentation.
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/contacts" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
"displayName": "John Doe",
"listIds": ["12bd0e40-9361-4e32-8b26-99b4ab7eae09"]
}'
Create a contact with providing all the details
In this example, we're creating a contact providing all the examples above.
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/contacts" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
"displayName": "John Doe",
"listIds": ["12bd0e40-9361-4e32-8b26-99b4ab7eae09"],
"identifiers": [
{
"key": "emailaddress",
"value": "[email protected]"
}
],
"attributes": {
"firstName": "John",
"lastName": "Doe"
}
}'
Last updated
Was this helpful?