GSMA Camara Project SMS Delivery Notification Subscription API

openapi: 3.0.3
info:
  title: Global System for Mobile Communications GSMA Camara Project SMS Delivery Notification Subscription API
  description: >-
    API to create, retrieve and delete event subscriptions related to a sms
    delivery operation performed on an associated phone number.
  termsOfService: http://swagger.io/terms/
  contact:
    email: [email protected]
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 0.1.0-alpha.1
externalDocs:
  description: Product documentation at CAMARA
  url: https://github.com/camaraproject/sendsms
servers:
  - url: '{apiRoot}/sms-delivery-notification-subscriptions/v0alpha1'
    variables:
      apiRoot:
        default: http://localhost:9091
        description: API root
tags:
  - name: SMS Delivery Notification Subscription
    description: Operation to manage event subscription on sms delivery event (swapped)
paths:
  /subscriptions:
    post:
      tags:
        - SMS Delivery Notification Subscription
      summary: Global System for Mobile Communications Create a sms delivery event subscription for a given consumer
      description: Create a sms delivery event subscription for a given consumer
      operationId: createSMSDeliverySubscription
      parameters:
        - $ref: '#/components/parameters/x-correlator'
      security:
        - openId:
            - sms-delivery:subscriptions:create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscription'
        required: true
      callbacks:
        notifications:
          '{$request.body#/webhook/notificationUrl}':
            post:
              tags:
                - Session notifications callback
              summary: Session notifications callback
              description: >
                Important: this endpoint is to be implemented by the API
                consumer.

                The sim swap server will call this endpoint whenever a swapped
                event occurs.
              operationId: postNotification
              parameters:
                - $ref: '#/components/parameters/x-correlator'
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/CloudEvent'
                    examples:
                      STATUS:
                        $ref: '#/components/examples/STATUS'
                      SUBSCRIPTION_ENDS:
                        $ref: '#/components/examples/SUBSCRIPTION_ENDS'
              responses:
                '204':
                  description: Successful notification
                  headers:
                    x-correlator:
                      $ref: '#/components/headers/x-correlator'
                '400':
                  $ref: '#/components/responses/Generic400'
                '401':
                  $ref: '#/components/responses/Generic401'
                '403':
                  $ref: '#/components/responses/Generic403'
                '500':
                  $ref: '#/components/responses/Generic500'
                '503':
                  $ref: '#/components/responses/Generic503'
              security:
                - {}
                - notificationsBearerAuth: []
      responses:
        '201':
          description: Created
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionInfo'
        '202':
          description: >-
            Request accepted to be processed. It applies for async creation
            process.
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionAsync'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '409':
          $ref: '#/components/responses/Generic409'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
    get:
      tags:
        - SMS Delivery Notification Subscription
      summary: Global System for Mobile Communications Retrieve a list of SMS Delivery event subscription
      description: Retrieve a list of SMS Delivery event subscription(s)
      operationId: retrieveSubscriptionList
      parameters:
        - $ref: '#/components/parameters/x-correlator'
      security:
        - openId:
            - sim-swap:subscriptions:read
      responses:
        '200':
          description: List of event subscription details
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubscriptionInfo'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
  /subscriptions/{subscriptionId}:
    get:
      tags:
        - SMS Delivery Notification Subscription
      summary: Global System for Mobile Communications Retrieve a sms delivery event subscription for a phone number
      description: retrieve event subscription information for a given subscription.
      operationId: retrieveSubscription
      security:
        - openId:
            - sim-swap:subscriptions:read
      parameters:
        - $ref: '#/components/parameters/SubscriptionId'
        - $ref: '#/components/parameters/x-correlator'
      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionInfo'
        '400':
          $ref: '#/components/responses/SubscriptionIdRequired'
        '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'
    delete:
      tags:
        - SMS Delivery Notification Subscription
      summary: Global System for Mobile Communications Delete a sms delivery event subscription
      operationId: deleteSubscription
      description: delete a given event subscription.
      security:
        - openId:
            - sim-swap:subscriptions:delete
      parameters:
        - $ref: '#/components/parameters/SubscriptionId'
        - $ref: '#/components/parameters/x-correlator'
      responses:
        '202':
          description: >-
            Request accepted to be processed. It applies for async deletion
            process.
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionAsync'
        '204':
          description: event subscription deleted
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
        '400':
          $ref: '#/components/responses/SubscriptionIdRequired'
        '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:
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
  parameters:
    SubscriptionId:
      name: subscriptionId
      in: path
      description: >-
        Subscription identifier that was obtained from the create event
        subscription operation
      required: true
      schema:
        $ref: '#/components/schemas/SubscriptionId'
    x-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services
      schema:
        type: string
  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        type: string
  schemas:
    SenderId:
      type: string
      description: >-
        Identifer for the matching criteria basis which call back would be
        triggered by the server. In this case it would be the message sender id.
      example: AD-HDFCBK
    MsgId:
      type: string
      example: 56647d96-b3e6-48d2-b93f-ab0d56bdd965
      description: >-
        Every request from sender application to send SMS to recepient is
        acknowledged with a MsgId. This MsgId is sent in the call back.
    Status:
      type: string
      example: SUCCESS
      description: >-
        Every request from sender application to send SMS to recepient is
        acknowledged with a MsgId. This MsgId is sent in the call back.
      enum:
        - SUCCESS
        - FAIL
    ErrorInfo:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: integer
          description: HTTP response status code
        code:
          type: string
          description: Code given to this error
        message:
          type: string
          description: Detailed error description
    CreateSubscription:
      description: The request for creating a sim swap event subscription
      type: object
      required:
        - webhook
        - subscriptionDetail
      properties:
        subscriptionDetail:
          $ref: '#/components/schemas/SubscriptionDetail'
        subscriptionExpireTime:
          type: string
          format: date-time
          example: '2023-01-17T13:18:23.682Z'
          description: The subscription expiration time in date-time format.
        subscriptionMaxEvents:
          type: integer
          description: >-
            Identifies the maximum number of event reports to be generated (>=1)
            - Once this number is reached, the subscription ends. -1 means there
            is no limit.
          example: -1
        webhook:
          $ref: '#/components/schemas/Webhook'
    Webhook:
      description: Webhook information for event channel
      type: object
      required:
        - notificationUrl
      properties:
        notificationUrl:
          type: string
          example: https://application-server.com
          description: https callback address where the event notification must be POST-ed
        notificationAuthToken:
          type: string
          example: c8974e592c2fa383d4a3960714
          description: >
            OAuth2 token to be used by the callback API endpoint. It MUST be
            indicated within HTTP Authorization header e.g. Authorization:
            Bearer $notificationAuthToken
    SubscriptionDetail:
      type: object
      description: The detail of the requested event subscription
      required:
        - senderId
        - type
      properties:
        senderId:
          $ref: '#/components/schemas/SenderId'
        type:
          $ref: '#/components/schemas/SmsDeliveryNotificationEventType'
    SmsDeliveryNotificationEventType:
      type: string
      description: >
        sms-delivery - Event triggered after sms-delivery task is complete. This
        sms-delivery tasks completion may have status/outcome as success or
        failure which is returned back in callback to the requestor.
      enum:
        - org.camaraproject.sms.v0.sms-delivery-status
    SubscriptionInfo:
      description: Represents a sim swaps subscription.
      required:
        - startsAt
        - subscriptionId
      allOf:
        - $ref: '#/components/schemas/CreateSubscription'
        - type: object
          properties:
            subscriptionId:
              $ref: '#/components/schemas/SubscriptionId'
            subscriptionDetail:
              $ref: '#/components/schemas/SubscriptionDetail'
            subscriptionExpireTime:
              type: string
              format: date-time
              example: '2023-01-17T13:18:23.682Z'
              description: The subscription expiration time in date-time format.
            webhook:
              $ref: '#/components/schemas/Webhook'
            startsAt:
              type: string
              format: date-time
              description: date time when subscription started
            expiresAt:
              type: string
              format: date-time
              description: date time when subscription will expire or expired
          required:
            - eventSubscriptionId
            - type
    SubscriptionAsync:
      description: >-
        Response for a sim swap operation managed asynchronously (Creation or
        Deletion)
      type: object
      properties:
        subscriptionId:
          $ref: '#/components/schemas/SubscriptionId'
    SubscriptionId:
      type: string
      description: The event subscription identifier.
      example: qs15-h556-rt89-1298
    CloudEvent:
      description: The notification callback
      required:
        - id
        - source
        - specversion
        - type
        - data
      properties:
        id:
          type: string
          description: identifier of this event, that must be unique in the source context.
        source:
          $ref: '#/components/schemas/Source'
        type:
          $ref: '#/components/schemas/SmsDeliveryNotificationEventType'
        specversion:
          type: string
          description: >-
            Version of the specification to which this event conforms (must be
            1.0 if it conforms to cloudevents 1.0.2 version)
          example: 1
        datacontenttype:
          type: string
          description: >-
            media-type that describes the event payload encoding, must be
            "application/json" for CAMARA APIs
          example: application/json
        data:
          type: object
          description: >-
            Event details payload described in each CAMARA API and referenced by
            its type
        time:
          $ref: '#/components/schemas/DateTime'
      discriminator:
        propertyName: type
        mapping:
          org.camaraproject.sms.v0.sms-delivery-status: '#/components/schemas/EventSimSwap'
          org.camaraproject.sms.v0.subscription-ends: '#/components/schemas/EventSimSwapSubscriptionEnds'
    Source:
      type: string
      format: uri-reference
      minLength: 1
      description: >-
        Identifies the context in which an event happened in the specific
        Provider Implementation.
      example:
        - https://github.com/cloudevents
        - mailto:[email protected]
        - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66
        - cloudevents/spec/pull/123
        - /sensors/tn-1234567/alerts
        - 1-555-123-4567
    DateTime:
      type: string
      format: date-time
      description: Timestamp of when the occurrence happened. Must adhere to RFC 3339.
      example: '2018-04-05T17:31:00Z'
    EventSimSwap:
      description: event structure for swapped event
      allOf:
        - $ref: '#/components/schemas/CloudEvent'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/DeliveryStatus'
    EventSimSwapSubscriptionEnds:
      description: event structure for event subscription ends
      allOf:
        - $ref: '#/components/schemas/CloudEvent'
        - type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/SubscriptionEnds'
    DeliveryStatus:
      description: Event detail structure for SMS Delivery event.
      type: object
      required:
        - msgId
        - subscriptionId
      properties:
        msgId:
          $ref: '#/components/schemas/MsgId'
        status:
          $ref: '#/components/schemas/Status'
        subscriptionId:
          $ref: '#/components/schemas/SubscriptionId'
    SubscriptionEnds:
      description: Event detail structure for SUBSCRIPTION_ENDS event
      type: object
      required:
        - msgId
        - terminationReason
        - subscriptionId
      properties:
        msgId:
          $ref: '#/components/schemas/MsgId'
        subscriptionId:
          $ref: '#/components/schemas/SubscriptionId'
        terminationReason:
          $ref: '#/components/schemas/TerminationReason'
        terminationDescription:
          type: string
    TerminationReason:
      type: string
      description: >
        - NETWORK_TERMINATED - API server stopped sending notification

        - SUBSCRIPTION_EXPIRED - Subscription expire time (optionally set by the
        requester) has been reached

        - MAX_EVENTS_REACHED - Maximum number of events (optionally set by the
        requester) has been reached
      enum:
        - MAX_EVENTS_REACHED
        - NETWORK_TERMINATED
        - SUBSCRIPTION_EXPIRED
  responses:
    Generic400:
      description: Problem with the client request
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 400
            code: INVALID_ARGUMENT
            message: Client specified an invalid argument, request body or query param
    Generic401:
      description: Authentication problem with the client request
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 401
            code: UNAUTHENTICATED
            message: >-
              Request not authenticated due to missing, invalid, or expired
              credentials
    Generic403:
      description: Client does not have sufficient permission
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 403
            code: PERMISSION_DENIED
            message: Client does not have sufficient permissions to perform this action
    Generic404:
      description: Resource Not Found
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 404
            code: NOT_FOUND
            message: The specified resource is not found
    Generic409:
      description: Conflict
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 409
            code: CONFLICT
            message: The specified resource is in a conflict
    Generic500:
      description: Server error
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 500
            code: INTERNAL
            message: Server error
    Generic503:
      description: Service unavailable. Typically the server is down.
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 503
            code: UNAVAILABLE
            message: Service unavailable
    SubscriptionIdRequired:
      description: Problem with the client request
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            Generic400:
              summary: Schema validation failed
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: >-
                  Client specified an invalid argument, request body or query
                  param
            subscriptionIdRequired:
              summary: subscription id is required
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: 'Expected property is missing: subscriptionId'
  examples:
    STATUS:
      value:
        id: 123655
        source: supertelco.notificationSendServer12
        type: org.camaraproject.sms.v0.sms-delivery-status
        specversion: '1.0'
        datacontenttype: application/json
        data:
          msgId: 56647d96-b3e6-48d2-b93f-ab0d56bdd965
          subscriptionId: 2ghy-55gg-7iup-yuo9
        time: '2023-01-18T13:18:23.682Z'
    SUBSCRIPTION_ENDS:
      value:
        id: 123658
        source: supertelco.notificationSendServer12
        type: org.camaraproject.sim-swap.v0.subscription-ends
        specversion: '1.0'
        datacontenttype: application/json
        data:
          phoneNumber: 123456789
          terminationReason: SUBSCRIPTION_EXPIRED
          subscriptionId: 2ghy-55gg-7iup-yuo9
          terminationDescription: subscription expire time reached
        time: '2023-01-19T13:18:23.682Z'