REST API

API Documentation

REST API for SMS messaging, contacts and contact groups management. Integrate with N8n, Bitrix24, custom scripts, or any HTTP client.

Introduction

This API lets you send SMS messages and manage contacts and contact groups programmatically. All 6 public endpoints accept JSON request bodies and return JSON responses. No OAuth or session cookies required — authentication is key-based (see Authentication).

Common use cases: bulk imports from CRM systems, N8n automation workflows, Bitrix24 integration, mass SMS campaigns, and AI agent pipelines.

POST /api/messages/ — send a single SMS
POST /api/messages/bulk/ — send up to 1 000 SMS in one request
POST /api/contacts/contacts/ — create or update a single contact (+ optional SMS)
POST /api/contacts/contacts/bulk/ — create/update up to 500 contacts
POST /api/contacts/groups/ — create a single contact group
POST /api/contacts/groups/bulk/ — create up to 200 groups (idempotent)

Base URL

The API is available under both brand domains. The endpoints and contracts are identical — only the base URL differs.

Brand	Base URL
AwesomeSMS	https://awesomesms.com
LepszeSMSy.pl	https://lepszesmsy.pl

Authentication

There are two authentication methods depending on the endpoint group. Both use fields included in the JSON request body — no HTTP headers required.

Method 1 — License key (SMS endpoints)

Used by POST /api/messages/ and POST /api/messages/bulk/. Include the field license__key in the request body. The key is 6 or 12 characters long. The license must be active and assigned to a user with a valid subscription.

Method 2 — License key + API key (Contact & Group endpoints)

Used by all /api/contacts/ endpoints. Include both key (6–12 chars, license key) and api_key (exactly 12 chars) in the request body. Both must be valid and belong to the same active account.

Rate Limits

Endpoint	Max per request	Additional limits
POST /api/messages/bulk/	1 000 messages	Daily SMS limit (max_daily_sms) per user
POST /api/contacts/contacts/bulk/	500 contacts	—
POST /api/contacts/groups/bulk/	200 groups	—

When the daily SMS limit is exceeded the request returns 403 Forbidden. Single-item endpoints have no per-request batch limit.

Personalization

Message text can include the {name} variable. It is replaced with the contact's name by MessagePersonalizationService before the SMS is queued.

{name} — contact name (available in all contact and group endpoints)

Note: the POST /api/messages/ and bulk SMS endpoints operate without a contact context, so {name} personalization is not available there.

SMS Endpoints

POST /api/messages/

Creates a single SMS message. The message is queued and delivered asynchronously by the mobile app (up to 15 min delay depending on the device schedule).

Authentication

license__key in request body.

Request body

Field	Type	Required	Description
external_id	string	required	Unique message identifier per license. Used for deduplication.max 255 chars
license__key	string	required	License key for authentication.6 or 12 chars
message	string	required	SMS text content.
phone	string	required	Recipient phone number in E.164 format.e.g. +48123456789
send_after	ISO datetime	optional	Earliest time to send the message. If omitted, sending hours policy applies.
send_before	ISO datetime	optional	Deadline — message is skipped if not sent before this time.
priority	integer	optional	Higher value = higher priority. Default: 10.default: 10

Request example

POST /api/messages/

{
  "external_id": "order-confirmation-12345",
  "license__key": "ABC123",
  "message": "Your order #12345 has been confirmed. Delivery: 2-3 business days.",
  "phone": "+48123456789",
  "send_after": "2026-04-10T09:00:00",
  "priority": 10
}

Response 201

{
  "id": 98765,
  "external_id": "order-confirmation-12345",
  "phone": "+48123456789",
  "message": "Your order #12345 has been confirmed. Delivery: 2-3 business days.",
  "status": "pending",
  "send_after": "2026-04-10T09:00:00",
  "created_at": "2026-04-09T14:32:00Z"
}

Response codes

Code	Status	Description
201	Created	Message queued successfully.
400	Bad Request	Missing required fields or validation error.
404	Not Found	License key not found.
500	Server Error	Internal server error.

POST /api/messages/bulk/

Creates up to 1 000 SMS messages in a single request. Supports partial success (default) or atomic all-or-nothing mode.

Authentication

license__key in request body. License must be active (IsLicenseActive) and key must have valid length (LicenseKeyLength).

Request body

