Developers and More

Getting Started with API

elfoA2P is a powerful SMS messaging platform that provides a robust set of APIs for developers to integrate seamless SMS capabilities into their applications. The elfoA2P Developers Documentation is a comprehensive resource that outlines the various APIs, endpoints, and data models available for developers to leverage the platform’s functionalities effectively.

In this article, we’ll explore the key features and components of the elfoA2P Developers Documentation, helping you get started with the platform and enabling you to build innovative SMS-based solutions.

Generating API Keys

This section provides instructions on how to generate a valid API key, which is essential for authenticating and authorizing API requests: https://apis-a2p.elfo.com

Note: the provided BASE_URL (https://apis-a2p.elfo.com) for making API requests.

To use these API, you need a valid and active API key. Please generate one from your API Credentials at elfoA2P.

Response Object Structure:

This section outlines the standardized format of the API responses from elfoA2P, ensuring consistency and ease of understanding. It explains the structure of the response object, including the status code, message, error flag, data payload, and pagination data (if applicable).

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:

At elfoA2P, we understand the importance of keeping you informed about the status of your SMS messages in real-time. That’s why we’ve introduced the Webhook SMS Notification feature, which allows you to receive instant updates whenever the status of an SMS message changes.

Developers can set up a Webhook SMS Notification URL to receive real-time updates when the status of an SMS changes, allowing for timely updates on SMS delivery statuses.

While creating your API Key, you can now add an SMS Webhook Notification URL that will be used to send the SMS status notification for the Send Single SMS flow only.

How It Works

1. Set up Your Webhook URL: When creating or updating your API Key in your account, you’ll find an input field for the “SMS Webhook Notification URL.” This is where you’ll provide the URL that elfoA2P will use to send you SMS status notifications for the “Send Single SMS” flow.
2. Receive Notifications: Once elfoA2P has an updated status for one of your SMS messages, our system will make a POST API call to the Webhook URL you’ve provided. This call will be authorized with your API Key, which will be sent in the Authorization header, allowing you to secure the incoming requests on your end.
3. Notification Payload: The body of the API call will contain the following information:

{
  "sms_id": "The ID of this SMS",
  "status": "Check the possible statuses in the SMS Object"
}

The sms_id field represents the unique identifier of the SMS message, and the status field indicates the current status of the SMS message. You can find the list of possible status values in the “SMS Object” section of our documentation.

• Updating Your Webhook URL: If you update your Webhook Notification URL in your account settings, elfoA2P will update all the SMS records in our system that haven’t been notified yet, ensuring that you receive notifications with the latest URL.
• Single Notification: Please note that the Webhook URL will be called only once for each SMS message. Therefore, it’s crucial to ensure that the URL is working correctly before adding it to your account settings.

By setting up the Webhook SMS Notification feature, you’ll always be in the loop regarding the delivery status of your SMS messages, allowing you to take appropriate actions and provide a seamless experience to your customers.

SEND A SINGLE SMS

SENDING A SINGLE SMS:

To send a single SMS message, you need to make a POST request to the following endpoint:

 POST {BASE_URL}/api/sms/send

Please note that the SMS message won’t be sent immediately. Instead, it will be queued and sent shortly after your request.

Request Headers

Header	Type	Description
Authorization	String	Your API Key (Required)
Content-Type	String	application/json (Required)

• Authorization: Your API Key (Required)
• Content-Type: application/json (Required)

 

Body Parameters

Field	Required	Type	Description
message	true	String	The content of your SMS message. The length should be 1 to 459 characters.
msisdn	true	String	The phone number that will receive the SMS message. Include the country code for international SMS. Format: +{country_code}{phone_number} or 00{country_code}{phone_number}.

• message  (Required, String): The content of your SMS message. The length should be between 1 and 459 characters.
• msisdn (Required, String): The phone number that will receive the SMS message. For international SMS, make sure to include the country code in the format +{country_code}{phone_number} or 00{country_code}{phone_number}.

Example Request

Bash

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": "+1234567890"
}'

Successful Response Example

json

