openapi: 3.0.3 info: title: KYC Tenure description: | # Summary 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. # API functionality The API defines one service endpoint: - `POST /check-tenure` Takes the network subscription identifier (e.g. the mobile phone number for a mobile network subscriber) and the specified minimum tenure date to validate for the associated network subscription. This endpoint will respond with a confirmation of whether or not the network subscriber tenure is longer than the specified date timestamp, optionally supplemented with details of the subscription contract type. To call this endpoint, the API consumer must first obtain a valid access token with the specified scope from the specified token endpoint, which is then passed to the endpoint via the `Authorization` header. For more details on access token processing, see below. ## Inputs The endpoint request body is a JSON object with the following parameters: - `tenureDate`: The date from which continuous tenure of the identified network subscriber is required to be confirmed. This field is always required. - `phoneNumber`: The network subscription identifier (i.e. the phone number of the subscriber). This field is only required if no network subscription identifier is associated with the access token. ## Outputs If successful, a JSON object is returned containing the following data: - `tenureDateCheck`: `true` when the identified network subscription has had valid tenure since `tenureDate`, otherwise `false` - `contractType`: The network subscription account type, if known An example of a JSON response object is as follows: ``` { "tenureDateCheck": true, "contractType": "PAYM" } ``` ## Errors If the authentication token is missing, not a valid token, or is no longer valid, a `401 UNAUTHENTICATED` error is returned If the API call contain a formatting or other error, a `400 INVALID_ARGUMENT` error is returned. If the network subscription cannot be identified from the provided parameters (e.g. the subscription identifier is not associated with any customer of the CSP), a `404 IDENTIFIER_NOT_FOUND` error is returned. If the API consumer has a valid access token that does not have the required scope to obtain tenure information for the specified network subscription, then a `403 PERMISSION_DENIED` error is returned. ### Additional CAMARA error responses The list of error codes in this API specification is not exhaustive. Therefore the API specification may not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`. Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version. As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. # Identifying the phone number from the access token This API requires the API consumer to identify a phone number as the subject of the API as follows: - When the API is invoked using a two-legged access token, the subject will be identified from the optional `phoneNumber` field, which therefore MUST be provided. - When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token. This approach simplifies API usage for API consumers using a three-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the authentication process. ## Error handling: - If the subject cannot be identified from the access token and the optional `phoneNumber` field is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code. - If the subject can be identified from the access token and the optional `phoneNumber` field is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same phone number is identified by these two methods, as the server is unable to make this comparison. # Authorization and authentication The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile. The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation. In cases where personal data is processed by the API and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design. # Further info and support (FAQs will be added in a later version of the documentation) version: 0.2.0 x-camara-commonalities: 0.6 license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html externalDocs: description: Product documentation at CAMARA url: https://github.com/camaraproject/Tenure servers: - url: "{apiRoot}/kyc-tenure/v0.2" variables: apiRoot: default: https://localhost:9091 description: API root tags: - name: Check Subscriber Tenure description: Check details about the length of tenure of the subscriber paths: /check-tenure: post: tags: - Check Subscriber Tenure summary: The KYC Tenure service API description: | 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. security: - openId: - kyc-tenure:check-tenure operationId: checkTenure parameters: - in: header name: x-correlator description: Correlation id for the different services required: false schema: $ref: "#/components/schemas/XCorrelator" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/Tenure" responses: "200": description: Respond with tenure information headers: x-correlator: $ref: "#/components/headers/X-Correlator" content: application/json: schema: $ref: "#/components/schemas/TenureInfo" "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: securitySchemes: openId: type: openIdConnect openIdConnectUrl: https://example.com/.well-known/openid-configuration headers: X-Correlator: description: Correlation id for the different services required: false schema: $ref: "#/components/schemas/XCorrelator" responses: Generic400: description: Bad Request headers: x-correlator: $ref: "#/components/headers/X-Correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 400 code: enum: - INVALID_ARGUMENT - OUT_OF_RANGE examples: GENERIC_400_INVALID_ARGUMENT: description: Invalid Argument. Generic Syntax Exception value: status: 400 code: INVALID_ARGUMENT message: Client specified an invalid argument, request body or query param. GENERIC_400_OUT_OF_RANGE: description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested value: status: 400 code: OUT_OF_RANGE message: Client specified an invalid range. Generic401: description: Unauthorized headers: x-correlator: $ref: "#/components/headers/X-Correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 401 code: enum: - UNAUTHENTICATED examples: GENERIC_401_UNAUTHENTICATED: description: Request cannot be authenticated and a new authentication is required value: status: 401 code: UNAUTHENTICATED message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required. Generic403: description: Forbidden headers: x-correlator: $ref: "#/components/headers/X-Correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 403 code: enum: - PERMISSION_DENIED examples: GENERIC_403_PERMISSION_DENIED: description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security value: status: 403 code: PERMISSION_DENIED message: Client does not have sufficient permissions to perform this action. Generic404: description: Not found headers: x-correlator: $ref: "#/components/headers/X-Correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 404 code: enum: - IDENTIFIER_NOT_FOUND examples: GENERIC_404_IDENTIFIER_NOT_FOUND: description: The phone number is not associated with a CSP customer account value: status: 404 code: IDENTIFIER_NOT_FOUND message: The phone number provided is not associated with a customer account Generic422: description: Unprocessable Content headers: x-correlator: $ref: "#/components/headers/X-Correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 422 code: enum: - SERVICE_NOT_APPLICABLE - MISSING_IDENTIFIER - UNNECESSARY_IDENTIFIER examples: GENERIC_422_SERVICE_NOT_APPLICABLE: description: Service is not applicable for the provided phone number value: status: 422 code: SERVICE_NOT_APPLICABLE message: The service is not applicable for the provided phone number GENERIC_422_MISSING_IDENTIFIER: description: No phone number has been provided either explicitly or associated with the access token value: status: 422 code: MISSING_IDENTIFIER message: No phone number has been provided GENERIC_422_UNNECESSARY_IDENTIFIER: description: An explicit phone number has been provided when one is already associated with the access token value: status: 422 code: UNNECESSARY_IDENTIFIER message: An explicit phone number has been provided when one is already associated with the access token schemas: Tenure: description: Specifies date from which continuous tenure of the identified mobile subscriber is required to be confirmed type: object 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 of the identified network subscriber is required to be confirmed format: date example: "2023-07-03" required: - tenureDate PhoneNumber: description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. type: string pattern: '^\+[1-9][0-9]{4,14}$' example: "+123456789" TenureInfo: properties: tenureDateCheck: description: | `true` when the identified mobile subscription has had valid tenure since `tenureDate`, otherwise `false` example: true type: boolean contractType: 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" type: string enum: ["PAYG", "PAYM", "Business"] required: - tenureDateCheck ErrorInfo: type: object required: - status - code - message properties: status: type: integer description: HTTP response status code code: type: string description: A human-readable code to describe the error message: type: string description: A human-readable description of what the event represents XCorrelator: type: string pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$ example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"