Promptxt API Guide

The API allows a third party to send SMS messages and to retrieve reporting information. This document is intended for those parties who wish to develop applications that make use of the API.

All methods in the guide use this base end-point:



In order to use the API you must obtain an access token and include it as part of the headers for each request. This token identifies you as a valid user of the service. The API implements the standardized OAuth 2.0 bearer token specification already supported by many HTTP clients.

Autorization: Bearer <token>

API tokens can be generated from the Promptxt application.

Send messages

To send a text message with a single request, it is necessary to submit a JSON data payload as a POST operation to the end-point on the Promptxt API server. This operation must provide an access token to identify the sender of the message and at least two parameters describing the message data.

POST /sendsms

Parameter Required Description
text Required The message text you wish to send. Messages exceeding 160 characters will be split and sent separately.
to Required The phone number to which you wish to the send the message. The number must be prefixed with the international dialing code of the destination country.
tag Optional The senders optional custom tag or reference.

Sample JSON payload

{"text":"Test message","to": "12154356264"}

The content type must be set to application/json.

Content-Type: application/json

This cURL command shows how to send the parameters as data with the access token and content type as part of the header.

curl -X POST -H "Authorization: Bearer b42486249233da89afc9d8049b77fd230214eb2e7cdd67bc074bba2b3dfc2ede" -H "Content-Type: application/json" -d '{"text":"Test message","to":"12154356264"}'

Server responses

The API will return one of these codes. Only a 200 code with status: 'ok' is successful. Otherwise the response will return an error object with the status code and error message.

HTTP status code Status Message
200 ok Pending delivery
401 1 Unauthorized
400 2 Bad message format
404 3 No route found
500 4 Custom message

Reply callback

The inbound gateway provided allows third parties to capture data from users who opt-in or opt-out of phone lists. The server will handle the mobile originated reply from the user according to the account settings, and then send a callback is made to the third party server using the HTTP protocol.

Receiving a callback

The third party must provide a callback end-point URL to which the server can send parameters via GET, preferably over https. The callback end-point URL should provide a response of '1' for success and '0' for failure. There must be a response within 20 seconds otherwise a response of '0' is assumed. Auto-responses are only sent for '1' response codes.

The following parameters are sent:

Parameter Description
keyword Phone list keyword
mobile Mobile number of subscriber, e.g. 16463211164
type Type 1 is opt-in. Type 2 is opt-out
param Additional parameter sent from the user. Typically the word that follows the keyword.


Here the user has sent answer 'b' to the WINACAR list. The 'b' part is sent as the parameter.

Callback procedure

The procedure for sending callback requests is best demonstrated with some examples.

An opt-in request is sent using the following query string:

An opt-in request with parameter is sent using the following query string:

An opt-out request is sent using the following query string:

Server responses

The third party system will return one of these codes following a GET operation.

Code Message
1 Request successfully received
0 Request failed

To enable the reply callback service please contact a member of our team.

Opt-out numbers

Get a list of opted-out numbers

Numbers that have replied with STOP messages and no longer wish to be contacted.

GET /numbers/optouts

The server will return an array of numbers.

{ "numbers": ["16463211164","17354654633"] }

Add opt-out number

POST /numbers/optouts

Parameter Description
number The handset number that should be blocked

{ "number":"16463211164" }

The server will return with a success or fail message.

{ "status": 0, "message":"Added opt-out number" } { "status": 3, "message":"Bad format" }