What it Does

The SMS API allows sending SMS messages in two ways:

• Single (one number per request).

• Bulk (many numbers in one request) using:

  • JSON (up to 200,000 records).
  • Parquet (up to 500,000 records and recommended for performance).

---

Authentication and Required Headers

All requests must include:

• x-auth: API key provided by Saem Colombia (if missing, the request will be rejected).
• x-prefix: country code sent as a header (example: 57).

Rule: without these headers, the API will not process the request.

---

Data Model (Input Parameters)

The guide lists the following fields (depending on endpoint/format):

• from: authorized sender identifier.

• flash: required in all services; values yes or no.

• numbers: list of messages to send; each item includes:

  • to: destination number.
  • content: message text (must include the required shortname, see errors section).

• msg_id (optional): unique message ID; if not provided, the system will generate it.

Important note: the guide specifies “content including the shortname”, and the error SHORTNAME_NOT_FOUND occurs if it is missing.

---

Endpoint: Single Message Sending

URL: https://apisms.saem.tel/v3/send

Method: GET

Headers: x-auth, x-prefix

How it Works

• Parameters are sent as query params (to, content, from, flash).
• The system processes one SMS to a single recipient.

When to Use

• Individual notifications (OTP, confirmations, alerts, etc.).

---

Endpoint: Bulk Sending in JSON

URL: https://apisms.saem.tel/v3/send

Method: POST

Headers: x-auth, x-prefix

Body: JSON

Limit

• Maximum 200,000 records per JSON request.
• If exceeded → error SMS_008.

How it Works

• You send an object with metadata (e.g., from, flash) and the numbers list.
• Each element inside numbers represents an SMS to be sent.

Practical Recommendation

• If you need traceability, send your own msg_id (UUID) to correlate messages.
• If not provided, the API will generate it automatically.

---

Endpoint: Bulk Sending in Parquet

URL: https://apisms.saem.tel/v3/send/parquet

Method: POST

Headers: x-auth, x-prefix

Body: form-data (Parquet .parquet file + additional parameters)

Limit

• Maximum 500,000 records.
• If exceeded → error SMS_008.

How it Works

• Instead of sending numbers in JSON, you upload a Parquet file containing the records.

The guide recommends Parquet because it provides:

• faster uploads,
• smaller file size,
• better overall performance.

---

Output Parameters

Fields returned in the response (especially for bulk campaigns):

• request_id: unique ID of the bulk campaign.
• total_credits: credits consumed.
• records: total number of messages processed.
• total_pdu_count: total PDUs generated across all messages (useful to understand segmentation of long SMS messages).

---

Error Handling

Authentication Errors

Code	HTTP Status	Description
AUTH.TOKEN_MISSING	400	The x-auth header was not sent.
API_KEY_NOT_FOUND	400	The provided API key does not exist or is invalid.
USER_NOT_FOUND	404	The user associated with the API key was not found.
USER_INACTIVE	401	The user is inactive.
COUNTRY_001	400	The prefix (x-prefix) is not associated with any country or is not configured.

---

Sending / Validation Errors

Code	HTTP Status	Description
SMS_002	402	Insufficient credits (prepaid accounts).
SMS_008	400	The maximum allowed number of records was exceeded.
SMS_009	400	Invalid or malformed Parquet file.
DUPLICATED_MSG_ID	400	The msg_id has already been used in a previous campaign.
FORBIDDEN_TERMS	400	The message content contains prohibited terms.
SHORTNAME_INACTIVE	400	The shortname is inactive.
SHORTNAME_NOT_FOUND	400	The shortname was not found in the message content.
CONTENT_TOO_LONG	400	The message content exceeds the allowed length.