ENG – REST API HTTP Protocol

OVERVIEW #

AgileTelecom’s REST API allows SMS sending through simple HTTP calls. The service supports advanced features such as concatenated SMS, Unicode, scheduled sending, and bulk messaging.

Base URL #

https://secure.agiletelecom.com/services/

Authentication #

The API supports two authentication methods, both to be included in the request header:

1. Basic Authentication

Authorization: Basic <base64_encoded_credentials>

2. API Key

X-Api-Key: <your-api-key>

Endpoints #

1. Send SMS

Send one or more SMS to single or multiple recipients.

POST /sms/send

Required Headers

Content-Type: application/json

Body Structure (JSON)

{
  "globalId": "string",
  "maxIdLen": 64,
  "enableConcatenated": true,
  "enableUnicode": true,
  "enableDelivery": true,
  "simulation": false,
  "messages": [
    {
      "ids": ["string"],
      "destinations": ["+393351234567"],
      "sender": "string",
      "body": "string",
      "hexBody": false,
      "udhData": "string",
      "scheduling": "2025-12-08 06:00:00.002+0200"
    }
  ]
}

Parameters

FIELD	TYPE	MANDATORY	DEFAULT	NOTES
globalId	string	no	–	Unique sending identifier for the client
maxIdLen	integer	no	64	Maximum length (characters) of IDs
enableConcatenated	boolean	no	true	Enable concatenation if necessary
enableUnicode	boolean	no	true	Enable Unicode text
enableDelivery	boolean	no	true	Enable delivery receipt to client
simulation	boolean	no	false	Allows simulation, without actual sending of the message
messages	array	yes		List of messages to send

Parameters for each message

FIELD	TYPE	MANDATORY	DEFAULT	NOTES
destinations	array	yes		List of recipients (international format)
ids	array	no		List of message IDs
sender	string	yes		Message sender (max 11 alphanumeric or 16 numeric characters)
body	string	yes		Message text
hexBody	boolean	no	false	Indicates if text is in HEX format
udhData	string	no		UDH code to insert in message
scheduling	string	no		Scheduling date (format: “yyyy-MM-dd HH:mm:ss.SSSZ”)

2. Check Credit

Get the account’s remaining credit.

GET /sms/credit

Success Response (JSON)

{
  "credit": 10.324
}

Usage Examples #

Example 1: Simple SMS

curl -X POST https://secure.agiletelecom.com/services/sms/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key" \
  -d '{
    "messages": [
      {
        "destinations": ["+393351234567"],
        "sender": "TechNews",
        "body": "Latest tech news! Discover the new smartphones coming soon and the best deals. Visit our website for more details."
      }
    ]
  }'

Example 2: SMS with Custom ID

{
  "messages": [
    {
      "ids": ["157d541b-e0cd-4340-ac77-bc5d530dasdv"],
      "destinations": ["+393351234567"],
      "sender": "TechNews",
      "body": "Latest tech news! Discover the new smartphones coming soon and the best deals. Visit our website for more details."
    }
  ]
}

Example 3: Multipart SMS (Long)

{
  "messages": [
    {
      "ids": ["157d541b-e0cd-4340-ac77-bc5d530dasdv"],
      "destinations": ["+393351234567"],
      "sender": "HealthTips",
      "body": "Stay healthy this summer by following our top tips. Drink plenty of water to stay hydrated, wear sunscreen to protect your skin, and try to include fresh fruits and vegetables in your diet. Regular exercise in the early morning or evening can also help you stay fit and energized."
    }
  ]
}

Example 4: Unicode SMS

{
  "messages": [
    {
      "ids": ["157d541b-e0cd-4340-ac77-unicode-test1"],
      "destinations": ["+393351234567"],
      "sender": "WeatherNow",
      "body": "Attention: Tomorrow temperatures reaching up to 38°C"
    }
  ]
}

Example 5: Scheduled SMS

{
  "messages": [
    {
      "ids": ["157d541b-e0cd-4340-ac77-bc5d530dasdv"],
      "destinations": ["+393351234567"],
      "sender": "TechNews",
      "body": "Latest tech news! Discover the new smartphones coming soon and the best deals. Visit our website for more details.",
      "scheduling": "2025-12-08 06:00:00.002+0200"
    }
  ]
}

Example 6: Simulation (Without Actual Sending)

