Documentation
Sign inGet started
शुरू करें
गाइड
API Reference
SDKs
CLI
Knowledge Base
Changelog

Create a contact

POST
/v1/contacts
const contact = await bird.contacts.create({
  email: "jane@acme.com",
  first_name: "Jane",
});
console.log(contact.id); // "con_…"
Creates a contact in the workspace, identified by an email address, a phone number, or both; at least one is required. Email is stored trimmed and lowercased, and phone in its canonical international form. Creating a second contact with the same email or phone number, 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
The contact's email address. Trimmed and lowercased before it is stored and checked for uniqueness. Unique within the workspace. Supply an email address, a phone number, or both.
phone_number
string
The contact's phone number in E.164 format, including the leading + and country code. Spaces and punctuation are accepted and stripped; the number is stored in its canonical form, which may differ from what you send, and is unique within the workspace. An empty string is treated as if the field were omitted. Supply an email address, a phone number, or both.
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, boolean, or RFC 3339 datetime 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
आवश्यक
ID of the contact (con_-prefixed), accepted by every operation that takes a contact_id.
email
nullable string
आवश्यक
The contact's email address, in its stored form, trimmed and lowercased before uniqueness is checked. Unique within the workspace. Null when the contact has no email address.
phone_number
nullable string
आवश्यक
The contact's phone number in normalized international form (a leading + and four to 15 digits), which may differ from the form it was supplied in. Bird normalizes formatting but does not verify the number against numbering-plan metadata. Unique within the workspace. Carriers recycle disconnected numbers, so a long-stored number can come to belong to someone else; external_id is the durable key for your own records. Null when the contact has no phone number.
first_name
nullable string
The contact's first name. Available in broadcast templates as bird.contact.first_name.
last_name
nullable string
The contact's last name. Available in broadcast templates as bird.contact.last_name.
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 in broadcast templates as bird.contact.<key>. Each key is a property created via the contact properties API, and each value is a string, number, boolean, or RFC 3339 datetime 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.
audiences
array of object
The audiences this contact belongs to, most-recently-joined first. Only present when listing contacts; omitted from every other contact operation.
चाइल्ड एट्रिब्यूट दिखाएँ
audiences.id
string
आवश्यक
ID of the referenced audience (adn_-prefixed).
audiences.name
string
आवश्यक
The audience's display name.
created_at
string
आवश्यक
updated_at
string
आवश्यक