GSMA Check Device Swap API

openapi: 3.2.0
info:
  title: Check Device Swap API
  description: 'This API allows to check the last time that the phone (device) - phone number association has changed


    # Introduction


    The Device Swap API performs real-time checks on the last Device Swap event, providing real-time information about whether the SIM card associated with a user''s phone number has been transferred to a different physical device.'
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 0.2.0
  x-camara-commonalities: 0.5
servers:
- url: '{apiRoot}/device-swap/v0.2'
  variables:
    apiRoot:
      default: http://localhost:9091
      description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`
tags:
- name: Check Device Swap
  description: Validate if the SIM of the end-user has been installed in a different device during a past period
paths:
  /check:
    post:
      tags:
      - Check Device Swap
      description: Check if device swap has been performed during a past period
      operationId: checkDeviceSwap
      security:
      - openId:
        - device-swap
      - openId:
        - device-swap:check
      parameters:
      - $ref: '#/components/parameters/x-correlator'
      requestBody:
        required: true
        description: 'Create a check device swap request for a phone number.

          '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCheckDeviceSwap'
            examples:
              CHECK_3LEGS:
                $ref: '#/components/examples/CHECK_3LEGS'
              CHECK_2LEGS:
                $ref: '#/components/examples/CHECK_2LEGS'
      responses:
        '200':
          description: Returns whether a device swap has been performed during a past period
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckDeviceSwapInfo'
        '400':
          $ref: '#/components/responses/Generic400Check'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '422':
          $ref: '#/components/responses/Generic422'
      summary: Check device swap
      x-summary-source: derived
components:
  responses:
    Generic422:
      description: Unprocessable Content
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 422
                code:
                  enum:
                  - SERVICE_NOT_APPLICABLE
                  - MISSING_IDENTIFIER
                  - UNNECESSARY_IDENTIFIER
          examples:
            GENERIC_422_SERVICE_NOT_APPLICABLE:
              description: Service not applicable for the provided identifier
              value:
                status: 422
                code: SERVICE_NOT_APPLICABLE
                message: The service is not available for the provided identifier.
            GENERIC_422_MISSING_IDENTIFIER:
              description: phone number is not included in the request (in case of 2-legged) or the phone number identification cannot be derived from access token (in 3-legged)
              value:
                status: 422
                code: MISSING_IDENTIFIER
                message: The device cannot be identified.
            GENERIC_422_UNNECESSARY_IDENTIFIER:
              description: An explicit identifier is provided when a device or phone number has already been identified from the access token
              value:
                status: 422
                code: UNNECESSARY_IDENTIFIER
                message: The device is already identified by the access token.
    Generic401:
      description: Unauthorized
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 401
                code:
                  enum:
                  - UNAUTHENTICATED
          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.
    Generic400Check:
      description: "Bad Request \n\nIn addition to regular scenario of INVALID_ARGUMENT, other scenarios may exist:\n- Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested (\"code\": \"OUT_OF_RANGE\",\"message\": \"Client specified an invalid range.\")"
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 400
                code:
                  enum:
                  - INVALID_ARGUMENT
                  - OUT_OF_RANGE
          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.
            GENERIC_400_OUT_OF_RANGE:
              description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested
              value:
                status: 400
                code: OUT_OF_RANGE
                message: Client specified an invalid range.
    Generic404:
      description: Not found
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 404
                code:
                  enum:
                  - NOT_FOUND
                  - IDENTIFIER_NOT_FOUND
          examples:
            GENERIC_404_NOT_FOUND:
              description: Resource is not found
              value:
                status: 404
                code: NOT_FOUND
                message: The specified resource is not found.
            GENERIC_404_IDENTIFIER_NOT_FOUND:
              description: Some identifier cannot be matched to a device
              value:
                status: 404
                code: IDENTIFIER_NOT_FOUND
                message: Device identifier not found.
    Generic403:
      description: Forbidden
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 403
                code:
                  enum:
                  - PERMISSION_DENIED
          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.
  examples:
    CHECK_2LEGS:
      summary: Check request without 3-legged access tokens
      value:
        phoneNumber: '+346661113334'
        maxAge: 120
    CHECK_3LEGS:
      summary: Check request with 3-legged access tokens
      value:
        maxAge: 120
  schemas:
    CreateCheckDeviceSwap:
      type: object
      properties:
        phoneNumber:
          $ref: '#/components/schemas/PhoneNumber'
        maxAge:
          type: integer
          example: 240
          description: 'Period in hours to be checked for device swap.

            '
          format: int32
          minimum: 1
          maximum: 2400
          default: 240
    PhoneNumber:
      type: string
      pattern: ^\+[1-9][0-9]{4,14}$
      example: '+34666111333'
      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
    CheckDeviceSwapInfo:
      type: object
      required:
      - swapped
      properties:
        swapped:
          type: boolean
          description: Indicates whether the device has been swapped during the period within the provided age.
  parameters:
    x-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services
      schema:
        type: string
        pattern: ^[a-zA-Z0-9-]{0,55}$
  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        type: string
        pattern: ^[a-zA-Z0-9-]{0,55}$
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration