Send OTP

Endpoint

For sending messages, the base url is:

@bulk_base/api/v1

Method

Method URI
POST /send-otp

Request Params

Param Type Description
sender string (required) The Sender ID to send the message with.
phone string (required) Phone Number to receive the OTP (same format rules as SMS).
expiry_time integer (optional) OTP validity in seconds. Defaults to 300 (5 minutes).
character_type string (optional) OTP format: numeric (default), alpha, or mixed.
length integer (optional) OTP length. Defaults to 6.
correlator string (optional) Unique identifier generated by your system for tracking.
endpoint string (optional) Your delivery receipt endpoint.

Sample Request Header

{
    "Content-type: application/json",
    "Accept: application/json",
    "Authorization: Bearer 123456666"
}

Sample Request Body

{
    "sender": "BONGATECH",
    "phone": "254712345678",
    "expiry_time": 300,
    "character_type": "numeric",
    "length": 6,
    "correlator": "otp-789"
}

Sample Success Response

StatusCode 200

Content

{
    "status": true,
    "message": "Message successfully queued!",
    "data": {
        "correlator": 2,
        "uniqueId": "unique-string",
        "phone": "254XXXXXXXXX",
        "sms_units": 1
    }
}

Verify OTP

The Verify OTP endpoint allows you to confirm whether a one-time password (OTP) sent to a user’s phone is valid.
This step is typically used during login, registration, or sensitive transactions to ensure that the user has access
to the phone number they provided. The OTP must match the most recent, unexpired code issued to that phone number.

Method

Method URI
POST /verify-otp

Request Params

Request Params

Param Type Description
phone string (required) Phone number the OTP was sent to, in the same format as when requesting.
otp string (required) The OTP entered by the user.

Request Body |

{
    "phone": "07XXXXXXXX",
    "otp": "482195"
}

Sample Success Response

StatusCode 200

Content

{
    "status": true,
    "message": "OTP verified successfully"
}

Sample Error Response

Reason Invalid or Missing OTP

Content

{
    "status": false,
    "message": "Invalid OTP."
}

Delivery Receipts Structure

All Requested delivery receipts will be delivered via a POST method with the below structure.

{
    "phone": "254XXXXXXXXX",
    "correlator": 2,
    "uniqueId": "unique-string",
    "deliveryStatus": "DeliveredToTerminal",
    "deliveryTime": "2020-01-01 00:00:00"
}