Create a contact
POST
/contactsAuthorization
AuthorizationBearer token · headerrequiredA BillionSend API key (bs_…).
Request body
requiredapplication/jsonemailstring<email>requiredBare email address (no display name); unique per team
first_namestringFirst name
last_namestringLast name
unsubscribedbooleanGlobal opt-out from all marketing sends
propertiesobjectFlat map of custom properties (string or number values)
segmentsobject[]Segments to add the contact to on creation
Show propertiesHide properties
Array of
objectidstring<uuid>requiredtopicsobject[]Initial per-topic subscription choices
Show propertiesHide properties
Array of
objectidstring<uuid>requiredsubscriptionstringrequiredAllowed:
opt_inopt_outResponses
200
Contact created
objectstringrequiredAllowed:
contactidstring<uuid>required401
Missing, malformed, unknown or revoked API key
statusCodenumberrequirednamestringrequiredmessagestringrequired403
Plan limit reached
statusCodenumberrequirednamestringrequiredmessagestringrequired404
Unknown segment or topic
statusCodenumberrequirednamestringrequiredmessagestringrequired409
Contact already exists
statusCodenumberrequirednamestringrequiredmessagestringrequired422
Validation error
statusCodenumberrequirednamestringrequiredmessagestringrequired429
Over the rate limit (rate_limit_exceeded, with Retry-After)
statusCodenumberrequirednamestringrequiredmessagestringrequired