openapi: 3.0.3
info:
  title: 'TikoSMS API Documentation'
  description: ''
  version: 1.0.0
servers:
  -
    url: 'https://api.tikosms.com'
tags:
  -
    name: Balance
    description: ''
  -
    name: 'SMS API'
    description: ''
  -
    name: 'SMS Rates'
    description: ''
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: 'You can retrieve your token in your profile settings.'
security:
  -
    default: []
paths:
  /v1/balance:
    get:
      summary: "Get current user's SMS balance"
      operationId: getCurrentUsersSMSBalance
      description: 'Requires authentication via Bearer token.'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  balance_updated: '2025.07.03 13:34:34'
                  currency_code: EUR
                  balance: 634.9288
                  in_credit_limit: 1000
                properties:
                  balance_updated:
                    type: string
                    example: '2025.07.03 13:34:34'
                  currency_code:
                    type: string
                    example: EUR
                  balance:
                    type: number
                    example: 634.9288
                  in_credit_limit:
                    type: integer
                    example: 1000
        401:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  error: 'User not authenticated'
                properties:
                  error:
                    type: string
                    example: 'User not authenticated'
      tags:
        - Balance
  /v1/messages:
    post:
      summary: ''
      operationId: postV1Messages
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  campaign_id: bc7f100a-bebb-4449-8f5a-cf5154ef2fcf
                  recipients: 3
                  duplicates_removed: 1
                properties:
                  success:
                    type: boolean
                    example: true
                  campaign_id:
                    type: string
                    example: bc7f100a-bebb-4449-8f5a-cf5154ef2fcf
                  recipients:
                    type: integer
                    example: 3
                  duplicates_removed:
                    type: integer
                    example: 1
        422:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error: 'Invalid callback URL provided'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: 'Invalid callback URL provided'
      tags:
        - 'SMS API'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from:
                  type: string
                  description: 'Sender name. Max 16 chars.'
                  example: MyBrand
                  nullable: false
                message:
                  type: string
                  description: 'The message text.'
                  example: 'Big sale today!'
                  nullable: false
                recipients:
                  type: array
                  description: "Array of recipient objects (max 100,000). Each object must have 'to' field. Duplicates are automatically removed."
                  example:
                    -
                      to: '380501234567'
                      client_ref: order-1
                  items:
                    type: string
                callback_url:
                  type: string
                  description: 'Optional global callback URL for all recipients without individual callback_url.'
                  example: 'https://example.com/callback'
                  nullable: true
                scheduled_at:
                  type: date
                  description: 'Optional future datetime when to start sending (ISO 8601 format).'
                  example: '2025-08-12 10:00:00'
                  nullable: true
                concurrency:
                  type: integer
                  description: 'Optional parameter (currently not used in processing). Accepts values 1-100. Default: 10.'
                  example: 20
                  nullable: true
              required:
                - from
                - message
                - recipients
  /v1/get_messages:
    get:
      summary: ''
      operationId: getV1Get_messages
      description: ''
      parameters:
        -
          in: query
          name: campaign_id
          description: 'uuid Filter to a single campaign.'
          example: null
          required: false
          schema:
            type: string
            description: 'uuid Filter to a single campaign.'
            example: null
            nullable: false
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  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'
                properties:
                  success:
                    type: boolean
                    example: true
                  campaigns:
                    type: array
                    example:
                      -
                        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'
                    items:
                      type: object
                      properties:
                        campaign_id:
                          type: string
                          example: bc7f100a-bebb-4449-8f5a-cf5154ef2fcf
                        sender:
                          type: string
                          example: MyBrand
                        message:
                          type: string
                          example: 'Big sale today!'
                        recipients:
                          type: integer
                          example: 1
                        created_at:
                          type: string
                          example: '2025-08-11T13:12:34.000000Z'
                        updated_at:
                          type: string
                          example: '2025-08-11T13:12:34.000000Z'
        404:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error: 'Campaign not found'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: 'Campaign not found'
      tags:
        - 'SMS API'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                campaign_id:
                  type: string
                  description: 'Must be a valid UUID.'
                  example: 6ff8f7f6-1eb3-3525-be4a-3932c805afed
                  nullable: true
  /v1/message:
    post:
      summary: ''
      operationId: postV1Message
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message_id: d3b0e5a1-2224-4a7e-8b12-7c61d3a7bfb9
                  campaign_id: 7e9d2a5c-3b8e-4b8d-9b5f-1a2c3d4e5f60
                properties:
                  success:
                    type: boolean
                    example: true
                  message_id:
                    type: string
                    example: d3b0e5a1-2224-4a7e-8b12-7c61d3a7bfb9
                  campaign_id:
                    type: string
                    example: 7e9d2a5c-3b8e-4b8d-9b5f-1a2c3d4e5f60
        403:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error: 'No SMS rate is available for this destination for your account. Please contact sales team.'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: 'No SMS rate is available for this destination for your account. Please contact sales team.'
        422:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error: "Oops! We couldn't find this number in any country on Earth. Mind giving it another look?"
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: "Oops! We couldn't find this number in any country on Earth. Mind giving it another look?"
      tags:
        - 'SMS API'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from:
                  type: string
                  description: 'Sender name. Max 15 chars.'
                  example: MySender
                  nullable: false
                message:
                  type: string
                  description: 'Message content (max 160 chars).'
                  example: 'Your OTP is 1234'
                  nullable: false
                to:
                  type: string
                  description: 'Recipient phone number in international format.'
                  example: '380501234567'
                  nullable: false
                callback_url:
                  type: string
                  description: 'The URL to send delivery reports to.'
                  example: 'https://yourdomain.com/sms-callback'
                  nullable: true
                client_ref:
                  type: string
                  description: 'Optional reference to associate with the message.'
                  example: invoice-10294
                  nullable: true
              required:
                - from
                - message
                - to
  /v1/get_message:
    get:
      summary: ''
      operationId: getV1Get_message
      description: ''
      parameters:
        -
          in: query
          name: message_id
          description: 'The UUID of the message.'
          example: d3b0e5a1-2224-4a7e-8b12-7c61d3a7bfb9
          required: false
          schema:
            type: string
            description: 'The UUID of the message.'
            example: d3b0e5a1-2224-4a7e-8b12-7c61d3a7bfb9
            nullable: false
        -
          in: query
          name: campaign_id
          description: 'The UUID of the campaign.'
          example: 7e9d2a5c-3b8e-4b8d-9b5f-1a2c3d4e5f60
          required: false
          schema:
            type: string
            description: 'The UUID of the campaign.'
            example: 7e9d2a5c-3b8e-4b8d-9b5f-1a2c3d4e5f60
            nullable: false
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  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'
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    example:
                      -
                        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'
                    items:
                      type: object
                      properties:
                        message_id:
                          type: string
                          example: d3b0e5a1-2224-4a7e-8b12-7c61d3a7bfb9
                        campaign_id:
                          type: string
                          example: 7e9d2a5c-3b8e-4b8d-9b5f-1a2c3d4e5f60
                        to:
                          type: string
                          example: '380501234567'
                        message:
                          type: string
                          example: 'Your code is 1234'
                        from:
                          type: string
                          example: MySender
                        sender_type:
                          type: string
                          example: Alpha
                        status:
                          type: string
                          example: DELIVRD
                        data_coding:
                          type: integer
                          example: 0
                        mccmnc:
                          type: string
                          example: '25501'
                        cost:
                          type: string
                          example: '0.050'
                        part:
                          type: integer
                          example: 1
                        total_parts:
                          type: integer
                          example: 1
                        sent_at:
                          type: string
                          example: '2025-08-06 12:35:18'
                        delivered_at:
                          type: string
                          example: '2025-08-06 12:35:19'
                        client_ref:
                          type: string
                          example: order-123
                        callback_url:
                          type: string
                          example: 'https://example.com/sms-callback'
        404:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error: 'Message(s) not found'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: 'Message(s) not found'
      tags:
        - 'SMS API'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                message_id:
                  type: string
                  description: 'Must not be greater than 255 characters.'
                  example: b
                  nullable: true
                campaign_id:
                  type: string
                  description: 'Must not be greater than 255 characters.'
                  example: 'n'
                  nullable: true
  /v1/sms-rates:
    get:
      summary: ''
      operationId: getV1SmsRates
      description: ''
      parameters:
        -
          in: query
          name: mccmnc
          description: 'MCCMNC code (e.g. 255001 or 255).'
          example: '255001'
          required: true
          schema:
            type: string
            description: 'MCCMNC code (e.g. 255001 or 255).'
            example: '255001'
            nullable: false
        -
          in: query
          name: country
          description: 'Country name.'
          example: Ukraine
          required: false
          schema:
            type: string
            description: 'Country name.'
            example: Ukraine
            nullable: false
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  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'
                properties:
                  success:
                    type: boolean
                    example: true
                  rate:
                    type: object
                    properties:
                      mcc:
                        type: string
                        example: '255'
                      mnc:
                        type: string
                        example: '001'
                      mccmnc:
                        type: string
                        example: '255001'
                      country:
                        type: string
                        example: Ukraine
                      rate:
                        type: string
                        example: '0.045000'
                      rate_start_date:
                        type: string
                        example: '2025-08-01 00:00:00'
                      rate_end_date:
                        type: string
                        example: '2100-01-01 00:00:00'
        404:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error: 'No SMS rate found for this destination.'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: 'No SMS rate found for this destination.'
      tags:
        - 'SMS Rates'