{
   "status_code": 200,
   "message": "SMS queued successfully.",
   "error": false,
   "code": 12134,
   "data": SMS Object
}

Important Notes

• If the SMS length exceeds the maximum allowed limit or if your account doesn’t have enough credit to send the SMS, the SMS won’t be sent, and no credit will be deducted from your account.
• You can always check the status of each SMS message using the “Get SMS” API endpoint.

If you encounter any other errors, please don’t hesitate to contact our support team for further assistance.

By following these simple steps, you can easily send single SMS messages through our platform, ensuring that your communication reaches its intended recipients promptly and efficiently.

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 459 characters.
400	12151	Invalid phone number.
400	12149	Insufficient credit to send SMS.

If you encounter any other errors, please don’t hesitate to contact our support team for further assistance.

By following these simple steps, you can easily send single SMS messages through our platform, ensuring that your communication reaches its intended recipients promptly and efficiently.

GET SMS STATUS

At elfoA2P, we understand the importance of keeping track of your SMS messages and managing your lead lists effectively. Our platform provides you with the ability to retrieve the status of a sent SMS and get a list of your lead lists. Here’s a guide on how to utilize these features:

Retrieving SMS Status

To retrieve the status of a single SMS message, you need to make a GET request to the following endpoint:

GET {BASE_URL}/api/sms/:id


Replace :id with the unique identifier of the SMS message you want to retrieve.

Request Headers

Header	Type	Description
Authorization	String	Your API Key (Required)

Authorization:  Your API Key (Required)
Content-Type: application/json   (Required)

Body Parameters

Field	Required	Type	Description
id	true	String	SMS ID to be retrieved.

Example Request

curl --location --request GET '{BASE_URL}/api/sms/:id' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json'

Successful Response Example
{
   "status_code": 200,
   "message": "SMS found successfully.",
   "error": false,
   "code": 12165,
   "data": SMS Object
}

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 don’t hesitate to contact our support team for further assistance.

Retrieving Lead Lists

To retrieve a list of your lead lists, you need to make a GET request to the following endpoint:

GET {BASE_URL}/api/lead-list


Request Headers

Header	Type	Description
Authorization	String	Your API Key (Required)

Authorization: Your API Key (Required)

Query Parameters

Parameter	Required	Type	Description
page	Optional	Integer	Page number, default is 1.
limit	Optional	Integer	Limit for each page, default is 10, maximum is 50.
type	Optional	Integer	Filter lead lists by their type.
search	Optional	String	Filter lead lists by their names. Search query must be at least 2 characters.

• page (Optional, Integer): Page number, default is 1.
• limit (Optional, Integer): Limit for each page, default is 10, maximum is 50.
• type (Optional, Integer): Filter lead lists by their type.
• search (Optional, String): Filter lead lists by their names. Search query must be at least 2 characters.

Example Request

Bash

curl --location --request GET '{BASE_URL}/api/lead-list?page=1&limit=3&type=1' \
--header 'Authorization: YOUR_API_KEY'

Successful Response Example

json

{
   "status_code": 200,
   "message": "Lead list created successfully.",
   "error": false,
   "code": 11016,
   "data": [ Array of Lead List Object ],
   "pagination_data": Pagination Object
}

Potential Errors

status_code	code	Description
401	-1	Unauthorized! API Key is not valid or disabled.
400	11063	type parameter is invalid.
400	11023	page parameter is invalid.
400	11024	limit parameter is invalid.
400	11027	search parameter length is invalid.
404	11018	Lead lists not found. In case of no data found or no more data.

If you encounter any other errors, please don’t hesitate to contact our support team for further assistance.

GETTING LEAD LISTS

At elfoA2P, we understand the importance of managing your lead lists effectively. Our platform provides you with the ability to retrieve a list of your lead lists, which can be filtered and paginated according to your needs. Here’s a guide on how to utilize this feature:

Retrieving Lead Lists

To retrieve a list of your lead lists, you need to make a GET request to the following endpoint:

GET {BASE_URL}/api/lead-list

Request Headers

Header	Type	Description
Authorization	String	Your API Key (Required)

