openapi: 3.0.3
info:
  title: Telesign PhoneID Fraud Scoring Verification API
  description: The Telesign PhoneID API provides global phone number intelligence, enabling businesses to verify and enrich phone number data for fraud prevention and risk assessment. Submit any phone number to receive carrier information, location data, phone type, and subscriber intelligence.
  version: '2'
  contact:
    name: Telesign Developer Support
    url: https://developer.telesign.com/enterprise
  termsOfService: https://www.telesign.com/terms-conditions/
servers:
- url: https://rest-ww.telesign.com/v1
  description: Telesign REST API
security:
- BasicAuth: []
tags:
- name: Verification
  description: Create, retrieve, and update verification processes
paths:
  /verify:
    post:
      operationId: createVerification
      summary: Create Verification Process
      description: Initiate a verification process by sending an OTP to a phone number via the specified channel (SMS, voice, WhatsApp, etc.). Returns a reference ID to track the verification.
      tags:
      - Verification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - phone_number
              properties:
                phone_number:
                  type: string
                  description: The end user's phone number including country code.
                channel:
                  type: string
                  description: Delivery channel for the OTP.
                  enum:
                  - sms
                  - voice
                  - whatsapp
                  - viber
                  - rcs
                  - email
                  default: sms
                language:
                  type: string
                  description: Language for the OTP message (BCP 47 language tag).
                template:
                  type: string
                  description: Custom message template for the OTP.
                code_length:
                  type: integer
                  description: Length of the OTP code (4-10 digits).
                  minimum: 4
                  maximum: 10
                  default: 6
      responses:
        '200':
          description: Verification process created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
        '400':
          description: Invalid request parameters
        '401':
          description: Unauthorized
        '429':
          description: Rate limit exceeded
  /verify/{reference_id}:
    get:
      operationId: getVerification
      summary: Retrieve Verification Process
      description: Check the status of an existing verification process.
      tags:
      - Verification
      parameters:
      - name: reference_id
        in: path
        required: true
        schema:
          type: string
        description: The reference ID returned when the verification was created.
      responses:
        '200':
          description: Verification status retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
        '401':
          description: Unauthorized
        '404':
          description: Reference ID not found
    patch:
      operationId: updateVerification
      summary: Update Verification Process
      description: Submit the OTP code entered by the end user to complete verification.
      tags:
      - Verification
      parameters:
      - name: reference_id
        in: path
        required: true
        schema:
          type: string
        description: The reference ID of the verification to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - verify_code
              properties:
                verify_code:
                  type: string
                  description: The OTP code entered by the end user.
      responses:
        '200':
          description: Verification update processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
        '400':
          description: Invalid OTP code
        '401':
          description: Unauthorized
        '404':
          description: Reference ID not found
components:
  schemas:
    VerificationStatus:
      type: object
      properties:
        code:
          type: integer
          description: Status code for the verification state.
        description:
          type: string
          description: Human-readable status description.
        updated_on:
          type: string
          format: date-time
          description: Timestamp of the last status update.
    VerifyResponse:
      type: object
      properties:
        reference_id:
          type: string
          description: Unique identifier for the verification transaction.
        status:
          $ref: '#/components/schemas/VerificationStatus'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: Basic authentication using Customer ID as username and API key as password.