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.

POSThttps://api.bird.com/workspaces/{workspaceId}/contacts

Path parameters

workspaceId*string (uuid)

Your workspace identifier.

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

Body

displayName*string

The display name for the contact.

Example: "John Doe"

identifiersnullable array of Contacts_CreateIdentifier (object)

accountIdsarray of string

The list of account ids for the contact.

listIdsarray of string

The list of list ids for the contact.

attributesnullable Contacts_AttributesObject (object)

A map of key-value pairs, where the values are boolean, number, or string, or a non-empty array of those, or null

Other propertiesany

Response

The contact was created successfully.

Body

id*string

The unique identifier for the contact.

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

computedDisplayNamestring

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"

createdAt*string (date-time)

updatedAt*string (date-time)

workspaceIdstring

Your workspace identifier.

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

featuredIdentifiersarray of IdentifierRef

The list of identifiers for the contact.

attributesnullable Contacts_AttributesObject (object)

A map of key-value pairs, where the values are boolean, number, or string, or a non-empty array of those, or null

identifierCountinteger

The number of identifiers for the contact.

Example: 2

accountIdsarray of string

The list of account ids for the contact.

listIdsarray of string

The list of list ids for the contact.

Request

const response = await fetch('https://api.bird.com/workspaces/{workspaceId}/contacts', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "displayName": "John Doe"
    }),
});
const data = await response.json();

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "computedDisplayName": "John Doe",
  "createdAt": "2025-01-21T01:28:04.889Z",
  "updatedAt": "2025-01-21T01:28:04.889Z",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "featuredIdentifiers": [
    {
      "key": "emailaddress",
      "value": "contacts@bird.com"
    }
  ],
  "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": "contacts@bird.com"
    }
  ],
  "displayName": "John Doe"
}'

{
  "id": "12bd0e40-9361-4e32-8b26-99b4ab7eae09",
  "computedDisplayName": "John Doe",
  "featuredIdentifiers": [
    {
      "key": "emailaddress",
      "value": "contacts@bird.com"
    }
  ],
  "identifierCount": 1,
  "attributes": {
    "displayName": "John Doe",
    "emailaddress": [
      "contacts@bird.com"
    ],
    "initialReference": "028d45dd-8e3f-43bb-8aa5-9d6833f08945",
    "timezone": "America/Sao_Paulo"
  },
  "createdAt": "2024-11-26T15:00:00.000Z",
  "updatedAt": "2024-11-26T15:00:00.000Z"
}

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

{
  "id": "12bd0e40-9361-4e32-8b26-99b4ab7eae09",
  "computedDisplayName": "John",
  "identifierCount": 0,
  "attributes": {
    "firstName": "John",
    "initialReference": "32d6f4f9-7e9c-4271-bd83-9d6976808f2f",
    "lastName": "Doe",
    "timezone": "America/Sao_Paulo"
  },
  "createdAt": "2024-11-26T15:00:00.000Z",
  "updatedAt": "2024-11-26T15:00:00.000Z"
}

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

{
  "id": "12bd0e40-9361-4e32-8b26-99b4ab7eae09",
  "computedDisplayName": "",
  "identifierCount": 0,
  "attributes": {
    "initialReference": "32d6f4f9-7e9c-4271-bd83-9d6976808f2f",
    "timezone": "America/Sao_Paulo"
  },
  "listIds": [
    "12bd0e40-9361-4e32-8b26-99b4ab7eae09"
  ],
  "createdAt": "2024-11-26T15:00:00.000Z",
  "updatedAt": "2024-11-26T15:00:00.000Z"
}

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": "contacts+2@bird.com"
    }
  ],
  "attributes": {
    "firstName": "John",
    "lastName": "Doe"
  }
}'

{
  "id": "12bd0e40-9361-4e32-8b26-99b4ab7eae09",
  "computedDisplayName": "John",
  "featuredIdentifiers": [
    {
      "key": "emailaddress",
      "value": "contacts@bird.com"
    }
  ],
  "identifierCount": 1,
  "attributes": {
    "emailaddress": [
      "contacts@bird.com"
    ],
    "firstName": "John",
    "initialReference": "32d6f4f9-7e9c-4271-bd83-9d6976808f2f",
    "lastName": "Doe",
    "timezone": "America/Sao_Paulo"
  },
  "listIds": [
    "12bd0e40-9361-4e32-8b26-99b4ab7eae09"
  ],
  "createdAt": "2024-11-26T15:00:00.000Z",
  "updatedAt": "2024-11-26T15:00:00.000Z"
}

Last updated 1 month ago

const response = await fetch('https://api.bird.com/workspaces/{workspaceId}/contacts', { method: 'POST', headers: { "Content-Type": "application/json" }, body: JSON.stringify({ "displayName": "John Doe" }), }); const data = await response.json();

{ "id": "123e4567-e89b-12d3-a456-426614174000", "computedDisplayName": "John Doe", "createdAt": "2025-01-21T01:28:04.889Z", "updatedAt": "2025-01-21T01:28:04.889Z", "workspaceId": "123e4567-e89b-12d3-a456-426614174000", "featuredIdentifiers": [ { "key": "emailaddress", "value": "contacts@bird.com" } ], "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" ] }