Authorization: Your API Key (Required)

Query Parameters

Parameter	Required	Type	Description
page	false	Integer	Page number, default is 1.
limit	false	Integer	Limit for each page, default is 10, maximum is 50.
type	false	Integer	Filter lead lists by their type.
search	false	String	Filter lead lists by their names. Search query must be at least 2 characters.

• page (Optional, Integer): Page number, default is 1.
• limit (Optional, Integer): Limit for each page, default is 10, maximum is 50.
• type (Optional, Integer): Filter lead lists by their type.
• search (Optional, String): Filter lead lists by their names. Search query must be at least 2 characters.

Example Request

Json

{
   "status_code": 200,
   "message": "Lead list created successfully.",
   "error": false,
   "code": 11016,
   "data": [ Array of Lead List Object ],
   "pagination_data": Pagination Object
}


Potential Errors

status_code	code	Description
401	-1	Unauthorized! API Key is not valid or disabled.
400	11063	type parameter is invalid.
400	11023	page parameter is invalid.
400	11024	limit parameter is invalid.
400	11027	search parameter length is invalid.
404	11018	Lead lists not found. In case of no data found or no more data.

If you encounter any other errors, please don’t hesitate to contact our support team for further assistance.

By following these guidelines, you can easily retrieve a list of your lead lists, filter them by type or name, and paginate the results according to your requirements. This feature allows you to manage your lead lists effectively, ensuring that you have the necessary information to streamline your marketing and communication efforts.

CREATING A LEAD LIST

Creating Lead Lists

At elfoA2P, we understand the importance of organizing and managing your leads effectively. Our platform allows you to create custom lead lists, which can be tailored to your specific needs. Here’s a guide on how to create a new lead list:

Creating a Lead List

To create a new lead list, you need to make a POST request to the following endpoint:

POST {BASE_URL}/api/lead-list


Request Headers

Header	Type	Description
Authorization	String	Your API Key (Required)
Content-Type	String	application/json (Required)

Authorization: Your API Key (Required)
Content-Type: application/json (Required)

Body Parameters

Parameter	Required	Type	Description
name	true	String	The name of your lead list. The length should be between 3 and 100 characters.
fields_list	true	String	An encoded array of JSON objects representing the custom fields for your lead list.

• name (Required, String): The name of your lead list. The length should be between 3 and 100 characters.
• fields_list (Required, String): An encoded array of JSON objects representing the custom fields for your lead list. The format should be [{ “key”: “key”, “label”: “Label” }].

Example Request

Bash

curl --location --request POST '{BASE_URL}/api/lead-list' \ --header 'Authorization: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Lead List Name", "fields_list": "[{\"key\": \"name\", \"label\": \"Name\"}, {\"key\": \"age\", \"label\": \"Age\"}]" }'

Successful Response Example

Json

{
   "status_code": 200,
   "message": "Lead list created successfully.",
   "error": false,
   "code": 11013,
   "data": Lead List Object
}

Potential Errors

status_code	code	Description
401	-1	Unauthorized! API Key is not valid or disabled.
400	11003	name parameter length is invalid.
400	11010	name parameter is required.
400	11012	Lead list name already exists.
400	11032	fields_list parameter is invalid.

If you encounter any other errors, please don’t hesitate to contact our support team for further assistance.

By following these guidelines, you can easily create custom lead lists tailored to your specific needs. These lead lists can be used for targeted SMS campaigns, personalized communication, and effective lead management, ensuring that your marketing and communication efforts are streamlined and effective.

CREATING A LEAD

Creating Leads

At elfoA2P, we understand the importance of managing your leads effectively. Our platform allows you to create individual leads within your existing lead lists, which can be used for targeted SMS campaigns, personalized communication, and effective lead management. Here’s a guide on how to create a new lead:

Creating a Lead

To create a new lead, you need to make a POST request to the following endpoint:

POST {BASE_URL}/api/lead


Important Note

If the lead list you’re adding this lead to is used by a running campaign that’s set to send SMS messages individually to newly added leads, an SMS will be queued to be sent to that lead in case it has a valid phone number in the key used in this campaign.

