Sms Api

How it Works

Our SMS API is a JSON-based synchronous API designed for ease of use, allowing you to send and receive SMS messages.

Considerations

Before integrating with this API, please consider the following:

Treat your account details and credentials as confidential. You are responsible for each request submitted.
All submissions to the system are audited for management and security purposes.
If you submit duplicate lookups, you will be charged for each individual submission.

API

The first step is to set up an API token, you can generate this within your account under "Profile" -> "API Authentication". Make sure to set up the correct token for your needs and never share a private token with an end user.

It is also important to ensure you have enough credits. If you don't have credits yet, you can purchase them from within your account or by contacting us at 0203 856 0422.

Making Requests

All API requests should be made to our subdomain https://api.datasoap.co.uk/ using SSL on port 443, the content should be in JSON format and must include your token in an authentication header:

Authorization:

Bearer: f07772e880ae4789b5a964c91a151as1f1fee11d53as64807bd5f76f03b4333fa

The above token is an example and must be replaced with your own token.

Sending Messages

This will queue single messages to be sent and will return back an ID, which can be checked later for deliverability

Note: You can only send from your approved SMS headers and will be prevented from sending to anyone in the associated unsubscribe group

Method (POST)

https://api.datasoap.co.uk/v1/sms/single

Request

{
  "to": "07976123456",
  "from": "DataSoap",
  "message": "Hi John...... etc"
}

Response

{
  "id": 1634215,
  "status": "Pending"
}

The status code will be either "Pending" or "Failed" on the initial request.

If there is an error, we will respond with an error field containing the relevant information, examples are available in Errors section.

Checking status

Gets the current status of a message, which can be used to determine the deliverability of a message.

Method (GET)

https://api.datasoap.co.uk/v1/sms/status/{id}

Response

{
  "id": "1634215",
  "status": "Delivered"
}

The status codes are as follows::

Status	Description
Pending	Message is queued for sending and has not been sent yet
Sent	The message has been sent
Delivered	Mobile network has marked the message as delivered
Undeliverable	Unable to deliver the message, this could be due to a network fault or the number might not be valid

Sent Messages

Provides a list of all the messages that have been sent in a pagination format

Method (POST)

https://api.datasoap.co.uk/v1/sms/sent

Request

{
  "pageSize": 10,
  "pageNumber": 1,
  "from": "No Reply",
  "to": "07976123456",
  "date": {
    "from": "2023-01-07T11:08:22.897Z",
    "to": "2024-12-07T11:08:22.897Z"
  }
}

All the fields are optional and are used to filter the returned data, you can remove the ones you do not need.

Response

{
  "data": [
    {
      "id": 1634215,
      "from": "DataSoap",
      "to": "+447976123456",
      "message": "Hi John...... etc",
      "sentOn": "2023-01-31T11:45:40.363"
    },
    {
      "id": 1634214,
      "from": "NoReply",
      "to": "+447976123456",
      "message": "Your 2FA code is 123456",
      "sentOn": "2023-01-31T11:45:40.363"
    }
]
}

Received Messages

Provides a list of all the messages that have been received in a pagination format

Note: you will need to buy a number from your account before you can start receiving messages

Method (POST)

https://api.datasoap.co.uk/v1/sms/received

Request

{
  "pageSize": 10,
  "pageNumber": 1,
  "from": "07976123456",
  "to": "079761210023",
  "date": {
    "from": "2023-01-07T11:08:22.897Z",
    "to": "2024-12-07T11:08:22.897Z"
  }
}

All the fields are optional and are used to filter the returned data, you can remove the ones you do not need.

Response

{
  "data": [
    {
      "id": 634215,
      "from": "+447976123456",
      "to": "+4479761210023",
      "message": "Hi, can I get a call back?",
      "receivedOn": "2023-01-32T09:45:04.133"
    }
]
}

Errors

If an error occurs our response will contain a field 'errors' with the relevant information

Example

{
  "errors": [
    {
      "code": "-110",
      "message": "Invalid format, check your model is valid and numbers are in E146 format",
      "temporary": false
    }
  ]
}

The following is a list of our all status codes relevant to SMS API:

Code	T or P	Description
-99	NA	Your password or your username wasn't recognised. Please ensure you are using your API credentials and not your account login details.
-98	NA	You do not have enough credit on your account for this operation. Please top-up using the website or by contacting your Account Manager
-97	* Temporary	"Please report to Data Soap" is usually seen when an unexpected error occurs. In small volumes these are not usually significant but we like to keep track of them. You should see very few of these.
-101	NA	Invalid format, check your model is valid and that numbers are in E146 format
-111	NA	An approved originator must be selected, please refer to your account, or for help please contact support on 0207 856 0422
-112	NA	The country/network is inside a restricted range, for more information contact support.
-113	NA	The SMS ID is not valid for this account
-114	NA	Unable to send to number as it is on the Unsubscribe list associated with the originator

* Temporary error codes may return a different result when tried a second time in quick succession due to network fluctuations.