Voice SMS API Documentation

Getting Started

The current API version is v1. All Voice SMS endpoints use the following base path:

https://digitalmediaplus.org/api/v1/voice-sms

Create an API key from your Voice SMS API Access page. The full key is displayed only when it is created or regenerated, so copy it and store it securely.

Authentication

Send your API key as a Bearer token in the Authorization header.

Authorization: Bearer dmp_live_your_api_key

/api/v1/voice-sms/campaigns

Every campaign submission requires a unique Idempotency-Key header. Repeating the same request with the same key will not create a duplicate campaign.

Recording example

curl -X POST \
  https://digitalmediaplus.org/api/v1/voice-sms/campaigns \
  -H "Authorization: Bearer dmp_live_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10482-voice-call" \
  -d '{
    "name": "Customer Notification",
    "message_type": "recording",
    "recording_id": 2,
    "sender_id": 18,
    "recipients": [
      "08012345678",
      "2348098765432"
    ],
    "delivery_type": "immediate"
  }'

Required fields

/api/v1/voice-sms/recordings

Returns recordings belonging to your account that are ready for use. Use the returned id as recording_id when submitting a recording campaign.

Text-to-Speech

When Text-to-Speech is enabled for the service, set message_type to tts and provide tts_message. You may also provide a supported tts_voice.

{
  "name": "Appointment Reminder",
  "message_type": "tts",
  "tts_message": "This is a reminder about your appointment tomorrow.",
  "tts_voice": "supported_voice",
  "recipients": ["08012345678"],
  "delivery_type": "immediate"
}

Use the Capabilities endpoint to retrieve the currently enabled TTS settings and available voices.

/api/v1/voice-sms/sender-ids

Returns Sender IDs currently available to your account. Depending on service configuration these may include the default sender, verified phone numbers and assigned virtual numbers.

Pass the returned numeric Sender ID as sender_id when submitting a campaign. If your account is using the platform default sender, the API may return it with a null ID.

Verify Your Phone Number as a Sender ID

You can verify a Nigerian mobile number that you control. Verification is completed using a phone call and a four-digit code.

1. Request verification

POST /api/v1/voice-sms/sender-ids/request-code

{
  "phone_number": "08012345678"
}

A successful request returns the new sender_id.

2. Confirm the code

POST /api/v1/voice-sms/sender-ids/{senderId}/confirm-code

{
  "verification_code": "1234"
}

After successful confirmation, the number becomes a verified Sender ID and can be returned by the Sender IDs endpoint.

Scheduling

To schedule a campaign, set delivery_type to scheduled and provide scheduled_at.

{
  "delivery_type": "scheduled",
  "scheduled_at": "2026-09-23 10:30:00"
}

/api/v1/voice-sms/campaigns?per_page=20

Returns your campaigns in newest-first order. Pagination supports between 1 and 100 records per page.

Campaign records include reserved, used and returned units, message type, delivery type, campaign status and timestamps.

/api/v1/voice-sms/campaigns/{campaign_id}

Returns campaign delivery totals, success percentage, unit accounting and recipient-level results.

Recipient-facing delivery statuses are normalised to Delivered, No Response or Sending.

/api/v1/voice-sms/balance

Returns units_balance, units_reserved and units_available.

/api/v1/voice-sms/capabilities

Use this endpoint instead of hard-coding service limits. It reports recording limits, Text-to-Speech availability and voices, Sender ID capabilities, billing seconds per unit, and supported delivery modes.

/api/v1/voice-sms/account

Returns information about the client account authenticated by the current API key.

Error Responses

API errors use a consistent JSON structure:

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Description of the error."
  }
}

Rate Limits