openapi: 3.0.3
info:
  title: API Manager
  description: |
    API Manager for GSMA's CAMARA project capabilities. This service acts as a gateway that receives 
    requests conforming to the CAMARA standard and routes them to the appropriate microservices.

    The API Manager provides centralized handling of CAMARA-compliant requests, including validation,
    authentication, and proper routing to backend services. It ensures all interactions follow the 
    standardized CAMARA specifications, enabling developers to access telco network capabilities 
    through consistent interfaces regardless of the underlying implementation.

    Key features:
    - CAMARA standard compliance validation
    - Request routing to specialized microservices
    - API versioning support
    - Telco capability exposure management
    
    # Number Verification

    Number Verification API performs real-time checks to verify the phone number of the mobile device being used to access a service provider (SP) service, where the mobile device is accessing the *service provider* over a mobile network (WiFi connections are out of this API scope) either by getting the comparison result or receiving the phone number of the device that it is used, so they can verify it themselves.
    It uses direct mobile network connections to verify possession of a phone number in the background without requiring user interaction. There are neither OTPs (One-time passwords) received by SMS nor authenticator app downloads, so it is much simpler. It can be used at sign up, login, or transaction time to validate that a user's SIM (Subscriber Identity Module) is both actively connected to the mobile network and not spoofed or cloned.

    # SIM SWAP
    
    A SIM swap is a process in which a user's mobile phone number (MSISDN) is associated with a new SIM card (IMSI). This is typically done by contacting the user's mobile service provider and requesting a new SIM card for various reasons, such as a lost or damaged SIM card or upgrading to a new phone.
    SIM swap also happens during other actions like changing user's phone number, changing mobile service provider keeping user's mobile phone number or when activating a new SIM associated to the same phone number, known as multisim service. New subscription is considered as a SIM swap as well, the MSISDN which can be used by another person earlier, is associated with a SIM card it was not associated before.

    # DEVICE SWAP
    
    This API allows to check the last time that the phone (device) - phone number association has changed
    
    # KYC MATCH

    This API provides the customer with the ability to compare the information it (Service Provider, SP) has for a particular mobile phone user with that on file (and verified) by the mobile phone user's Operator in their own KYC records, in order for the SP to confirm the accuracy of the information and provide a specific service to the mobile phone user.
    
    # KYC AGE VERIFICATION
    
    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..
    
    # KYC Tenure
    
    The CAMARA Know Your Customer (KYC) Tenure API allows for verification that a network subscriber has been a customer of the Communications Service Provider (CSP) for a specified minimum length of time so as to establish a level of trust for the associated network subscription identifier.

    # Consent Information
    
    The Consent Info API allows API Consumers to easily validate whether they have the necessary permissions to process User's personal data for a specific Purpose before using other CAMARA APIs. It provides a simple `true`/`false` response and, when applicable, a URL to direct the User to manage their Consent.
    
    # Quality of Service (QoS) Profiles
    
    The Quality-of-Service (QoS) Profiles API provides a set of predefined network performance characteristics, such as latency, throughput, and priority, identified by a unique name. These profiles allow application developers to specify the desired network behavior for their application's data traffic, ensuring optimal performance. By selecting an appropriate QoS profile, developers can request stable latency (reduced jitter) or throughput for specific data flows between client devices and application servers when used by the Quality-On-Demand APIs.

    # Quality on Demand (QoD)
    
    The Quality-On-Demand (QoD) API provides a programmable interface for developers and other users (API consumers) to request stable latency or throughput managed by networks without the necessity to have an in-depth knowledge of the underlying network complexity (e.g. the 4G/5G system in case of a mobile network).

    # Number Recycling
    
    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 a user and prevent the mis-delivery of SMS messages.
    
    # AUTHN - AUTHNZ
    
    CAMARA User Authentication/Authorization follows the CAMARA Security and Interoperability Profile technical specification.
    This section describes the authorization flows that can be used to access CAMARA APIs:
      * Authorization code flow (Frontend flow) - Used to obtain a Three-Legged Access Token from the Authorization Server and initiated from the Consumption Device
      * CIBA flow (Backend flow) - Used to obtain a Three-Legged Access Token from the Authorization Server and initiated from the ASP's Application Backend
      * JWT Bearer flow - Used to obtain a Two-Legged Access Token from the Authorization Server by using a signed JWT as client assertion

  version: 1.14.0
tags:
  - name: API Manager
    description: Operations for managing and routing CAMARA-compliant API requests.
  - name: Number Verification
    description: API operation to verify a phone number received as input. It can be received either in plain text or hashed format.
  - name: Sim Swap
    description: API operation related with sim swap.
  - name: Device Swap
    description: API operation related with device swap.
  - name: KYC Match
    description: API operation related with kyc match.
  - name: KYC Age Verification
    description: API operation related with kyc age verification.
  - name: KYC Tenure
    description: API operation to check the length of tenure of a subscriber.
  - name: Consent Information
    description: API related with the consent information.
  - name: QoS Profiles
    description: API related with the QoS Profiles.
  - name: QoD
    description: API related with the QoD.
  - name: Number Recycling
    description: API related with the number recycling.
  - name: Location Retrieval
    description: API related with the location retrieval.
  - name: Authentication
    description: API related with the Authentication.
  - name: Authorization Code
    description: API related with the authorization based in authorization code.
  - name: CIBA Flow
    description: API related with the Authentication based in CIBA Flow.
servers:
  - url: 'https://apimanager-opengateway.sta.k8s.masmovil.com'
    description: staging public
  - url: 'https://apimanager-opengateway.private.sta.k8s.masmovil.com'
    description: staging private
