openapi: 3.0.0
info:
  title: Instasent Transactional API (A2P Messaging API)
  description: |
    Instasent Transactional API, also known as the **A2P Messaging API**.
    Send SMS, perform lookups and manage transactional traffic from your
    application.
  version: 1.0.0
  contact:
    name: Instasent
    email: dev@instasent.com
    url: https://instasent.com
  license:
    name: Instasent
    url: https://www.instasent.com/aviso-legal
externalDocs:
  url: https://docs.instasent.com,
  description: Access to external documentation
servers:
  - url: https://api.instasent.com
    description: Instasent Transactional API (A2P Messaging API)
security:
  - BearerAuth: []
tags:
  - name: account
    description: Account related operations
  - name: lookup
    description: Lookup related operations
  - name: price
    description: Price related operations
  - name: sms
    description: Sms related operations
paths:
  /sms:
    get:
      operationId: sms-list
      summary: List SMS
      description: |
        Request SMS collection, paginated via `page` and `per_page`.

        - Results are sorted by creation date, descending.
        - Only SMS charged within the **last 21 days** are returned.
        - SMS in `draft`, `unpaid` and `error` status are always excluded.

        To track SMS status changes in real time, use delivery report webhooks.
      tags:
        - sms
      parameters:
        - name: page
          in: query
          description: 'Page number, zero-based. Maximum: 100.'
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 100
            default: 0
        - name: per_page
          in: query
          description: 'Number of results per page. Maximum: 50.'
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 50
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entities:
                    type: array
                    items:
                      $ref: '#/components/schemas/ResponseSmsItem'
                  metadata:
                    $ref: '#/components/schemas/ListMetadata'
                required:
                  - entities
                  - metadata
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      path: /sms
      method: GET
    post:
      operationId: sms-create
      summary: Create an SMS
      description: |
        Create an SMS.

        ### Senders are required

        Every message goes out from a sender registered in your account (in the panel, SMS > Senders).
        A message whose sender is not registered is refused with `422` on `from`, and nothing is sent
        or charged.

        The only exception is the **wildcard route**, for wholesale providers that carry the traffic of
        third parties under their own customers' sender names (transit traffic). It is not available by
        default: you request it from the panel (SMS > Settings) with your wholesale legal profile, and
        Instasent enables it for your account. Once enabled, a `from` that matches none of your senders
        is delivered through the wildcard route instead of being refused, and the transit registrations
        each regulated country requires are filed for you.

        ### Sender resolution

        Two ways to identify the sender, in order of preference:

        | # | Body field          | Behavior                                                                                                                                | When to use                                                                              |
        |---|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
        | 1 | `sender` (id)       | Direct lookup of one of your senders. **Recommended.** Unknown ids return `422`.                                                | All traffic. Stable across renames; unambiguous. |
        | 2 | `from` (name)       | Sender name: 3 to 11 characters, or 3 to 14 digits when numeric. Matches one of your senders by name. If none matches: `422`, or delivery through the wildcard route when your account has that mode. | Clients that pass the sender name only, and wholesale (wildcard route) traffic.        |

        Notes:

        - When `sender` is provided, `from` may be omitted; the response always returns the sender's canonical name.
        - When both `sender` and `from` are sent, **`sender` wins** and `from` in the response is overwritten with the sender's name.
        - Mode #1 always identifies a sender — it never falls through to the wildcard route. Mode #2 is the only path that can produce wildcard route traffic, and only with the mode on.

        ### Destination countries

        You can restrict where your account sends SMS (SMS > Settings): a list of allowed countries
        (empty means every country) and a list of blocked ones, applied on top. They protect you from
        SMS pumping, where bots trigger messages to numbers in other countries. A message to a country
        that is not allowed is refused with `422` on `to`, and nothing is sent or charged.
      tags:
        - sms
      requestBody:
        $ref: '#/components/requestBodies/SmsItemBody'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entity:
                    $ref: '#/components/schemas/ResponseSmsItem'
                required:
                  - entity
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '402':
          $ref: '#/components/responses/NoFundsError'
        '413':
          $ref: '#/components/responses/RequestTooLarge'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      path: /sms
      method: POST
  /sms/{id}:
    get:
      operationId: sms-view
      summary: Get an SMS
      description: Request single SMS
      tags:
        - sms
      parameters:
        - name: id
          in: path
          description: SMS identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entity:
                    $ref: '#/components/schemas/ResponseSmsItem'
                required:
                  - entity
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      path: /sms/{id}
      method: GET
  /sms/bulk:
    post:
      operationId: sms-create-bulk
      summary: Create a Bulk SMS
      description: |
        Create an SMS collection (up to 100 items per call).

        Sender resolution is identical to `POST /sms` and is applied per
        item — see that endpoint's description for the full rules
        (registered senders, the wildcard route for wholesale accounts,
        destination countries). **The `sender` (id) field is the
        recommended form.** An item refused for its sender or its
        destination country is reported in `errors` and the rest are sent.
        One exception: a `sender` id that does not exist refuses the whole
        call with `422`, before any item is processed.
      tags:
        - sms
      requestBody:
        $ref: '#/components/requestBodies/SmsCollectionBody'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entity:
                    type: array
                    items:
                      $ref: '#/components/schemas/ResponseSmsItem'
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        fields:
                          type: object
                          properties:
                            to:
                              type: array
                              items:
                                type: string
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '402':
          $ref: '#/components/responses/NoFundsError'
        '413':
          $ref: '#/components/responses/RequestTooLarge'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      path: /sms/bulk
      method: POST
  /sms/metrics:
    get:
      operationId: sms-metrics
      summary: Get SMS metrics
      description: |
        SMS traffic metrics of your API tokens, all of them or the one
        `tokenId` names: totals, one row per day or month of the window
        (those without traffic at zero) and a breakdown per country,
        network and token.

        - Only charged messages are counted, by charge date in UTC. Test
          traffic is left out.
        - Figures are aggregated periodically: `dataUpTo` says up to when,
          and the buckets from `finalBefore` on may still change.
        - `cost` is what you were charged, in EUR.
      tags:
        - sms
      parameters:
        - name: from
          in: query
          description: 'First day of the window, included, as `YYYY-MM-DD` (UTC). With `granularity=month`, `YYYY-MM` is accepted too.'
          required: true
          schema:
            type: string
            example: '2026-09-01'
        - name: to
          in: query
          description: 'Last day of the window, included, in the same format as `from`.'
          required: true
          schema:
            type: string
            example: '2026-09-30'
        - name: granularity
          in: query
          description: 'Bucket size. `day` allows a window of at most 92 days, `month` of at most 1100 days.'
          required: false
          schema:
            type: string
            enum:
              - day
              - month
            default: day
        - name: tokenId
          in: query
          description: 'Narrows the metrics to one token, by the `tokenId` that `breakdown.byToken` returns. A token without traffic answers zeros.'
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entity:
                    $ref: '#/components/schemas/ResponseSmsMetrics'
                required:
                  - entity
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      path: /sms/metrics
      method: GET
  /lookup:
    get:
      operationId: lookup-list
      summary: List Lookup
      description: |
        Request Lookup collection, paginated via `page` and `per_page`.

        - Results are sorted by creation date, descending.
        - Lookups in `enqueued`, `unpaid` and `error` status are always excluded.
      tags:
        - lookup
      parameters:
        - name: page
          in: query
          description: 'Page number, zero-based.'
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: per_page
          in: query
          description: 'Number of results per page. Maximum: 50.'
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 50
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entities:
                    type: array
                    items:
                      $ref: '#/components/schemas/ResponseLookupItem'
                  metadata:
                    $ref: '#/components/schemas/ListMetadata'
                required:
                  - entities
                  - metadata
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      path: /lookup
      method: GET
    post:
      operationId: lookup-create
      summary: Create a Lookup
      description: Create a Lookup
      tags:
        - lookup
      requestBody:
        $ref: '#/components/requestBodies/LookupItemBody'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entity:
                    $ref: '#/components/schemas/ResponseLookupItem'
                required:
                  - entity
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '402':
          $ref: '#/components/responses/NoFundsError'
        '413':
          $ref: '#/components/responses/RequestTooLarge'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      path: /lookup
      method: POST
  /lookup/{id}:
    get:
      operationId: lookup-view
      summary: Get a Lookup
      description: Request single Lookup
      tags:
        - lookup
      parameters:
        - name: id
          in: path
          description: Lookup identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entity:
                    $ref: '#/components/schemas/ResponseLookupItem'
                required:
                  - entity
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      path: /lookup/{id}
      method: GET
  /organization/account:
    get:
      operationId: account-balance
      summary: Get account balance
      description: Request organization balance
      tags:
        - account
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entity:
                    type: object
                    properties:
                      currency:
                        type: string
                      available:
                        type: number
                    required:
                      - currency
                      - available
                required:
                  - entity
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      path: /organization/account
      method: GET
  /sms/price-profile/me/countries:
    get:
      operationId: sms-price-country
      summary: Get SMS price
      description: Request Sms country prices
      tags:
        - price
        - sms
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entities:
                    type: array
                    items:
                      type: object
                      properties:
                        currency:
                          type: string
                        price:
                          type: number
                      required:
                        - currency
                        - price
                required:
                  - entities
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      path: /sms/price-profile/me/countries
      method: GET
  /lookup/price-profile/me/countries:
    get:
      operationId: lookup-price-country
      summary: Get Lookup price
      description: Request Lookup country prices
      tags:
        - price
        - lookup
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entities:
                    type: array
                    items:
                      type: object
                      properties:
                        currency:
                          type: string
                        price:
                          type: number
                      required:
                        - currency
                        - price
                required:
                  - entities
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalError'
      path: /lookup/price-profile/me/countries
      method: GET
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
  requestBodies:
    SmsItemBody:
      description: A single SMS item
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RequestSmsItem'
    SmsCollectionBody:
      description: A collection of SMS items
      required: true
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/RequestSmsItem'
            minItems: 1
            maxItems: 100
    LookupItemBody:
      description: A single Lookup item
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RequestLookupItem'
  schemas:
    ListMetadata:
      type: object
      description: Pagination metadata for list responses
      properties:
        count:
          type: integer
          description: Number of entities in the current page
        total_count:
          type: integer
          description: Total number of entities matching the listing
        items_per_page:
          type: integer
          description: Page size applied to the request
        page_number:
          type: integer
          description: Zero-based page number of the current page
      required:
        - count
        - total_count
        - items_per_page
        - page_number
    RequestSmsItem:
      type: object
      description: |
        SMS request payload. The sender is identified via either `sender`
        (recommended) or `from` — see the sender resolution table on the
        `POST /sms` endpoint. At least one of the two must be provided.
      properties:
        clientId:
          type: string
          maxLength: 40
          description: Must be unique per SMS
        sender:
          type: string
          description: |
            **Recommended.** Id of one of your senders. When provided,
            `from` may be omitted; the response always returns the
            sender's canonical name in `from`. Unknown ids return `422`.
        from:
          type: string
          minLength: 3
          maxLength: 14
          description: |
            Sender name: 3 to 11 characters when alphanumeric, 3 to 14
            when numeric. Must match one of your registered senders by
            name, or the message is refused with `422`. Only accounts
            with the wildcard route (wholesale providers carrying
            third-party transit traffic) can send a name that matches
            none of their senders: it is delivered through the wildcard
            route. Optional when `sender` is provided.
        to:
          type: string
          maxLength: 15
          description: E164 format
        text:
          type: string
        allowUnicode:
          type: boolean
          default: false
      required:
        - to
        - text
    ResponseSmsItem:
      type: object
      properties:
        id:
          type: string
        clientId:
          type: string
          nullable: true
          default: null
        status:
          type: string
        statusCode:
          type: integer
          nullable: true
          default: null
        sender:
          type: string
          nullable: true
          description: |
            Id of the sender used for delivery (resolved server-side). When the
            message went via the wildcard route (wholesale accounts only), this is
            the id of your wildcard sender, which cannot be sent back in `sender`
            (it returns `422`).
            Null on messages sent before senders were resolved.
        from:
          type: string
          description: |
            Sender name actually used for delivery. For traffic routed
            via a sender this is the sender's canonical name; for
            traffic routed via the wildcard route (wholesale accounts
            only) this is the client-supplied name.
        country:
          type: string
        to:
          type: string
        normalizedTo:
          type: string
        charsCount:
          type: integer
        text:
          type: string
        deliveredText:
          type: string
        messagesCount:
          type: integer
        encoding:
          type: string
        unicode:
          type: boolean
        allowUnicode:
          type: boolean
        charged:
          type: boolean
        pricePerSms:
          type: number
        priceUser:
          type: number
        scheduledAt:
          type: string
          nullable: true
          default: null
        sentAt:
          type: string
          nullable: true
          default: null
        deliveredAt:
          type: string
          nullable: true
          default: null
      required:
        - id
        - clientId
        - status
        - from
        - country
        - to
        - normalizedTo
        - charsCount
        - text
        - deliveredText
        - messagesCount
        - encoding
        - unicode
        - allowUnicode
        - charged
    SmsMetricsCounters:
      type: object
      description: Counters of the window, of one bucket or of one breakdown row.
      properties:
        messages:
          type: integer
        parts:
          type: integer
          description: Message parts charged
        delivered:
          type: integer
        failed:
          type: integer
        error:
          type: integer
        sent:
          type: integer
        enqueued:
          type: integer
        expired:
          type: integer
        rejected:
          type: integer
        noDR:
          type: integer
          description: Messages without a delivery report
        cost:
          type: number
          description: Amount charged, in EUR
      required:
        - messages
        - parts
        - delivered
        - failed
        - error
        - sent
        - enqueued
        - expired
        - rejected
        - noDR
        - cost
    ResponseSmsMetrics:
      type: object
      properties:
        channelType:
          type: string
          enum:
            - sms
        granularity:
          type: string
          enum:
            - day
            - month
        from:
          type: string
          description: First bucket of the window, `YYYY-MM-DD` by day or `YYYY-MM` by month
        to:
          type: string
          description: Last bucket of the window, in the same format
        timezone:
          type: string
          enum:
            - UTC
        dataUpTo:
          type: string
          format: date-time
          nullable: true
          description: The figures hold the traffic charged up to this instant. Null when unknown.
        finalBefore:
          type: string
          description: First bucket that may still change, in the format of `from`; every earlier one is final.
        totals:
          $ref: '#/components/schemas/SmsMetricsCounters'
        series:
          type: array
          description: Every bucket of the window, in time order
          items:
            allOf:
              - type: object
                properties:
                  date:
                    type: string
                required:
                  - date
              - $ref: '#/components/schemas/SmsMetricsCounters'
        breakdown:
          type: object
          description: Rows sorted by `messages`, busiest first
          properties:
            byCountry:
              type: array
              items:
                allOf:
                  - type: object
                    properties:
                      country:
                        type: string
                        nullable: true
                  - $ref: '#/components/schemas/SmsMetricsCounters'
            byNetwork:
              type: array
              items:
                allOf:
                  - type: object
                    properties:
                      network:
                        type: string
                        nullable: true
                        description: MCC-MNC
                  - $ref: '#/components/schemas/SmsMetricsCounters'
            byToken:
              type: array
              items:
                allOf:
                  - type: object
                    properties:
                      tokenId:
                        type: string
                        nullable: true
                      name:
                        type: string
                      deleted:
                        type: boolean
                        description: The token no longer exists
                  - $ref: '#/components/schemas/SmsMetricsCounters'
      required:
        - channelType
        - granularity
        - from
        - to
        - timezone
        - dataUpTo
        - finalBefore
        - totals
        - series
        - breakdown
    RequestLookupItem:
      type: object
      properties:
        to:
          type: string
          maxLength: 15
          description: E164 format
      required:
        - to
    ResponseLookupItem:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        subscriberStatus:
          type: string
          nullable: true
          default: null
        statusCode:
          type: integer
          nullable: true
          default: null
        country:
          type: string
        imsi:
          type: string
          nullable: true
          default: null
        servingMsc:
          type: string
          nullable: true
          default: null
        to:
          type: string
        normalizedTo:
          type: string
        ported:
          type: boolean
        roaming:
          type: boolean
        network:
          type: string
        charged:
          type: boolean
        pricePerSms:
          type: number
        createdAt:
          type: string
        deliveredAt:
          type: string
          nullable: true
          default: null
      required:
        - id
        - status
        - country
        - to
        - normalizedTo
    ResponseErrorDetail:
      type: object
      properties:
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
      required:
        - title
        - status
        - detail
    ResponseErrorMessage:
      type: object
      properties:
        message:
          type: string
        code:
          type: integer
      required:
        - message
    ResponseErrorValidation:
      type: object
      properties:
        errors:
          type: object
          properties:
            fields:
              type: object
              properties:
                to:
                  type: array
                  items:
                    type: string
          required:
            - fields
      required:
        - errors
  responses:
    WrongRequestError:
      description: Request body is malformed or something went wrong with your request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorDetail'
    UnauthorizedError:
      description: |
        The token is missing or does not exist (mistyped, rotated or deleted),
        or the request comes from an IP address outside the token's accepted IPs.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorDetail'
    ForbiddenError:
      description: |
        The token exists but cannot be used for this request: it is disabled,
        expired, the user or account is deleted, not enabled or pending
        verification, or it is not a Transactional API token with HTTP access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorDetail'
    NoFundsError:
      description: You're out of money
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorDetail'
    NotFound:
      description: Resource can't be found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorDetail'
    RequestTooLarge:
      description: You are sending a large body in your request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorDetail'
    ValidationError:
      description: Some field of your request body is not valid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorValidation'
    RateLimitError:
      description: |
        You reached your endpoint rate limit. The body is the plain text below,
        not a JSON document, although the `Content-Type` header says
        `application/json`; the `X-RateLimit-Reset` header says when to retry.
      content:
        application/json:
          schema:
            type: string
            example: You exceeded the rate limit
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorDetail'
