Contacts API
Create 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) (opens in a new tab)

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,
  "name": "John Doe",
  "phone_number": "0700000000",
  "email": "john@doe.com",
  "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
phone_numberstringContact's phone number
emailstringContact's email address
created_atstringISO 8601 timestamp of creation
updated_atstringISO 8601 timestamp of last update

Error Responses

400 Bad Request

{
  "error": "Invalid phone number format",
  "message": "The phone number must be a valid format"
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid API credentials"
}
Fetch GroupsDelete Contact