BulkSMS JSON REST API
Overview The JSON REST API allows you to submit and receive [BulkSMS](https://www.bulksms.com/) messages. You can also get access to past messages and see…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
Overview
The JSON REST API allows you to submit and receive BulkSMS messages. You can also get access to past messages and see your account profile.
The base URL to use for this service is https://api.bulksms.com/v1. The base URL cannot be used on its own; you must append a path that identifies an operation and you may have to specify some path parameters as well.
Click here to go to the main BulkSMS developer site.
In order to give you an idea on how the API can be used, some JSON snippets are provided below. Have a look at the messages section for more information.
Probably the most simple example
{
"to": "+27001234567",
"body": "Hello World!"
}You can send unicode automatically using the auto-unicode query parameter.
Alternatively, you can specify UNICODE for the encoding property in the request body.
Please note: when auto-unicode is specified and the value of the encoding property is UNICODE, the message will always be sent as UNICODE.
Here is an example that sets the encoding explicitly
{
"to": "+27001234567",
"body": "Dobrá práce! Jak se máš?",
"encoding": "UNICODE"
}You can also specify a from number
{
"from": "+27007654321",
"to": "+27001234567",
"body": "Hello World!"
}Similar to above, but repliable
{
"from": { "type": "REPLIABLE" },
"to": "+27001234567",
"body": "Hello World!"
}A message to a group called Everyone
{
"to": { "type": "GROUP", "name": "Everyone" },
"body": "Hello World!"
}A message to multiple recipients
{
"to": ["+27001234567", "+27002345678", "+27003456789"],
"body": "Happy Holidays!"
}Sending more than one message in the same request
[
{
"to": "+27001234567",
"body": "Hello World!"
},
{
"to": "+27002345678",
"body": "Hello Universe!"
}
]The insecure base URL http://api.bulksms.com/v1 is deprecated and may in future result in a 301 redirect response, or insecure requests may be rejected outright. Please use the secure (https) URI above.
HTTP Content Type
All API methods expect requests to supply a Content-Type header with the value application/json. All responses will have the Content-Type header set to application/json.
JSON Formatting
You are advised to format your JSON resources according to strict JSON format rules. While the API does attempt to parse strictly invalid JSON documents, doing so may lead to incorrect interpretation and unexpected results.
Good JSON libraries will produce valid JSON suitable for submission, but if you are manually generating the JSON text, be careful to follow the JSON format. This include correct escaping of control characters and double quoting of property names.
See the JSON specification for further information.
Date Formatting
Dates are formatted according to ISO-8601, such as 1970-01-01T10:00:00+01:00 for 1st January 1970, 10AM UTC+1.
See the Wikipedia ISO 8601 reference for further information.
Specifically, calendar dates are formatted with the 'extended' format YYYY-MM-DD. Basic format, week dates and ordinal dates are not supported. Times are also formatted in the 'extended' format hh:mm:ss. Hours, minutes and seconds are mandatory. Offset from UTC must be provided; this is to ensure that there is no misunderstanding regarding times provided to the API.
The format we look for is yyyy-MM-ddThh:mm:ss[Z|[+-]hh:mm]
Examples of valid date/times are2011-12-31T12:00:00Z 2011-12-31T12:00:00+02:00
Entity Format Modifications
It is expected that over time some changes will be made to the request and response formats of various methods available in the API.
Where possible, these will be implemented in a backwards compatible way.
To make this possible you are required to ignore unknown properties.
This enables the addition of information in response documents while maintaining compatibility with older clients.
Optional Request Entity Properties
There are many instances where requests can be made without having to specify every single property allowable in the request format.
Any such optional properties are noted as such in the documentation and their default value is noted.
Endpoints 15
Message
- GETRetrieve Messages
/messages?limit=0.0&filter=string&sortOrder=ASCENDINGRetrieve the messages you have sent or received. Scheduled messages are available for retrieval only after the delivery date. All the parameters are optional.… - POSTSend Messages
/messages?deduplication-id=0&auto-unicode=false&schedule-date=2024-01-01T00:00:00Z&schedule-description=stringSend messages to one or more recipients. You can post up to 30 000 messages in a batch. But note that the deduplication-id is set per submission, so it is… - GETSend message by simple GET or POST
/messages/send?to=string&body=string&deduplication-id=0A really simple interface for people who require a GET mechanism to submit a single message. The URI is interpreted as UTF-8. HTTP Basic Auth is used for… - GETShow Message
/messages/:idGet a the message by id. GET /v1/messages/4023457654 - GETList Related Messages
/messages/:id/relatedReceivedMessagesGet the messages related to a sent message identified by id. For more information how this work, see the relatedSentMessageId field in the message.
Profile
- GETGet profile
/profileReturns information about your user profile
Blocked Numbers
- GETList blocked numbers
/blocked-numbers?min-id=0&limit=0 - POSTCreate a blocked number
/blocked-numbersBlocked numbers are phone numbers to which your account is not permitted to send messages. The numbers can be created via this API, by a recipient replying…
Credits
- POSTTransfer credits to another account
/credit/transferBefore you can use the transfer credits endpoint, the _credit-transfer facility_ must be activated for your account. You can request activation from…
Attachments
- POSTUpload an attachment via a signed URL
/rmm/pre-sign-attachmentWhen composing an SMS, you can add SMS attachments by adding a URL to your text. When the recipient clicks on the URL, the attached file will be downloaded…
Webhooks
- GETList webhooks
/webhooksContains a list of your webhooks - POSTCreate a webhook
/webhooksA webhook is an URL that you can register when you want the BulkSMS system to notify you about your messages. You can register multiple webhooks, and each one… - GETRead a webhook
/webhooks/:id - POSTUpdate a webhook
/webhooks/:id - DELETEDelete a webhook
/webhooks/:id
API details
- Base URL
https://api.bulksms.com/v1- Authentication
- HTTP Basic authentication (username and password)
- Operations
- 15 operations on 10 pathsGET 8POST 6DELETE 1
- Main resources
- Message 5Webhooks 5Blocked Numbers 2Attachments 1Credits 1Profile 1
- Response formats
application/json- Description format
- OpenAPI 3.0.0, API version
1.0.0 - Links
- OpenAPI document
- Listed from
- APIs.guru OpenAPI Directory (CC0-1.0)
Source updated
How to test the BulkSMS JSON REST API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the BulkSMS JSON REST API collection, without the publisher's secrets.
- Add your credentialsThis API uses HTTP Basic authentication (username and password). Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Retrieve Messages” (GET /messages?limit=0.0&filter=string&sortOrder=ASCENDING), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the BulkSMS JSON REST API?
Overview The JSON REST API allows you to submit and receive [BulkSMS](https://www.bulksms.com/) messages. You can also get access to past messages and see… It is listed under Communication and has 15 endpoints.
Who publishes the BulkSMS JSON REST API?
It is listed from Bulksms's public API description (an OpenAPI document), not published by Bulksms on Swastik Codes. Anyone who controls bulksms.com can claim the profile by adding a DNS TXT record.
What is the base URL of the BulkSMS JSON REST API?
Requests go to https://api.bulksms.com/v1. Endpoint paths are added to this base URL.
How do I authenticate with the BulkSMS JSON REST API?
With HTTP Basic authentication (username and password).
How many endpoints does the BulkSMS JSON REST API have?
15 operations on 10 paths (8 GET, 6 POST, 1 DELETE). The largest groups are Message, Webhooks, Blocked Numbers, Attachments.
Is forking the BulkSMS JSON REST API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.