Reference Documentation

Service endpoint

A service endpoint is a base URL that specifies the network address of an API service. One service might have multiple service endpoints. This service has the following service endpoint and all URIs below are relative to this service endpoint:

https://developers.smswithoutborders.com:14000

API V1 Endpoints

Action	Endpoint	Parameters	Request body
Send SMS	POST /v1/sms	None	auth_id = STRING twilio_account_sid = STRING twilio_auth_token = STRING twilio_service_sid = STRING twilio_from = STRING whitelist = [STRING] data = [{text = STRING, number = STRING, operator_name = STRING}] callback_url = STRING uuid = STRING
Get Phone number operator name	POST /v1/sms/operators	None	[{text = STRING, number = STRING}]
Update message status	PUT /v1/metrics/<uid>	uid = STRING	[{status = STRING, message = STRING}]

Warning

We advise you to use this endpoint safely in the back-end to avoid exposing your developer’s token to unauthorized persons.

Examples using curl

Send single SMS message

Note

To send messages using Twilio Messaging Service, twilio_account_sid, twilio_auth_token and, either twilio_service_sid or twilio_from fields should be present in the request body.

Phone numbers with country calling codes listed in the whitelist, will NOT receive messages through the Twilio Messaging Service.

Country calling codes listed in the whitelist field should begin with a + symbol (e.g “+237”).

Note

The uuid key is any random string provided by the user used to identify the request. If left empty, OpenAPI will populate the uuid key with a randomly generated uuid.

The callback_url will be invoked after the request is complete with a POST in the form:

{
    "errors": [{
        "operator_name":"",
        "number":"",
        "error_message": "",
        "timestamp": ""
        }],
    "uuid": ""
}

If the errors array is empty all messages were requested successfully.
callback_url field accepts multiple urls, seperate each with a comma. Example “callback_url”:”https://example.com,https://example1.com,https://example2.com”

The phone number format to be used in the request bodies of the API calls should be E.164.

curl --location --request POST 'https://developers.smswithoutborders.com:14000/v1/sms' \
--header 'Content-Type: application/json' \
--data-raw '{
"auth_id":"",
"twilio_account_sid": "",
"twilio_auth_token": "",
"twilio_service_sid": "",
"twilio_from": "",
"whitelist": ["+237"],
"data": [{
    "text":"",
    "number":""
    }],
"callback_url": "",
"uuid": ""
}'

Send bulk SMS messages

Note

To send messages using Twilio Messaging Service, twilio_account_sid, twilio_auth_token and, either twilio_service_sid or twilio_from fields should be present in the request body.

Phone numbers with country calling codes listed in the whitelist, will NOT receive messages through the Twilio Messaging Service.

Country calling codes listed in the whitelist field should begin with a + symbol (e.g “+237”).

Note

The uuid key is any random string provided by the user used to identify the request. If left empty, OpenAPI will populate the uuid key with a randomly generated uuid.

The callback_url will be invoked after the request is complete with a POST in the form:

{
    "errors": [{
        "operator_name":"",
        "number":"",
        "error_message": "",
        "timestamp": ""
        }],
    "uuid": ""
}

If the errors array is empty all messages were requested successfully.
callback_url field accepts multiple urls, seperate each with a comma. Example “callback_url”:”https://example.com,https://example1.com,https://example2.com”

The phone number format to be used in the request bodies of the API calls should be E.164.

curl --location --request POST 'https://developers.smswithoutborders.com:14000/v1/sms' \
--header 'Content-Type: application/json' \
--data-raw '{
"auth_id":"",
"twilio_account_sid": "",
"twilio_auth_token": "",
"twilio_service_sid": "",
"twilio_from": "",
"whitelist": ["+237"],
"data": [{
    "text":"",
    "number":""
    },
    {
    "text":"",
    "number":""
    },
    {
    "text":"",
    "number":""
    }],
"callback_url": "",
"uuid": ""
}'

Get Phone Number operator name

The text key is optional and can be left out of the request body.

curl --location --request POST 'https://developers.smswithoutborders.com:14000/v1/sms/operators' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
    "text":"",
    "number":""
    },
    {
    "text":"",
    "number":""
    },
    {
    "text":"",
    "number":""
    }
]'

Update message status

There are two steps involved in the update process

1. Authorization

Note

This step requires the user to have an SMSWithoutBorders Developer Back-end server setup.

The user has to provide the following in the request body:

Auth key (From an SMSWithoutBorders Developer Back-end server)
Auth id (From an SMSWithoutBorders Developer Back-end server)

The user also must configure their header to:

Content-Type = application/json

Here is an example. Running SMSWithoutBorders Developer Back-end server locally on port 3000

curl --location --request POST 'http://localhost:3000/v1/authenticate' \
--header 'Content-Type: application/json' \
--data-raw '{
    "auth_key": "",
    "auth_id": ""
}'

If successful a cookie is set on the user’s agent valid for two hours. The cookie is used to track the user’s seesion. Also the response should have a status of 200 and the body should contain an empty object

{}

2. Update status

Note

This step requires the user to have an SMSWithoutBorders OpenAPI setup and configured to communitcate with their SMSWithoutBorders Developer Back-end server.

The user has to make sure SMSWithoutBorders Developer Back-end server is running.

The user has to provide the following in the request body:

status (The message status. Either sent, delivered, failed, requested)
message (Information regarding the message status)

The user also must configure their header to:

Content-Type = application/json

Here is an example. Running SMSWithoutBorders OpenAPI locally on port 4000

curl --location --request POST 'http://localhost:4000/v1/metrics/<uid>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "status": "",
    "message": ""
}'

If successful the response should have a status of 200.