{
  "simulation": true,
  "messages": [
    {
      "ids": ["157d541b-e0cd-4340-ac77-bc5d530dasdv"],
      "destinations": ["+393351234567"],
      "sender": "TechNews",
      "body": "Latest tech news! Discover the new smartphones coming soon and the best deals. Visit our website for more details."
    }
  ]
}

Example 7: SMS Without Delivery Report

{
  "enableDelivery": false,
  "messages": [
    {
      "ids": ["157d541b-e0cd-4340-ac77-bc5d530dasdv"],
      "destinations": ["+393351234567"],
      "sender": "TechNews",
      "body": "Latest tech news! Discover the new smartphones coming soon and the best deals. Visit our website for more details."
    }
  ]
}

Example 8: SMS with UDH

{
  "messages": [
    {
      "ids": ["157d541b-e0cd-4340-ac77-bc5d530dudhx"],
      "destinations": ["+393351234567"],
      "sender": "TechNews",
      "body": "Latest tech news! Discover the new smartphones coming soon and the best deals. Visit our website for more details.",
      "udhData": "070645670000"
    }
  ]
}

Example 9: SMS with HEX Body

{
  "messages": [
    {
      "ids": ["157d541b-e0cd-4340-ac77-unicode-test1"],
      "destinations": ["+393351234567"],
      "sender": "WeatherNow",
      "body": "0041007400740065006E00740069006F006E003A00200054006F006D006F00720072006F0077002000740065006D0070006500720061007400750072006500730020007200650061006300680069006E006700200075007000200074006F00200033003800B00043",
      "hexBody": true
    }
  ]
}

Example 10: Bulk Sending – Same SMS to Multiple Recipients

{
  "messages": [
    {
      "ids": [
        "157d541b-e0cd-4340-ac77-bc5d530dd90e",
        "d0f2e3c1-a043-418d-ad5e-0248184b9833"
      ],
      "destinations": [
        "+393351234567",
        "+393351234568"
      ],
      "sender": "PromoDeals",
      "body": "Don't miss out! Buy 2 products and get the 3rd one free. Offer valid until Sunday."
    }
  ]
}

Example 11: Bulk Sending – Different SMS

{
  "messages": [
    {
      "ids": ["157d541b-e0cd-4340-ac77-bc5d530dd90p"],
      "destinations": ["+393351234567"],
      "sender": "ShopNow",
      "body": "Big Sale! Today only, get up to 50% off on all items. Visit our store and take advantage of the offer!"
    },
    {
      "ids": ["157d541b-e0cd-4340-ac77-bc5d530dd90a"],
      "destinations": ["+393351234561"],
      "sender": "Foodies",
      "body": "Try our new summer menu! Book your table now and receive a complimentary dessert."
    }
  ]
}

Example 12: Check Credit

curl -X GET https://secure.agiletelecom.com/services/sms/credit \
  -H "X-Api-Key: your-api-key"

Responses #

Success Response (2XX)

{
  "globalId": "f9b865ef-5ce3-4e44-b65c-615fd71bbd09",
  "processedMessages": 2,
  "processedSmsParts": 4,
  "credit": 10.324
}

FIELD	TYPE	NOTES
globalId	string	Global ID value from the request
processedMessages	integer	Messages accepted as per messages section in request
processedSmsParts	integer	Parts to be sent (differs from above in case of concatenated messages)
credit	double	Remaining account credit in €

Client Errors (4XX)

{
  "status": "fail",
  "data": { 
    "body": "Missing message body(ies)",
    "number": "Wrong destination number(s)"
  },
  "code": 6
}

FIELD	TYPE	NOTES
status	string	Always “fail” for 4XX errors
data	object / string	Key-value list with problematic fields or descriptive string
code	integer	Custom error code

Server Errors (4XX)

{
  "status": "error",
  "message": "Number check service unavailable",
  "code": 9
}

FIELD	TYPE	NOTES
status	string	Always “error” for 5XX errors
message	string	Description of the server-side problem
code	integer	Custom error code

Error codes: #

CODE	DESCRIPTION
1	Wrong credentials
2	Insufficient credit
8	Server error
9	Server error (service timeout)
26	Alias (Sender) is not allowed
100	Source IP is not allowed

Delivery Report (Webhook) #

If enabled, AgileTelecom will send a delivery notification to the URL specified by the client.

