GSMA Send SMS API

openapi: 3.2.0
info:
  title: Global System for Mobile Communications GSMA Camara Project…
  description: SMS API provides the customer with the ability to send an SMS to a mobile phone number in use on a mobile phone device. There are 3 different categories of SMS, namely Service SMS, Promotional SMS and Transactional SMS. The SMS API can also be used to send a binary message to a mobile phone number which is being used on an (IoT) device.
  version: 0.1.0-alpha.1
  termsOfService: http://example.com/terms/
  contact:
    name: API Support
    url: http://www.example.com/support
    email: support@example.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: '{apiRoot}/{basePath}'
  variables:
    apiRoot:
      default: http://localhost:9091
      description: API root
    basePath:
      default: sms/v0alpha1
      description: Base path for the Short Message Service
tags:
- name: Send SMS
paths:
  /short-message:
    post:
      security:
      - openId:
        - send-sms:short-message
      tags:
      - Send SMS
      summary: Global System for Mobile Communications Send SMS
      description: The customer application server makes a request to the SMS API to send SMS message to the destination address.
      operationId: send-sms
      parameters:
      - $ref: '#/components/parameters/x-correlator'
      requestBody:
        description: 'Submit a request for sending SMS to the destination address

          '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageRequest'
            examples:
              MessageRequest:
                value:
                  to:
                  - '+910123456789'
                  from: '+919876543210'
                  category: PROMOTION
                  message: xxxxxxxxxx
        required: true
      responses:
        '200':
          $ref: '#/components/responses/Generic200'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
components:
  responses:
    Generic500:
      description: Server error
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 500
            code: INTERNAL
            detail: Server error
    Generic400:
      description: Problem with the client request
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 400
            code: INVALID_ARGUMENT
            detail: Client specified an invalid argument, request body or query param
    Generic401:
      description: Authentication problem with the client request
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 401
            code: UNAUTHENTICATED
            detail: Request not authenticated due to missing, invalid, or expired credentials
    Generic503:
      description: Service unavailable. Typically the server is down.
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 503
            code: UNAVAILABLE
            detail: Service unavailable
    Generic200:
      description: OK
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageResponse'
          example:
            msgId: 56647d96-b3e6-48d2-b93f-ab0d56bdd965
            timestamp: '2024-03-19T12:33:27.070Z'
    Generic404:
      description: Resource Not Found
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 404
            code: NOT_FOUND
            detail: A specified resource is not found
    Generic403:
      description: Client does not have sufficient permission
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            PermissionDenied:
              value:
                status: 403
                code: PERMISSION_DENIED
                detail: Client does not have sufficient permissions to perform this action
            InvalidTokenContext:
              value:
                status: 403
                code: INVALID_TOKEN_CONTEXT
                detail: Phone number cannot be deducted from access token context
  parameters:
    x-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services
      schema:
        type: string
  schemas:
    MessageRequest:
      type: object
      required:
      - to
      - from
      - message
      properties:
        to:
          type: array
          description: The recipients MSISDN
          items:
            type: string
        from:
          type: string
          description: The senders MSISDN
        category:
          type: string
          enum:
          - PROMOTION
          - SERVICE
          - TRANSACTION
        message:
          type: string
          description: SMS message
    ErrorInfo:
      type: object
      required:
      - status
      - code
      - detail
      properties:
        status:
          type: integer
          description: HTTP response status code
        code:
          type: string
          description: Code given to this error
        detail:
          type: string
          description: Detailed error description
    MessageResponse:
      type: object
      required:
      - msgId
      - timestamp
      properties:
        msgId:
          type: string
          description: The SMS messages sent to the recipients are identified by smsnumber are identified.
        timestamp:
          type: string
          format: date-time
          description: Timestamp when SMS was delivered. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
externalDocs:
  description: Product documentation at Camara
  url: https://github.com/camaraproject/ShortMessageService