Field	Type	Required	Description
license__key	string	required	License key for authentication.6 or 12 chars
messages	array	required	Array of SMS objects to send.1–1000 items
all_or_nothing	boolean	optional	If true, any validation error aborts the entire batch with rollback. Default: false (partial success).default: false

Message item schema

Field	Type	Required	Description
external_id	string	required	Unique identifier per license. Duplicate IDs are skipped.max 255 chars
message	string	required	SMS text content.
phone	string	required	Recipient phone in E.164 format.+[country][number]
send_after	ISO datetime	optional	Earliest send time. If absent, sending hours policy applies.
send_before	ISO datetime	optional	Send deadline.
priority	integer	optional	Message priority. Higher = sent sooner.default: 10

Skipped reasons

Reason	Description
duplicate_external_id	A message with this external_id already exists for this license.
opted_out	The recipient has opted out of SMS messages.
outside_sending_hours	send_after was omitted and current time is outside configured sending hours.

Request example

POST /api/messages/bulk/

{
  "license__key": "ABC123",
  "all_or_nothing": false,
  "messages": [
    {
      "external_id": "promo-april-001",
      "message": "Spring sale — 20% off all orders this week!",
      "phone": "+48123456789",
      "priority": 5
    },
    {
      "external_id": "promo-april-002",
      "message": "Spring sale — 20% off all orders this week!",
      "phone": "+48987654321",
      "send_after": "2026-04-10T10:00:00",
      "priority": 5
    }
  ]
}

Response 201

{
  "created_count": 1,
  "skipped_count": 1,
  "skipped": [
    {
      "index": 0,
      "reason": "duplicate_external_id",
      "external_id": "promo-april-001"
    }
  ]
}

Response codes

Code	Status	Description
201	Created	Batch processed. Check created_count and skipped array.
400	Bad Request	Validation error, batch exceeds 1000, or all_or_nothing=true failure.
403	Forbidden	Inactive license or daily SMS limit exceeded.
404	Not Found	License key not found.

Contact Endpoints

POST /api/contacts/contacts/

Creates a new contact or updates an existing one (matched by phone number per user). Optionally assigns to a group and sends an SMS — all in a single request.

Authentication

key + api_key in request body.

Request body

Field	Type	Required	Description
key	string	required	License key.6–12 chars
api_key	string	required	API key.12 chars
name	string	required	Contact full name.
phone	string	required	Phone in E.164 format.+[country][number]
group_name	string	optional	Group to assign the contact to. Created automatically if it does not exist.
message	string	optional	SMS content. Supports {name} personalization. Requires send_after.
send_after	ISO datetime	optional	Required when message is provided. Earliest time to send the SMS.
send_before	ISO datetime	optional	SMS send deadline.
priority	integer	optional	SMS priority. Default: 10.default: 10
ignore_foreign_numbers	boolean	optional	Skip SMS sending for non-local phone numbers. Default: false.default: false

Deduplication behavior

Phone already exists (same user) → contact name is updated, returns 200 OK

New phone → contact is created, returns 201 Created

group_name → group created via get_or_create (case-sensitive)

Request example

POST /api/contacts/contacts/

{
  "key": "ABC123",
  "api_key": "DEF456GHI789",
  "name": "Jan Kowalski",
  "phone": "+48123456789",
  "group_name": "VIP Clients",
  "message": "Welcome {name}! You have been added to our VIP list.",
  "send_after": "2026-04-10T09:00:00",
  "priority": 10,
  "ignore_foreign_numbers": false
}

Response 201

{
  "id": 5432,
  "name": "Jan Kowalski",
  "phone": "+48123456789",
  "group_name": "VIP Clients",
  "created": true
}

Response codes

Code	Status	Description
200	OK	Contact updated (phone already existed).
201	Created	New contact created.
400	Bad Request	Missing fields, invalid phone format, or send_after missing when message is provided.
401	Unauthorized	Invalid or inactive license / API key.

POST /api/contacts/contacts/bulk/

Creates or updates up to 500 contacts in a single request. Optimised with bulk DB operations: one pre-fetch query for existing contacts, one for existing groups, and bulk_create / bulk_update for new objects.

Authentication

key + api_key in request body.

Request body

Field	Type	Required	Description
key	string	required	License key.6–12 chars
api_key	string	required	API key.12 chars
contacts	array	required	Array of contact objects.1–500 items
ignore_foreign_numbers	boolean	optional	Skip SMS for non-local numbers. Applied globally to all items.default: false
all_or_nothing	boolean	optional	Reserved for future use.default: false

