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)