SMS Sending API Usage Guide

Abbreviations

Abbreviation	Description
PARQUET	File format designed to store large amounts of data in an organized and efficient way.
PDU	Protocol Data Unit, which represents the number of fragments an SMS is split into for delivery.
UUID	Universally Unique Identifier (randomly generated code) used for msg_id and request_id.

Introduction

The SMS Sending API allows you to perform single and bulk text message deliveries using JSON or Parquet formats.

Through this guide you will learn how to authenticate, which services are available and which structures must be used to send messages correctly, which methods are available and which formats must be used to make requests.

1. Authentication and Security

Before using the Bulk Sending API, you must have a secure access key ("api key"). This key is delivered directly by the Saem Colombia team and must be included in every request within the x-auth header.

Without this authentication, the system will reject the request.

In addition to the api key, the x-prefix header must be included, indicating the country code, in all requests.

Example (headers):

Key	Value
x-auth	api-key-00000000000000000000000000000000000000
x-prefix	57

Services Available in the SMS API

Input Parameters

Field	Description
from	Identifier of the sender authorized to send messages.
numbers	List of messages to send. Each object must include to, content and optionally msg_id.
msg_id	Unique message ID. If not sent, it is generated automatically.
to	Recipient's mobile number.
content	Message text including the shortname.
flash	Defines whether the SMS will be displayed immediately in a pop-up window (yes or no). This field is mandatory for all services.
unique-numbers	If required, use this parameter to validate and reject duplicate numbers in the delivery. Accepts yes or no. Otherwise, it does not need to be included.
x-prefix	Country code, must be sent as a header.
x-auth	Authentication token, must be sent as a header.

2. Single Sending

• URL: https://apisms.saem.tel/v3/send
• Method: GET
• Headers: x-auth: api-key-XXX000X00000, x-prefix: 57 Params example (query string):

Key	Value
to	573999999999
content	Prueba oficial SMS API V3 claro
from	saemcolombia
flash	no

Full request example:

GET https://apisms.saem.tel/v3/send?to=573999999999&content=Prueba oficial SMS API V3 claro&from=saemcolombia&flash=no

💡 IMPORTANT For all our services in JSON format, a maximum of 200,000 records can be uploaded. If a higher amount is sent, the system will reject the request with the error: SMS_008.

3. Bulk Sending — JSON Format

• URL: https://apisms.saem.tel/v3/send
• Method: POST
• Headers: x-auth: api-key-XXX000X00000, x-prefix: 57 Body example:

{
  "from": "SaemColombia",
  "coding": 0,
  "dlr": "no",
  "dlr-url": "",
  "dlr-level": "",
  "dlr-method": "",
  "flash": "no",
  "unique-numbers": "yes",
  "numbers": [
    { "to": "3000000000", "content": "Hola Saem, este es tu mensaje de prueba oficial" },
    { "to": "3123457891", "content": "Hola Saem, este es tu mensaje de prueba oficial" },
    { "to": "3999999999", "content": "Hola Saem, este es tu mensaje de prueba oficial" },
    { "to": "3999999999", "content": "Hola Saem, este es tu mensaje de prueba oficial" },
    { "to": "3999999999", "content": "Hola Saem, este es tu mensaje de prueba oficial" }
  ]
}

For the following format, keep in mind that the request body must be sent as form-data, including the .parquet file and the other required parameters.

💡 Recommendation: We suggest using the .Parquet format instead of JSON files, since it allows a much faster upload, reduces the file size and improves the overall performance of the process.

For this format, a maximum of 500,000 records can be uploaded. If a higher amount is sent, the system will reject the request with the error SMS_008.

4. Bulk Sending — Parquet Format

• URL: https://apisms.saem.tel/v3/send/parquet
• Method: POST
• Headers: x-auth: api-key-XXX000X00000, x-prefix: 57 Body example (form-data):

Key	Type	Value
file	File	sms_prueba.parquet
from	Text	saemcolombia
coding	Text	0
dlr	Text	no
dlr-url	Text	(empty)
dlr-level	Text	1
dlr-method	Text	POST
flash	Text	(empty)

5. Common Errors and Responses

Code	Status	Description
USER_NOT_FOUND	404	The user is not valid.
USER_INACTIVE	401	The user is inactive or does not have permissions to perform the action.
AUTH.TOKEN_MISSING	400	The authentication token is missing.
API_KEY_NOT_FOUND	400	The API key was not found or has been revoked.
COUNTRY_001	400	No country associated with the prefix was found.
SMS_002	402	Insufficient credits for prepaid plan users.
SMS_008	400	The number of records sent exceeds the allowed limit.
SMS_009	400	The Parquet file sent is not valid or does not meet the expected format.
DUPLICATED_MSG_ID	400	One or more msg_id identifiers already exist in a previous campaign.
FORBIDDEN_TERMS	400	The content contains terms that are not allowed.
SHORTNAME_INACTIVE	400	The shortname is not active for the user.
SHORTNAME_NOT_FOUND	400	The message does not contain the mandatory shortname.
CONTENT_TOO_LONG	400	The content exceeds the length limit allowed for an SMS.

Output Parameters

Field	Description
request_id	Unique ID assigned to the bulk campaign.
total_credits	Total credits consumed by the delivery.
records	Total messages processed in the campaign.
total_pdu_count	Total PDUs generated across all messages.