Request Headers

Header	Type	Description
Authorization	String	Your API key.

Authorization: Your API Key (Required)
Content-Type: application/json (Required)

Body Parameters

Field	Required	Type	Description
lead_list_id	true	String	Lead List ID to add this lead to.
payload	true	String	Encoded JSON object of lead data with the format: { key1: “Value 1”, key2: “Value 2” }.

• lead_list_id (Required, String): The unique identifier of the lead list you want to add this lead to. You can retrieve your lead list IDs by calling the “Get Lead Lists” API endpoint or create a new lead list using the “Create Lead List” API endpoint.
• payload (Required, String): An encoded JSON object containing the lead data. The format should be { “key1”: “Value 1”, “key2”: “Value 2” }. The keys in the payload should match the custom fields defined in the lead list.

Example Request

Bash

curl --location --request POST '{BASE_URL}/api/lead' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "lead_list_id": "XXXXXXXXXXXXXXXXXXXXXXXX",
    "payload": "{\"name\": \"Lead Name\", \"age\": \"Lead Age\"}"
}'

Successful Response Example

Json

{
   "status_code": 200,
   "message": "Lead created successfully.",
   "error": false,
   "code": 11005,
   "data": Lead Object
}

Potential Errors

status_code	code	Description
401	-1	Unauthorized! API Key is not valid or disabled.
400	11039	lead_list_id parameter is invalid.
400	11033	payload parameter is invalid.
400	11035	Payload fields do not match lead list fields. In case none of the keys sent in the payload exist in the lead list fields_list.

If you encounter any other errors, please don’t hesitate to contact our support team for further assistance.

By following these guidelines, you can easily create new leads within your existing lead lists, ensuring that your marketing and communication efforts are targeted and effective. Additionally, if the lead list is associated with a running campaign, an SMS will be automatically queued for leads with valid phone numbers, ensuring seamless communication with your new leads.

DATA MODELS

When working with the elfoA2P API, you will encounter various models in the response. Understanding these models is crucial for effectively integrating the API into your application. Below, we provide a detailed guide to the models you will encounter in the elfoA2P API responses.

SMS Model

Key	Type	Description
id	String	ID of the SMS that was sent. Use this ID to check the SMS status later.
campaign_id	Integer	ID of the campaign to which this SMS belongs.
cost	Double	Cost of the SMS in your currency. For the send API endpoint, the value is 0 until the SMS is sent.
status	Integer	Status of the SMS. Possible values: {-1: queued, 1: sent_to_carrier, 2: delivered, 3: undelivered, … }
country	String	ISO2 country code of the recipient MSISDN.
phone_number	String	MSISDN of the recipient.
transaction_count	Integer	Number of transactions in this SMS, based on length and encoding.
created_at	Timestamp	Epoch time of the SMS creation date.
completed_at	Timestamp	Epoch time of the SMS completion date (for Delivered or Undelivered status).
preview	String	Preview of the SMS content received by the user.
message_id	String	ID of the message sent to the recipient.

Lead List Model

Key	Type	Description
id	String	ID of the Lead List.
name	String	Name of the Lead List.
status	Integer	Status of the Lead List. Possible values: {1: ready, 2: syncing}.
type	Integer	Type of the Lead List. Possible values: {1: contact, 2: quick_sms, 3: api_messaging}.
count	Integer	Number of leads in the Lead List. Always 0 for newly created lead lists.
fields_list	Array	Array of Lead List’s fields. Format: [{ key: “key”, label: “Label” }].

Lead Model

Key	Type	Description
id	String	ID of the Lead.
lead_list_id	String	ID of the Lead List to which this lead belongs.
payload	JSON	JSON Object of the lead payload. Format: { key1: “Value 1”, key2: “Value 2” }.

Pagination Object

Key	Type	Description
current_page	Integer	Current page number.
current_count	Integer	Current count of the current page.
total_count	Integer	Total count based on the current criteria.

Understanding these models will help you effectively utilize the elfoA2P API in your application. If you have any questions or need further assistance, please refer to the full API documentation or contact our support team.