TikoSMS API Documentation

Postman collection → OpenAPI spec →

Introduction

This documentation aims to provide all the information you need to work with our API. As you scroll, you'll see code examples for working with the API in different programming languages in the dark area to the right (or as part of the content on mobile). You can switch the language used with the tabs at the top right (or from the nav menu at the top left on mobile).

Getting Started

All API endpoints require authentication using Bearer tokens.

Obtaining API Token

  1. Register at https://tikosms.com/register
  2. Login to your account
  3. Navigate to your profile at https://tikosms.com/profile
  4. Generate your API token in the API section

Using API Token

Include your token in every request header:

Authorization: Bearer YOUR_API_TOKEN_HERE
Content-Type: application/json

Webhooks (Callbacks)

TikoSMS can send delivery reports to your server via HTTP POST requests.

Setting up callbacks:

  1. Include callback_url parameter in your SMS request
  2. Ensure your endpoint accepts POST requests
  3. Return HTTP 200 status to acknowledge receipt

Callback types:

  • create - Initial callback when SMS is accepted (status: SENT)
  • update - Final callback with delivery status (status: DELIVRD, UNDELIV, etc.)

Callback security:

  • All callbacks include a timestamp for verification
  • Callbacks are sent from TikoSMS servers with User-Agent: TikoSMS-Callback/1.0
  • Implement proper validation on your endpoint

Example "create" callback (SMS accepted):

{
  "create": {
    "message_id": "6fcfcd12-8ea5-4e45-b1b7-66e3f5e67600",
    "from": "MySender",
    "to": "380501234567",
    "status": "SENT",
    "sent_at": "2025-08-06 15:32:18"
    "callback_url": "https://yoursite.com/callback",
    "client_ref": "order-123",
    "mccmnc": "255001",
    "cost": 0.045,
    "part": 1,
    "total_parts": 1,
  }
}

Example "update" callback (final status):

{
  "update": {
    "message_id": "6fcfcd12-8ea5-4e45-b1b7-66e3f5e67600",
    "from": "MySender",
    "to": "380501234567",
    "status": "DELIVRD",
    "delivered_at": "2025-08-06 15:33:45",
    "callback_url": "https://yoursite.com/callback",
    "client_ref": "order-123",
    "mccmnc": "255001",
    "cost": 0.045,
    "part": 1,
    "total_parts": 1,
    "timestamp": "2025-08-06T15:33:45.123"
  }
}

### SMS Status Values

All SMS operations use these standard status codes:

- `SENT` - Message accepted for delivery
- `DELIVRD` - Successfully delivered to handset
- `UNDELIV` - Failed to deliver
- `EXPIRED` - Message expired before delivery
- `REJECTD` - Rejected by carrier
- `UNKNOWN` - Status unknown

### Example Request