Contact item schema

Field	Type	Required	Description
name	string	required	Contact full name.
phone	string	required	E.164 format.^\+[1-9]\d{1,14}$
group_name	string	optional	Group to assign. Created if not exists.
message	string	optional	SMS content. Supports {name} personalization.
send_after	ISO datetime	optional	Required when message is provided.
send_before	ISO datetime	optional	SMS send deadline.
priority	integer	optional	SMS priority.default: 10

Request example

POST /api/contacts/contacts/bulk/

{
  "key": "ABC123",
  "api_key": "DEF456GHI789",
  "ignore_foreign_numbers": false,
  "all_or_nothing": false,
  "contacts": [
    {
      "name": "Anna Nowak",
      "phone": "+48111222333",
      "group_name": "Newsletter",
      "message": "Hi {name}, thanks for signing up!",
      "send_after": "2026-04-10T09:00:00"
    },
    {
      "name": "Piotr Wiśniewski",
      "phone": "+48444555666",
      "group_name": "Newsletter"
    }
  ]
}

Response 201

{
  "created_count": 1,
  "updated_count": 1,
  "skipped_count": 0,
  "skipped": [],
  "messages_created_count": 1
}

Response codes

Code	Status	Description
201	Created	Batch processed. Check created_count, updated_count, and skipped.
400	Bad Request	Validation error or batch exceeds 500.
401	Unauthorized	Invalid or inactive license / API key.

Contact Group Endpoints

POST /api/contacts/groups/

Creates a single contact group. Note: there is no uniqueness validation — creating a group with the same name twice will produce two separate groups. Use the bulk endpoint for idempotent group creation.

Authentication

key + api_key in request body.

Request body

Field	Type	Required	Description
key	string	required	License key.6–12 chars
api_key	string	required	API key.12 chars
name	string	required	Group name.

Request example

POST /api/contacts/groups/

{
  "key": "ABC123",
  "api_key": "DEF456GHI789",
  "name": "Summer Campaign 2026"
}

Response 201

{
  "id": 42,
  "name": "Summer Campaign 2026",
  "created_by": 7
}

Response codes

Code	Status	Description
201	Created	Group created.
400	Bad Request	Missing required fields.
401	Unauthorized	Invalid or inactive license / API key.

POST /api/contacts/groups/bulk/

Creates up to 200 contact groups in a single request. Idempotent — if a group with the same name already exists for this user, it is returned with status: "existed" and no duplicate is created.

Authentication

key + api_key in request body.

Request body

Field	Type	Required	Description
key	string	required	License key.6–12 chars
api_key	string	required	API key.12 chars
groups	array	required	Array of objects with a name field.1–200 items

Request example

POST /api/contacts/groups/bulk/

{
  "key": "ABC123",
  "api_key": "DEF456GHI789",
  "groups": [
    { "name": "VIP Clients" },
    { "name": "Newsletter" },
    { "name": "Inactive Users" }
  ]
}

Response 201

{
  "groups": [
    { "name": "VIP Clients", "id": 10, "status": "existed" },
    { "name": "Newsletter", "id": 43, "status": "created" },
    { "name": "Inactive Users", "id": 44, "status": "created" }
  ]
}

Response codes

Code	Status	Description
201	Created	Batch processed. Each group has status: created or existed.
400	Bad Request	Empty list or batch exceeds 200.
401	Unauthorized	Invalid or inactive license / API key.

Response Codes (summary)

Code	Status	Description
200	OK	Contact updated (phone already existed).
201	Created	New resource created or batch processed.
400	Bad Request	Validation error, missing fields, batch size exceeded, or all_or_nothing failure.
401	Unauthorized	Invalid or inactive license / API key.
403	Forbidden	Inactive license or daily SMS limit exceeded.
404	Not Found	License key or resource not found.
409	Conflict	Resource conflict (future use).
429	Too Many Requests	Rate limit exceeded.
500	Server Error	Internal server error.

SMS delivery architecture

This API queues messages in the database — it is not an SMS gateway. Actual delivery is handled by the mobile companion app (Android) which polls for pending messages every 15 minutes, sending one SMS every 10 seconds via the device's SIM card. Plan your send times accordingly.