What this API Does

It allows creating automated call campaigns (massive) in two modes:

• STANDARD: prerecorded audio (referenced by audioId)
• CUSTOM: text-to-speech (TTS) per contact (content), using a voice (voice = "Juan" or "Maria")

---

Authentication

All requests must include:

• x-auth: API key provided by Saem.

Unlike the SMS API, here prefix is a body field for campaigns, not a header in the CallB sending endpoints according to the guide.

---

Key Payload Concepts

Fields used in this API:

• subService: "standard" or "custom"

• prefix: origin country code (example: 57)

• gmt: local timezone in format +/-HH:MM (affects execution window)

• nameCampaign: campaign name

• mailbox: true/false (leave voicemail if the call is not answered)

• configProgramming: list of execution schedules

  • maximum 5 configurations

  • if more than one configuration is sent, a separate campaign is created for each

  • includes:

    • dateStart, dateEnd
    • reviews (retries)
    • configReview: retry conditions (max 5 retries)

• numbers:

  • STANDARD: list of phone numbers (without symbols)
  • CUSTOM: array of objects { number, content }

Retry Conditions (configReview)

Allowed values:

buzon, colgo, congestion, fallo, maquina, mcolgo, msatisfactorio, nocontesta, satisfactorio.

---

Load Limits

For JSON services:

• Maximum 200,000 records
• If exceeded → error CALLB_022

For Parquet:

• Maximum 500,000 records
• If exceeded → CALLB_022

---

STANDARD Flow: How to Build a Campaign

Step A: Obtain or Create audioId

The audioId field can be obtained:

• From the “Resources” module in the web platform (each audio has an ID), or
• By generating it via API (next step).

---

Step B: Generate Audio via API (optional but recommended)

If you automate campaign creation.

URL: https://apicallb.saem.tel/audio/generate Method: POST Headers: x-auth

Body fields:

• text
• voice
• resource_name (base name of the .wav file)

---

Step C: Create STANDARD Campaign (JSON)

URL: https://apicallb.saem.tel/send/massive Method: POST Headers: x-auth

Example Body

{
  subService: "standard",
  prefix,
  gmt,
  nameCampaign,
  audioId,
  configProgramming: [...],
  numbers: [...]
}

(numbers is a list of phone numbers)

---

CUSTOM Flow: TTS Campaign (Text-to-Speech)

Create CUSTOM Campaign (JSON)

URL: https://apicallb.saem.tel/send/massive Method: POST Headers: x-auth

Example Body

{
  subService: "custom",
  voice: "Juan" | "Maria",
  numbers: [{ number, content }, ...],
  prefix,
  gmt,
  configProgramming
}

---

Templates (CUSTOM)

Tags interpreted by the system per contact:

• {I} identifier
• {N} name
• {S} balance/value
• {T} phone number
• {E} email
• {C} account

---

Campaigns with Parquet

URL: https://apicallb.saem.tel/send/massive/parquet Method: POST Headers: x-auth Body: form-data (Parquet file + parameters)

File Rules

• STANDARD → Parquet file with column number
• CUSTOM → Parquet file with columns number and content

configProgramming must be sent in form-data as a JSON string, not as an object:

[{"dateStart":"...","dateEnd":"...","reviews":2}]

---

Campaign Creation Response

When a campaign is created, a summary response is returned containing:

• sends: count grouped by operator (includes "null" for invalid numbers detected)

• summary:

  • total_records
  • total_credits
  • seconds_aprox (approximate total seconds)

---

Errors

Authentication Errors

Code	HTTP Status	Description
AUTH.TOKEN_MISSING	400	x-auth header was not sent
API_KEY_NOT_FOUND	400	API key does not exist or is invalid
USER_NOT_FOUND	404	User associated with the API key not found
USER_INACTIVE	401	User is inactive and cannot run campaigns

---

Configuration Errors

Code	HTTP Status	Description
CALLB_015	404	Multimedia resource not found (audioId invalid)
CALLB_016	404	No configuration exists for the country/prefix
CALLB_018	400	Configured schedule is outside the allowed country range

---

Processing Errors

Code	HTTP Status	Description
CALLB_019	400	Invalid or malformed Parquet file
CALLB_021	402	Insufficient credits to execute the campaign
CALLB_022	400	Maximum number of records exceeded

---

Audio Generation Errors

Code	HTTP Status	Description
CALLB_AUD_001	400	resource_name invalid or wrong format
CALLB_AUD_002	409	Audio resource already exists (duplicate name)

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.