openapi: 3.0.3
info:
  title: Age Verify (CAMARA)

  description: |

    # Summary
    This API provides the customer with the ability to check if the user of the line is older than a provided age, in order to provide API customer's age-restricted services, access to its age-restricted website etc..

    # API functionality

    The API defines one service endpoint:

    - `POST /verify`

      Takes the network subscription identifier (e.g. the mobile phone number for a mobile network subscriber) and checks if the age of the subscriber is older than the age threshold in the request.
      Additionally, as optional function, provides (1) if age check is done against another form of official identification (Note) or not (verifiedStatus), (2) an overall score of how certain is the response using both information provided in the request and information that the Operator holds(identityMatchScore), (3) an indicator on whether the subscription has any kind of content lock (contentLock) and (4) an indicator on whether the subscription has any kind of parental control activated (parentalControl).
      Note: Depending on the country, credit-check or other mechanism can be used instead of official identification for Age Verification. For details, please contact API Provider.

    ## Inputs

    The endpoint request body is a JSON object with the following parameters:
    - `phoneNumber`: The network subscription identifier (i.e. the phone number of the subscriber). [Required only in case a 2-legged flow has been agreed between API Provider and API Consumer following CAMARA directives; otherwise, phoneNumber must not be included]
    - `ageThreshold`: The age threshold from which the age of the user must be compared. [Required]
    - any of `idDocument`, `name`, `givenName`, `familyName`, `middleNames`, `familyNameAtBirth`, `birthdate`, `email`; additional subscriber's information to be checked in order to confirm that the subscriber is the contract's owner [Optional]
    - `includeContentLock` and `includeParentalControl`: These two flags allow the API Client to indicate that the corresponding response properties `contentLock` and `parentalControl` should be returned. Its implementation is optional for the API Provider, so in such cases, these parameters will be ignored. [Optional]


    ## Outputs

    If successful, a JSON object is returned containing the following data:
    - `ageCheck`: Indicate 'true' when the age of the user is the same age or older than the age threshold (age >= age threshold), and 'false' if not (age < age threshold).  Otherwise, 'not_available'.
    - `verifiedStatus`: true if the information provided was checked against another form of official identification (Note), otherwise false. Note: Depending on the country, credit-check or other mechanism can be used instead of official identification for Age Verification. For details, please contact API Provider.
    - `identityMatchScore`: The overall score of identity information available in the Operator, information either provided in the request body comparing it to the one that the MNO holds or directly using internal MNO's information. It is optional for the Operator to return the Identity match score.
    - `contentLock`: Indicates if the subscription associated with the phone number has any kind of content lock (i.e certain web content blocked).
    - `parentalControl`: Indicates if the subscription associated with the phone number has any kind of parental control activated.

    ## Errors

    - If the authentication access token is not valid, a `401 UNAUTHENTICATED` error is returned
    - If the API call contains a formatting or other any other syntactic error, a `400 INVALID_ARGUMENT` error is returned.
    - If the network subscription cannot be identified from the provided parameters (e.g. the subscription identifier is not associated with any customer of the CSP), a `404 IDENTIFIER_NOT_FOUND` error is returned.
    - If the API consumer has a valid access token that does not have the required scope to obtain Age Verification information for the specified network subscription, then a `403 PERMISSION_DENIED` error is returned.

    ### 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.

    # 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.

    # 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.

    # Further info and support

    (FAQs will be added in a later version of the documentation)

  version: v0.2
  # x-camara-commonalities: 0.6
  # license:
  #   name: Apache 2.0
  #   url: https://www.apache.org/licenses/LICENSE-2.0.html

# servers:
#   - url: "{apiRoot}/kyc-age-verification/v0.2rc2"
#     variables:
#       apiRoot:
#         default: http://localhost:9091
#         description: API root
        
servers:

  - url: https://api-sandbox.vf-dmp.engineering.vodafone.com
    description: "Sandbox"
  - url: https://api.vf-dmp.engineering.vodafone.com
    description: "Production"

