Developers and More
- Home
- >
- 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
- 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.
- 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.
- 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 Requestcurl --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.