Create Contact

This endpoint allows you to create a new contact. Contacts can be used for managing recipients of your SMS messages and organizing your audience.

Endpoint

POST /contacts

Authentication

All requests must include your API token in the header:

X-Huduma: Bearer {your_api_token}

Request Body

Parameter	Type	Required	Description
names	string	Yes	The contact's full name or identifier
number	string	Yes	The contact's phone number (must be in international format, e.g., 255712345678)
email	string	No	The contact's email address

Example Request Body

{
  "names": "John Doe",
  "number": "255712345678",
  "email": "john.doe@example.com"
}

Response

Success Response (201 Created)

A successful request returns a JSON response with the following structure:

{
  "status": "201 CREATED",
  "code": 0,
  "message": "Contact created successfully",
  "timestamp": "2025-04-10T07:32:57.067Z",
  "reqId": "req-123456789",
  "path": "/contacts",
  "data": {
    "createdAt": "2025-04-10T07:32:57.067Z",
    "updatedAt": "2025-04-10T07:32:57.067Z",
    "id": 12345,
    "deletedAt": null,
    "names": "John Doe",
    "number": "255712345678",
    "email": "john.doe@example.com"
  }
}

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters or validation errors
401	Unauthorized - Invalid or missing API token
402	Payment Required - Account has payment issues
403	Forbidden - Insufficient permissions
404	Not Found - Resource not found
405	Method Not Allowed - Invalid HTTP method
422	Unprocessable Entity - Invalid input parameters
500	Internal Server Error - Server-side error

Error Response Format

{
  "status": "400 BAD REQUEST",
  "code": 4000,
  "message": "Invalid request parameters",
  "timestamp": "2025-04-10T07:32:57.068Z",
  "reqId": "req-123456789",
  "path": "/contacts",
  "errors": [
    {
      "field": "number",
      "message": "Must be a valid phone number in international format",
      "rejectedValue": "12345",
      "rejectingValues": {}
    }
  ]
}

Code Examples

TypeScript Example

import axios from 'axios';

interface ContactRequest {
  names: string;
  number: string;
  email?: string;
}

interface ContactResponse {
  status: string;
  code: number;
  message: string;
  timestamp: string;
  reqId: string;
  path: string;
  data: {
    createdAt: string;
    updatedAt: string;
    id: number;
    deletedAt: string | null;
    names: string;
    number: string;
    email: string | null;
  }
}

async function createContact(
  apiToken: string, 
  contactData: ContactRequest
): Promise<ContactResponse> {
  try {
    const response = await axios.post(
      'https://sms-api.huduma.cloud/api/v3/contacts',
      contactData,
      {
        headers: {
          'X-Huduma': `Bearer ${apiToken}`,
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Error creating contact:', error);
    throw error;
  }
}

// Example usage
const apiToken = 'your_api_token_here';
const newContact: ContactRequest = {
  names: 'Alice Smith',
  number: '255712345678',
  email: 'alice.smith@example.com'
};

createContact(apiToken, newContact)
  .then(response => {
    console.log('Contact created successfully:', response.data);
  })
  .catch(error => {
    console.error('Failed to create contact:', error.response?.data || error.message);
  });

JavaScript Example

const axios = require('axios');

async function createContact(apiToken, contactData) {
  try {
    const response = await axios.post(
      'https://sms-api.huduma.cloud/api/v3/contacts',
      contactData,
      {
        headers: {
          'X-Huduma': `Bearer ${apiToken}`,
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Error creating contact:', error);
    throw error;
  }
}

// Example usage
const apiToken = 'your_api_token_here';
const newContact = {
  names: 'Bob Johnson',
  number: '255787654321',
  email: 'bob.johnson@example.com'
};

createContact(apiToken, newContact)
  .then(response => {
    console.log('Contact created successfully:', response.data);
  })
  .catch(error => {
    console.error('Failed to create contact:', error.response?.data || error.message);
  });

Additional Notes

• Phone numbers must be in international format with the country code (e.g., 255 for Tanzania) Without plus sign(+).
• The email field is optional but should be a valid email address if provided.
• Each contact must have a unique phone number within your account.
• Maximum length for the names field is 100 characters.