Get started
BASE_URL https://apis-a2p.elfo.com
This document contains all the APIs that you can use with your API Key through our system.
To use these API, you need a valid and active API key. Please generate one from your account settings here.
Response Object
All API responses will be sent with 200 HTTP response status code, and the actual status code will
be
represented using a status_code
key in the response object itself.
Key | Type | Description |
---|---|---|
status_code | Integer | The status code of response: ( 200, 400, 401, 404, 500 ). |
message | String | A string message to explain the response. |
error | Boolean | A flag to identify errors in the response. |
code | Integer | A code that uniqely identify each response message. |
data | Object | An object or array of objects corresponsing the requested resources. null in case of error. |
pagination_data | Object |
An object only sent for listing API endpoints
for
pagination data. We will always mention in the success response sample. |
Webhook SMS Notification URL
When you send an SMS through our system, the status of the SMS isn't available right away. We have some jobs running on our servers that keep checking the status of the sent SMS from the telcos side.
With Webhook SMS Notification URL, you can get notified once we get the SMS status update.
While creating your API Key, you can now add an SMS Webhook Notificaion URL that will be used to send the SMS status notification for the Send Single SMS flow only.
How does it work?
- In the create API Key modal, you will find an input field for SMS Webhook Notification URL.
- This URL will be called via a POST API call, once we have an updated SMS status.
- The call to this URL will be authorized with the same API Key, to allow you to secure the call to this URL in your side. We will send the API Key in the Authorization header.
-
The body of this API call will contain the SMS ID and the status as following:
{
.
sms_id: "The ID of this SMS",
status: "Check the possible statuses in the SMS Object"
} - If you update this URL at any point of time in the settings page, we will update all the SMS records in our side that we haven't called the webhook URL for yet, to make sure you get notified with the latest URL.
- The Webhook URL will be called only once for each SMS, so make sure the URL is working before you add it to the system!
Send a single SMS
To send a single SMS, you need to make a POST call to the following url:
POST {BASE_URL}/api/sms/send
Note that the SMS won't be sent right away, it will rather be queued to be sent shortly after the
request.
If the SMS length exceeds the maximum allowed limit, or the account doesn't have enough credit to
send the SMS, it won't be sent and we won't deduct any credit from your account.
You can always check the status of each SMS using the get SMS API
endpoint.
# Here is a curl example
curl --location --request POST '{BASE_URL}/api/sms/send' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"message": "This is a test message.",
"msisdn": "+xxxxxxxxxxx"
}'
Success Response example:
{
status_code: 200,
message: "SMS queued successfully.",
error: false,
code: 12134,
data: SMS Object
}
HEADERS
Header | Type | Description |
---|---|---|
Authorization | String | Your API key. |
BODY PARAMETERS
Field | Required | Type | Description |
---|---|---|---|
message | true | String | Message content to be sent. Should be between 1 and 312 characters length. |
msisdn | true | String |
Phone number to receive the SMS. For international SMS, please make sure to add the country code with the Phone Number. +{country_code}{phone_number} 00{country_code}{phone_number}
|
Potential Errors
status_code | code | Description |
---|---|---|
401 | -1 | Unauthorized! API Key is not valid or disabled. |
400 | 12150 | msisdn parameter is required. |
400 | 12148 | msisdn parameter is invalid. |
400 | 12099 | message parameter length is invalid, should be between 1 and 312 characters. |
400 | 12151 | Invalid phone number. |
400 | 12149 | Insufficient credit to send SMS. |
If you encounter any other errors, please contact us.
Get SMS
To get a single SMS, you need to make a GET call to the following url:
GET {BASE_URL}/api/sms/:id
# Here is a curl example
curl --location --request GET '{BASE_URL}/api/sms/:id' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
Success Response example:
{
status_code: 200,
message: "SMS found successfully.",
error: false,
code: 12165,
data: SMS Object
}
HEADERS
Header | Type | Description |
---|---|---|
Authorization | String | Your API key. |
BODY PARAMETERS
Field | Required | Type | Description |
---|---|---|---|
id | true | String | SMS ID to be retreived. |
Potential Errors
status_code | code | Description |
---|---|---|
401 | -1 | Unauthorized! API Key is not valid or disabled. |
400 | 12015 | id parameter is invalid. |
404 | 12093 | SMS(s) not found. |
If you encounter any other errors, please contact us.
Models
You will need to work with the following models in the response of our APIs
SMS
Key | Type | Description |
---|---|---|
id | String | ID of SMS that was sent. This ID can be used later again to check the SMS status. |
campaign_id | Integer | ID of campaign that this SMS belongs to. |
cost | Double |
Cost of the SMS in your currency. In case of send API endpoint, the value will be 0 until the queued SMS is sent. You can check your currency and change it from your account settings via this link.
|
status | Integer |
SMS status. One of the following values:{ -1: queued, 1: sent_to_carrier, 2: delivered, 3: undelivered, 4: carrier_failure, 5: failed, 6: exceeds_limit, 7: insufficient_credit }.
|
country | String | Country ISO2 of the recipient MSISDN. |
phone_number | String | MSISDN that received the SMS. |
transaction_count | Integer | How many transactions in this SMS. This differ according to both the length and the encoding of each SMS. |
created_at | Timestamp | Epoch time of the date of creation of the SMS. |
completed_at | Timestamp | Epoch time of the date of completing the SMS in case of Delivered or Undelivered, null otherwise. |
preview | String | Preview of the SMS content that the user has received. |
message_id | String | ID of the Message that was sent to recipient. |