Delete Contacts

This endpoint allows you to delete one or multiple contacts at once. You can choose to move contacts to trash (soft delete) or permanently delete them.

Endpoint

DELETE /contacts

Authentication

All requests must include your API token in the header:

X-Huduma: Bearer {your_api_token}

Request Body

Parameter	Type	Required	Description
trash	boolean	No	If set to true, contacts are moved to trash (soft delete). If false or omitted, contacts are permanently deleted
ids	array of numbers	No*	Array of contact IDs to delete
uuids	array of strings	No*	Array of contact UUIDs to delete

*Note: Either ids or uuids must be provided. You can use either or both methods to specify which contacts to delete.

Example Request Body

{
  "trash": true,
  "ids": [123, 456, 789],
  "uuids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"]
}

Response

Success Response (200 OK)

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

{
  "status": "200 OK",
  "code": 0,
  "message": "Contacts deleted successfully",
  "timestamp": "2025-04-10T07:56:47.801Z",
  "reqId": "req-123456789",
  "path": "/contacts",
  "data": [
    {
      "createdAt": "2025-04-10T07:56:47.801Z",
      "updatedAt": "2025-04-10T07:56:47.801Z",
      "id": 123,
      "deletedAt": "2025-04-10T07:56:47.801Z",
      "names": "John Doe",
      "number": "255712345678",
      "email": "john.doe@example.com"
    },
    {
      "createdAt": "2025-04-10T07:56:47.801Z",
      "updatedAt": "2025-04-10T07:56:47.801Z",
      "id": 456,
      "deletedAt": "2025-04-10T07:56:47.801Z",
      "names": "Jane Smith",
      "number": "255787654321",
      "email": "jane.smith@example.com"
    }
  ]
}

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API token
402	Payment Required - Account has payment issues
403	Forbidden - Insufficient permissions
404	Not Found - One or more contacts 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": "One or more contacts not found",
  "timestamp": "2025-04-10T07:56:47.815Z",
  "reqId": "req-123456789",
  "path": "/contacts",
  "errors": [
    {
      "field": "ids",
      "message": "Contact with ID 999 not found",
      "rejectedValue": 999,
      "rejectingValues": {}
    }
  ]
}

Code Examples

TypeScript Example

import axios from 'axios';

interface DeleteContactsRequest {
  trash?: boolean;
  ids?: number[];
  uuids?: string[];
}

interface DeleteContactsResponse {
  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 deleteContacts(
  apiToken: string,
  request: DeleteContactsRequest
): Promise<DeleteContactsResponse> {
  if (!request.ids?.length && !request.uuids?.length) {
    throw new Error('Either ids or uuids must be provided');
  }
  
  try {
    const response = await axios.delete(
      'https://api.huduma.cloud/sms/api/v3/contacts',
      {
        headers: {
          'X-Huduma': `Bearer ${apiToken}`,
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        },
        data: request
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Error deleting contacts:', error);
    throw error;
  }
}

// Example usage
const apiToken = 'your_api_token_here';
const deleteRequest: DeleteContactsRequest = {
  trash: true, // Move to trash instead of permanent deletion
  ids: [123, 456, 789]
};

deleteContacts(apiToken, deleteRequest)
  .then(response => {
    console.log(`${response.data.length} contacts moved to trash:`, response.data);
  })
  .catch(error => {
    console.error('Failed to delete contacts:', error.response?.data || error.message);
  });

JavaScript Example

const axios = require('axios');

async function deleteContacts(apiToken, request) {
  if ((!request.ids || request.ids.length === 0) && 
      (!request.uuids || request.uuids.length === 0)) {
    throw new Error('Either ids or uuids must be provided');
  }
  
  try {
    const response = await axios.delete(
      'https://api.huduma.cloud/sms/api/v3/contacts',
      {
        headers: {
          'X-Huduma': `Bearer ${apiToken}`,
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        },
        data: request
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Error deleting contacts:', error);
    throw error;
  }
}

// Example usage
const apiToken = 'your_api_token_here';
const deleteRequest = {
  trash: false, // Permanently delete
  uuids: ['3fa85f64-5717-4562-b3fc-2c963f66afa6']
};

deleteContacts(apiToken, deleteRequest)
  .then(response => {
    console.log(`${response.data.length} contacts permanently deleted:`, response.data);
  })
  .catch(error => {
    console.error('Failed to delete contacts:', error.response?.data || error.message);
  });

Additional Notes

• The trash parameter allows for soft deletion (moving contacts to trash) when set to true. This is useful if you might need to recover the contacts later.
• When using permanent deletion (trash set to false or omitted), contacts cannot be recovered.
• You can delete contacts by specifying either their numeric IDs or their UUIDs, or a combination of both.
• The response includes the complete information about the deleted contacts, including the deletedAt timestamp.
• Bulk deletion is processed as a single transaction. If any contact in the request cannot be deleted, none will be deleted and an error will be returned.