Create a contact
POST
/v1/contacts
curl -X POST "https://us1.platform.bird.com/v1/contacts" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"email": "alice@acme.com",
"first_name": "Alice",
"last_name": "Anderson"
}'Creates a contact in the workspace. The email address is the contact's identity: it is stored trimmed and lowercased, and creating a second contact with the same email, or reusing another contact's external_id, returns a conflict error.
To create or update many contacts in one request, or to write a contact without knowing whether the address already exists, use Create or update contacts in bulk instead.
Request Payload
email
string
required
The contact's email address. Trimmed and lowercased before it is stored and checked for uniqueness. Unique within the workspace.
first_name
string
The contact's first name.
last_name
string
The contact's last name.
external_id
string
Your own identifier for this contact, such as a user ID in your system. Unique within the workspace when set.
data
object
Custom property values for this contact. Each key must be a property created via the contact properties API, and each value must be a string, number, or boolean matching the property's declared type (strings up to 500 characters); a null value is ignored. Unregistered or archived keys are rejected with a validation error. Total size is capped at 2 KB serialized.
Response Payload
id
string
required
ID of the contact (con_-prefixed), accepted by every operation that takes a contact_id.
email
string
required
The contact's email address, stored trimmed and lowercased. Unique within the workspace.
first_name
nullable string
The contact's first name. Available in broadcast templates as the contact.first_name variable.
last_name
nullable string
The contact's last name. Available in broadcast templates as the contact.last_name variable.
external_id
nullable string
Your own identifier for this contact, such as a user ID in your system. Unique within the workspace when set.
data
object
Custom property values for this contact, available as template variables in broadcasts. Each key is a property created via the contact properties API, and each value is a string, number, or boolean matching the property's declared type (strings up to 500 characters). Total size is capped at 2 KB serialized. Values stored under a property that was later archived remain readable here.
channels
array of string
Channels this contact can be reached on, derived from the identifiers it has. A contact with an email address includes email. More values are added as a contact gains identifiers for other channels.
created_at
string
required
updated_at
string
required