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.