Create a contact▾
POST

Create a contact

Add someone ahead of a broadcast, with tags and custom attributes.

Creating a contact does not open a conversation and does not permit messaging on its own — you still need an approved template and, for marketing, a lawful opt-in.

Opt-in is your responsibility

WhatsApp requires a documented opt-in before marketing templates. Importing a purchased list is the fastest route to a quality-rating drop and a messaging-limit cut.
POST/v1/contacts

Body parameters

phonestringrequired

E.164 with a leading +.

namestring

Display name in the inbox.

localestring

BCP-47 code used to pick a template language.

tagsarray

Strings used for segmentation.

attributesobject

Flat key/value pairs, up to 50 keys.

opted_inbooleandefault false

Whether you hold a marketing opt-in.

curl -X POST https://api.sendport.tech/v1/contacts \
  -H "Authorization: Bearer $SENDPORT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+201005550123","name":"Nadia Haddad","tags":["vip"],"attributes":{"plan":"pro"},"opted_in":true}'

Responses

201Created
{
  "object": "contact",
  "id": "ct_01JZQ7B2M4N8P0R2T4V6X8ZACE",
  "wa_id": "201005550123",
  "phone": "+201005550123",
  "name": "Nadia Haddad",
  "locale": "en",
  "tags": ["vip", "cairo"],
  "attributes": { "plan": "pro", "city": "Cairo" },
  "opted_in": true,
  "last_seen_at": "2026-09-06T08:41:02.000Z",
  "created_at": "2026-05-14T08:12:44.000Z"
}
409Exists
{
  "error": {
    "type": "invalid_request_error",
    "code": "contact_exists",
    "message": "A contact with wa_id 201005550123 already exists.",
    "param": "phone",
    "doc_url": "https://sendport.tech/docs/errors#contact_exists",
    "request_id": "req_6b2c8f0e94a1d75c30ee"
  }
}
401Unauthorized
{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No API key provided.",
    "doc_url": "https://sendport.tech/docs/errors#missing_api_key",
    "request_id": "req_9f3c2a7b41de08c5b2e6"
  }
}
Try itsandbox
PreviousList contactsNextRetrieve a contact