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

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"
        }
      ]
    }
  }'

JavaScript


const apiKey = 'your_api_key';
const apiSecret = 'your_api_secret';
const credentials = btoa(`${apiKey}:${apiSecret}`);
 
const createContact = async (contactData) => {
  try {
    const response = await fetch('https://api.smsleopard.com/v1/contacts/create', {
      method: 'POST',
      headers: {
        'Authorization': `Basic ${credentials}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(contactData)
    });
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    const data = await response.json();
    console.log('Contact created:', data);
    return data;
  } catch (error) {
    console.error('Error creating contact:', error);
  }
};
 
// Example usage
const newContact = {
  name: "John Doe",
  phone_number: "0700000000",
  email: "john@doe.com",
  group_ids: [1, 2, 3],
  custom_metadata: {
    fields: [
      {
        name: "account",
        value: "12345"
      }
    ]
  }
};
 
createContact(newContact);

Python


import requests
from base64 import b64encode
import json
 
def create_contact(contact_data):
    api_key = 'your_api_key'
    api_secret = 'your_api_secret'
    
    credentials = b64encode(f'{api_key}:{api_secret}'.encode()).decode()
    
    headers = {
        'Authorization': f'Basic {credentials}',
        'Content-Type': 'application/json'
    }
    
    try:
        response = requests.post(
            'https://api.smsleopard.com/v1/contacts/create',
            headers=headers,
            json=contact_data
        )
        response.raise_for_status()
        
        data = response.json()
        print('Contact created:', json.dumps(data, indent=2))
        return data
    except requests.exceptions.RequestException as e:
        print(f'Error creating contact: {e}')
        return None
 
# Example usage
new_contact = {
    "name": "John Doe",
    "phone_number": "0700000000",
    "email": "john@doe.com",
    "group_ids": [1, 2, 3],
    "custom_metadata": {
        "fields": [
            {
                "name": "account",
                "value": "12345"
            }
        ]
    }
}
 
create_contact(new_contact)

PHP


<?php
function createContact($contactData) {
    $apiKey = 'your_api_key';
    $apiSecret = 'your_api_secret';
    $credentials = base64_encode($apiKey . ':' . $apiSecret);
    
    $headers = [
        'Authorization: Basic ' . $credentials,
        'Content-Type: application/json'
    ];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://api.smsleopard.com/v1/contacts/create');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($contactData));
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 201) {
        $data = json_decode($response, true);
        echo "Contact created: " . json_encode($data, JSON_PRETTY_PRINT);
        return $data;
    } else {
        echo "Error creating contact. HTTP Code: " . $httpCode;
        echo "\nResponse: " . $response;
        return null;
    }
}
 
// Example usage
$newContact = [
    "name" => "John Doe",
    "phone_number" => "0700000000",
    "email" => "john@doe.com",
    "group_ids" => [1, 2, 3],
    "custom_metadata" => [
        "fields" => [
            [
                "name" => "account",
                "value" => "12345"
            ]
        ]
    ]
];
 
createContact($newContact);
?>

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

Field	Type	Description
`id`	integer	Unique identifier for the created contact
`name`	string	Contact’s full name
`phone_number`	string	Contact’s phone number
`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


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

401 Unauthorized


{
  "error": "Unauthorized",
  "message": "Invalid API credentials"
}