Telstra Check Subscriber Tenure API

openapi: 3.2.0
info:
  description: '# Summary


    The CAMARA Know Your Customer (KYC) Tenure API allows for verification that a network subscriber has been a customer of Telstra 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. **Telstra does not currently return this field**


    An example of a JSON response object is as follows:

    ```

    {

    "tenureDateCheck": true,

    }

    ```


    ## 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 Telstra), 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. **Telstra only uses three-legged access tokens, therefore the phoneNumber field must not be provided**


    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.'
  title: KYC Tenure Check Subscriber Tenure API
  version: 0.2.0
  x-camara-commonalities: 0.6
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://prod.okapi.ogw.evolve.okapi.telstra.com/mobility/products-api/kyc/kyc-tenure/v0.2
tags:
- name: Check Subscriber Tenure
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:
            examples:
              CheckTenureRequestBodyExample:
                value:
                  tenureDate: '2023-07-03'
            schema:
              $ref: '#/components/schemas/Tenure'
      responses:
        '200':
          description: Respond with tenure information
          headers:
            x-correlator:
              $ref: '#/components/headers/X-Correlator'
          content:
            application/json:
              examples:
                CheckTenureResponseBodyExample:
                  value:
                    tenureDateCheck: true
              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'
        '429':
          $ref: '#/components/responses/Generic429'
components:
  responses:
    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
    Generic429:
      description: Too Many Requests
      headers:
        x-correlator:
          $ref: '#/components/headers/X-Correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 429
                code:
                  enum:
                  - TOO_MANY_REQUESTS
          examples:
            GENERIC_429_TOO_MANY_REQUESTS:
              description: Access to the API has been temporarily blocked due to rate or spike arrest limits being reached
              value:
                status: 429
                code: TOO_MANY_REQUESTS
                message: Rate limit reached.
    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
    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.
    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.
  schemas:
    XCorrelator:
      type: string
      pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
      example: b4333c46-49c0-4f62-80d7-f0ef930f1c46
    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
    TenureInfo:
      properties:
        tenureDateCheck:
          description: '`true` when the identified mobile subscription has had valid tenure since `tenureDate`, otherwise `false`

            '
          example: true
          type: boolean
        contractType:
          description: '**Telstra does not currently return this field**


            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
    PhoneNumber:
      description: '**Telstra only uses three-legged access tokens, therefore this field must not be provided**. 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: '+61462925583'
  headers:
    X-Correlator:
      description: Correlation id for the different services
      required: false
      schema:
        $ref: '#/components/schemas/XCorrelator'
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
externalDocs:
  description: Product documentation at CAMARA
  url: https://github.com/camaraproject/Tenure