tags:
  - name: Authentication Flow
  - name: Age Verification
    description: Operations to verify the age of a user.

paths:

  /openIDConnectCIBA/v1/bc-authorize:
    post:
      # security:
      #   - BasicAuth: []
      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"
        # "403":
        #   $ref: "#/components/responses/AuthError403"
        # "406":
        #   $ref: "#/components/responses/AuthError406"
        # "415":
        #   $ref: "#/components/responses/AuthError415"
        # "500":
        #   $ref: "#/components/responses/AuthError500"
        # "502":
        #   $ref: "#/components/responses/AuthError502"
        # "503":
        #   $ref: "#/components/responses/AuthError503"

  /openIDConnectCIBA/v1/token:
    post:
      # security:
      #   - BasicAuth: []
      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"
        # - $ref: "#/components/parameters/vf-trace-transaction-id"
        # - $ref: "#/components/parameters/vf_ext_bp_id"


      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"

  /kyc-age-verification/v0.2/verify:
    post:
      tags:
        - Age Verification
      summary: Verify Age Threshold
      description: |
        Verify that the age of the subscriber associated with a phone number is equal to or greater than the specified age threshold value.

        As it is possible that the person holding the contract and the end-user of the subscription may not be the same, the endpoint also admits a list of optional properties to be included in the request to improve the identification. The response may optionally include the `identityMatchScore` property with a value that indicates how certain it is that the information returned relates to the person that the API Client is requesting. To increase the reliability of the information returned, the API Provider may include in the response the `verifiedStatus` property, indicating whether the identity information in its possession has been verified against an identification document legally accepted as an age verification document (Note). Note: Depending on the country, credit-check or other mechanism can be used instead of official identification for Age Verification. For details, please contact API Provider.

        If the API Client indicates request properties `includeContentLock` or `includeParentalControl` with value `true` and the API Provider implements this functionality, then the response will also include `contentLock` and `parentalControl` properties to indicate if the subscription has any kind of content filtering enabled. On the other hand, if the request properties are not included or the API Client specifies value `false`, then the response properties will not be returned. If the API Provider doesn't implement this functionality, request properties will be ignored and response properties won't be returned in any case.
      operationId: verifyAge
      # security:
      #   - openId:
      #       - kyc-age-verification:verify
      parameters:
        - $ref: "#/components/parameters/authorization-bearer"
        - $ref: '#/components/parameters/x-correlator'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyRequestBody'
            examples:
              # Two-Legged Access Token Example:
              #   value:
              #     ageThreshold: 18
              #     #phoneNumber: '+34629255833' # Note: Only required in case a 2-legged flow has been agreed between API Provider and API Consumer; otherwise, do not include phoneNumber
              #     idDocument: 66666666q
              #     name: Federica Sanchez Arjona
              #     givenName: Federica
              #     familyName: Sanchez Arjona
              #     middleNames: Sanchez
              #     familyNameAtBirth: YYYY
              #     birthdate: '1978-08-22'
              #     email: "federicaSanchez.Arjona@example.com"
              #     includeContentLock: true
              #     includeParentalControl: true
              Three-Legged Access Token Example:
                value:
                  ageThreshold: 18
                  idDocument: 66666666q
                  name: Federica Sanchez Arjona
                  givenName: Federica
                  familyName: Sanchez Arjona
                  middleNames: Sanchez
                  familyNameAtBirth: YYYY
                  birthdate: '1978-08-22'
                  email: "federicaSanchez.Arjona@gmail.com"
                  includeContentLock: true
                  includeParentalControl: true

      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponseBody'
              examples:
                KYC_200Example:
                  value:
                    ageCheck: "true"
                    verifiedStatus: true
                    identityMatchScore: 90
                    contentLock: "false"
                    parentalControl: "true"
        "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'

  /kyc-age-verification/v0.2/ping:
    get:
      tags:
        - Monitoring
      summary: Check the upstream system is up and running.
      description: |-
        This API is to check the upstream system is up and running.

      # security:
      #   - apiClientCredentials: []

      operationId: getPing

      parameters:
        - in: header
          name: x-correlator
          description: Correlation id for the different services
          required: false
          schema:
            $ref: "#/components/schemas/XCorrelator"

      responses:
        "200":
          description: "**OK**"
          content:
            application/json:
              examples:
                success_response:
                  value: {
                            "suffix": "/ping",
                            "client": "35.191.13.203",
                            "startTime": "2023-06-05T19:47:16.794Z",
                            "endTime": "2023-06-05T19:47:16.888Z",
                            "responseTime": 94,
                            "message": "PONG"
                          }
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'

  # /status:
  #   get:
  #     tags:
  #       - Monitoring
  #     summary: Check the downstream system is up and running.
  #     description: |-
  #       This API is to check the downstream system is up and running.

  #     # security:
  #     #   - apiClientCredentials: []

  #     operationId: getStatus

  #     parameters:
  #       - in: header
  #         name: x-correlator
  #         description: Correlation id for the different services
  #         required: false
  #         schema:
  #           $ref: "#/components/schemas/XCorrelator"

  #     responses:
  #       "200":
  #         description: "**OK**"
  #         content:
  #           application/json:
  #             examples:
  #               success_response:
  #                 value: {
  #                           "status": "OK",

  #                         }
  #       '400':
  #         $ref: '#/components/responses/Generic400'
  #       '401':
  #         $ref: '#/components/responses/Generic401'
 
