Upload Contacts in Bulk

This endpoint allows you to upload multiple contacts at once using an Excel file. This is ideal for adding large numbers of contacts to your HudumaSMS account without having to create them one by one.

Endpoint

POST /contacts/upload

Authentication

All requests must include your API token in the header:

X-Huduma: Bearer {your_api_token}

Request Body

The request must be a multipart/form-data request with the following parameter:

Parameter	Type	Required	Description
contacts	file	Yes	An Excel file (.xls or .xlsx) containing contact information

Excel File Format Requirements

Your Excel file should contain the following columns:

• names (Required): The contact's full name or identifier
• number (Required): The contact's phone number in international format (e.g., 255712345678)
• email (Optional): The contact's email address

Example Excel structure:

names	number	email
John Doe	255712345678	john.doe@example.com
Jane Smith	255787654321	jane.smith@example.com
David Johnson	255798765432	david.j@example.com

Response

Success Response (202 Accepted)

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

{
  "status": "202 ACCEPTED",
  "code": 0,
  "message": "Contacts upload initiated successfully",
  "timestamp": "2025-04-10T07:50:11.274Z",
  "reqId": "req-987654321",
  "path": "/contacts/upload",
  "data": {
    "jobId": "job-123456789",
    "expectedCount": 250,
    "status": "PROCESSING"
  }
}

Error Responses

Status Code	Description
400	Bad Request - Invalid file format or missing required file
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 file structure or data format
500	Internal Server Error - Server-side error

Error Response Format

{
  "status": "400 BAD REQUEST",
  "code": 4000,
  "message": "Invalid file format",
  "timestamp": "2025-04-10T07:50:11.275Z",
  "reqId": "req-987654321",
  "path": "/contacts/upload",
  "errors": [
    {
      "field": "contacts",
      "message": "Only Excel files (.xls or .xlsx) are supported",
      "rejectedValue": "contacts.csv",
      "rejectingValues": {}
    }
  ]
}

Code Examples

TypeScript Example

import axios from 'axios';

async function uploadContacts(
  apiToken: string,
  excelFile: File
): Promise<any> {
  // Validate file extension
  const extension = excelFile.name.split('.').pop()?.toLowerCase();
  if (extension !== 'xls' && extension !== 'xlsx') {
    throw new Error('Only Excel files (.xls or .xlsx) are supported');
  }

  const formData = new FormData();
  formData.append('contacts', excelFile);

  try {
    const response = await axios.post(
      'https://sms-api.huduma.cloud/api/v3/contacts/upload',
      formData,
      {
        headers: {
          'X-Huduma': `Bearer ${apiToken}`,
          'Content-Type': 'multipart/form-data'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Error uploading contacts:', error);
    throw error;
  }
}

// Example usage
const apiToken = 'your_api_token_here';
const fileInput = document.getElementById('fileInput') as HTMLInputElement;
const file = fileInput?.files?.[0];

if (file) {
  uploadContacts(apiToken, file)
    .then(response => {
      console.log('Contacts upload initiated:', response.data);
    })
    .catch(error => {
      console.error('Failed to upload contacts:', error.response?.data || error.message);
    });
} else {
  console.error('No file selected');
}

JavaScript Example

const axios = require('axios');

async function uploadContacts(apiToken, excelFile) {
  // Validate file extension
  const extension = excelFile.name.split('.').pop().toLowerCase();
  if (extension !== 'xls' && extension !== 'xlsx') {
    throw new Error('Only Excel files (.xls or .xlsx) are supported');
  }

  const formData = new FormData();
  formData.append('contacts', excelFile);

  try {
    const response = await axios.post(
      'https://sms-api.huduma.cloud/api/v3/contacts/upload',
      formData,
      {
        headers: {
          'X-Huduma': `Bearer ${apiToken}`,
          'Content-Type': 'multipart/form-data'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Error uploading contacts:', error);
    throw error;
  }
}

// Example usage
const apiToken = 'your_api_token_here';
const fileInput = document.getElementById('fileInput');
const file = fileInput?.files?.[0];

if (file) {
  uploadContacts(apiToken, file)
    .then(response => {
      console.log('Contacts upload initiated:', response.data);
    })
    .catch(error => {
      console.error('Failed to upload contacts:', error.response?.data || error.message);
    });
} else {
  console.error('No file selected');
}

Additional Notes

• Only Excel files (.xls or .xlsx) are supported for bulk uploads.
• The upload is processed asynchronously. The API returns a 202 Accepted response with a job ID that you can use to check the status of the upload.
• Phone numbers must be in international format with the country code (e.g., 255 for Tanzania) without the plus sign (+).
• The maximum file size allowed is 10MB.
• A single upload can contain up to 5,000 contacts.
• Duplicate phone numbers (within your account) will be updated rather than creating new contacts.