API Reference

Base URL And Authentication

https://api.notify.africa

Authorization: Bearer ntfy_your_api_key
Content-Type: application/json

The key must include the VOICE service grant. Every operation is scoped to the customer that owns the key and requires an active Voice subscription.

Endpoint Inventory

Method	Path	Success	Reference
`POST`	`/api/v1/voice-api/calls`	`202` wrapped	Start call
`GET`	`/api/v1/voice-api/calls`	`200` wrapped	List calls
`GET`	`/api/v1/voice-api/calls/{callSessionId}`	`200` wrapped	Get call

Success Envelope

{
  "status": 200,
  "message": "Success",
  "timestamp": "2026-09-10T09:00:00.000Z",
  "path": "/api/v1/voice-api/calls",
  "data": {}
}

Start Call

POST /api/v1/voice-api/calls

Request Body

Field	Type	Required	Validation
`customerNumber`	string	Yes	E.164 number matching `+` and 7 to 15 total digits

{
  "customerNumber": "+255700000001"
}

Success

HTTP 202 with:

{
  "status": 202,
  "message": "Success",
  "data": {
    "callAttemptId": "voice-call-attempt-550e8400-e29b-41d4-a716-446655440000",
    "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

List Calls

GET /api/v1/voice-api/calls

Query Parameters

Parameter	Type	Required	Notes
`q`	string	No	Search session ID, caller number, or destination number
`currentPage`	number	No	Page number
`pageSize`	number	No	Page size
`sortBy`	string	No	Sort field
`sortOrder`	`ASC` or `DESC`	No	Sort direction

Success Data

Each returned item uses the Voice call session summary shape:

Field	Type	Notes
`id`	string	Notify Africa session row ID
`callAttemptId`	string	Backend-generated call attempt ID
`direction`	string	Usually `OUTBOUND` for developer-started calls
`callerNumber`	string	Voice source number
`destinationNumber`	string	Called customer number
`status`	string	Current call status
`recordingMediaId`	string or null	Archived recording media ID when available
`startedAt`	string or null	Start timestamp
`endedAt`	string or null	End timestamp

Get Call

GET /api/v1/voice-api/calls/{callSessionId}

Path Parameters

Parameter	Type	Required	Validation
`callSessionId`	string	Yes	Voice call session row ID or backend call attempt ID; max 128 characters

Success Data

Returns the full Voice call session shape. Compared with list results, a retrieved call can include recordingMedia with temporary download URL metadata when recording media is archived.

On this page