openapi: 3.1.0
info:
  title: Telstra Mobile Number Verification API
  description: |
    Telstra Mobile Number Verification (formerly Mobile Origin Verification)
    provides silent, friction-free verification that the device making a
    request is on the Telstra mobile data network, and that the SIM
    associated with the data session matches the MSISDN supplied by the
    customer. Designed to replace SMS OTP for in-app sign-in, account
    recovery, and fraud checks on the Telstra consumer mobile network.
  version: '1.0.0'
  contact:
    name: Telstra Developer Support
    url: https://dev.telstra.com
servers:
  - url: https://tapi.telstra.com/v1
    description: Production Server
security:
  - OAuth2ClientCredentials: [MNV]
tags:
  - name: Verification
    description: Mobile number verification operations.
paths:
  /mobile-number-verification/verify:
    post:
      summary: Telstra Verify Mobile Number
      description: Issue a verification request for a Telstra-network MSISDN. The device must initiate the request from a Telstra mobile data session for a successful match.
      operationId: verifyMobileNumber
      tags:
        - Verification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyRequest'
      responses:
        '200':
          description: Verification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  securitySchemes:
    OAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://tapi.telstra.com/v2/oauth/token
          scopes:
            MNV: Mobile Number Verification.
  responses:
    BadRequest:
      description: Bad Request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Too Many Requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    VerifyRequest:
      type: object
      required:
        - msisdn
      properties:
        msisdn:
          type: string
          description: Claimed MSISDN in E.164 format (e.g. +61412345678).
        consentToken:
          type: string
          description: Optional opaque token attesting the end-user has consented to verification.
        clientReference:
          type: string
          description: Application-supplied correlation identifier echoed in the response.
    VerifyResponse:
      type: object
      required:
        - verified
      properties:
        verified:
          type: boolean
          description: True if the device's network session matches the supplied MSISDN.
        carrier:
          type: string
          description: Reported carrier (typically Telstra).
        clientReference:
          type: string
        timestamp:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: string
        code:
          type: string
        message:
          type: string