components:
  # securitySchemes:
  #   openId:
  #     type: openIdConnect
  #     openIdConnectUrl: https://example.com/.well-known/openid-configuration

  headers:
    x-correlator:
      description: Correlation id for the different services
      required: false
      schema:
        $ref: "#/components/schemas/XCorrelator"

  parameters:
    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
    x-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services
      required: false
      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 kyc-age-verification:verify 
          example: openid kyc-age-verification:verify
          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   
    VerifyRequestBody:
      type: "object"
      description: Request to verify the age threshold provided.
      required:
        - ageThreshold
      properties:
        ageThreshold:
          $ref: "#/components/schemas/AgeThreshold"
        phoneNumber:
          $ref: "#/components/schemas/PhoneNumber"
        idDocument:
          $ref: "#/components/schemas/IdDocument"
        name:
          $ref: "#/components/schemas/Name"
        givenName:
          $ref: "#/components/schemas/GivenName"
        familyName:
          $ref: "#/components/schemas/FamilyName"
        middleNames:
          $ref: "#/components/schemas/MiddleNames"
        familyNameAtBirth:
          $ref: "#/components/schemas/FamilyNameAtBirth"
        birthdate:
          $ref: "#/components/schemas/Birthdate"
        email:
          $ref: "#/components/schemas/Email"
        includeContentLock:
          $ref: "#/components/schemas/IncludeContentLock"
        includeParentalControl:
          $ref: "#/components/schemas/IncludeParentalControl"

    AgeThreshold:
      type: "integer"
      minimum: 0
      maximum: 120
      description: The age to be verified. The indicated range is a global definition of maximum and minimum values allowed to be requested. It is important to note that this range might be more restrictive in some implementations due to local regulations of a country i.e. A country does not allow to request for an age under 18. This limitation must be informed during the onboarding process.

    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"

    IdDocument:
      type: "string"
      description: Id number associated to the official identity document in the country. It may contain alphanumeric characters.

    Name:
      type: "string"
      description: Complete name of the customer, usually composed of first/given name and last/family/sur- name in a country.  Depending on the country, the order of first/give name and last/family/sur- name varies, and middle name could be included.  It can use givenName, middleNames, familyName and/or familyNameAtBirth. For example, in ESP, name+familyName; in NLD, it can be name+middleNames+familyName or name+middleNames+familyNameAtBirth, etc.

    GivenName:
      type: "string"
      description: First/given name or compound first/given name of the customer.

    FamilyName:
      type: "string"
      description: Last name, family name, or surname of the customer.

    MiddleNames:
      type: "string"
      description: Middle name/s of the customer.

    FamilyNameAtBirth:
      type: "string"
      description: Last/family/sur- name at birth of the customer.

    Birthdate:
      type: string
      format: date
      description: The birthdate of the customer, in RFC 3339 / ISO 8601 calendar date format (YYYY-MM-DD).

    Email:
      type: string
      format: email
      description: Email address of the customer in the RFC specified format (local-part@domain).

    IncludeContentLock:
      type: boolean
      default: false
      description: If this parameter is included in the request with value `true`, the response property `contentLock` will be returned. If it is not included or its value is `false`, the response property will not be returned.

    IncludeParentalControl:
      type: boolean
      default: false
      description: If this parameter is included in the request with value `true`, the response property `parentalControl` will be returned. If it is not included or its value is `false`, the response property will not be returned.

    VerifyResponseBody:
      type: "object"
      description: Response to an age verification request
      required:
        - ageCheck
      properties:
        ageCheck:
          $ref: "#/components/schemas/AgeCheck"
        verifiedStatus:
          $ref: "#/components/schemas/VerifiedStatus"
        identityMatchScore:
          $ref: "#/components/schemas/IdentityMatchScore"
        contentLock:
          $ref: "#/components/schemas/ContentLock"
        parentalControl:
          $ref: "#/components/schemas/ParentalControl"

    AgeCheck:
      type: "string"
      description: Indicate `"true"` when the age of the user is the same age or older than the age threshold (age >= age threshold), and `"false"` if not (age < age threshold). If the API Provider doesn't have enough information to perform the validation, a `not_available` can be returned.
      enum:
        - 'true'
        - 'false'
        - 'not_available'

    VerifiedStatus:
      type: "boolean"
      description: |
        Indicate `true` if the information provided has been compared against information based on an identification document legally accepted as an age verification document (Note), otherwise indicate `false`.  Note: Depending on the country, credit-check or other mechanism can be used instead of official identification for Age Verification. For details, please contact API Provider.

    IdentityMatchScore:
      type: "integer"
      minimum: 0
      maximum: 100
      description: The overall score of identity information available in the API Provider, information either provided in the request body comparing it to the one that the API Provider holds or directly using internal API Provider's information. It is optional for the API Provider to return the Identity match score.

    ContentLock:
      type: "string"
      description: Indicate `"true"` if the subscription associated with the phone number has any kind of content lock (i.e certain web content blocked) and `"false"` if not. If the information is not available the value `not_available` can be returned.
      enum:
        - 'true'
        - 'false'
        - 'not_available'

    ParentalControl:
      type: "string"
      description: Indicate `"true"` if the subscription associated with the phone number has any kind of parental control activated and `"false"` if not. If the information is not available the value `not_available` can be returned.
      enum:
        - 'true'
        - 'false'
        - 'not_available'

    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

    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"
                      }


    Generic400:
      description: Bad 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:
            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.

    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 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: 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.

    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:
                      - IDENTIFIER_NOT_FOUND
          examples:
            GENERIC_404_IDENTIFIER_NOT_FOUND:
              description: The phone number is not associated with a CSP customer account
              value:
                status: 404
                code: IDENTIFIER_NOT_FOUND
                message: The phone number provided is not associated with a customer account

    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 is not applicable for the provided phone number
              value:
                status: 422
                code: SERVICE_NOT_APPLICABLE
                message: The service is not applicable for the provided phone number
            GENERIC_422_MISSING_IDENTIFIER:
              description: No phone number has been provided either explicitly or associated with the access token
              value:
                status: 422
                code: MISSING_IDENTIFIER
                message: No phone number has been provided
            GENERIC_422_UNNECESSARY_IDENTIFIER:
              description: An explicit phone number has been provided when one is already associated with the access token
              value:
                status: 422
                code: UNNECESSARY_IDENTIFIER
                message: An explicit phone number has been provided when one is already associated with the access token