Delivery Report Structure

{
  "messageId": "157d541b-e0cd-4340-ac77-bc5d530dd90e",
  "destination": "41793026727",
  "statusCode": 3,
  "description": "Delivered",
  "doneDate": "2022-05-09 09:00:05.002+0200",
  "concatTotal": 2,
  "concatProgressive": 1,
  "lcrOperator": "22210",
  "realOperator": "22201",
  "price": 0.003
}

Delivery Report Parameters

FIELD	TYPE	NOTES
messageId	string	Unique ID identifying the sent message
destination	string	Recipient’s phone number
statusCode	integer	Receipt status code
description	string	Status description
doneDate	string	Delivery date
concatTotal	integer	Total number of parts for concatenated message
concatProgressive	integer	Message part number
lcrOperator	string	(Optional) Operator identified by LCR service
realOperator	string	(Optional) Actual operator of the number
price	double	(Optional) Sending cost

Delivery Status Codes

CODE	STATUS
1	Accepted
2	Rejected
3	Delivered
4	Expired
5	Deleted
6	Undeliverable

Postman Collection #

Download the collection: Download Postman Collection
Import into Postman:
– Open Postman
– Click “Import” in the top left
– Drag the downloaded JSON file or click “Upload Files”
– Confirm the import
Configure variables:
– Click on the collection name “Http Post Example” in the side panel
– Select the “Variables” tab
– You’ll find two columns:
– “Initial Value”: default variable value
– “Current Value”: value actually used in calls
– Modify values in the “Current Value” column:
– username: enter your username (for Basic Auth)
– password: enter your password (for Basic Auth)
– api-key: enter your API key (for API Key authentication)
– enable_apikey: set true to use API Key, false for Basic Auth
– Save changes by clicking the “Save” button in the top right

Collection Postman Notes

Test values: The default values in the collection (user, pass, api-value) are test credentials that simulate sending without actually sending SMS
Payload testing: You can use these test values to verify the JSON structure correctness before using your real credentials
Organization: The collection is organized in folders:
– Basic example: simple sending examples
– Advanced example: advanced features (scheduling, UDH, simulation)
– Multiple sending: bulk sends
– ApiKey No PostMan Script: direct examples with API Key
– Basic Auth No PostMan Script: direct examples with Basic Auth

Environment Configuration

The collection includes pre-request scripts that automatically handle authentication based on the enable_apikey variable:

if enable_apikey = true: uses API Key authentication
if enable_apikey = false: uses Basic Authentication

Code Generation from Postman

Postman offers a very useful feature to generate code in various programming languages:

Open a request in the collection
Click the “< />” icon (Code snippet) on the right side of the window
Select the desired language from the dropdown menu:
– cURL
– Python (requests)
– JavaScript (fetch, axios)
– PHP
– Java
– C#
– Go
– Ruby
– and many more…
Copy the generated code and use it as a reference implementation for your integration

Example of automatically generated cURL:

curl --location 'https://secure.agiletelecom.com/services/sms/send' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: your-api-key' \
--data '{
    "messages": [
        {
            "destinations": ["+393351234567"],
            "sender": "TechNews",
            "body": "Latest tech news!"
        }
    ]
}'

This feature is particularly useful for:

Speeding up integration in your preferred language
Verifying correct request formatting
Quickly testing APIs from command line
Creating code examples for internal documentation

Important Notes #

Number format: Destination numbers must be in international format with country code (e.g., +39 for Italy)
SMS limits:
– Standard SMS (GSM 7-bit): 160 characters
– Unicode SMS: 70 characters
– Longer SMS are automatically concatenated if enableConcatenated is true
Sender:
– Alphanumeric: maximum 11 characters
– Numeric: maximum 16 digits
Encoding: Message body can be sent in UTF-8 or hexadecimal format
Rate limiting: Check with AgileTelecom for any sending limits per second/minute

Support #

For technical assistance or commercial information, contact AgileTelecom support at help@agiletelecom.com.

Send SMS

Receive SMS

Credit Check

Mobile Number Portability

ENG – REST API HTTP Protocol

OVERVIEW #

Base URL #

Authentication #

Endpoints #

Usage Examples #

Responses #

Error codes: #

Delivery Report (Webhook) #

Postman Collection #

Important Notes #

Support #

What are your Feelings

Products

Industries

Developers

How we work

Get in touch