paths:
  /bc-authorize:
    post:
      tags:
        - Authentication
        - CIBA Flow
      summary: The Backchannel Authentication Endpoint
      description: "The Backchannel Authentication Endpoint is used to initiate an out-of-band authentication of the end-user. This is done by sending an HTTP POST message directly from the Client to the OpenID Provider's Backchannel Authentication Endpoint"
      operationId: postBcAuthorize-ciba-authentication
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                login_hint:
                  description: "A hint to the OpenID Provider regarding the end-user for whom authentication is being requested. The value contains a msisdn, which identifies the end-user to the OP. RFC 3966 The tel URI for Telephone Numbers"
                  example: "tel:+34xxxxxxx"
                  type: string
                scope:
                  description: Scope of permissions
                  type: string
                binding_message:
                  description: "A human-readable identifier or message intended to be displayed on both the consumption device and the authentication device to interlock them together for the transaction by way of a visual cue for the end-user. This interlocking message enables the end-user to ensure that the action taken on the authentication device is related to the request initiated by the consumption device."
                  example: "usuario@gmail.com"
                  type: string
                client_id:
                  description: The client identifier (required when using client_assertion)
                  example: M7p4ae2yWH7SymwbUYGq2UuweVjzXNOG
                  type: string
                client_assertion_type:
                  description: Must be urn:ietf:params:oauth:client-assertion-type:jwt-bearer (if you use client_assertion authorization)
                  example: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
                  type: string
                client_assertion:
                  description: The signed JWT
                  type: string
              required:
                - login_hint
                - scope
      parameters:
        - name: Authorization
          in: header
          description: "Basic <base64(client_id:client_secret)>"
          required: false
          schema:
            type: string
      responses:
        "200":
          description: OK
          headers:
            Cache-Control:
              description: The authorization server MUST include the HTTP "Cache-Control"
                response header field with a value of "no-store" in any response
                containing tokens, secrets, or other sensitive information.
              schema:
                type: string
                enum:
                  - no-store
                default: no-store
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/bcAuthorizeResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorAccessTokenResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorAccessTokenResponse"
  /token:
    post:
      tags:
        - Authentication
        - Authorization Code
        - CIBA Flow
      summary: Token polling endpoint
      description: "After a successful authentication, the Client polls the Token Endpoint to obtain an Access Token sending an authentication request id. The Client MUST poll the Token Endpoint at a rate not exceeding that specified by the interval parameter included in the response from the Backchannel Authentication Endpoint (/bc-authorize)."
      operationId: postToken-authentication
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  description: Grant type
                  example: urn:openid:params:grant-type:ciba
                  type: string
                  enum:
                    - urn:openid:params:grant-type:ciba
                    - urn:ietf:params:oauth:grant-type:jwt-bearer
                    - authorization_code
                assertion:
                  description: Assertion with which to get an access_token (required for grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer).
                  type: string
                auth_req_id:
                  description: It is the unique identifier to identify the authentication request (transaction) made by the Client.
                  example: d221eb9b-9d33-4fe9-ba41-9711ed0309ce
                  type: string
                code:
                  description: It is the authorization code received from the /authorize endpoint.
                  example: SplxlOBeZQQYbYS6WxSbIA
                  type: string
                redirect_uri:
                  description: It is the redirection URI used in the /authorize endpoint.
                  example: https://myapp.com/callback
                  type: string
                client_id:
                  description: The client identifier
                  example: M7p4ae2yWH7SymwbUYGq2UuweVjzXNOG
                  type: string
                client_assertion_type:
                  description: Must be urn:ietf:params:oauth:client-assertion-type:jwt-bearer (if you use client_assertion authorization)
                  example: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
                  type: string
                client_assertion:
                  description: The signed JWT
                  type: string
              required:
                - grant_type
      parameters:
        - name: Authorization
          in: header
          description: "Basic <base64(client_id:client_secret)>"
          required: false
          schema:
            type: string
      responses:
        "200":
          description: OK
          headers:
            Cache-Control:
              description: The authorization server MUST include the HTTP "Cache-Control"
                response header field with a value of "no-store" in any response
                containing tokens, secrets, or other sensitive information.
              schema:
                type: string
                enum:
                  - no-store
                default: no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/postTokenResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorPostTokenResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorPostTokenResponse"
  /authorize:
    get:
      tags:
        - Authentication
        - Authorization Code
      summary: Get authentication page
      description: Logs in the user or redirects it to a page to authenticate itself
      operationId: getAuthorization-authorizationcode-authentication
      parameters:
        - name: client_id
          in: query
          description: The identifier of the client representing the app.
          required: true
          example: TtsdmebPcQtEnvLsKw7x
          schema:
            type: string
        - name: response_type
          in: query
          description: Which in a basic authorization code flow request should be code. Authn only support code
          required: true
          example: token
          schema:
            type: string
            enum:
              - token
              - code
        - name: redirect_uri
          in: query
          required: false
          description: Should be the HTTP endpoint on your server that will receive the response from Authn. The value must exactly match one of the authorized redirect URIs for the OAuth 2.0 client, which you configured in the register of application. If this value doesn't match an authorized URI, the request will fail with a 401 error.
          example: https://masmovil.com/login/callback
          schema:
            type: string
        - name: state
          in: query
          required: true
          description: Should include the value of the anti-forgery unique session token, as well as any other information needed to recover the context when the user returns to your application, e.g., the starting URL.
          example: 0AxLygT73V6kreKzkQySOjfYShIvK/TR
          schema:
            type: string
        - name: login_hint
          in: query
          required: false
          description: If your application knows which user is trying to authenticate, it can use this parameter to provide a hint to the Authentication Server. The server uses the hint to simplify the login flow either by prefilling the email field in the sign-in form or by selecting the appropriate multi-login session.
          example: my_user@masmovil.com
          schema:
            type: string
        - name: groups_hint
          in: query
          required: false
          description: The sub string is equivalent to the groups in the provider (only support Google ). If you do not provide a groups_hint and the user is currently logged in, in the next request of token, the access_token will not contain claim groups
          example: group1+group2
          schema:
            type: string
        - name: access_type
          in: query
          required: false
          description: The allowed values are offline and online. If an access token is being requested, the client does not receive a refresh token unless a value of offline is specified.
          example: online
          schema:
            type: string
        - name: code_challenge
          in: query
          required: false
          description: Specifies an encoded code_verifier that will be used as a server-side challenge during authorization code exchange. This string helps mitigating against the threat usually through the use of Proof Key for Code Exchange (PKCE)
          example: 5VTycQU924SQ3jHp5g9zcvMF2ai3aN89kxzB2D5QJUrejxam3jddqFUugD8F
          schema:
            type: string
        - name: code_challenge_method
          in: query
          required: false
          description: Specifies what method was used to encode a code_verifier that will be used during authorization code exchange. This parameter must be used with the code_challenge parameter. The value of the code_challenge_method defaults to plain if not present in the request that includes a code_challenge. The only supported values for this parameter are S256 or plain.
          example: S256
          schema:
            type: string
        - name: scopes
          in: query
          required: false
          example: openid dpv:FraudPreventionAndDetection number-verification:verify
          schema:
            type: string
      responses:
        "302":
          description: Authorization code/Implicit grant response
          headers:
            Location:
              description: The redirect uri of the client
              schema:
                type: string
        "400":
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/errorAccessTokenResponse"
        "401":
          description: Unauthorized
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/errorAccessTokenResponse"
  /kyc-match/v0/match:
    post:
      tags:
        - KYC Match
        - API Manager
      summary: (V0) Matching a customer identity by checking a set of attributes related against the account data bound to their phone number.
      description: "(V0) Verify matching of a number of attributes related to a customer identity against the verified data bound to their phone number in the Operator systems. Regardless of whether the `phoneNumber` is explicitly stated in the request body, at least one of the other fields must be provided, otherwise a `HTTP 400 - KNOW_YOUR_CUSTOMER.INVALID_PARAM_COMBINATION` error will be returned.
        In order to proceed with the match check, some Operators may have the requirement to perform an additional level of validation based on the `idDocument` property. This means that, in those cases, the `idDocument` is required and the provided value needs to match the one stored in the Operator system associated with the indicated `phoneNumber`. This validation will be done before proceeding with the match check of the rest of the properties. The following two rules apply only in the cases where the Operator have the requirement to validate the `idDocument`:
        - If no `idDocument` is provided, then a `HTTP 403 - KNOW_YOUR_CUSTOMER.ID_DOCUMENT_REQUIRED` error will be returned.
        - If the provided `idDocument` does not match the one stored in the Operator systems, then a `HTTP 403 - KNOW_YOUR_CUSTOMER.ID_DOCUMENT_MISMATCH` error will be returned.
        The API will return the result of the matching process for each requested attribute. This means that the response will **only** contain the attributes for which validation has been requested. Possible values are:
          - **true**: the attribute provided matches with the one in the Operator systems.
          - **false**: the attribute provided does not match with the one in the Operator systems.
          - **not_available**: the attribute is not available to validate. "
      operationId: kycmatch-v0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KYC_MatchRequestBody'
            examples:
              Two-Legged and Three-leg Access Token Example:
                value:
                  phoneNumber: '+34629255833'
                  idDocument: 66666666q
                  name: Federica Sanchez Arjona
                  givenName: Federica
                  familyName: Sanchez Arjona
                  nameKanaHankaku: federica
                  nameKanaZenkaku: Ｆｅｄｅｒｉｃａ
                  middleNames: Sanchez
                  familyNameAtBirth: YYYY
                  address: Tokyo-to Chiyoda-ku Iidabashi 3-10-10
                  streetName: Nicolas Salmeron
                  streetNumber: '4'
                  postalCode: '1028460'
                  region: Tokyo
                  locality: ZZZZ
                  country: JP
                  houseNumberExtension: VVVV
                  birthdate: '1978-08-22'
                  email: abc@example.com
                  gender: OTHER
              Three-Legged Without Phone Number Example:
                value:
                  idDocument: 66666666q
                  name: Federica Sanchez Arjona
                  givenName: Federica
                  familyName: Sanchez Arjona
                  nameKanaHankaku: federica
                  nameKanaZenkaku: Ｆｅｄｅｒｉｃａ
                  middleNames: Sanchez
                  familyNameAtBirth: YYYY
                  address: Tokyo-to Chiyoda-ku Iidabashi 3-10-10
                  streetName: Nicolas Salmeron
                  streetNumber: '4'
                  postalCode: '1028460'
                  region: Tokyo
                  locality: ZZZZ
                  country: JP
                  houseNumberExtension: VVVV
                  birthdate: '1978-08-22'
                  email: abc@example.com
                  gender: OTHER
      parameters:
        - name: Authorization
          in: header
          description: "Bearer 'token'"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KYC_MatchResponse'
              examples:
                KYC_Match200Example:
                  value:
                    idDocumentMatch: 'true'
                    nameMatch: 'true'
                    givenNameMatch: 'not_available'
                    familyNameMatch: 'not_available'
                    nameKanaHankakuMatch: 'true'
                    nameKanaZenkakuMatch: 'false'
                    middleNamesMatch: 'true'
                    familyNameAtBirthMatch: 'false'
                    familyNameAtBirthMatchScore: 90
                    addressMatch: 'true'
                    streetNameMatch: 'true'
                    streetNumberMatch: 'true'
                    postalCodeMatch: 'true'
                    regionMatch: 'true'
                    localityMatch: 'not_available'
                    countryMatch: 'true'
                    houseNumberExtensionMatch: 'not_available'
                    birthdateMatch: 'false'
                    emailMatch: 'false'
                    emailMatchScore: 87
                    genderMatch: 'false'
        '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/verify:
    post:
      tags:
        - KYC Age Verification
        - API Manager
      summary: (V0) Verify Age Threshold
      description: |
        (V0) 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: kycAgeVerificationVerify-v0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KYCAgeVerificationVerifyRequestBody'
            example:
              ageThreshold: 18
              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
      parameters:
        - name: Authorization
          in: header
          description: "Bearer 'token'"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KYCAgeVerificationVerifyResponseBody'
              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'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'
  /kyc-tenure/v0/check-tenure:
    post:
      tags:
        - KYC Tenure
        - API Manager
      summary: (V0) The KYC Tenure service API
      description: |
        (V0) Verifies a specified length of tenure, based on a provided date, for a network
        subscriber to establish a level of trust for the network subscription identifier.
      operationId: checkTenure-v0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TenureRequest"
            example:
              phoneNumber: "+34629255833"
              tenureDate: "2023-07-03"
      parameters:
        - name: Authorization
          in: header
          description: "Bearer 'token'"
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Respond with tenure information
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TenureResponse"
              examples:
                TenureCheckExample:
                  value:
                    tenureDateCheck: true
                    contractType: "PAYM"
        "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'
  /device-swap/v0/retrieve-date:
    post:
      tags:
        - Device Swap
        - API Manager
      description: (V0) Get timestamp of last device swap for a mobile user account provided with phone number.
      operationId: retrieveDeviceSwapDate-v0
      requestBody:
        description: "Create a device swap date request for a phone number."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDeviceSwapDate"
        required: true
      parameters:
        - name: Authorization
          in: header
          description: "Bearer 'token'"
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Contains information about Device swap change
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeviceSwapInfo"
        "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"
  /device-swap/v0/check:
    post:
      tags:
        - Device Swap
        - API Manager
      description: (V0) Check if device swap has been performed during a past period
      operationId: checkDeviceSwap-v0
      requestBody:
        description: |
          Create a check device swap request for a phone number.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateCheckDeviceSwap"
        required: true
      parameters:
        - name: Authorization
          in: header
          description: "Bearer 'token'"
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Returns whether a device swap has been performed during a past period
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckDeviceSwapInfo"
        "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"
  /consent-info/v0/retrieve:
    post:
      tags:
        - Consent Information
        - API Manager
      summary: (V0) Create a request to retrieve the validity status of the data processing
      description: >
        (V0) Create a request to retrieve the validity status of the API Consumer
        data processing for a given User, scope(s) and Purpose.
      operationId: consentInfoRetrieve-v0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentInfoRetrieveStatusRequestBody'
      parameters:
        - name: Authorization
          in: header
          description: "Bearer 'token'"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentInfoRetrieveStatusResponseBody'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '422':
          $ref: '#/components/responses/Generic422'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'

  /number-verification/v1/verify:
    post:
      tags:
        - Number Verification
        - API Manager
      summary: (V1) Verifies if the received hashed/plain text phone number matches the phone number associated with the access token
      description: "(V1) Verifies if the specified phone number (either in plain text or hashed format) matches the one that the user is currently using. Only one of the plain or hashed formats must be provided.
        - The number verification will be done for the user that has authenticated via mobile network
        - It returns true/false depending on if the hashed phone number received as input matches the authenticated user's `device phone number` associated to the access token"
      operationId: phoneNumberVerify-v1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NumberVerificationRequestBody'
        required: true
      parameters:
        - name: Authorization
          in: header
          description: "Bearer 'token'"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberVerificationMatchResponse'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'
  /number-verification/v1/device-phone-number:
    get:
      tags:
        - Number Verification
        - API Manager
      summary: (V1) Returns the phone number associated with the access token
      description: "(V1) Returns the phone number so the API clients can verify the number themselves:
        - It will be done for the user that has authenticated via mobile network
        - It returns the authenticated user's `device phone number` associated to the access token"
      operationId: phoneNumberShare-v1
      parameters:
        - name: Authorization
          in: header
          description: "Bearer 'token'"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberVerificationShareResponse'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'
  /number-verification/v2/verify:
    post:
      tags:
        - Number Verification
        - API Manager
      summary: (V2) Verifies if the received hashed/plain text phone number matches the phone number associated with the access token
      description: "(V2) Verifies if the specified phone number (either in plain text or hashed format) matches the one that the user is currently using. Only one of the plain or hashed formats must be provided.
        - The number verification will be done for the user that has authenticated via mobile network
        - It returns true/false depending on if the hashed phone number received as input matches the authenticated user's `device phone number` associated to the access token"
      operationId: phoneNumberVerify-v2
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NumberVerificationRequestBody'
        required: true
      parameters:
        - name: Authorization
          in: header
          description: "Bearer 'token'"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberVerificationMatchResponse'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'
  /number-verification/v2/device-phone-number:
    get:
      tags:
        - Number Verification
        - API Manager
      summary: (V2) Returns the phone number associated with the access token
      description: "(V2) Returns the phone number so the API clients can verify the number themselves:
        - It will be done for the user that has authenticated via mobile network
        - It returns the authenticated user's `device phone number` associated to the access token"
      operationId: phoneNumberShare-v2
      parameters:
        - name: Authorization
          in: header
          description: "Bearer 'token'"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberVerificationShareResponse'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'
  /sim-swap/v1/retrieve-date:
    post:
      tags:
        - Sim Swap
        - API Manager
      description: (V1) Get timestamp of last SIM swap event for a mobile user account provided with phone number.
      operationId: retrieveSimSwapDate-v1
      requestBody:
        description: |
          Create a SIM swap date request for a phone number.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSimSwapDate"
        required: true
      parameters:
        - name: Authorization
          in: header
          description: "Bearer 'token'"
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Contains information about SIM swap change
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
          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"
  /sim-swap/v1/check:
    post:
      tags:
        - Sim Swap
        - API Manager
      description: (V1) Check if SIM swap has been performed during a past period
      operationId: checkSimSwap-v1
      requestBody:
        description: |
          Create a check SIM swap request for a phone number.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateCheckSimSwap"
        required: true
      parameters:
        - name: Authorization
          in: header
          description: "Bearer 'token'"
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Returns whether a SIM swap has been performed during a past period
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
          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"
  /qos-profiles/v1/retrieve-qos-profiles:
    post:
      tags:
        - QoS Profiles
        - API Manager
      description: (V1) Returns all QoS Profiles that match the given criteria.
      operationId: retrieveQoSProfiles-v1
      requestBody:
        description: Parameters to query QoS Profiles for a given device
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QosProfileDeviceRequest"
        required: true
      parameters:
        - name: Authorization
          in: header
          description: "Bearer 'token'"
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Contains information about QoS Profiles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/QosProfile"
              examples:
                List of QoS Profiles:
                  summary: A list of QoS profiles with a single entry
                  description: Example response when requesting a list of QoS profiles
                  value:
                    - name: "voice"
                      description: "QoS profile for high-quality interactive voice"
                      status: "ACTIVE"
                      targetMinUpstreamRate:
                        value: 100
                        unit: "kbps"
                      targetMinDownstreamRate:
                        value: 100
                        unit: "kbps"
                      minDuration:
                        value: 1
                        unit: "Days"
                      maxDuration:
                        value: 10
                        unit: "Days"
                      priority: 10
                      packetDelayBudget:
                        value: 50
                        unit: "Milliseconds"
                      jitter:
                        value: 5
                        unit: "Milliseconds"
                      packetErrorLossRate: 3
                      l4sQueueType: "non-l4s-queue"
        "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"
  /qos-profiles/v1/qos-profiles/{name}:
    get:
      tags:
        - QoS Profiles
        - API Manager
      description: (V1) Returns a QoS Profile that matches the given name.
      operationId: getQoSProfile-v1
      parameters:
        - name: Authorization
          in: header
          description: "Bearer 'token'"
          required: true
          schema:
            type: string
        - name: name
          in: path
          description: Qos Profile name
          required: true
          schema:
            $ref: "#/components/schemas/QosProfileName"
      responses:
        "200":
          description: Contains information about QoS Profiles
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QosProfile"
        "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"
  /quality-on-demand/v1/sessions:
    post:
      tags:
        - QoD
        - API Manager
      summary: Creates a new session
      description: |
        Create QoS Session to manage latency/throughput priorities
        
        If the qosStatus in the API response is "AVAILABLE" and a notification callback is provided the API consumer will receive in addition to the response a
        `QOS_STATUS_CHANGED` event notification with `qosStatus` as `AVAILABLE`.
        
        If the `qosStatus` in the API response is `REQUESTED`, the client will receive either
        - a `QOS_STATUS_CHANGED` event notification with `qosStatus` as `AVAILABLE` after the network notifies that it has created the requested session, or
        - a `QOS_STATUS_CHANGED` event notification with `qosStatus` as `UNAVAILABLE` and `statusInfo` as `NETWORK_TERMINATED` after the network notifies that it has failed to provide the requested session.
        
        A `QOS_STATUS_CHANGED` event notification with `qosStatus` as `UNAVAILABLE` will also be send if the network terminates the session before the requested duration expired
        
        **NOTES:**
        - In case of a `QOS_STATUS_CHANGED` event with `qosStatus` as `UNAVAILABLE` and `statusInfo` as `NETWORK_TERMINATED` the resources of the QoS session are not directly released, but will get deleted automatically at earliest 360 seconds after the event.
        
          This behavior allows API consumers which are not receiving notification events but are polling to get the session information with the `qosStatus` `UNAVAILABLE` and `statusInfo` `NETWORK_TERMINATED`. Before a API consumer can attempt to create a new QoD session for the same device and flow period they must release the session resources with an explicit `delete` operation if not yet automatically deleted.
        - The access token may be either 2-legged or 3-legged. See "Identifying the device from the access token" for further information
          - When the API is invoked using a two-legged access token, the subject will be identified from the optional `device` object, 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.

      operationId: createSessionQoD-v1
      parameters:
        - name: Authorization
          in: header
          description: "Bearer 'token'"
          required: true
          schema:
            type: string
      requestBody:
        description: Parameters to create a new session
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSession"
        required: true
      callbacks:
        notifications:
          "{$request.body#/sink}":
            post:
              tags:
                - Session notifications callback
              summary: "Session notifications callback"
              description: |
                Important: this endpoint is to be implemented by the API consumer.
                The API provider will call this endpoint whenever any QoS session change (e.g. network termination) related event occurs.
                Currently only QOS_STATUS_CHANGED event is defined.
              operationId: postNotification
              parameters:
                - $ref: "#/components/parameters/x-correlator"
              requestBody:
                required: true
                content:
                  application/cloudevents+json:
                    schema:
                      $ref: "#/components/schemas/CloudEvent"
                    examples:
                      QOS_STATUS_CHANGED_EXAMPLE:
                        summary: QoS status changed
                        description: Cloud event example for QoS status change to UNAVAILABLE due to DURATION_EXPIRED
                        value:
                          id: 83a0d986-0866-4f38-b8c0-fc65bfcda452
                          source: 'https://api.example.com/qod/v1/sessions/123e4567-e89b-12d3-a456-426614174000'
                          specversion: '1.0'
                          type: "org.camaraproject.quality-on-demand.v1.qos-status-changed"
                          time: '2024-06-01T13:00:00Z'
                          data:
                            sessionId: '123e4567-e89b-12d3-a456-426614174000'
                            qosStatus: 'UNAVAILABLE'
                            statusInfo: 'DURATION_EXPIRED'
              responses:
                "204":
                  description: Successful notification
                  headers:
                    x-correlator:
                      $ref: '#/components/headers/x-correlator'
                "400":
                  $ref: "#/components/responses/Generic400"
                "401":
                  $ref: "#/components/responses/Generic401"
                "403":
                  $ref: "#/components/responses/Generic403"
                "410":
                  $ref: "#/components/responses/Generic410"
              security:
                - { }
                - notificationsBearerAuth: [ ]
      responses:
        "201":
          description: Session created
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionInfo"
              examples:
                Successful Session Creation:
                  summary: Successful session creation with device not included in response
                  description: Example response after a new QoS session has been created using a 3-legged access token, or possibly a single device identifier
                  value:
                    applicationServer:
                      ipv4Address: 198.51.100.0/24
                    qosProfile: QOS_L
                    sink: https://application-server.com/notifications
                    sessionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    duration: 3600
                    qosStatus: REQUESTED
                Successful Session Creation With Device Disambiguation:
                  summary: Successful session creation with device included in response
                  description: Example response after a new QoS session has been created using a 2-legged access token with multiple device identifiers, or possibly only a single device identifier
                  value:
                    device:
                      phoneNumber: "+123456789"
                    applicationServer:
                      ipv4Address: 198.51.100.0/24
                    qosProfile: QOS_L
                    sink: https://application-server.com/notifications
                    sessionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    duration: 3600
                    qosStatus: REQUESTED
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "409":
          $ref: "#/components/responses/Generic409"
        "422":
          $ref: "#/components/responses/Generic422"
  /quality-on-demand/v1/sessions/{sessionId}:
    get:
      tags:
        - QoD
        - API Manager
      summary: Get QoS session information
      description: |
        Querying for QoS session resource information details
        
        **NOTES:**
        - The access token may be either 2-legged or 3-legged.
        - If a 3-legged access token is used, the end user (and device) associated with the session must also be associated with the access token.
        - The session must have been created by the same API client given in the access token

      operationId: getSessionQoD-v1
      parameters:
        - name: Authorization
          in: header
          description: "Bearer 'token'"
          required: true
          schema:
            type: string
        - name: sessionId
          in: path
          description: Session ID that was obtained from the createSession operation
          required: true
          schema:
            $ref: "#/components/schemas/SessionId"
        - $ref: "#/components/parameters/x-correlator"
      responses:
        "200":
          description: Contains information about active session
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionInfo"
              examples:
                SESSION_AVAILABLE_EXAMPLE:
                  summary: QoS session status is available
                  description: QoS session info when status is available
                  value:
                    duration: 3600
                    applicationServer:
                      ipv4Address: 198.51.100.0/24
                    qosProfile: QOS_L
                    sink: https://application-server.com/notifications
                    sessionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    startedAt: "2024-06-01T12:00:00Z"
                    expiresAt: "2024-06-01T13:00:00Z"
                    qosStatus: AVAILABLE
                SESSION_UNAVAILABLE_EXAMPLE:
                  summary: QoS session is unavailable
                  description: QoS session info when status is unavailable due to network termination
                  value:
                    duration: 2428
                    applicationServer:
                      ipv4Address: 198.51.100.0/24
                    qosProfile: QOS_L
                    sink: https://application-server.com/notifications
                    sessionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    startedAt: "2024-06-01T12:00:00Z"
                    expiresAt: "2024-06-01T12:40:28Z"
                    qosStatus: UNAVAILABLE
                    statusInfo: NETWORK_TERMINATED
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
    delete:
      tags:
        - QoD
        - API Manager
      summary: Delete a QoS session
      description: |
        Release resources related to QoS session
        
        If the notification callback is provided and the `qosStatus` of the session was `AVAILABLE` the client will receive in addition to the response a `QOS_STATUS_CHANGED` event with
        - `qosStatus` as `UNAVAILABLE` and
        - `statusInfo` as `DELETE_REQUESTED`
        There will be no notification event if the `qosStatus` was already `UNAVAILABLE`.
        
        **NOTES:**
        - The access token may be either 2-legged or 3-legged.
        - If a 3-legged access token is used, the subject associated with the session must also be associated with the access token.
        - The session must must have been created by the same API consumer given in the access token

      operationId: deleteSessionQoD-v1
      parameters:
        - name: Authorization
          in: header
          description: "Bearer 'token'"
          required: true
          schema:
            type: string
        - name: sessionId
          in: path
          description: Session ID that was obtained from the createSession operation
          required: true
          schema:
            $ref: "#/components/schemas/SessionId"
        - $ref: "#/components/parameters/x-correlator"
      responses:
        "204":
          description: Session deleted
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
  /quality-on-demand/v1/sessions/{sessionId}/extend:
    post:
      tags:
        - QoD
        - API Manager
      summary: "Extend the duration of an active session"
      description: |
        Extend the overall session duration of an active QoS session (with qosStatus = AVAILABLE).
        The overall duration of the QoS session, including the additional extended duration, shall not exceed the maximum duration limit fixed for the QoS Profile. If the current duration plus the value of `requestedAdditionalDuration` exceeds the maximum limit, the new overall duration shall be capped to the maximum value allowed.
        An example: For a QoS profile limited to a `maxDuration` of 50,000 seconds, a QoD session was originally created with duration 30,000 seconds. Before the session expires, the developer requests to extend the session by another 30,000 seconds:
        - Previous duration: 30,000 seconds
        - Requested additional duration: 30,000 seconds
        - New overall session duration: 50,000 seconds (the maximum allowed)
        
        **NOTES:**
        - The access token may be either 2-legged or 3-legged.
        - If a 3-legged access token is used, the subject associated with the session must also be associated with the access token.
        - The session must must have been created by the same API consumer given in the access token

      operationId: extendQosSessionDurationQoD-v1
      parameters:
        - name: Authorization
          in: header
          description: "Bearer 'token'"
          required: true
          schema:
            type: string
        - name: sessionId
          in: path
          description: Session ID that was obtained from the createSession operation
          required: true
          schema:
            $ref: "#/components/schemas/SessionId"
        - $ref: "#/components/parameters/x-correlator"
      requestBody:
        description: Parameters to extend the duration of an active session
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExtendSessionDuration"
        required: true
      responses:
        "200":
          description: Contains information about active session
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionInfo"
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "409":
          $ref: "#/components/responses/Generic409"
  /quality-on-demand/v1/retrieve-sessions:
    post:
      tags:
        - QoD
        - API Manager
      summary: Get QoS session information for a device
      description: |
        Querying for QoS session resource information details for a device
        
        **NOTES:**
        - The access token may be either 2-legged or 3-legged.
          - If a 3-legged access token is used, the subject associated with the session must also be associated with the access token. In this case the optional `device` parameter MUST NOT be provided in the request.
          - If a 2-legged access token is used, the device parameter must be provided and identify a device.
        - The session must have been created by the same API consumer given in the access token
        - If no QoS session is found for the requested device, an empty array is returned.
        - This call uses the POST method instead of GET to comply with the CAMARA Commonalities guidelines for sending sensitive or complex data in API calls. Since the device field may contain personally identifiable information, it should not be sent via GET.
          [CAMARA API Design Guidelines](https://github.com/camaraproject/Commonalities/blob/r3.3/documentation/CAMARA-API-Design-Guide.md#65-post-or-get-for-transferring-sensitive-or-complex-data)

      operationId: retrieveSessionsByDeviceQoD-v1
      parameters:
        - $ref: "#/components/parameters/x-correlator"
      requestBody:
        description: Parameters to get QoS session information by device
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RetrieveSessionsInput"
        required: true
      responses:
        "200":
          description: Returns the QoS sessions information for a given device. A device may have multiple sessions, thus the response is an array. An empty array is returned if no sessions are found.
          headers:
            x-correlator:
              $ref: "#/components/headers/x-correlator"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetrieveSessionsOutput"
              examples:
                RETRIEVE_SESSIONS_ONE_ITEM:
                  summary: List of QoS sessions for the specified device
                  description: A single QoS session for the specified device is available
                  value:
                    - applicationServer:
                        ipv4Address: 0.0.0.0/0
                      qosProfile: QOS_L
                      sink: https://application-server.com/notifications
                      sessionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                      duration: 3600
                      startedAt: "2024-06-01T12:00:00Z"
                      expiresAt: "2024-06-01T13:00:00Z"
                      qosStatus: AVAILABLE
                RETRIEVE_SESSIONS_EXAMPLE_WITH_DEVICE_RESPONSE:
                  summary: List of QoS sessions for a specified device with the device in the response
                  description: A single QoS session for the device is available and the device to which the session applies is included in the response
                  value:
                    - device:
                        phoneNumber: "+123456789"
                      applicationServer:
                        ipv4Address: 0.0.0.0/0
                      qosProfile: QOS_L
                      sink: https://application-server.com/notifications
                      sessionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                      duration: 3600
                      startedAt: "2024-06-01T12:00:00Z"
                      expiresAt: "2024-06-01T13:00:00Z"
                      qosStatus: AVAILABLE
                RETRIEVE_SESSIONS_EMPTY_EXAMPLE:
                  summary: No sessions found for the device
                  description: An empty array is returned when no sessions are found for the device
                  value: [ ]
        "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/check:
    post:
      tags:
        - Number Recycling
        - API Manager
      description: Check whether the subscriber of the phone number has changed.
      operationId: checkNumberRecycling-v0
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NumberRecyclingCreateCheck'
        required: true
      parameters:
        - name: Authorization
          in: header
          description: "Bearer 'token'"
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberRecyclingCheckInfo'
        "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"
  /location-retrieval/v0/retrieve:
    post:
      tags:
        - Location Retrieval
        - API Manager
      description: Retrieve the area where a certain user device is localized.
      operationId: retrieveLocation-v0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrievalRequest'
      parameters:
        - name: Authorization
          in: header
          description: "Bearer 'token'"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Location retrieval result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Location'
        '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'


components:
  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        $ref: "#/components/schemas/XCorrelator"
  parameters:
    x-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services
      schema:
        $ref: "#/components/schemas/XCorrelator"
  schemas:
    XCorrelator:
      description: Value for the x-correlator
      type: string
    bcAuthorizeResponse:
      type: object
      required:
        - auth_req_id
        - expires_in
        - interval
      properties:
        auth_req_id:
          type: string
          description: REQUIRED. This is a unique identifier to identify the authentication request made by the Client.
          example: d221eb9b-9d33-4fe9-ba41-9711ed0309ce
        expires_in:
          type: integer
          description: The duration in seconds for which the authentication request is valid.
          example: 360
        interval:
          type: integer
          description: The minimum amount of time in seconds that the client SHOULD wait between polling to check if the authentication request has been completed.
          example: 60
    postTokenResponse:
      type: object
      required:
        - access_token
        - token_type
      properties:
        access_token:
          type: string
          description: A token used by the client to make authenticated requests on behalf
            of the resource owner
          example: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik1VTkJaNa0ZGTWtKQlFqVkRPVFV4TlVWQ04wRTRPVEV5UWpGRFJFSTFNMFZEUXpBMU1UVTVNQSJ9.eyJpc3MiOiJodHRwczovL21hc21vdmlsLmV1LmF1dGgwLmNvbS8iLCJzdWIiOiJNN3A0YWUyeVdIN1N5bXdiVVlHcTJVdXdlVmp6WE5PR0BjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9tYXNtb3ZpbC5ldS5hdXRoMC5jb20vYXBpL3YyLyIsImlhdCI6MTU1MDQyMDM3NywiZXhwIjoxNTUwNTA2Nzc3LCJhenAiOiJNN3A0YWUyeVdIN1N5bXdiVVlHcTJVdXdlVmp6WE5PRyIsInNjb3BlIjoicmVhZDpjbGllbnRfZ3JhbnRzIGNyZWF0ZTpjbGllbnRfZ3JhbnRzIGRlbGV0ZTpjbGllbnRfZ3JhbnRzIHVwZGF0ZTpjbGllbnRfZ3JhbnRzIHJlYWQ6dXNlcnMgdXBkYXRlOnVzZXJzIGRlbGV0ZTp1c2VycyBjcmVhdGU6dXNlcnMgcmVhZDp1c2Vyc19hcHBfbWV0YWRhdGEgdXBkYXRlOnVzZXJzX2FwcF9tZXRhZGF0YSBkZWxldGU6dXNlcnNfYXBwX21ldGFkYXRhIGNyZWF0ZTp1c2Vyc19hcHBfbWV0YWRhdGEgY3JlYXRlOnVzZXJfdGlja2V0cyByZWFkOmNsaWVudHMgdXBkYXRlOmNsaWVudHMgZGVsZXRlOmNsaWVudHMgY3JlYXRlOmNsaWVudHMgcmVhZDpjbGllbnRfa2V5cyB1cGRhdGU6Y2xpZW50X2tleXMgZGVsZXRlOmNsaWVudF9rZXlzIGNyZWF0ZTpjbGllbnRfa2V5cyByZWFkOmNvbm5lY3Rpb25zIHVwZGF0ZTpjb25uZWN0aW9ucyBkZWxldGU6Y29ubmVjdGlvbnMgY3JlYXRlOmNvbm5lY3Rpb25zIHJlYWQ6cmVzb3VyY2Vfc2VydmVycyB1cGRhdGU6cmVzb3VyY2Vfc2VydmVycyBkZWxldGU6cmVzb3VyY2Vfc2VydmVycyBjcmVhdGU6cmVzb3VyY2Vfc2VydmVycyByZWFkOmRldmljZV9jcmVkZW50aWFscyB1cGRhdGU6ZGV2aWNlX2NyZWRlbnRpYWxzIGRlbGV0ZTpkZXZpY2VfY3JlZGVudGlhbHMgY3JlYXRlOmRldmljZV9jcmVkZW50aWFscyByZWFkOnJ1bGVzIHVwZGF0ZTpydWxlcyBkZWxldGU6cnVsZXMgY3JlYXRlOnJ1bGVzIHJlYWQ6cnVsZXNfY29uZmlncyB1cGRhdGU6cnVsZXNfY29uZmlncyBkZWxldGU6cnVsZXNfY29uZmlncyByZWFkOmVtYWlsX3Byb3ZpZGVyIHVwZGF0ZTplbWFpbF9wcm92aWRlciBkZWxldGU6ZW1haWxfcHJvdmlkZXIgY3JlYXRlOmVtYWlsX3Byb3ZpZGVyIGJsYWNrbGlzdDp0b2tlbnMgcmVhZDpzdGF0cyByZWFkOnRlbmFudF9zZXR0aW5ncyB1cGRhdGU6dGVuYW50X3NldHRpbmdzIHJlYWQ6bG9ncyByZWFkOnNoaWVsZHMgY3JlYXRlOnNoaWVsZHMgZGVsZXRlOnNoaWVsZHMgdXBkYXRlOnRyaWdnZXJzIHJlYWQ6dHJpZ2dlcnMgcmVhZDpncmFudHMgZGVsZXRlOmdyYW50cyByZWFkOmd1YXJkaWFuX2ZhY3RvcnMgdXBkYXRlOmd1YXJkaWFuX2ZhY3RvcnMgcmVhZDpndWFyZGlhbl9lbnJvbGxtZW50cyBkZWxldGU6Z3VhcmRpYW5fZW5yb2xsbWVudHMgY3JlYXRlOmd1YXJkaWFuX2Vucm9sbG1lbnRfdGlja2V0cyByZWFkOnVzZXJfaWRwX3Rva2VucyBjcmVhdGU6cGFzc3dvcmRzX2NoZWNraW5nX2pvYiBkZWxldGU6cGFzc3dvcmRzX2NoZWNraW5nX2pvYiByZWFkOmN1c3RvbV9kb21haW5zIGRlbGV0ZTpjdXN0b21fZG9tYWlucyBjcmVhdGU6Y3VzdG9tX2RvbWFpbnMgcmVhZDplbWFpbF90ZW1wbGF0ZXMgY3JlYXRlOmVtYWlsX3RlbXBsYXRlcyB1cGRhdGU6ZW1haWxfdGVtcGxhdGVzIiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIn0.h6GTIB8OMcMXDxyUzUW8tJ8LW7U_yIQfCshDuOW9E-_rd9NNRBxzsPhVHllawcB336Xfo3kwrVmS0KdkLGWz4BJo67R_4KXjQ_1VcmHD2WfzpS06fmjdV1DWZbd5dv3LBtPXEIYxWVzFSUcAlIKo5cstYlUWvb1weh56yBu26Y48UK5CIjwLmqAtlxL3kNcMI_PPuM-UmiQPeNe8cKPN4c7Tf_aVw38DcGydY53GIJ_fTeRvB5kb9CO4bs6g4iWOFZFFuLAluRFZsKcqJwNdW1RDYB_blmva5Q8JrBeU5TkbfdrWIL2QfdD93hjLFcWgE9z6txUz5opW2qkcMoQkLA
        scope:
          type: string
          description: Scopes
          example: read:client_grants create:client_grants delete:client_grants
            update:client_grants
        expires_in:
          type: integer
          example: 86400
        token_type:
          type: string
          example: Bearer
        refresh_token:
          type: string
          description: A token used by the client to obtain a new access token without
            having to involve the resource owner.
          example: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik1VTkJNa0ZGTWtKQlFqVkRPVFV4TlVWQ04wRTRPVEV5UWpGRFJFSTFNMFZEUXpBMU1UVTVNQSJ9
    KYC_MatchRequestBody:
      type: object
      description: Payload to validate the customer data.
      properties:
        phoneNumber:
          type: string
          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 '+'.
          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.
        nameKanaHankaku:
          type: string
          description: Complete name of the customer in Hankaku-Kana format (reading of name) for Japan.
        nameKanaZenkaku:
          type: string
          description: Complete name of the customer in Zenkaku-Kana format (reading of name) for Japan.
        middleNames:
          type: string
          description: Middle name/s of the customer.
        familyNameAtBirth:
          type: string
          description: Last/family/sur- name at birth of the customer.
        address:
          type: string
          description: Complete address of the customer.  For some countries, it is built following the usual concatenation of parameters in a country, but for other countries, this is not the case.  For some countries, it can use streetName, streetNumber and/or houseNumberExtension. For example, in ESP, streetName+streetNumber; in NLD, it can be streetName+streetNumber or streetName+streetNumber+houseNumberExtension.
        streetName:
          type: string
          description: Name of the street of the customer's address. It should not include the type of the street.
        streetNumber:
          type: string
          description: The street number of the customer's address.  Number identifying a specific property on the 'streetName'.
        postalCode:
          type: string
          description: Zip code or postal code
        region:
          type: string
          description: Region/prefecture of the customer's address
        locality:
          type: string
          description: Locality of the customer's address
        country:
          type: string
          description: Country of the customer's address. Format ISO 3166-1 alpha-2
        houseNumberExtension:
          type: string
          description: Specific identifier of the house needed depending on the property type. For example, number of apartment in an apartment building.
        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).
        gender:
          type: string
          description: Gender of the customer (Male/Female/Other).
          enum:
            - MALE
            - FEMALE
            - OTHER
    MatchResult:
      type: string
      enum:
        - 'true'
        - 'false'
        - 'not_available'
    MatchScoreResult:
      type: integer
      description: Indicates the similarity score assigned to the input value when it does not exactly match the value stored in the operator's system. This property shall only be returned when the value of the corresponding match field is `false`.
      minimum: 0
      maximum: 100
    KYC_MatchResponse:
      type: object
      properties:
        idDocumentMatch:
          allOf:
            - $ref: '#/components/schemas/MatchResult'
            - description: Indicates whether Id number associated to the ID document of the customer matches with the one on the Operator's system.
        nameMatch:
          allOf:
            - $ref: '#/components/schemas/MatchResult'
            - description: Indicates whether the complete name of the customer matches with the one on the Operator's system.
        nameMatchScore:
          $ref: '#/components/schemas/MatchScoreResult'
        givenNameMatch:
          allOf:
            - $ref: '#/components/schemas/MatchResult'
            - description: Indicates whether First name/given name of the customer matches with the one on the Operator's system.
        givenNameMatchScore:
          $ref: '#/components/schemas/MatchScoreResult'
        familyNameMatch:
          allOf:
            - $ref: '#/components/schemas/MatchResult'
            - description: Indicates whether last name/ family name/ surname of the customer matches with the one on the Operator's system.
        familyNameMatchScore:
          $ref: '#/components/schemas/MatchScoreResult'
        nameKanaHankakuMatch:
          allOf:
            - $ref: '#/components/schemas/MatchResult'
            - description: Indicates whether complete name of the customer in Hankaku-Kana format (reading of name) for Japan matches with the one on the Operator's system.
        nameKanaHankakuMatchScore:
          $ref: '#/components/schemas/MatchScoreResult'
        nameKanaZenkakuMatch:
          allOf:
            - $ref: '#/components/schemas/MatchResult'
            - description: Indicates whether complete name of the customer in Zenkaku-Kana format (reading of name) for Japan matches with the one on the Operator's system.
        nameKanaZenkakuMatchScore:
          $ref: '#/components/schemas/MatchScoreResult'
        middleNamesMatch:
          allOf:
            - $ref: '#/components/schemas/MatchResult'
            - description: Indicates whether the middle names of the customer matches with the one on the Operator's system.
        middleNamesMatchScore:
          $ref: '#/components/schemas/MatchScoreResult'
        familyNameAtBirthMatch:
          allOf:
            - $ref: '#/components/schemas/MatchResult'
            - description: Indicates whether the Family Name At Birth of the customer matches with the one on the Operator's system.
        familyNameAtBirthMatchScore:
          $ref: '#/components/schemas/MatchScoreResult'
        addressMatch:
          allOf:
            - $ref: '#/components/schemas/MatchResult'
            - description: Indicates whether complete address of the customer matches with the one on the Operator's system.
        addressMatchScore:
          $ref: '#/components/schemas/MatchScoreResult'
        streetNameMatch:
          allOf:
            - $ref: '#/components/schemas/MatchResult'
            - description: Indicates whether the street name of the customer matches with the one on the Operator's system.
        streetNameMatchScore:
          $ref: '#/components/schemas/MatchScoreResult'
        streetNumberMatch:
          allOf:
            - $ref: '#/components/schemas/MatchResult'
            - description: Indicates whether the street number of the customer matches with the one on the Operator's system.
        streetNumberMatchScore:
          $ref: '#/components/schemas/MatchScoreResult'
        postalCodeMatch:
          allOf:
            - $ref: '#/components/schemas/MatchResult'
            - description: Indicates whether the postal code / zip code of the customer matches with the one on the Operator's system.
        regionMatch:
          allOf:
            - $ref: '#/components/schemas/MatchResult'
            - description: Indicates whether the region of the customer's address matches with the one on the Operator's system.
        regionMatchScore:
          $ref: '#/components/schemas/MatchScoreResult'
        localityMatch:
          allOf:
            - $ref: '#/components/schemas/MatchResult'
            - description: Indicates whether the locality of the customer's address matches with the one on the Operator's system.
        localityMatchScore:
          $ref: '#/components/schemas/MatchScoreResult'
        countryMatch:
          allOf:
            - $ref: '#/components/schemas/MatchResult'
            - description: Indicates whether the country of the customer's address matches with the one on the Operator's system.
        houseNumberExtensionMatch:
          allOf:
            - $ref: '#/components/schemas/MatchResult'
            - description: Indicates whether the house number extension of the customer's address matches with the one on the Operator's system.
        birthdateMatch:
          allOf:
            - $ref: '#/components/schemas/MatchResult'
            - description: Indicates whether the birthdate of the customer matches with the one on the Operator's system.
        emailMatch:
          allOf:
            - $ref: '#/components/schemas/MatchResult'
            - description: Indicates whether the email address of the customer matches with the one on the Operator's system.
        emailMatchScore:
          $ref: '#/components/schemas/MatchScoreResult'
        genderMatch:
          allOf:
            - $ref: '#/components/schemas/MatchResult'
            - description: Indicates whether the gender of the customer matches with the one on the Operator's system.
    NumberVerificationRequestBody:
      type: object
      description: Payload to verify the phone number.
      minProperties: 1
      maxProperties: 1
      properties:
        phoneNumber:
          $ref: '#/components/schemas/PhoneNumber'
        hashedPhoneNumber:
          description: Hashed phone number. SHA-256 (in hexadecimal representation) of the mobile phone number in **E.164 format (starting with country code)**. Prefixed with '+'.
          type: string
          example: 32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba
    NumberVerificationMatchResponse:
      type: object
      description: Number verification result
      required:
        - devicePhoneNumberVerified
      properties:
        devicePhoneNumberVerified:
          $ref: '#/components/schemas/DevicePhoneNumberVerified'
    NumberVerificationShareResponse:
      type: object
      description: Number verification share result
      required:
        - devicePhoneNumber
      properties:
        devicePhoneNumber:
          $ref: '#/components/schemas/PhoneNumber'
    DevicePhoneNumberVerified:
      description: Number verification. True, if it matches
      type: boolean
    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 '+'.
    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.
    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"
    DeviceSwapInfo:
      type: object
      required:
        - latestDeviceChange
      properties:
        latestDeviceChange:
          type: string
          format: date-time
          description: Timestamp of latest device 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"
    CreateDeviceSwapDate:
      type: object
      properties:
        phoneNumber:
          $ref: "#/components/schemas/PhoneNumber"
    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
    CheckDeviceSwapInfo:
      type: object
      required:
        - swapped
      properties:
        swapped:
          type: boolean
          description: Indicates whether the device has been swapped during the period within the provided age.
    ConsentInfoRetrieveStatusRequestBody:
      type: object
      description: The request body for the retrieve status request.
      required:
        - phoneNumber
        - scopes
        - purpose
        - requestCaptureUrl
      properties:
        phoneNumber:
          $ref: "#/components/schemas/PhoneNumber"
        scopes:
          $ref: '#/components/schemas/ConsentInfoScopes'
        purpose:
          $ref: '#/components/schemas/ConsentInfoPurpose'
        requestCaptureUrl:
          type: boolean
          description: A boolean flag indicating whether the API Consumer requests API Provider to return a Consent capture URL.
          example: true
    ConsentInfoScopes:
      type: array
      minItems: 1
      items:
        type: string
      description: List of requested scopes.
      example:
        - 'location-verification:verify'
    ConsentInfoPurpose:
      type: string
      pattern: '^dpv:[a-zA-Z0-9]+$'
      description: The reason for which personal data will be processed by the API Consumer. CAMARA uses the [W3C Data Privacy Vocabulary](https://w3c.github.io/dpv/2.0/dpv/) (DPV) to represent these purposes e.g. `dpv:FraudPreventionAndDetection` or `dpv:RequestedServiceProvision`.
      example: 'dpv:FraudPreventionAndDetection'
    ConsentInfoRetrieveStatusResponseBody:
      type: object
      required:
        - statusInfo
      properties:
        statusInfo:
          $ref: '#/components/schemas/ConsentInfoStatusInfo'
        captureUrl:
          type: string
          format: url
          description: URL where the User can provide the necessary Consent.
    ConsentInfoStatusInfo:
      type: array
      description: Provides information about the validity status of the requested data
        processing for the specified scope(s) and Purpose.
      items:
        $ref: '#/components/schemas/ConsentInfoStatusInfoObject'
      minItems: 1
    ConsentInfoStatusInfoObject:
      type: object
      required:
        - scopes
        - purpose
        - statusValidForProcessing
      properties:
        scopes:
          $ref: '#/components/schemas/ConsentInfoScopes'
        purpose:
          $ref: '#/components/schemas/ConsentInfoPurpose'
        statusValidForProcessing:
          type: boolean
          description: Boolean flag that shows the validity status of the requested data processing for the specified scope(s) and Purpose.
        statusReason:
          type: string
          enum:
            - PENDING
            - REQUESTED
            - REVOKED
            - EXPIRED
            - OBJECTED
          description: This field must be present if `statusValidForProcessing` is `false`.
        expirationDate:
          type: string
          format: date-time
          description: The date and time at which the validity of the data processing is set to expire or has expired.
          example: '2023-07-03T14:27:08.312+02:00'
    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
    errorAccessTokenResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: A single error code
          example: invalid_request
          enum:
            - invalid_request
            - access_denied
            - invalid_client
            - invalid_grant
            - unauthorized_client
            - unauthorized_grant_type
            - invalid_scope
            - error_description
            - error_uri
        error_description:
          type: string
          description: A human-readable text providing additional information, used to
            assist in the understanding and resolution of the error occurred
        error_uri:
          type: string
    errorPostTokenResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: A single error code
          example: invalid_request
          enum:
            - authorization_pending
            - invalid_request
            - access_denied
            - invalid_client
            - invalid_grant
            - unauthorized_client
            - unauthorized_grant_type
            - invalid_scope
            - error_description
            - error_uri
        error_description:
          type: string
          description: A human-readable text providing additional information, used to
            assist in the understanding and resolution of the error occurred
        error_uri:
          type: string
    KYCAgeVerificationVerifyRequestBody:
      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.
    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.
    KYCAgeVerificationVerifyResponseBody:
      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'
    TenureRequest:
      type: "object"
      description: Request for tenure verification
      required:
        - tenureDate
      properties:
        phoneNumber:
          $ref: "#/components/schemas/PhoneNumber"
        tenureDate:
          type: string
          description: The date, in RFC 3339 / ISO 8601 compliant format "YYYY-MM-DD", from which continuous tenure is required to be confirmed. Must not be in the future.
          format: date
          pattern: '^\d{4}-\d{2}-\d{2}$'
          example: "2023-07-03"
    TenureResponse:
      type: "object"
      description: Tenure verification result
      required:
        - tenureDateCheck
      properties:
        tenureDateCheck:
          type: boolean
          description: |
            `true` when the identified mobile subscription has had valid tenure since `tenureDate`, otherwise `false`
          example: true
        contractType:
          type: string
          description: |
            If exists, populated with:
            - `PAYG` - prepaid (pay-as-you-go) account
            - `PAYM` - contract account
            - `Business` - Business (enterprise) account

            This attribute may be omitted from the response set if the information is not available
          example: "PAYM"
          enum:
            - "PAYG"
            - "PAYM"
            - "Business"
    QosProfile:
      description: |
        Data type with attributes of a QosProfile
      type: object
      properties:
        name:
          $ref: "#/components/schemas/QosProfileName"
        description:
          description: |
            A description of the QoS profile.
          type: string
          example: "QoS profile for video streaming"
        status:
          $ref: "#/components/schemas/QosProfileStatusEnum"
        countryAvailability:
          description: |
            A list of countries, and optionally networks, for which the API provider makes the profile available.
            - When profiles are filtered for a specific device (i.e. using a 3-legged access token or an explicit device filter parameter), the profile can be used by that device in any of these countries when connected to any of the listed networks (assuming roaming is permitted for networks that are not the device's home network), or the API provider's own network if no networks are listed
            - When there is no device filter, availability for a given country means that the QoS profile may be available to some devices connected to the listed networks in that country (or to the API provider’s default network if none are listed). However, this does not imply that the profile is available to all devices, or that a particular device will be able to use the profile across all listed countries or networks. In particular, the response does not provide enough information to determine availability for roaming for specific devices; consumers should query the API with a specific device identifier to get definitive availability.
            - If this field is not present in the QoS profile, no assumption can be made about the availability of the profile in any given country or for any given network
          allOf:
            - $ref: "#/components/schemas/Availability"
        targetMinUpstreamRate:
          description: |
            This is the target minimum upload speed for the QoS profile.
            It represents the minimum rate that the network attempts to deliver.
            Please note that this is a target value—the network might not always be able to provide this rate under all conditions.
            It helps ensure that applications like video calls or live streaming perform consistently.
          allOf:
            - $ref: "#/components/schemas/Rate"
        maxUpstreamRate:
          description: |
            The maximum best effort data
          allOf:
            - $ref: "#/components/schemas/Rate"
        maxUpstreamBurstRate:
          description: |
            When defined, this is the maximum upstream burst rate for the QoS profile, that will enable
            the network to burst data at a higher rate than the maxUpstreamRate for a period of time.
          allOf:
            - $ref: "#/components/schemas/Rate"
        targetMinDownstreamRate:
          description: |
            This is the target maximum upload speed for the QoS profile.
            It represents the maximum rate that the network attempts to deliver.
            Please note that this is a target value—the network might not always be able to provide this rate under all conditions.
            It helps ensure that applications like video calls or live streaming perform consistently.
          allOf:
            - $ref: "#/components/schemas/Rate"
        maxDownstreamRate:
          description: |
            The maximum best effort rate
          allOf:
            - $ref: "#/components/schemas/Rate"
        maxDownstreamBurstRate:
          description: |
            When defined, this is the maximum downstream burst rate for the QoS profile, that will enable
            the network to burst data at a higher rate than the maxDownstreamRate for a period of time.
            This can result in improved user experience when there is additional network capacity.
            For instance, when a user is streaming a video, the network can burst data at a higher rate
            to fill the buffer, and then return to the maxUpstreamRate once the buffer is full.
          allOf:
            - $ref: "#/components/schemas/Rate"
        minDuration:
          description: |
            The shortest time period that this profile can be deployed.
          allOf:
            - $ref: "#/components/schemas/Duration"
        maxDuration:
          description: |
            The maximum time period that this profile can be deployed.
            Overall session duration must not exceed this value. This includes the initial requested duration plus any extensions.
          allOf:
            - $ref: "#/components/schemas/Duration"
        priority:
          type: integer
          example: 20
          description: |
            Priority levels allow efficient resource allocation and ensure optimal performance
            for various services in each technology, with the highest priority traffic receiving
            preferential treatment.
            The lower value the higher priority.
            Not all access networks use the same priority range, so this priority will be
            scaled to the access network's priority range.
          format: int32
          minimum: 1
          maximum: 100
        packetDelayBudget:
          description: |
            The packet delay budget is the maximum allowable one-way latency between the customer's device
            and the gateway from the operator's network to other networks. By limiting the delay, the network
            can provide an acceptable level of performance for various services, such as voice calls,
            video streaming, and data.
            The end-to-end or round trip latency will be about two times this value plus the latency not controlled
            by the operator
          allOf:
            - $ref: "#/components/schemas/Duration"
        jitter:
          description: |
            The jitter requirement aims to limit the maximum variation in round-trip
            packet delay for the 99th percentile of traffic, following ITU Y.1540
            standards. It considers only acknowledged packets in a session, which are
            packets that receive a confirmation of receipt from the recipient (e.g.,
            using TCP). This requirement helps maintain consistent latency, essential
            for real-time applications such as VoIP, video calls, and gaming.
          allOf:
            - $ref: "#/components/schemas/Duration"
        packetErrorLossRate:
          type: integer
          description: |
            This field specifies the acceptable level of data loss during transmission.
            The value is an exponent of 10, so a value of 3 means that up to 10⁻³, or 0.1%, of the
            data packets may be lost. This setting is part of a broader system that categorizes
            different types of network traffic (like phone calls, video streams, or data transfers)
            to ensure they perform reliably on the network.
          format: int32
          minimum: 1
          maximum: 10
          example: 3
        l4sQueueType:
          type: string
          enum:
            - non-l4s-queue
            - l4s-queue
            - mixed-queue
          description: |

            **NOTE**: l4sQueueType is experimental and could change or be removed in a future release.

            Specifies the type of queue for L4S (Low Latency, Low Loss, Scalable Throughput) traffic management. L4S is an advanced queue management approach designed to provide ultra-low latency and high throughput for internet traffic, particularly beneficial for interactive applications such as gaming, video conferencing, and virtual reality.

            **Queue Type Descriptions:**

            - **non-l4s-queue**:
              A traditional queue used for legacy internet traffic that does not utilize L4S enhancements. It provides standard latency and throughput levels.

            - **l4s-queue**:
              A dedicated queue optimized for L4S traffic, delivering ultra-low latency, low loss, and scalable throughput to support latency-sensitive applications.

            - **mixed-queue**:
              A shared queue that can handle both L4S and traditional traffic, offering a balance between ultra-low latency for L4S flows and compatibility with non-L4S flows.

          externalDocs:
            description: For more details, refer to the L4S standard.
            url: https://datatracker.ietf.org/doc/rfc9330/
        serviceClass:
          type: string
          description: |

            **NOTE**: serviceClass is experimental and could change or be removed in a future release.

            The name of a Service Class, representing a QoS Profile designed to provide optimized behavior for a specific application type. While DSCP values are commonly associated with Service Classes, their use may vary across network segments and may not be applied throughout the entire end-to-end QoS session. This aligns with the serviceClass concept used in HomeDevicesQoQ for consistent terminology.

            Service classes define specific QoS behaviors that map to DSCP (Differentiated Services Code Point) values or Microsoft QoS traffic types.

            The supported mappings are:
            1. Values aligned with the [RFC4594](https://datatracker.ietf.org/doc/html/rfc4594) guidelines for differentiated traffic classes.
            2. Microsoft [QOS_TRAFFIC_TYPE](https://learn.microsoft.com/en-us/windows/win32/api/qos2/ne-qos2-qos_traffic_type) values for Windows developers.

            **Supported Service Classes**:

            | Service Class Name    | DSCP Name | DSCP value (decimal) | DCSP value (binary) | Microsoft Value | Application Examples                                                 |
            |-----------------------|-----------|----------------------|---------------------|-----------------|----------------------------------------------------------------------|
            | Microsoft Voice       |    CS7    |          56          |        111000       |       4,5       | Microsoft QOSTrafficTypeVoice and QOSTrafficTypeControl              |
            | Microsoft Audio/Video |    CS5    |          40          |        101000       |       2,3       | Microsoft QOSTrafficTypeExcellentEffort and QOSTrafficTypeAudioVideo |
            | Real-Time Interactive |    CS4    |          32          |        100000       |                 | Video conferencing and Interactive gaming                            |
            | Multimedia Streaming  |    AF31   |          26          |        011010       |                 | Streaming video and audio on demand                                  |
            | Broadcast Video       |    CS3    |          24          |        011000       |                 | Broadcast TV & live events                                           |
            | Low-Latency Data      |    AF21   |          18          |        010010       |                 | Client/server transactions Web-based ordering                        |
            | High-Throughput Data  |    AF11   |          10          |        001010       |                 | Store and forward applications                                       |
            | Low-Priority Data     |    CS1    |           8          |        001000       |        1        | Any flow that has no BW assurance - also:                            |
            |                       |           |                      |                     |                 | Microsoft QOSTrafficTypeBackground                                   |
            | Standard              |  DF(CS0)  |           0          |        000000       |        0        | Undifferentiated applications - also:                                |
            |                       |           |                      |                     |                 | Microsoft QOSTrafficTypeBestEffort                                   |
          enum:
            - microsoft_voice                # Microsoft QOSTrafficTypeVoice or Control
            - microsoft_audio_video          # Microsoft QOSTrafficTypeExcellentEffort or AudioVideo
            - real_time_interactive          # Video conferencing and interactive gaming
            - multimedia_streaming           # Streaming video or audio on demand
            - broadcast_video                # Broadcast TV and live events
            - low_latency_data               # Client/server transactions Web-based ordering
            - high_throughput_data           # STore and forward applications
            - low_priority_data              # Low-priority background traffic
            - standard                       # Default traffic class
          example: real_time_interactive
      required:
        - name
        - status
    Device:
      description: |
        End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators.

        The developer can choose to provide the below specified device identifiers:

        * `ipv4Address`
        * `ipv6Address`
        * `phoneNumber`
        NOTE1: the network operator might support only a subset of these options. The API consumer can provide multiple identifiers to be compatible across different operators. In this case the identifiers MUST belong to the same device.
        NOTE2: as for this Commonalities release, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines.

      type: object
      properties:
        phoneNumber:
          $ref: "#/components/schemas/PhoneNumber"
        networkAccessIdentifier:
          $ref: "#/components/schemas/NetworkAccessIdentifier"
        ipv4Address:
          $ref: "#/components/schemas/DeviceIpv4Addr"
        ipv6Address:
          $ref: "#/components/schemas/DeviceIpv6Address"
      minProperties: 1
    DeviceIpv4Addr:
      type: object
      description: |
        The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers).

        If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then  the same address should be specified for both publicAddress and privateAddress.

        If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object)

        In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone.
      properties:
        publicAddress:
          $ref: "#/components/schemas/SingleIpv4Addr"
        privateAddress:
          $ref: "#/components/schemas/SingleIpv4Addr"
        publicPort:
          $ref: "#/components/schemas/Port"
      anyOf:
        - required: [ publicAddress, privateAddress ]
        - required: [ publicAddress, publicPort ]
      example:
        {
          "publicAddress": "203.0.113.0",
          "publicPort": 59765
        }
    Port:
      description: TCP or UDP port number
      type: integer
      minimum: 0
      maximum: 65535
    SingleIpv4Addr:
      description: A single IPv4 address with no subnet mask
      type: string
      format: ipv4
      example: "203.0.113.0"
    DeviceIpv6Address:
      description: |
        The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix).

        The session shall apply to all IP flows between the device subnet and the specified application server, unless further restricted by the optional parameters devicePorts or applicationServerPorts.
      type: string
      format: ipv6
      example: 2001:db8:85a3:8d3:1319:8a2e:370:7344
    NetworkAccessIdentifier:
      description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator.
      type: string
      example: "123456789@domain.com"
    QosProfileName:
      description: |
        A unique name for identifying a specific QoS profile.
        This may follow different formats depending on the service providers implementation.
        Some options addresses:
          - A UUID style string
          - Support for predefined profile names like `QOS_E`, `QOS_S`, `QOS_M`, and `QOS_L`
          - A searchable descriptive name
      type: string
      example: voice
      minLength: 3
      maxLength: 256
      pattern: "^[a-zA-Z0-9_.-]+$"
    QosProfileStatusEnum:
      description: |
        The current status of the QoS Profile
        - `ACTIVE`- QoS Profile is available to be used
        - `INACTIVE`- QoS Profile is not currently available to be deployed
        - `DEPRECATED`- QoS profile is actively being used in a QoD session, but can not be deployed in new QoD sessions
      type: string
      enum:
        - ACTIVE
        - INACTIVE
        - DEPRECATED
    Availability:
      description: A list of countries, and optionally networks, for which the API provider makes the profile available
      type: array
      items:
        type: object
        required:
          - countryName
        properties:
          countryName:
            description: The two letter ISO 3166-2 country code for the country in which the QoS profile is available in at least one network
            type: string
            pattern: ^[A-Z]{2}$
            example: "GB"
          networks:
            description: A list of networks within the country for which the QoS profile is available from the API provider
            type: array
            items:
              description: The network identifier. For mobile networks, this is the PLMN Identifier (MCC + MNC), which is a 5 or 6 digit integer.
              type: string
              example: "23591"
            example: [ "23591", "23415" ]
        example: { "countryName": "GB", "networks": [ "23591", "23415" ] }
      example: [ { "countryName": "GB", "networks": [ "23591", "23415" ] }, { "countryName": "DE", "networks": [ "26202" ] } ]
    Rate:
      description: Specification of rate
      type: object
      properties:
        value:
          description: Quantity of rate
          type: integer
          example: 10
          format: int32
          minimum: 0
          maximum: 1024
        unit:
          $ref: "#/components/schemas/RateUnitEnum"
    RateUnitEnum:
      description: Units of rate
      type: string
      enum:
        - bps
        - kbps
        - Mbps
        - Gbps
        - Tbps
    Duration:
      description: Specification of duration
      type: object
      properties:
        value:
          description: Quantity of duration
          type: integer
          example: 12
          format: int32
          minimum: 1
        unit:
          $ref: "#/components/schemas/TimeUnitEnum"
    TimeUnitEnum:
      description: Units of time
      type: string
      enum:
        - Days
        - Hours
        - Minutes
        - Seconds
        - Milliseconds
        - Microseconds
        - Nanoseconds
    QosProfileDeviceRequest:
      description: |
        Request object for QoS Profiles for a given device
      type: object
      properties:
        device:
          $ref: "#/components/schemas/Device"
        name:
          $ref: "#/components/schemas/QosProfileName"
        status:
          $ref: '#/components/schemas/QosProfileStatusEnum'
    SinkCredential:
      type: object
      properties:
        credentialType:
          type: string
          enum:
            - PLAIN
            - ACCESSTOKEN
            - REFRESHTOKEN
          description: |
            The type of the credential.
            Note: Type of the credential - MUST be set to ACCESSTOKEN for now
      discriminator:
        propertyName: credentialType
        mapping:
          PLAIN: "#/components/schemas/PlainCredential"
          ACCESSTOKEN: "#/components/schemas/AccessTokenCredential"
          REFRESHTOKEN: "#/components/schemas/RefreshTokenCredential"
      required:
        - credentialType
    PlainCredential:
      type: object
      description: A plain credential as a combination of an identifier and a secret. MUST not be used in this API version.
      allOf:
        - $ref: "#/components/schemas/SinkCredential"
        - type: object
          required:
            - identifier
            - secret
          properties:
            identifier:
              description: The identifier might be an account or username.
              type: string
            secret:
              description: The secret might be a password or passphrase.
              type: string
    AccessTokenCredential:
      type: object
      description: An access token credential.
      allOf:
        - $ref: "#/components/schemas/SinkCredential"
        - type: object
          properties:
            accessToken:
              description: REQUIRED. An access token is a previously acquired token granting access to the target resource.
              type: string
            accessTokenExpiresUtc:
              type: string
              format: date-time
              description: |
                REQUIRED. An absolute (UTC) timestamp at which the token shall be considered expired. Token expiration should occur
                after the termination of the requested session, allowing the client to be notified of any changes during the
                sessions's existence. If the token expires while the session is still active, the client will stop receiving notifications.
                If the access token is a JWT and registered "exp" (Expiration Time) claim is present, the two expiry times should match.
                It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
              example: "2023-07-03T12:27:08.312Z"
            accessTokenType:
              description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). For the current version of the API the type MUST be set to `Bearer`.
              type: string
              enum:
                - bearer
          required:
            - accessToken
            - accessTokenExpiresUtc
            - accessTokenType
    RefreshTokenCredential:
      type: object
      description: An access token credential with a refresh token. MUST not be used in this API version.
      allOf:
        - $ref: "#/components/schemas/SinkCredential"
        - type: object
          properties:
            accessToken:
              description: REQUIRED. An access token is a previously acquired token granting access to the target resource.
              type: string
            accessTokenExpiresUtc:
              type: string
              format: date-time
              description: |
                REQUIRED. An absolute UTC instant at which the token shall be considered expired.
                If the access token is a JWT and registered "exp" (Expiration Time) claim is present, the two expiry times should match.
                It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
            accessTokenType:
              description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)).
              type: string
              enum:
                - bearer
            refreshToken:
              description: REQUIRED. An refresh token credential used to acquire access tokens.
              type: string
            refreshTokenEndpoint:
              type: string
              format: uri
              description: REQUIRED. A URL at which the refresh token can be traded for an access token.
      required:
        - accessToken
        - accessTokenExpiresUtc
        - accessTokenType
        - refreshToken
        - refreshTokenEndpoint
    EventQosStatusChanged:
      description: Event to notify a QoS status change
      allOf:
        - $ref: "#/components/schemas/CloudEvent"
        - type: object
          properties:
            data:
              type: object
              description: Event details depending on the event type
              required:
                - sessionId
                - qosStatus
              properties:
                sessionId:
                  $ref: "#/components/schemas/SessionId"
                qosStatus:
                  $ref: "#/components/schemas/EventQosStatus"
                statusInfo:
                  $ref: "#/components/schemas/StatusInfo"
          required:
            - data
    QoDDevice:
      description: |
        End-user equipment able to connect to a network. Examples of devices include smartphones or IoT sensors/actuators.

        The developer can choose to provide the below specified device identifiers:

        * `ipv4Address`
        * `ipv6Address`
        * `phoneNumber`
        * `networkAccessIdentifier`

        NOTE1: the network operator might support only a subset of these options. The API consumer can provide multiple identifiers to be compatible across different network operators. In this case the identifiers MUST belong to the same device.
        NOTE2: as for this Commonalities release, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines.
      type: object
      properties:
        phoneNumber:
          $ref: "#/components/schemas/PhoneNumber"
        networkAccessIdentifier:
          $ref: "#/components/schemas/NetworkAccessIdentifier"
        ipv4Address:
          $ref: "#/components/schemas/DeviceIpv4Addr"
        ipv6Address:
          $ref: "#/components/schemas/DeviceIpv6Address"
      minProperties: 1
    ApplicationServerIpv4Address:
      type: string
      example: "198.51.100.0/24"
      description: |
        IPv4 address may be specified in form <address/mask> as:
          - address - an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule.
          - address/mask - an IP number as above with a mask width of the form 1.2.3.4/24.
            In this case, all IP numbers from 1.2.3.0 to 1.2.3.255 will match. The bit width MUST be valid for the IP version.
    ApplicationServerIpv6Address:
      type: string
      example: "2001:db8:85a3:8d3:1319:8a2e:370:7344"
      description: |
        IPv6 address may be specified in form <address/mask> as:
          - address - The /128 subnet is optional for single addresses:
            - 2001:db8:85a3:8d3:1319:8a2e:370:7344
            - 2001:db8:85a3:8d3:1319:8a2e:370:7344/128
          - address/mask - an IP v6 number with a mask:
            - 2001:db8:85a3:8d3::0/64
            - 2001:db8:85a3:8d3::/64
    ApplicationServer:
      description: |
        A server hosting backend applications to deliver some business logic to clients.
        
        The developer can choose to provide the below specified device identifiers:
        
        * `ipv4Address`
        * `ipv6Address`
      type: object
      properties:
        ipv4Address:
          $ref: "#/components/schemas/ApplicationServerIpv4Address"
        ipv6Address:
          $ref: "#/components/schemas/ApplicationServerIpv6Address"
      minProperties: 1
    PortsSpec:
      description: Specification of several TCP or UDP ports
      type: object
      minProperties: 1
      properties:
        ranges:
          description: Range of TCP or UDP ports
          type: array
          minItems: 1
          items:
            type: object
            required:
              - from
              - to
            properties:
              from:
                $ref: "#/components/schemas/Port"
              to:
                $ref: "#/components/schemas/Port"
        ports:
          description: Array of TCP or UDP ports
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/Port"
      example:
        ranges:
          - from: 5010
            to: 5020
        ports:
          - 5060
          - 5070
    ExtendSessionDuration:
      description: Attributes required to extend the duration of an active session
      type: object
      properties:
        requestedAdditionalDuration:
          description: |
            Additional duration in seconds to be added to the current session duration. The overall session duration, including extensions, shall not exceed the maximum duration limit for the QoS Profile.
          type: integer
          format: int32
          minimum: 1
          example: 1800
      required:
        - requestedAdditionalDuration
    SessionInfo:
      description: |
        Session related information returned in responses.
        Note that the device object is defined as optional and will only to be returned if provided in createSession. If more than one type of device identifier was provided, only one identifier will be returned (at implementation choice and with the original value provided in createSession).
        Please note that IP addresses of devices can change and get reused, so the original values may no longer identify the same device. They identified the device at the time of session creation.
      allOf:
        - type: object
          properties:
            device:
              description: Disambiguates the device to which the session applies when multiple device identifiers were provided
              allOf:
                - $ref: "#/components/schemas/DeviceResponse"
                - example: { "phoneNumber": "+123456789" }
        - $ref: "#/components/schemas/BaseSessionInfo"
        - type: object
          properties:
            sessionId:
              $ref: "#/components/schemas/SessionId"
            duration:
              description: |
                Session duration in seconds. Implementations can grant the requested session duration or set a different duration, based on network policies or conditions.
                - When `qosStatus` is "REQUESTED", the value is the duration to be scheduled, granted by the implementation.
                - When `qosStatus` is AVAILABLE", the value is the overall duration since `startedAt. When the session is extended, the value is the new overall duration of the session.
                - When `qosStatus` is "UNAVAILABLE", the value is the overall effective duration since `startedAt` until the session was terminated.
              type: integer
              format: int32
              minimum: 1
              example: 3600
            startedAt:
              description: Date and time when the QoS status became "AVAILABLE". Not to be returned when `qosStatus` is "REQUESTED". It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
              type: string
              format: date-time
              example: "2024-06-01T12:00:00Z"
            expiresAt:
              description: |
                Date and time of the QoS session expiration. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
                - When `qosStatus` is "AVAILABLE", it is the limit time when the session is scheduled to finnish, if not terminated by other means.
                - When `qosStatus` is "UNAVAILABLE", it is the time when the session was terminated.
                - Not to be returned when `qosStatus` is "REQUESTED".
                When the session is extended, the value is the new expiration time of the session.
              type: string
              format: date-time
              example: "2024-06-01T13:00:00Z"
            qosStatus:
              $ref: "#/components/schemas/QosStatus"
            statusInfo:
              $ref: "#/components/schemas/StatusInfo"
          required:
            - sessionId
            - duration
            - qosStatus
    QosStatus:
      description: |
        The current status of the requested QoS session. The status can be one of the following:
        * `REQUESTED` - QoS has been requested by creating a session
        * `AVAILABLE` - The requested QoS has been provided by the network
        * `UNAVAILABLE` - The requested QoS cannot be provided by the network due to some reason
      type: string
      enum:
        - REQUESTED
        - AVAILABLE
        - UNAVAILABLE
    StatusInfo:
      description: |
        Reason for the new `qosStatus`. Currently `statusInfo` is only applicable when `qosStatus` is 'UNAVAILABLE'.
        * `DURATION_EXPIRED` - Session terminated due to requested duration expired
        * `NETWORK_TERMINATED` - Network terminated the session before the requested duration expired
        * `DELETE_REQUESTED`- User requested the deletion of the session before the requested duration expired

      type: string
      enum:
        - DURATION_EXPIRED
        - NETWORK_TERMINATED
        - DELETE_REQUESTED
    EventQosStatus:
      description: |
        The current status of a requested or previously available session. Applicable values in the event are:
        *  `AVAILABLE` - The requested QoS has been provided by the network.
        *  `UNAVAILABLE` - A requested or previously available QoS session is now unavailable. `statusInfo` may provide additional information about the reason for the unavailability.
      type: string
      enum:
        - AVAILABLE
        - UNAVAILABLE
    SessionId:
      description: Session ID in UUID format
      type: string
      format: uuid
    DeviceResponse:
      description: |
        An identifier for the end-user equipment able to connect to the network that the response refers to. This parameter is only returned when the API consumer includes the `device` parameter in their request (i.e. they are using a two-legged access token), and is relevant when more than one device identifier is specified, as only one of those device identifiers is allowed in the response.
        
        If the API consumer provides more than one device identifier in their request, the API provider must return a single identifier which is the one they are using to fulfil the request, even if the identifiers do not match the same device. API provider does not perform any logic to validate/correlate that the indicated device identifiers match the same device. No error should be returned if the identifiers are otherwise valid to prevent API consumers correlating different identifiers with a given end user.

      allOf:
        - $ref: "#/components/schemas/Device"
        - maxProperties: 1
    BaseSessionInfo:
      description: Common attributes of a QoD session
      type: object
      properties:
        applicationServer:
          $ref: "#/components/schemas/ApplicationServer"
        devicePorts:
          description: The ports used locally by the device for flows to which the requested QoS profile should apply. If omitted, then the qosProfile will apply to all flows between the device and the specified application server address and ports
          allOf:
            - $ref: "#/components/schemas/PortsSpec"
        applicationServerPorts:
          description: A list of single ports or port ranges on the application server
          allOf:
            - $ref: "#/components/schemas/PortsSpec"
        qosProfile:
          $ref: "#/components/schemas/QosProfileName"
        sink:
          type: string
          format: uri
          pattern: ^https:\/\/.+$
          description: The address to which events about all status changes of the session (e.g. session termination) shall be delivered using the selected protocol.
          example: "https://endpoint.example.com/sink"
        sinkCredential:
          description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target.
          allOf:
            - $ref: "#/components/schemas/SinkCredential"
      required:
        - applicationServer
        - qosProfile
    CloudEvent:
      description: Event compliant with the CloudEvents specification
      required:
        - id
        - source
        - specversion
        - type
        - time
      properties:
        id:
          description: Identifier of this event, that must be unique in the source context.
          type: string
        source:
          description: Identifies the context in which an event happened in the specific provider implementation.
          type: string
          format: uri-reference
        type:
          description: The type of the event.
          type: string
          enum:
            - "org.camaraproject.quality-on-demand.v1.qos-status-changed"
        specversion:
          description: Version of the specification to which this event conforms (must be 1.0 if it conforms to Cloudevents 1.0.2 version)
          type: string
          enum:
            - '1.0'
        datacontenttype:
          description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs'
          type: string
          enum:
            - 'application/json'
        data:
          description: Event notification details payload, which depends on the event type
          type: object
        time:
          description: |
            Timestamp of when the occurrence happened. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
          type: string
          format: date-time
      discriminator:
        propertyName: 'type'
        mapping:
          org.camaraproject.quality-on-demand.v1.qos-status-changed: "#/components/schemas/EventQosStatusChanged"
    CreateSession:
      description: Attributes required to create a session
      allOf:
        - type: object
          properties:
            device:
              $ref: "#/components/schemas/QoDDevice"
        - $ref: "#/components/schemas/BaseSessionInfo"
        - type: object
          properties:
            duration:
              description: |
                Requested session duration in seconds. Value may be explicitly limited for the QoS profile, as specified in the Qos Profile (see qos-profile API). Implementations can grant the requested session duration or set a different duration, based on network policies or conditions.
              type: integer
              format: int32
              minimum: 1
              example: 3600
          required:
            - duration
    RetrieveSessionsOutput:
      description: QoS session information for a given device
      type: array
      items:
        $ref: "#/components/schemas/SessionInfo"
      minItems: 0
    RetrieveSessionsInput:
      description: Parameters to get QoS session information by device
      type: object
      properties:
        device:
          $ref: "#/components/schemas/Device"
    NumberRecyclingCreateCheck:
      type: object
      required:
        - specifiedDate
      properties:
        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"
    NumberRecyclingCheckInfo:
      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”.

    RetrievalRequest:
      description: Request to retrieve the location of a device. Device is not required when using a 3-legged access token, following the rules in the description.
      type: object
      properties:
        device:
          $ref: '#/components/schemas/Device'
        maxAge:
          type: integer
          description: Maximum age of the location information which is accepted for the location retrieval (in seconds). Absence of maxAge means "any age" and maxAge=0 means a fresh calculation.
        maxSurface:
          type: integer
          minimum: 1
          description: Maximum surface in square meters which is accepted by the client for the location retrieval. Absence of maxSurface means "any surface size".
          example: 1000000
    Location:
      type: object
      description: Device location
      required:
        - lastLocationTime
        - area
      properties:
        lastLocationTime:
          $ref: "#/components/schemas/LastLocationTime"
        area:
          $ref: '#/components/schemas/Area'
        device:
          $ref: "#/components/schemas/DeviceResponse"
    Area:
      description: Base schema for all areas
      type: object
      properties:
        areaType:
          $ref: "#/components/schemas/AreaType"
      required:
        - areaType
      discriminator:
        propertyName: areaType
        mapping:
          CIRCLE: "#/components/schemas/Circle"
          POLYGON: "#/components/schemas/Polygon"
    AreaType:
      type: string
      description: |
        Type of this area.
        CIRCLE - The area is defined as a circle.
        POLYGON - The area is defined as a polygon.
      enum:
        - CIRCLE
        - POLYGON
    Circle:
      description: Circular area
      allOf:
        - $ref: "#/components/schemas/Area"
        - type: object
          required:
            - center
            - radius
          properties:
            center:
              $ref: "#/components/schemas/Point"
            radius:
              type: number
              description: Distance from the center in meters
              minimum: 1
    Polygon:
      description: Polygonal area
      allOf:
        - $ref: "#/components/schemas/Area"
        - type: object
          required:
            - boundary
          properties:
            boundary:
              $ref: "#/components/schemas/PointList"
    PointList:
      description: List of points defining a polygon
      type: array
      items:
        $ref: "#/components/schemas/Point"
      minItems: 3
      maxItems: 15
    Point:
      type: object
      description: Coordinates (latitude, longitude) defining a location in a map
      required:
        - latitude
        - longitude
      properties:
        latitude:
          $ref: "#/components/schemas/Latitude"
        longitude:
          $ref: "#/components/schemas/Longitude"
      example:
        latitude: 50.735851
        longitude: 7.10066
    LastLocationTime:
      description: Last date and time when the device was localized. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
      format: date-time
      type: string
      example: "2023-09-07T10:40:52Z"
    Latitude:
      description: Latitude component of a location
      type: number
      format: double
      minimum: -90
      maximum: 90
    Longitude:
      description: Longitude component of location
      type: number
      format: double
      minimum: -180
      maximum: 180

  responses:
    Generic400:
      description: Problem with the client request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 400
            code: INVALID_ARGUMENT
            message: Client specified an invalid argument, request body or query param
    Generic401:
      description: Unauthorized
      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.
            GENERIC_401_AUTHENTICATION_REQUIRED:
              description: New authentication is needed, authentication is no longer valid
              value:
                status: 401
                code: AUTHENTICATION_REQUIRED
                message: New authentication is required.
    Generic403:
      description: Forbidden
      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
      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.
    Generic409:
      description: Conflict with the current state of the server
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          examples:
            GENERIC_409_CONFLICT:
              description: Conflict with the current state of the server
              value:
                status: 409
                code: CONFLICT
                message: Request could not be completed due to a conflict with the current state of the target resource.
    Generic410:
      description: Resource is gone and will not be available again
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          examples:
            GENERIC_410_GONE:
              description: Resource is gone and will not be available again
              value:
                status: 410
                code: GONE
                message: The specified resource is no longer available and will not be available again.
    Generic422:
      description: Unprocessable Content
      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: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 500
            code: INTERNAL
            message: Server error
    Generic503:
      description: Service unavailable. Typically the server is down.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 503
            code: UNAVAILABLE
            message: Service unavailable
    Generic504:
      description: Request time exceeded. If it happens repeatedly, consider reducing the request complexity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 504
            code: TIMEOUT
            message: Request timeout exceeded. Try later.
