openapi: 3.0.3
info:
  title: Global System for Mobile Communications GSMA Camara Project SIM Swap API
  description: >-
    SIM Swap API checks the last date that the SIM card associated with a mobile
    phone number has changed. The response may be a timestamp or a yes/no for a
    defined period (e.g. last 24h).
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
  x-camara-commonalities: 0.4.0
externalDocs:
  description: Product documentation at Camara
  url: https://github.com/camaraproject/SimSwap
servers:
  - url: '{apiRoot}/sim-swap/v1'
    variables:
      apiRoot:
        default: http://localhost:9091
        description: >-
          API root, defined by the service provider, e.g. `api.example.com` or
          `api.example.com/somepath`
paths:
  /retrieve-date:
    post:
      security:
        - openId:
            - sim-swap:retrieve-date
        - openId:
            - sim-swap
      tags:
        - Retrieve SIM Swap Date
      description: >-
        Get timestamp of last SIM swap event for a mobile user account provided
        with phone number.
      operationId: retrieveSimSwapDate
      parameters:
        - $ref: '#/components/parameters/x-correlator'
      requestBody:
        description: |
          Create a SIM swap date request for a phone number.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSimSwapDate'
        required: true
      responses:
        '200':
          description: Contains information about SIM swap change
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimSwapInfo'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '422':
          $ref: '#/components/responses/Generic422'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'
  /check:
    post:
      security:
        - openId:
            - sim-swap:check
        - openId:
            - sim-swap
      tags:
        - Check SIM Swap
      description: Check if SIM swap has been performed during a past period
      operationId: checkSimSwap
      parameters:
        - $ref: '#/components/parameters/x-correlator'
      requestBody:
        description: |
          Create a check SIM swap request for a phone number.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCheckSimSwap'
        required: true
      responses:
        '200':
          description: Returns whether a SIM swap has been performed during a past period
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckSimSwapInfo'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '422':
          $ref: '#/components/responses/Generic422'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'
components:
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
  parameters:
    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:
    SimSwapInfo:
      type: object
      required:
        - latestSimChange
      properties:
        latestSimChange:
          type: string
          format: date-time
          description: >-
            Timestamp of latest SIM swap performed. 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)
          nullable: true
          example: '2023-07-03T14:27:08.312+02:00'
    CheckSimSwapInfo:
      type: object
      required:
        - swapped
      properties:
        swapped:
          type: boolean
          description: >-
            Indicates whether the SIM card has been swapped during the period
            within the provided age.
    PhoneNumber:
      type: string
      pattern: ^\+[1-9][0-9]{4,14}$
      example: '+346661113334'
      description: >-
        A public identifier addressing a telephone subscription. In mobile
        networks it corresponds to the MSISDN (Mobile Station International
        Subscriber Directory Number). In order to be globally unique it has to
        be formatted in international format, according to E.164 standard,
        prefixed with '+'.
    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
    CreateCheckSimSwap:
      type: object
      properties:
        phoneNumber:
          $ref: '#/components/schemas/PhoneNumber'
        maxAge:
          type: integer
          example: 240
          description: |
            Period in hours to be checked for SIM swap.
          format: int32
          minimum: 1
          maximum: 2400
          default: 240
    CreateSimSwapDate:
      type: object
      properties:
        phoneNumber:
          $ref: '#/components/schemas/PhoneNumber'
  responses:
    Generic400:
      description: Bad Request
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            GENERIC_400_INVALID_ARGUMENT:
              description: Invalid Argument. Generic Syntax Exception
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: >-
                  Client specified an invalid argument, request body or query
                  param.
    Generic401:
      description: Unauthorized
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            GENERIC_401_UNAUTHENTICATED:
              description: Request cannot be authenticated
              value:
                status: 401
                code: UNAUTHENTICATED
                message: >-
                  Request not authenticated due to missing, invalid, or expired
                  credentials.
    Generic403:
      description: Forbidden
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            GENERIC_403_PERMISSION_DENIED:
              description: >-
                Permission denied. OAuth2 token access does not have the
                required scope or when the user fails operational security
              value:
                status: 403
                code: PERMISSION_DENIED
                message: >-
                  Client does not have sufficient permissions to perform this
                  action.
            GENERIC_403_INVALID_TOKEN_CONTEXT:
              description: >-
                Reflect some inconsistency between information in some field of
                the API and the related OAuth2 Token
              value:
                status: 403
                code: INVALID_TOKEN_CONTEXT
                message: phoneNumber is not consistent with access token
    Generic404:
      description: Not found
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            GENERIC_404_NOT_FOUND:
              description: Resource is not found
              value:
                status: 404
                code: NOT_FOUND
                message: The specified resource is not found.
    Generic422:
      description: Unprocessable Content
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            GENERIC_422_NOT_SUPPORTED:
              description: Not Supported
              value:
                status: 422
                code: NOT_SUPPORTED
                message: Service not supported for this phoneNumber
            UNIDENTIFIABLE_PHONE_NUMBER:
              description: >-
                The phone number is not included in the request and the phone
                number information cannot be derived from the 3-legged access
                token
              value:
                status: 422
                code: UNIDENTIFIABLE_PHONE_NUMBER
                message: The phone number cannot be identified
    Generic500:
      description: Internal Server Error
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            GENERIC_500_INTERNAL:
              description: Problem in Server side. Regular Server Exception
              value:
                status: 500
                code: INTERNAL
                message: Unknown server error. Typically a server bug.
    Generic503:
      description: Service Unavailable
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            GENERIC_503_UNAVAILABLE:
              description: >-
                Service is not available. Temporary situation usually related to
                maintenance process in the server side
              value:
                status: 503
                code: UNAVAILABLE
                message: Service Unavailable.
    Generic504:
      description: Gateway Timeout
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            GENERIC_504_TIMEOUT:
              description: API Server Timeout
              value:
                status: 504
                code: TIMEOUT
                message: Request timeout exceeded.
tags:
  - name: Check SIM Swap
  - name: Retrieve SIM Swap Date