Create Contact
Creates a new contact record in your account.
Endpoint
POST https://api.smsleopard.com/v1/contacts/createAuthentication
This endpoint requires Basic Authentication using your API credentials. Click to Generate Credentials (API Keys and Secrets)
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
phone_number | string | Yes | Must be a valid phone number |
name | string | No | Contact’s full name |
email | string | No | Contact’s email address |
group_ids | array | No | Array of group IDs to add the contact to |
custom_metadata | object | No | Additional attributes about the contact |
Custom Metadata Structure
{
"custom_metadata": {
"fields": [
{
"name": "field_name",
"value": "field_value"
}
]
}
}Code Examples
cURL
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
| Field | Type | Description |
|---|---|---|
id | integer | Unique identifier for the created contact |
name | string | Contact’s full name |
custom_fields | object | The custom_metadata you sent, as {"fields": [...]}. Omitted when empty |
phone_number | object | country_code (e.g. +254) and number (national number, e.g. 700000000) |
email | string | Contact’s email address |
created_at | string | ISO 8601 timestamp of creation |
updated_at | string | ISO 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.