Create a contact

Create a contact

post

The contact creation endpoint allows adding a new contact with multiple identifiers, attributes, and lists, specifying their details and associations during the creation process.

Authorizations
Path parameters
workspaceIdstring · uuidRequired

Your workspace identifier.

Example: b4e02c85-c6d2-4b15-8885-e09671799c61
Body
displayNamestring · min: 1 · max: 150Required

The display name for the contact.

Example: John Doe
accountIdsstring[] · min: 1 · max: 10Optional

The list of account ids for the contact.

Example: 123e4567-e89b-12d3-a456-426614174000
listIdsstring[] · min: 1 · max: 10Optional

The list of list ids for the contact.

Example: 123e4567-e89b-12d3-a456-426614174000
Other propertiesanyOptional
Responses
201
The contact was created successfully.
application/json
post
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?