openapi: 3.0.0
info:
  title: Instasent transactional API
  description: Instasent transactional API
  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
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
      tags:
        - sms
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entities:
                    type: array
                    items:
                      $ref: '#/components/schemas/ResponseSmsItem'
                required:
                  - entities
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '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
      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'
        '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'
        '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 Sms collection
      tags:
        - sms
      requestBody:
        $ref: '#/components/requestBodies/SmsCollectionBody'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entities:
                    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'
        '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
  /lookup:
    get:
      operationId: lookup-list
      summary: List Lookup
      description: Request Lookup collection
      tags:
        - lookup
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entities:
                    type: array
                    items:
                      $ref: '#/components/schemas/ResponseLookupItem'
                required:
                  - entities
        '400':
          $ref: '#/components/responses/WrongRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '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'
        '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'
        '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'
        '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'
        '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'
        '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:
    RequestSmsItem:
      type: object
      properties:
        clientId:
          type: string
          maxLength: 40
          description: Must be unique per SMS
        from:
          type: string
          minLength: 3
          maxLength: 14
          description: Max 11 chars or 14 digits
        to:
          type: string
          maxLength: 15
          description: E164 format
        text:
          type: string
        allowUnicode:
          type: boolean
          default: false
      required:
        - from
        - 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
        from:
          type: string
        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
        createdAt:
          type: string
        chargedAt:
          type: string
          nullable: true
          default: null
        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
        - createdAt
    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: You are missing or using bad credentials
      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
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorMessage'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorDetail'