Skip to Content
Contacts APICreate Contact

Create Contact

Creates a new contact record in your account.

Endpoint

POST https://api.smsleopard.com/v1/contacts/create

Authentication

This endpoint requires Basic Authentication using your API credentials. Click to Generate Credentials (API Keys and Secrets)

Request Body

ParameterTypeRequiredDescription
phone_numberstringYesMust be a valid phone number
namestringNoContact’s full name
emailstringNoContact’s email address
group_idsarrayNoArray of group IDs to add the contact to
custom_metadataobjectNoAdditional attributes about the contact

Custom Metadata Structure

{ "custom_metadata": { "fields": [ { "name": "field_name", "value": "field_value" } ] } }

Code Examples

curl -X POST "https://api.smsleopard.com/v1/contacts/create" \ -u "your_api_key:your_api_secret" \ -H "Content-Type: application/json" \ -d '{ "name": "John Doe", "phone_number": "0700000000", "email": "john@doe.com", "group_ids": [1, 2, 3], "custom_metadata": { "fields": [ { "name": "account", "value": "12345" } ] } }'

Example Request Body

{ "name": "John Doe", "phone_number": "0700000000", "email": "john@doe.com", "group_ids": [1, 2, 3], "custom_metadata": { "fields": [ { "name": "account", "value": "12345" } ] } }

Response

Success Response (201 Created)

{ "id": 1, "custom_fields": { "fields": [{ "name": "account", "value": "12345" }] }, "organization_id": 10, "name": "John Doe", "phone_number": { "country_code": "+254", "number": "700000000" }, "email": "john@doe.com", "uploader_id": 20, "acquisition_source": "", "preferred_channel": "", "created_at": "2025-08-28T09:00:00Z", "updated_at": "2025-08-28T09:00:00Z" }

Response Fields

FieldTypeDescription
idintegerUnique identifier for the created contact
namestringContact’s full name
custom_fieldsobjectThe custom_metadata you sent, as {"fields": [...]}. Omitted when empty
phone_numberobjectcountry_code (e.g. +254) and number (national number, e.g. 700000000)
emailstringContact’s email address
created_atstringISO 8601 timestamp of creation
updated_atstringISO 8601 timestamp of last update

Error Responses

400 Bad Request

Errors use error_code, error_message and status_code. A number that is already a contact returns:

{ "error_code": "contact_exists", "error_message": "You are trying to add a contact with a phone number that has already been added", "status_code": 400 }

An invalid number returns invalid_phone; a malformed body returns invalid_form. Sandbox API keys get 403 (invalid_api_key_environment).

401 Unauthorized

{ "success": false, "message": "Unauthorized. Invalid API credentials.", "recipients": [] }

See Error Messages for every authentication error.