openapi: 3.0.3
info:
  title: Number Recycling Camara
  description: |
    The API can be used to check whether the subscriber of the phone number has changed.
    A common scenario is when Application service provider (ASP) wants to check whether there has been a change in the user associated with the phone number after the specified date. This allows the ASP to ensure that a phone number is correctly linked to an user and prevent the mis-delivery of SMS messages.

    For example, below is a potential scenarios:
    * Scenario 1
      * Pre-conditions
        * User A signed a contract with MNO A for the phone number '+123456789' on October 9, 2023, and is still using it.
        * User A also signed contracts with ASP A on December 22, 2023 for its services.
        * ASP A holds the contract date (2023-12-22) and the phone number (+123456789) for User A.
        * Currently, on November 2, 2024, ASP A wishes to send a SMS message to User A.
      * Potential operations
        * ASP A sends a request with specified date (2023-12-22) and phone number (+123456789) to the Number Recycling API.
        * The API response sets to 'false', indicating that there has not been a change in the user associated with the phone number.
      * Post-conditions
        * ASP A decides to send the SMS message to User A.
      * By following these steps, ASP A ensures that a phone number is linked to User A.

    <img width="4000" alt="Number_Recycling_scenario_1" src="https://raw.githubusercontent.com/camaraproject/NumberRecycling/r1.1/documentation/API_documentation/assets/Number_Recycling_scenario_1.png">

    Note:
    * When API receives a request with specified date on which a user signed a contract with MNO, the API respond sets to 'false'(e.g., 2023-10-09 in the Scenario 1 of the figure above).

      * Scenario 2
        * Pre-conditions
          * User A signed a contract with MNO A for the phone number '+123456789' on October 9, 2023, and canceled it on February 25, 2024. Subsequently, User B signed a contract with MNO A for the same phone number on September 21, 2024, and is still using it.
          * User A also signed contracts with ASP A on December 22, 2023 for its services.
          * ASP A holds the contract date (2023-12-22) and the phone number (+123456789) for User A.
          * Currently, on November 2, 2024, ASP A wishes to send a SMS message to User A.
        * Potential operations
          * ASP A sends a request with specified date (2023-12-22) and phone number (+123456789) to the Number Recycling API.
          * The API response sets to 'true', indicating that there has been a change in the user associated with the phone number.
        * Post-conditions
          * ASP A decides to stop sending the SMS message to User A and contacts User A by mail.
        * By following these steps, ASP A ensures that a phone number is not linked to User A and prevents the mis-delivery of the SMS message.

    <img width="4000" alt="Number_Recycling_scenario_2" src="https://raw.githubusercontent.com/camaraproject/NumberRecycling/r1.1/documentation/API_documentation/assets/Number_Recycling_scenario_2.png">

    Note:
    * When the API receives a request with specified date during which there is no contract with MNO for the phone number, the API respond sets to 'true'(e.g., the period between 2024-02-25 and 2024-09-20 in the Scenario 2 of the figure above).

    # Authorization and authentication

    The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile.

    The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation.

    In cases where personal data is processed by the API and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design.

    # Identifying the phone number from the access token

    This API requires the API consumer to identify a phone number as the subject of the API as follows:
    - When the API is invoked using a two-legged access token, the subject will be identified from the optional `phoneNumber` field, which therefore MUST be provided.
    - When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token.

    This approach simplifies API usage for API consumers using a three-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the authentication process.

    ## Error handling:

    - If the subject cannot be identified from the access token and the optional `phoneNumber` field is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code.
    - If the subject can be identified from the access token and the optional `phoneNumber` field is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same phone number is identified by these two methods, as the server is unable to make this comparison.

    ### Additional CAMARA error responses
    The list of error codes in this API specification is not exhaustive. Therefore the API specification may not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`.
    Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version.
    As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API.

  version: 0.2.0



        
servers:

  - url: https://api-sandbox.vf-dmp.engineering.vodafone.com
    description: "Sandbox"
  - url: https://api.vf-dmp.engineering.vodafone.com
    description: "Production"
paths:
  /oauth2/v2/token:
    post:
      tags:
        - JWT Authentication Flow
      summary: Get Access Token using JWT Bearer
      description: Exchange a signed JWT for an OAuth2 access token.
      requestBody:
        required: true
        content:
            application/x-www-form-urlencoded:
              schema:
                type: object
                required:
                  - grant_type
                  - assertion
                properties:
                  grant_type:
                    type: string
                    description: OAuth2 JWT Bearer grant type
                    example: urn:ietf:params:oauth:grant-type:jwt-bearer
                  assertion:
                    type: string
                    description: | 
                                  Signed JWT assertion
                                    - The JWT assertion defines who issued it who it applies to, and how it can be used:
                                    
                                    Supported assertions and scope mapping:
                                        
                                        - Assertion :
                                          Must be used only with scope:
                                          "dpv:FraudPreventionAndDetection openid number-recycling:check"
                                          The same scope value must be present in the JWT scope claim.

                                    JWT claim details:

                                        - issuer (iss): Identifies the client that created and signed the JWT. This is the DMP Consumer Key issued to the application.
                                        
                                        - subject (sub): Identifies the entity the token is acting on behalf of, typically a specific MSISDN
                                          (for example: msisdn:+1234567890).

                                        - audience (aud): Identifies the intended DMP endpoint that is allowed to accept and validate the JWT
                                          (for example: https://api.vf-dmp.engineering.vodafone.com/jwks/v1).

                                        - issued at (iat): The time when the JWT was issued, represented as a Unix timestamp.
                                          (for example: 1504804131)

                                        - expiration time (exp): The time after which the JWT expires and must no longer be accepted.
                                           (for example: 1504807731)

                                        - scope : Defines the permissions being requested. Only operations explicitly listed in the scope
                                          are authorized. Any operation outside the scope must be rejected.

                                        The scope provided in the request MUST exactly match the scope inside the JWT assertion.
                                        If the assertion and scope do not correspond, the request will be rejected.

                                        The JWT assertion must be valid, signed, unexpired, and authorized for the requested operation.

                    example: eyJraWQiOiJkbXAtcHJvZC1zYW5kYm94LWtpZCIsImFsZyI6IlJTMjU2IiwidHlwIjoiSldUIn0.eyJpc3MiOiJKRm1iZ0dpZ25pQ09LUlBibHJ1SXZsTXZJckJXU0JqMjgwN3cyMFQ2MlJPUzVubXkiLCJzdWIiOiI0NDc3NDk4MDY5ODMiLCJhdWQiOiJodHRwczovL2FwaS1zYW5kYm94LnZmLWRtcC5lbmdpbmVlcmluZy52b2RhZm9uZS5jb20vb2F1dGgyL3YyL3Rva2VuIiwic2NvcGUiOiJkcHY6RnJhdWRQcmV2ZW50aW9uQW5kRGV0ZWN0aW9uIG9wZW5pZCBudW1iZXItcmVjeWNsaW5nOmNoZWNrIiwiaWF0IjoxNzc2MTU0Mjg3LCJleHAiOjE3ODM5MzAyODd9.GDcFgM9sRllFR20FOOUIpEUTgbLLgimg1VBgTJ9IhirGwR4Co7QJa_y415Je_Azy2g9NZ5HMkgrgxKYXqAkoTD5T6HUJH1osrOiEunw4fGt45D3Z3cRgEf8h7sB48KXsQ9LM7Vgs_lqTtD1h2M52O8_8VBSCzdkiu58c7NFQ1FlPFxTwv8taOGcE47Q-JuF5ErmeM31NE_B56Fiko25YEHB5Tjqb8CKSfcU39Up3Tro-bwV7HSRCJBbR4fE6Vb0Cu_z-K4O-_zWPTSHvHrBJeif8gSEzkVYyTG__eSxLGrTHWuy72pL5lW1vVSyR_6r-FrHHnGS83T7TT0uVj5Mzmg

      responses:
        "200":
          description: "**OK**"
          content:
            application/json:
              schema:
                type: object
                properties:
                  token_type:
                    type: string
                    example: Bearer
                  access_token:
                    type: string
                  expires_in:
                    type: integer
                    example: 3599
                  scope:
                    type: string
              examples:
                success_response:
                  summary: Access token for number recycling check
                  description: Returned when scope includes `number-recycling:check`
                  value:
                    token_type: Bearer
                    access_token: 43W9uMMOmGzwz8PMllON15hUPYFz
                    expires_in: 3599
                    scope: dpv:FraudPreventionAndDetection openid number-recycling:check

        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"

  /openIDConnectCIBA/v1/bc-authorize:
    post:

      tags:
        - Authentication Flow
      description: The SP makes a request to Vodafone’s Backchannel Authentication Endpoint to ask for end-user authorization. Vodafone validates the MSISDN is a Vodafone MSISDN and checks consent. If successful, it passes the request to the VF IDGW for processing. Once VF IDGW processing is successful, an “auth_req_id” is provided in the response to the SP.
      operationId: authenticationRequest
      parameters:
        - $ref: "#/components/parameters/authorization-basic"
        - $ref: "#/components/parameters/x-correlator"
        # - $ref: "#/components/parameters/vf-trace-transaction-id"
        # - $ref: "#/components/parameters/vf_ext_bp_id"
        
      requestBody:
        description: |
          The SP makes a request to Vodafone’s Backchannel Authentication Endpoint to ask for end-user authorization. Vodafone validates the MSISDN is a Vodafone MSISDN and checks consent. If successful, it passes the request to the VF IDGW for processing. Once VF IDGW processing is successful, an “auth_req_id” is provided in the response to the SP.
        content :
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/AuthorizeReq"
        required: true
      responses:
        "200":
          description: | 
            **OK** If the authorization request is successfully completed (i.e. without error), an authorization id (auth_req_id) is returned by ID Gateway, in an HTTP 200 response in json payload with parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationResp"

        "400":
          $ref: "#/components/responses/AuthError400"
        "401":
          $ref: "#/components/responses/AuthError401"


  /openIDConnectCIBA/v1/token:
    post:

      tags:
        - Authentication Flow
      description: | 
        The request to the token endpoint must be sent using the HTTP POST method and have parameters populated in accordance with the rules
      operationId: tokenRequest
      parameters:
        - $ref: "#/components/parameters/authorization-basic"
        - $ref: "#/components/parameters/x-correlator"



      requestBody:
        description: |
          The request to the token endpoint must be sent using the HTTP POST method and have parameters populated in accordance with the rules.
        content :
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/TokenReq"
        required: true
      responses:
        "200":
          description: | 
            **OK** If the token request is successfully completed (i.e. without error), an acess_token is returned by Gateway, in an HTTP 200 response in json payload with parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResp"
        "400":
          $ref: "#/components/responses/AuthError400"
        "401":
          $ref: "#/components/responses/AuthError401"




  /number-recycling/v0.2.0/check:
    post:
      # security:
      #   - openId:
      #       - number-recycling:check
      tags:
        - Check Number Recycling
      summary: Check whether the subscriber of the phone number has changed.
      # description: Check whether the subscriber of the phone number has changed.

      description: >
        Retrieves phone number recycle status based on the provided `specifiedDate`.
        Requires a valid Bearer Token for authorization.

          **Mock behavior based on `specifiedDate`:**

          - **If specifiedDate is earlier than 2025‑04‑01, then**  
            Returns a successful response with `phoneNumberRecycled` set to `false`.
          - **If specifiedDate is on or after 2025‑04‑01, then**  
            Returns a successful response with `phoneNumberRecycled` set to `true`.

          - **2025-12-03**  
            Returns a business validation error when the service is not applicable for the provided phone number.  
            Status: `422` | Code: `SERVICE_NOT_APPLICABLE`

          - **2025-12-04**  
            Returns a validation error when the phone number identifier cannot be determined.  
            Status: `422` | Code: `MISSING_IDENTIFIER`

          - **2025-12-05**  
            Returns a not-found error when the phone number does not exist in the system.  
            Status: `404` | Code: `IDENTIFIER_NOT_FOUND`

          - **Any date with year < 2023**  
            Returns a bad request error due to an invalid date range.  
            Status: `400` | Code: `OUT_OF_RANGE`

      operationId: checkNumberRecycling
      parameters:
        - $ref: '#/components/parameters/x-correlator'
        - $ref: "#/components/parameters/authorization-bearer"
      requestBody:
        description: |
          Check whether the subscriber of the phone number has changed.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCheckNumRecycling'

            examples:
                    successRecycledWithPhoneNumber:
                      summary: Success-NumberRecycled Without PhoneNumber in Payload
                      value:
                        specifiedDate: "2025-12-01"
                    successNotRecycledWithoutPhoneNumber:
                      summary: Success-NumberRecycled With PhoneNumber in Payload
                      value:
                        phoneNumber: "+447772000001"
                        specifiedDate: "2024-12-01"
        required: true
      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              $ref: "#/components/headers/x-correlator"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckNumRecyclingInfo"
        '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'




  /number-recycling/v0.2.0/ping:
    get:
      tags:
      - Monitoring
      summary: ping operation
      description: This operation returns if the API is alive
      operationId: healthcheckPing
      # x-openapi-router-controller: app.controllers.admins_controller
      security:
        - openId:
            - number-recycling:check
      parameters:
      - $ref: '#/components/parameters/x-correlator'
      - $ref: "#/components/parameters/authorization-bearer"
      responses:
        "200":
          description: ping information returned in the result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PongInfo'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'


  # /check/0.2.0/status:
  #   get:
  #     tags:
  #     - Monitoring
  #     summary: Status operation
  #     description: This operation returns if the API is working E2E
  #     operationId: healthcheckStatus
  #     # x-openapi-router-controller: app.controllers.admins_controller
  #     security:
  #       - openId:
  #           - number-recycling:check
  #     parameters:
  #     - $ref: '#/components/parameters/x-correlator'
  #     - $ref: "#/components/parameters/authorization-bearer"
  #     responses:
  #       "200":
  #         description: ping information returned in the result
  #         content:
  #           application/json:
  #             schema:
  #               $ref: '#/components/schemas/StatusInfo'
  #       '400':
  #         $ref: '#/components/responses/Generic400'
  #       '401':
  #         $ref: '#/components/responses/Generic401'
  #       '403':
  #         $ref: '#/components/responses/Generic403'




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:
        $ref: "#/components/schemas/XCorrelator"
        
    authorization-basic:
      name: Authorization
      in: header
      required: true
      description: |
        “Basic “ + base_64_encode (client_id + “:” + client_secret)
      schema:
        type: string
        example: | 
          Basic d3lCOHF1R0RPWTdXTnUyVUV2eGF5Sk9aNVpTSU1KM1Y6V2ZHQUJqSUJpRDIySg==
          
    authorization-bearer:
      name: Authorization
      in: header
      required: true
      description: |
        “Bearer ” concatenated with the access token obtained from the token endpoint response.
      schema:
        type: string
        example: | 
          Bearer dUk4Bs0qgKQKujbGxQDvIdXkI6Bz

  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        $ref: "#/components/schemas/XCorrelator"
  schemas:
  
  
    AuthorizeReq:
      type: object
      required:
        - login_hint
        - scope
      properties:
        login_hint: 
          type: string
          example : "tel:+447772000001"
          description: | 
           End-user for whom the authentication is being requested. This is MSISDN in the format “tel:+{MSISDN}”, where +" prefix is optional. Examples: “tel:+447772000001” or “tel:447772000001”, Examples for UK: +447772000001 or 447772000001, for NL +31777100001, for DE +491722100001 and for ES +34600080001.
        scope: 
          type: string
          enum:
            - openid number-recycling:check
          example: openid number-recycling:check
          description: | 
            Authorization request MUST contain the scope value.
    AuthenticationResp:
      type: object
      properties:
        interval: 
          type: number
          format: number
          example: 0
          description: | 
            The time required to wait between receiving the authorization endpoint response and making the polling endpoint request (in seconds). This value can be ignored.
        auth_req_id: 
          type: string
          format: UUID
          example: 39da5b19-457a-4d30-a5c4-047c62dcca3b
          description: |
            Unique Id of this authorization (to be used in the token request).
        expires_in: 
          type: number
          format: number
          example: 300
          description: | 
            The timeout available to make a request to the token endpoint. i.e. The request must be made before the “expires_in” time is reached.   
    TokenReq:
      type: object
      required:
        - auth_req_id
        - grant_type
      properties:
        auth_req_id: 
          type: string
          example : "39da5b19-457a-4d30-a5c4-047c62dcca3b"
          description: | 
           The auth_req_id received in the successful authorization endpoint response.
        grant_type: 
          type: string
          example: urn:openid:params:grant-type:ciba
          description: | 
            For all token requests the value of the grant_type parameter MUST have the value: "urn:openid:params:grant-type:ciba" (Note: must be url encoded)
    TokenResp:
      type: object
      properties:
        access_token: 
          type: string
          example: dUk4Bs0qgKQKujbGxQDvIdXkI6Bz
          description: |
            OAuth 2.0 access_token used to gain access to the end-user information. This token CANNOT can be reused
        token_type: 
          type: string
          example: Always "Bearer"
          description: | 
            The timeout available to make a request to the token endpoint. i.e. The request must be made before the “expires_in” time is reached.
        expires_in: 
          type: number
          format: number
          example: 3599
          description: | 
            Expiration time of the Access Token in seconds since the response was generated.
        id_token: 
          type: string
          example: "eyJraWQiOiJ0ZXN0IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYeyJpc3MiOiJodHRwczovL2FwaXN0YWdpbmdyZWYuZGV2ZWxvcGVyLnZvZGFmb25lLmNvbSIsInN1YiI6ImRhNTNhOWRlLTljMmQtNGZkYy1hODY1LWE4OWZiZThmZGE2MyIsImF1ZCI6ImJSdlJKZVBHaGlMQndmelJSdEx3Z3REVFZ4UFdSQU1BIiwiZXhwIjoxNjA2OTE2Mzc2LCJpYXQiOjE2MDY5MTI3NzYsImF1dGhfdGltZSI6MTYwNjkxMjc1Niwibm9uY2UiOiI0NTI1OTUtOWRhMS00NDZiLWE0MmEtMWJkZmJmMTRhOGJjIiwiYXRfaGFzaCI6Ik9FRkZRVFpCTURCQ09FTkJRVVZFT0RnMU1qRTRSalJCUXpaQ1FUVXdRa1E0TWtRM1JFSTVSamsyT1RVMVJEbERPRE5GUkVFM05qa3hOVFl4UWpjM09BPT0iLCJhY3IiOiIwIiwiYW1yIjpbIk5PX0FVVEhOIl0sImF6cCI6IjU0NjEyNTk1LTlkYTAtNDQ2Yi1hNDJhLTFiZGZiZjE0YThhZiIsImhhc2hlZF9sb2dpbl9oaW50IjoiQUVBNkEwMEI4Q0FBRUQ4ODUyMThGNEFDNkJBNTBCRDgyRDdEQjlGOTY5NTVEOUM4M0VEQTc2OTE1NjFCNzc4In0.8Y4SArYeLdwyVUF7zjW9hyWTULiANn_MbvfXkxk62mKdPEeTI0HNOAG9tsItR1KVhHQdotAZOcoTNLRn66w4TMphQ1K2wfRcWTWKrTXtUA3Xuyx_bhZTkm7Zkz8k944JgpxejWgCjVUejlOiaQJZhu23UWufpd1An4x8UY7JU1LsKJj_OFMleESuM4xoJru0fPUkMMcNKB9D76sfBeSaZeMdqUARBhoWLyO_cb79sFfpu1Uf9V8SFB3NLRuktu0KANwqipwc_5c4LtxzP_rw3A_hWcaGpT67Qk1-tisW6ITCvrFKzZ5aqn8qWPEcte-XGoCXwd7pp0HKzgd1G8xw"
          description: | 
            This token is not used in CAMARA CIBA flows at this stage and can be ignored.
    AuthErrorInfo:
      type: object
      required:
        - status
        - code
        - message
      properties:
        error:
          type: integer
          description: HTTP response status code
        error_description:
          type: string
          description: Detailed error description   
    PongInfo:
      description: Pong response object in return to a ping request
      type: object
      required:
        - suffix
        - client
        - startTime
        - endTime
        - responseTime
        - message
      properties:
        suffix:
          type: string
          description: Operation URI Path
          enum:
          - "/ping"
          example: "/ping"
        client:
          type: string
          description: Origin IP that request the operation
          example: "35.191.14.51"
          format: ipv4
        startTime:
          type: string
          description: Start time of the request in date-time format
          example: "2024-02-08T14:42:20.675Z"
          format: date-time
        endTime:
          type: string
          description: End time of the operation
          example: "2024-02-08T14:42:20.687Z"
          format: date-time
        responseTime:
          type: integer
          description: Time in miliseconds between startTime and endTime
          example: 12
        message:
          type: string
          description: Response message for the PING, that allways will be PONG
          example: PONG
          enum:
          - "PONG"
    StatusInfo:
      description: Status response object
      type: object
      required:
        - status
      properties:
        status:
          type: string
          description: The status of the API, that returns if the API is working E2E
          example: OK
          enum:
          - OK
          - KO
  
    CreateCheckNumRecycling:
      type: object
      required:
        - specifiedDate
      properties:
        phoneNumber:
          $ref: '#/components/schemas/PhoneNumber'
        specifiedDate:
          type: string
          format: date
          description: Specified date to check whether there has been a change in the subscriber associated with the specific phone number, in RFC 3339 calendar date format (YYYY-MM-DD).
          example: "2024-10-31"
    PhoneNumber:
      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 '+'.
      type: string
      pattern: '^\+[1-9][0-9]{4,14}$'
      example: "+123456789"
    CheckNumRecyclingInfo:
      type: object
      required:
        - phoneNumberRecycled
      properties:
        phoneNumberRecycled:
          type: boolean
          description: |
            Set to true (Boolean, not string) when there has been a change in the subscriber associated with the specific phone number after “specifiedDate”.
    ErrorInfo:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: integer
          description: HTTP response status code
        code:
          type: string
          description: A human-readable code to describe the error
        message:
          type: string
          description: A human-readable description of what the event represents
    XCorrelator:
      type: string
      pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
      example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"
  responses:
    AuthError400:
      description: | 
        **Bad Request**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthErrorInfo'
          examples:
            login_hint missing:
              value: {
                        "error": "invalid_request",
                        "error_description": "The client specified an invalid argument, request body or query param"
                      }
            scope missing:
              value: {
                        "error": "invalid_request",
                        "error_description": "The request is missing a mandatory parameter scope"
                      }
            same param multiple time:
                  value: {
                           "error": "invalid_request",
                           "error_description": "Request contains same parameter multiple times"
                          }
            invalid vf-trace-transaction-id:
                  value: {
                           "error": "invalid_request",
                           "error_description": "The request parameter vf-trace-transaction-id is invalid"
                          }
            invalid X-Correlator:
                  value: {
                           "error": "invalid_request",
                           "error_description": "The request parameter X-Correlator is invalid"
                          }
            invalid MSISDN:
                  value: {
                           "error": "invalid_request",
                           "error_description": "The client specified an invalid argument, request body or query param"
                          }
            invalid scope:
                  value: {
                           "error": "invalid_request",
                           "error_description": "The request parameter scope is invalid"
                          }
    AuthError401:
      description: |
        **Unauthorized**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthErrorInfo'
          examples:
            auth header invalid:
              value: {
                        "error": "invalid_client",
                        "error_description": "Client Authentication failed"
                      }

    Generic200:
      description: OK
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CheckNumRecyclingInfo'

    Generic400:
      description: Problem with the client request
      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:
            InvalidArgument:
              description: Invalid Argument. Generic Syntax Exception
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: Client specified an invalid argument, request body or query param.
            OutOfRange:
              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.

    Generic401:
      description: Authentication problem with the client request
      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:
            Unauthenticated:
              description: Request cannot be authenticated and a new authentication is required
              value:
                status: 401
                code: UNAUTHENTICATED
                message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required.

    Generic403:
      description: Client does not have sufficient permission
      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:
            Permission Denied:
              description: Permission denied. OAuth2 token access 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

    Generic404:
      description: Resource 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:
                      - IDENTIFIER_NOT_FOUND
          examples:
            Phone Number Used By Different Network Operator:
              description: Provided phone number is used by a different network operator
              value:
                status: 404
                code: IDENTIFIER_NOT_FOUND
                message: Phone number not found.

    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:
            Device Not Applicable:
              description: Service not applicable for the provided phone number
              value:
                status: 422
                code: SERVICE_NOT_APPLICABLE
                message: The service is not available for the provided phone number
            Unnecessary Identifier:
              description: An explicit identifier is provided when a phone number has already been identified from the access token
              value:
                status: 422
                code: UNNECESSARY_IDENTIFIER
                message: The phone number is already identified by the access token
            Missing Identifier:
              description: An identifier is not included in the request and the phone number identification cannot be derived from the 3-legged access token
              value:
                status: 422
                code: MISSING_IDENTIFIER
                message: The phone number cannot be identified