Create a contact

Create a contact

post

https://api.bird.comhttp://localhost:3000https://api.bird.ai

/workspaces/{workspaceId}/contacts

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

MessageBird_userMessageBird_accessKey

AuthorizationstringRequired

An access token issued to a user.

Path parameters

workspaceIdstring · uuidRequired

Your workspace identifier.

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

Body

application/json

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

companyRefsstring[]Optional

The list of company references for the contact.

Other propertiesanyOptional

Responses

201

The contact was created successfully.

application/json

idstringRequired

The unique identifier for the contact.

Example: 123e4567-e89b-12d3-a456-426614174000

computedDisplayNamestringOptional

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.

Example: John Doe

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

workspaceIdstringOptional

Your workspace identifier.

Example: 123e4567-e89b-12d3-a456-426614174000

identifierCountintegerOptional

The number of identifiers for the contact.

Example: 2

accountIdsstring[]Optional

The list of account ids for the contact.

Example: 123e4567-e89b-12d3-a456-426614174000

listIdsstring[]Optional

The list of list ids for the contact.

Example: 123e4567-e89b-12d3-a456-426614174000

companyRefsstring[]Optional

The list of company references for the contact.

isAnonymousbooleanOptional

Whether the contact is anonymous. A contact is anonymous if it has no identifiers, or only has visitorid identifiers.

404

The workspace was not found.

application/json

409

The HTTP could not be completed because of a conflict with the current state of the resource.

application/json

422

The HTTP request is well-formed but was unable to be processed. The HTTP response should include details about the error.

application/json

post

/workspaces/{workspaceId}/contacts

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/contacts HTTP/1.1
Host: api.bird.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 439

{
  "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"
  ],
  "companyRefs": [
    "text"
  ],
  "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": "2026-03-13T11:46:39.492Z",
  "updatedAt": "2026-03-13T11:46:39.492Z",
  "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"
  ],
  "companyRefs": [
    "text"
  ],
  "isAnonymous": true
}

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.

Request

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"
}'

Response (200 - OK)

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.

Request

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"
  }
}'

Response (200 - OK)

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.

Request

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

Response (200 - OK)

Create a contact with providing all the details

In this example, we're creating a contact providing all the examples above.

Request

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"
  }
}'

Response (200 - OK)