Skip to content
Esc
↑↓navigate↵open⌘Jpreview

Create a contact

POST/contacts
Authorization
AuthorizationBearer token · headerrequired

A BillionSend API key (bs_…).

Request body
requiredapplication/json
emailstring<email>required

Bare email address (no display name); unique per team

first_namestring

First name

last_namestring

Last name

unsubscribedboolean

Global opt-out from all marketing sends

propertiesobject

Flat map of custom properties (string or number values)

segmentsobject[]

Segments to add the contact to on creation

Show properties
Array of object
idstring<uuid>required
topicsobject[]

Initial per-topic subscription choices

Show properties
Array of object
idstring<uuid>required
subscriptionstringrequired
Allowed:opt_inopt_out
Responses
200

Contact created

objectstringrequired
Allowed:contact
idstring<uuid>required
401

Missing, malformed, unknown or revoked API key

statusCodenumberrequired
namestringrequired
messagestringrequired
403

Plan limit reached

statusCodenumberrequired
namestringrequired
messagestringrequired
404

Unknown segment or topic

statusCodenumberrequired
namestringrequired
messagestringrequired
409

Contact already exists

statusCodenumberrequired
namestringrequired
messagestringrequired
422

Validation error

statusCodenumberrequired
namestringrequired
messagestringrequired
429

Over the rate limit (rate_limit_exceeded, with Retry-After)

statusCodenumberrequired
namestringrequired
messagestringrequired
Try it
Server
Authorization
Bodyapplication/json
Request
curl -X POST 'https://api.billionsend.com/contacts' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "user@example.com",
  "first_name": "string",
  "last_name": "string",
  "unsubscribed": true,
  "properties": {
    "property1": null,
    "property2": null
  },
  "segments": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    }
  ],
  "topics": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "subscription": "opt_in"
    }
  ]
}'
Response
{
  "object": "contact",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Was this page helpful?