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.