List Contacts

This endpoint allows you to retrieve a paginated list of contacts . You can filter the results and control pagination using query parameters.

Endpoint

GET /contacts

Authentication

All requests must include your API token in the header:

X-Huduma: Bearer {your_api_token}

Query Parameters

Parameter	Type	Required	Description
records	integer	No	Number of records to return per page. Default is 10.
page	integer	No	Page number for pagination. Default is 1.
userId	integer	No	Filter contacts by specific user ID (for admin accounts).
query	string	No	Search term to filter contacts by name, number, or email.

Response

Success Response (200 OK)

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

{
  "status": "200 OK",
  "code": 0,
  "message": "Contacts retrieved successfully",
  "timestamp": "2025-04-10T07:45:16.445Z",
  "reqId": "req-123456789",
  "path": "/contacts",
  "data": {
    "content": [
      {
        "id": 12345,
        "names": "John Smith",
        "number": "255712345678",
        "email": "john.smith@example.com",
        "createdAt": "2025-03-15T14:30:22Z",
        "updatedAt": "2025-04-05T09:22:15Z",
        "deletedAt": null
      },
      {
        "id": 12346,
        "names": "Alice Johnson",
        "number": "255723456789",
        "email": "alice.johnson@example.com",
        "createdAt": "2025-03-17T10:15:42Z",
        "updatedAt": "2025-03-17T10:15:42Z",
        "deletedAt": null
      }
    ],
    "totalElements": 45,
    "totalPages": 5,
    "size": 10,
    "number": 1,
    "sort": {
      "sorted": true,
      "unsorted": false,
      "empty": false
    },
    "first": true,
    "last": false,
    "numberOfElements": 10,
    "empty": false
  }
}

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 - 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:45:16.446Z",
  "reqId": "req-123456789",
  "path": "/contacts",
  "errors": [
    {
      "field": "records",
      "message": "Must be a positive integer",
      "rejectedValue": -5,
      "rejectingValues": {}
    }
  ]
}

Code Examples

TypeScript Example

import axios from 'axios';

interface ContactListParams {
  records?: number;
  page?: number;
  userId?: number;
  query?: string;
}

interface Contact {
  id: number;
  names: string;
  number: string;
  email: string | null;
  createdAt: string;
  updatedAt: string;
  deletedAt: string | null;
}

interface ContactListResponse {
  status: string;
  code: number;
  message: string;
  timestamp: string;
  reqId: string;
  path: string;
  data: {
    content: Contact[];
    totalElements: number;
    totalPages: number;
    size: number;
    number: number;
    sort: {
      sorted: boolean;
      unsorted: boolean;
      empty: boolean;
    };
    first: boolean;
    last: boolean;
    numberOfElements: number;
    empty: boolean;
  }
}

async function listContacts(
  apiToken: string,
  params: ContactListParams = {}
): Promise<ContactListResponse> {
  try {
    const response = await axios.get(
      'https://sms-api.huduma.cloud/api/v3/contacts',
      {
        params,
        headers: {
          'X-Huduma': `Bearer ${apiToken}`,
          'Accept': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Error listing contacts:', error);
    throw error;
  }
}

// Example usage
const apiToken = 'your_api_token_here';

// List contacts with pagination and search
listContacts(apiToken, {
  records: 20,
  page: 1,
  query: 'john'
})
  .then(response => {
    console.log(`Found ${response.data.totalElements} contacts`);
    console.log('First page of results:', response.data.content);
    
    // Process each contact
    response.data.content.forEach(contact => {
      console.log(`${contact.names}: ${contact.number}`);
    });
  })
  .catch(error => {
    console.error('Failed to list contacts:', error.response?.data || error.message);
  });

JavaScript Example

const axios = require('axios');

async function listContacts(apiToken, params = {}) {
  try {
    const response = await axios.get(
      'https://sms-api.huduma.cloud/api/v3/contacts',
      {
        params,
        headers: {
          'X-Huduma': `Bearer ${apiToken}`,
          'Accept': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Error listing contacts:', error);
    throw error;
  }
}

// Example usage
const apiToken = 'your_api_token_here';

// List all contacts (first page)
listContacts(apiToken)
  .then(response => {
    console.log(`Found ${response.data.totalElements} contacts`);
    
    // Display contact information
    response.data.content.forEach(contact => {
      console.log(`ID: ${contact.id}, Name: ${contact.names}, Number: ${contact.number}`);
    });
    
    // Check if there are more pages
    if (response.data.totalPages > 1) {
      console.log(`There are ${response.data.totalPages} pages of contacts available.`);
    }
  })
  .catch(error => {
    console.error('Failed to list contacts:', error.response?.data || error.message);
  });

Additional Notes

• The maximum number of records per page is 100.
• The query parameter searches across contact names, phone numbers, and email addresses.
• Results are sorted by creation date by default (newest first).
• The deletedAt field will be null for active contacts. If it contains a timestamp, the contact has been soft-deleted.
• For admin accounts, the userId parameter can be used to filter contacts by specific user.
• Contacts are returned in pages with metadata about the total number of records and pages.