HudumaSMS Docs

Appearance

Create a Sender ID ​

A Sender ID is a unique alphanumeric identity that appears as the sender of your SMS messages. This guide explains how to create a new Sender ID in HudumaSMS.

Overview ​

Sender IDs allow you to brand your messages and build recognition with your audience. When creating a Sender ID, consider the following:

  • Name: A descriptive name for internal reference
  • Purpose: Whether the Sender ID is for transactional, promotional, or notification messages
  • Access: Whether the Sender ID is private or public to other HudumaSMS Users
  • Sample: A sample message that demonstrates how you'll use the Sender ID

API Endpoint ​

POST /sender-ids

Request Parameters ​

ParameterTypeRequiredDescription
namestringYesA recognizable name for the Sender ID (1-11 characters)
purposestringYesPurpose of the Sender ID (TRANSACTIONAL, PROMOTIONAL, or NOTIFICATION)
accessstringYesAccess level for the Sender ID (PRIVATE or PUBLIC)
samplestringYesSample message demonstrating intended usage

Sample Request ​

Using TypeScript ​

typescript
import axios from 'axios';

interface SenderIdRequest {
  name: string;
  purpose: 'TRANSACTIONAL' | 'PROMOTIONAL' | 'NOTIFICATION';
  access: 'PRIVATE' | 'PUBLIC';
  sample: string;
}

async function createSenderId(apiToken: string, senderIdData: SenderIdRequest) {
  try {
    const response = await axios.post(
      'https://api.huduma.cloud/sms/api/v3/sender-ids',
      senderIdData,
      {
        headers: {
          'X-Huduma': `Bearer ${apiToken}`,
          'Content-Type': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Error creating sender ID:', error);
    throw error;
  }
}

// Example usage
const apiToken = 'your_api_token_here';
const newSenderId: SenderIdRequest = {
  name: 'MYCOMPANY',
  purpose: 'TRANSACTIONAL',
  access: 'PRIVATE',
  sample: 'Your verification code is 123456. Valid for 10 minutes.'
};

createSenderId(apiToken, newSenderId)
  .then(response => {
    console.log('Sender ID created successfully:', response);
  })
  .catch(error => {
    console.error('Failed to create sender ID:', error.response?.data || error.message);
  });

Response ​

A successful request returns HTTP status 201 (Created) with the newly created Sender ID details:

json
{
  "status": "100 CONTINUE",
  "code": 0,
  "message": "string",
  "timestamp": "2025-04-10T07:00:03.466Z",
  "reqId": "string",
  "path": "string",
  "data": {
    "id": 0,
    "name": "string",
    "purpose": "TRANSACTIONAL",
    "sample": "string",
    "access": "PRIVATE",
    "addedBy": {
      "id": 0,
      "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "firstName": "string",
      "lastName": "string",
      "gender": "string",
      "email": "string",
      "phone": "string",
      "address": "string"
    },
    "status": "string",
    "deletedAt": "2025-04-10T07:00:03.466Z",
    "createdAt": "2025-04-10T07:00:03.466Z",
    "updatedAt": "2025-04-10T07:00:03.466Z"
  }
}

Sender ID Status ​

After creation, your Sender ID will be in PENDING status while it awaits approval. You'll receive a notification once it's approved and ready for use.

Response Status Codes ​

The API may return the following status codes:

400 - Bad Request ​

Returned when the request contains invalid parameters.

json
{
  "status": "100 CONTINUE",
  "code": 0,
  "message": "string",
  "timestamp": "2025-04-10T07:13:07.670Z",
  "reqId": "string",
  "path": "string",
  "errors": [
    {
      "field": "string",
      "message": "string",
      "rejectedValue": {},
      "rejectingValues": {}
    }
  ]
}

401 - Unauthorized ​

Returned when authentication fails or API token is invalid.

json
{
  "status": "100 CONTINUE",
  "code": 0,
  "message": "string",
  "timestamp": "2025-04-10T07:13:07.671Z",
  "reqId": "string",
  "path": "string",
  "errors": [
    {
      "field": "string",
      "message": "string",
      "rejectedValue": {},
      "rejectingValues": {}
    }
  ]
}

402 - Payment Required ​

Returned when there are payment or account balance issues.

json
{
  "status": "100 CONTINUE",
  "code": 0,
  "message": "string",
  "timestamp": "2025-04-10T07:13:07.672Z",
  "reqId": "string",
  "path": "string",
  "errors": [
    {
      "field": "string",
      "message": "string",
      "rejectedValue": {},
      "rejectingValues": {}
    }
  ]
}

403 - Forbidden ​

Returned when you don't have permission to create a Sender ID.

json
{
  "status": "100 CONTINUE",
  "code": 0,
  "message": "string",
  "timestamp": "2025-04-10T07:13:07.673Z",
  "reqId": "string",
  "path": "string",
  "errors": [
    {
      "field": "string",
      "message": "string",
      "rejectedValue": {},
      "rejectingValues": {}
    }
  ]
}

404 - Not Found ​

Returned when the requested resource could not be found.

json
{
  "status": "100 CONTINUE",
  "code": 0,
  "message": "string",
  "timestamp": "2025-04-10T07:13:07.675Z",
  "reqId": "string",
  "path": "string",
  "errors": [
    {
      "field": "string",
      "message": "string",
      "rejectedValue": {},
      "rejectingValues": {}
    }
  ]
}

422 - Unprocessable Entity ​

Returned when the request is well-formed but cannot be processed due to semantic errors.

json
{
  "status": "100 CONTINUE",
  "code": 0,
  "message": "string",
  "timestamp": "2025-04-10T07:13:07.677Z",
  "reqId": "string",
  "path": "string",
  "errors": [
    {
      "field": "string",
      "message": "string",
      "rejectedValue": {},
      "rejectingValues": {}
    }
  ]
}

500 - Internal Server Error ​

Returned when an unexpected error occurs on the server.

json
{
  "status": "100 CONTINUE",
  "code": 0,
  "message": "string",
  "timestamp": "2025-04-10T07:13:07.678Z",
  "reqId": "string",
  "path": "string",
  "errors": [
    {
      "field": "string",
      "message": "string",
      "rejectedValue": {},
      "rejectingValues": {}
    }
  ]
}

Best Practices ​

  1. Choose meaningful names: Use recognizable brand names that recipients will trust
  2. Provide clear samples: Your sample message should accurately represent how you'll use the Sender ID
  3. Select the correct purpose: Choose the appropriate purpose that matches your messaging needs
  4. Plan ahead: Sender ID approval can take 1-3 business weeks, so create them before you need them