```bash
curl -X POST https://api.tikosms.com/api/v1/message \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "MySender",
    "to": "380501234567",
    "message": "Your OTP is 1234",
    "callback_url": "https://yoursite.com/sms-callback"
  }'

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_TOKEN}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your token in your profile settings.

Balance

Get current user's SMS balance

GET
https://api.tikosms.com
/v1/balance
requires authentication

Requires authentication via Bearer token.

Headers

Authorization
Example:
Bearer {YOUR_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json
Example request: 
curl --request GET \
    --get "https://api.tikosms.com/v1/balance" \
    --header "Authorization: Bearer {YOUR_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "balance_updated": "2025.07.03 13:34:34",
    "currency_code": "EUR",
    "balance": 634.9288,
    "in_credit_limit": 1000
}
{
    "error": "User not authenticated"
}

SMS API

POST v1/messages

POST
https://api.tikosms.com
/v1/messages
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://api.tikosms.com/v1/messages" \
    --header "Authorization: Bearer {YOUR_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"from\": \"MyBrand\",
    \"message\": \"Big sale today!\",
    \"recipients\": [
        {
            \"to\": \"380501234567\",
            \"client_ref\": \"order-1\"
        }
    ],
    \"callback_url\": \"https:\\/\\/example.com\\/callback\",
    \"scheduled_at\": \"2025-08-12 10:00:00\",
    \"concurrency\": 20
}"
Example response:
{
    "success": true,
    "campaign_id": "bc7f100a-bebb-4449-8f5a-cf5154ef2fcf",
    "recipients": 3,
    "duplicates_removed": 1
}
{
    "success": false,
    "error": "Invalid callback URL provided"
}

GET v1/get_messages

GET
https://api.tikosms.com
/v1/get_messages
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

campaign_id
string

uuid Filter to a single campaign.

Body Parameters

Example request: 
curl --request GET \
    --get "https://api.tikosms.com/v1/get_messages" \
    --header "Authorization: Bearer {YOUR_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"campaign_id\": \"6ff8f7f6-1eb3-3525-be4a-3932c805afed\"
}"
Example response:
{
    "success": true,
    "campaigns": [
        {
            "campaign_id": "bc7f100a-bebb-4449-8f5a-cf5154ef2fcf",
            "sender": "MyBrand",
            "message": "Big sale today!",
            "recipients": 1,
            "created_at": "2025-08-11T13:12:34.000000Z",
            "updated_at": "2025-08-11T13:12:34.000000Z"
        }
    ]
}
{
    "success": false,
    "error": "Campaign not found"
}

POST v1/message

POST
https://api.tikosms.com
/v1/message
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://api.tikosms.com/v1/message" \
    --header "Authorization: Bearer {YOUR_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"from\": \"MySender\",
    \"message\": \"Your OTP is 1234\",
    \"to\": \"380501234567\",
    \"callback_url\": \"https:\\/\\/yourdomain.com\\/sms-callback\",
    \"client_ref\": \"invoice-10294\"
}"
Example response:
{
    "success": true,
    "message_id": "d3b0e5a1-2224-4a7e-8b12-7c61d3a7bfb9",
    "campaign_id": "7e9d2a5c-3b8e-4b8d-9b5f-1a2c3d4e5f60"
}
{
    "success": false,
    "error": "No SMS rate is available for this destination for your account. Please contact sales team."
}
{
    "success": false,
    "error": "Oops! We couldn't find this number in any country on Earth. Mind giving it another look?"
}

GET v1/get_message

GET
https://api.tikosms.com
/v1/get_message
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

message_id
string

The UUID of the message.

Example:
d3b0e5a1-2224-4a7e-8b12-7c61d3a7bfb9
campaign_id
string

The UUID of the campaign.

Example:
7e9d2a5c-3b8e-4b8d-9b5f-1a2c3d4e5f60

Body Parameters

Example request: 
curl --request GET \
    --get "https://api.tikosms.com/v1/get_message?message_id=d3b0e5a1-2224-4a7e-8b12-7c61d3a7bfb9&campaign_id=7e9d2a5c-3b8e-4b8d-9b5f-1a2c3d4e5f60" \
    --header "Authorization: Bearer {YOUR_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"message_id\": \"b\",
    \"campaign_id\": \"n\"
}"
Example response:
{
    "success": true,
    "data": [
        {
            "message_id": "d3b0e5a1-2224-4a7e-8b12-7c61d3a7bfb9",
            "campaign_id": "7e9d2a5c-3b8e-4b8d-9b5f-1a2c3d4e5f60",
            "to": "380501234567",
            "message": "Your code is 1234",
            "from": "MySender",
            "sender_type": "Alpha",
            "status": "DELIVRD",
            "data_coding": 0,
            "mccmnc": "25501",
            "cost": "0.050",
            "part": 1,
            "total_parts": 1,
            "sent_at": "2025-08-06 12:35:18",
            "delivered_at": "2025-08-06 12:35:19",
            "client_ref": "order-123",
            "callback_url": "https://example.com/sms-callback"
        }
    ]
}
{
    "success": false,
    "error": "Message(s) not found"
}

SMS Rates

GET v1/sms-rates

GET
https://api.tikosms.com
/v1/sms-rates
requires authentication

Headers

Authorization
Example:
Bearer {YOUR_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

mccmnc
string
required

MCCMNC code (e.g. 255001 or 255).

Example:
255001
country
string

Country name.

Example:
Ukraine
Example request: 
curl --request GET \
    --get "https://api.tikosms.com/v1/sms-rates?mccmnc=255001&country=Ukraine" \
    --header "Authorization: Bearer {YOUR_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "success": true,
    "rate": {
        "mcc": "255",
        "mnc": "001",
        "mccmnc": "255001",
        "country": "Ukraine",
        "rate": "0.045000",
        "rate_start_date": "2025-08-01 00:00:00",
        "rate_end_date": "2100-01-01 00:00:00"
    }
}
{
    "success": false,
    "error": "No SMS rate found for this destination."
}