Update Contact

This endpoint allows you to update an existing contact's information by specifying the contact ID.

Endpoint

PUT /contacts/{contactId}

Authentication

All requests must include your API token in the header:

X-Huduma: Bearer {your_api_token}

Path Parameters

Parameter	Type	Required	Description
contactId	integer	Yes	The unique identifier of the contact to update

Request Body

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

Note: At least one of the request body parameters must be provided to update the contact.

Example Request Body

{
  "names": "John Smith",
  "number": "2554712345678",
  "email": "john.smith@example.com"
}

Response

Success Response (200 OK)

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

{
  "status": "200 OK",
  "code": 0,
  "message": "Contact updated successfully",
  "timestamp": "2025-04-10T07:38:51.750Z",
  "reqId": "req-123456789",
  "path": "/contacts/12345",
  "data": {
    "createdAt": "2025-03-15T14:30:22Z",
    "updatedAt": "2025-04-10T07:38:51.750Z",
    "id": 12345,
    "deletedAt": null,
    "names": "John Smith",
    "number": "2554712345678",
    "email": "john.smith@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 to update this contact
404	Not Found - Contact with specified ID 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": "404 NOT FOUND",
  "code": 4040,
  "message": "Contact not found",
  "timestamp": "2025-04-10T07:38:51.756Z",
  "reqId": "req-123456789",
  "path": "/contacts/99999",
  "errors": [
    {
      "field": "contactId",
      "message": "Contact with ID 99999 does not exist",
      "rejectedValue": 99999,
      "rejectingValues": {}
    }
  ]
}

Code Examples

TypeScript Example

import axios from 'axios';

interface ContactUpdateRequest {
  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 updateContact(
  apiToken: string,
  contactId: number,
  updateData: ContactUpdateRequest
): Promise<ContactResponse> {
  try {
    const response = await axios.put(
      `https://api.huduma.cloud/sms/api/v3/contacts/${contactId}`,
      updateData,
      {
        headers: {
          'X-Huduma': `Bearer ${apiToken}`,
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error(`Error updating contact ${contactId}:`, error);
    throw error;
  }
}

// Example usage
const apiToken = 'your_api_token_here';
const contactId = 12345;
const contactUpdates: ContactUpdateRequest = {
  names: 'John Smith',
  email: 'john.smith@newdomain.com'
};

updateContact(apiToken, contactId, contactUpdates)
  .then(response => {
    console.log('Contact updated successfully:', response.data);
  })
  .catch(error => {
    console.error('Failed to update contact:', error.response?.data || error.message);
  });

JavaScript Example

const axios = require('axios');

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

// Example usage
const apiToken = 'your_api_token_here';
const contactId = 12345;
const contactUpdates = {
  number: '255789012345' // Update only the phone number
};

updateContact(apiToken, contactId, contactUpdates)
  .then(response => {
    console.log('Contact updated successfully:', response.data);
  })
  .catch(error => {
    console.error('Failed to update contact:', error.response?.data || error.message);
  });

Additional Notes

• You only need to include the fields you want to update in the request body. Omitted fields will remain unchanged.
• If you want to remove a value (like an email address), send an empty string ("") for that field.
• Phone numbers must be in international format with the country code (e.g., 255 for Tanzania).
• Each contact must have a unique phone number within your account.
• The createdAt field will remain unchanged during updates.
• The updatedAt field will be automatically updated to the current timestamp.
• Maximum length for the names field is 100 characters.