List Sender IDs

This endpoint allows you to retrieve a list of sender IDs associated with your account. You can filter, sort, and paginate the results using various query parameters.

Endpoint

GET /sender-ids

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.
sort	array[string]	No	Fields to sort by (e.g., ["name:asc", "createdAt:desc"]).
userId	integer	No	Filter sender IDs by specific user ID.
query	string	No	Search term to filter sender IDs by name or other attributes.

Response

Success Response (200 OK)

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

{
  "status": "200 OK",
  "code": 0,
  "message": "Sender IDs retrieved successfully",
  "timestamp": "2025-04-10T07:17:56.907Z",
  "reqId": "req-123456789",
  "path": "/sender-ids",
  "data": {
    "content": [
      {
        "id": 123,
        "name": "MYCOMPANY",
        "purpose": "TRANSACTIONAL",
        "access": "PRIVATE",
        "sample": "Your verification code is 123456. Valid for 10 minutes.",
        "status": "APPROVED",
        "createdAt": "2025-03-15T14:30:22Z",
        "updatedAt": "2025-03-15T14:32:10Z"
      },
      {
        "id": 124,
        "name": "ALERTS",
        "purpose": "NOTIFICATION",
        "access": "PRIVATE",
        "sample": "Payment of $50.00 received. Thank you for your business.",
        "status": "PENDING",
        "createdAt": "2025-04-05T09:22:15Z",
        "updatedAt": "2025-04-05T09:22:15Z"
      }
    ],
    "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:17:56.909Z",
  "reqId": "req-123456789",
  "path": "/sender-ids",
  "errors": [
    {
      "field": "records",
      "message": "Must be a positive integer",
      "rejectedValue": -5,
      "rejectingValues": {}
    }
  ]
}

Code Examples

TypeScript Example

import axios from 'axios';

interface SenderIdListParams {
  records?: number;
  page?: number;
  sort?: string[];
  userId?: number;
  query?: string;
}

interface SenderIdResponse {
  status: string;
  code: number;
  message: string;
  timestamp: string;
  reqId: string;
  path: string;
  data: {
    content: Array<{
      id: number;
      name: string;
      purpose: 'TRANSACTIONAL' | 'PROMOTIONAL' | 'NOTIFICATION';
      access: 'PRIVATE' | 'PUBLIC';
      sample: string;
      status: 'PENDING' | 'APPROVED' | 'REJECTED';
      createdAt: string;
      updatedAt: string;
    }>;
    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 listSenderIds(
  apiToken: string,
  params: SenderIdListParams = {}
): Promise<SenderIdResponse> {
  try {
    const response = await axios.get(
      'https://sms-api.huduma.cloud/api/v3/sender-ids',
      {
        params,
        headers: {
          'X-Huduma': `Bearer ${apiToken}`,
          'Accept': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Error listing sender IDs:', error);
    throw error;
  }
}

// Example usage
const apiToken = 'your_api_token_here';

// List sender IDs with pagination and sorting
listSenderIds(apiToken, {
  records: 20,
  page: 1,
  sort: ['name:asc'],
  query: 'company'
})
  .then(response => {
    console.log(`Found ${response.data.totalElements} sender IDs`);
    console.log('First page of results:', response.data.content);
  })
  .catch(error => {
    console.error('Failed to list sender IDs:', error.response?.data || error.message);
  });

JavaScript Example

const axios = require('axios');

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

// Example usage
const apiToken = 'your_api_token_here';

// List all sender IDs
listSenderIds(apiToken)
  .then(response => {
    console.log('Sender IDs retrieved successfully:', response);
  })
  .catch(error => {
    console.error('Failed to list sender IDs:', error.response?.data || error.message);
  });

Additional Notes

• The maximum number of records per page is 100.
• Sorting is available on the following fields: name, purpose, access, status, createdAt, updatedAt.
• The query parameter searches across sender ID names and descriptions.
• You must have the appropriate permissions to view sender IDs.