openapi: 3.0.3
info:
  title: Sinch Verification Report Verification Start Verification API
  description: 'The Sinch Verification API (Sinch Verify) confirms that a user controls a mobile phone number, powering OTP, two-factor authentication (2FA), and anti-fraud sign-up flows. It supports four verification methods: SMS, flash call, phone call (callout), and data (seamless / silent). The flow is: start a verification, report the received code or caller ID, then read the pass/fail result. Status can also be queried by id, by number, or by a custom reference. Base URL is https://verification.api.sinch.com/verification/v1. Requests are server-to-server and authenticated with either an Application-signed request (HMAC-SHA256 over the request using your application key and secret) or HTTP Basic auth (recommended only for prototyping). Paths and methods below are grounded in the public Sinch developer documentation; request/response schemas are modeled and should be reconciled against the live API reference.'
  version: '1.0'
  contact:
    name: Sinch
    url: https://developers.sinch.com/docs/verification/
  x-modeled: true
servers:
- url: https://verification.api.sinch.com/verification/v1
  description: Sinch Verification API production
security:
- applicationSigned: []
- basicAuth: []
tags:
- name: Start Verification
  description: Initiate a phone number verification.
paths:
  /verifications:
    post:
      operationId: startVerification
      tags:
      - Start Verification
      summary: Start a verification
      description: Starts a verification using the chosen method (sms, flashcall, callout, or seamless). Provide the phone number as the identity. Sinch returns the template or CLI filter the client should observe. Used by the mobile and web Verification SDKs and callable directly from a backend.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartVerificationRequest'
      responses:
        '200':
          description: Verification started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartVerificationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Authentication failed or was missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    StartVerificationResponse:
      type: object
      properties:
        id:
          type: string
        method:
          type: string
          enum:
          - sms
          - flashcall
          - callout
          - seamless
        sms:
          type: object
          description: Present for SMS verifications; includes the template to match.
          properties:
            template:
              type: string
        flashCall:
          type: object
          description: Present for flash call verifications; includes the CLI filter.
          properties:
            cliFilter:
              type: string
            interceptionTimeout:
              type: integer
    StartVerificationRequest:
      type: object
      required:
      - identity
      - method
      properties:
        identity:
          $ref: '#/components/schemas/Identity'
        method:
          type: string
          enum:
          - sms
          - flashcall
          - callout
          - seamless
        reference:
          type: string
          description: Optional custom reference for tracking and later lookup.
        custom:
          type: string
          description: Optional custom string passed through to callbacks.
    Identity:
      type: object
      properties:
        type:
          type: string
          example: number
        endpoint:
          type: string
          description: The phone number in E.164 format.
          example: '+15551234567'
    Error:
      type: object
      properties:
        errorCode:
          type: integer
        message:
          type: string
        reference:
          type: string
  securitySchemes:
    applicationSigned:
      type: apiKey
      in: header
      name: Authorization
      description: Application-signed request. The Authorization header is "Application {application_key}:{signature}" where signature is a Base64-encoded HMAC-SHA256 of the canonicalized request (method, content type, Content-MD5, x-timestamp header, and path) using the Base64-decoded application secret. Recommended for production.
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication using the application key as username and the application secret as password. Recommended for prototyping only.