> ## Documentation Index
> Fetch the complete documentation index at: https://umbrella-docs.info/llms.txt
> Use this file to discover all available pages before exploring further.

# Verification Service

> Verification Service API Documentation

For a usage description of the Verification Service, please refer to the [Verification](/essentials/phoneServices) page.

## Endpoint

**POST** `/phone-service/verification`

## Swagger

<a href="/public/downloads/swagger/phoneServices/phoneService.postman_collection.json" download="phoneService.postman_collection.json">
  <button>⬇️ Download OpenAPI YAML</button>
</a>


## OpenAPI

````yaml POST /phone-service/verification
openapi: 3.1.0
info:
  title: Umbrella API
  version: 1.0.0
  description: >-
    API documentation for Umbrella services including KYB, KYC, AML, payments,
    phone intelligence, onboarding, and address verification.
servers:
  - url: https://api-umbrella.io/api/services
    description: Production
  - url: https://sandbox-umbrella-api.azurewebsites.net/api/services
    description: Sandbox
security:
  - bearerAuth: []
paths:
  /phone-service/verification:
    post:
      summary: Verification
      description: Deliver a one-time verification code to a user via SMS or Email.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationRequest'
            examples:
              email:
                value:
                  phoneNumber: '436501234567'
                  method: email
                  email: test@test.com
                  externalId: '12312'
                  securityFactor: '12345'
              sms:
                value:
                  phoneNumber: '436501234567'
                  method: sms
                  externalId: '12312'
                  securityFactor: '123456'
      responses:
        '200':
          description: Successfully initiated verification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResponse'
              examples:
                default:
                  value:
                    status: true
                    data:
                      mobileAppToken: a1378b455f3048059a7be9df6a9da3aa
                      recipient:
                        phoneNumber: '436501234567'
                      referenceId: 366691874BD00250933424F72F7C50CB
                      state: CREATED
                      status:
                        code: 3901
                        description: Request in progress
                        updatedOn: '2025-10-02T10:04:58.505000Z'
        '400':
          description: Bad Request - Malformed syntax in the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized - Authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Not Found - The server could not find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '429':
          description: Too Many Requests - Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
        '500':
          description: >-
            Invalid Transaction - Transaction not attempted due to a system
            issue.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '503':
          description: Service Unavailable - System is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error503'
components:
  schemas:
    VerificationRequest:
      type: object
      required:
        - method
      properties:
        phoneNumber:
          type: string
          description: >-
            Recipient's phone number in international format, no spaces or
            special characters. Required if method = sms.
          example: '436501234567'
          pattern: ^[0-9]+$
          minLength: 6
          maxLength: 20
        email:
          type: string
          format: email
          description: Recipient's email address. Required if method = email.
          example: test@test.com
        method:
          type: string
          description: The delivery method to use.
          enum:
            - sms
            - email
          example: email
        securityFactor:
          type: string
          description: >-
            A custom numeric OTP (3–10 digits). If omitted, a 6-digit OTP is
            auto-generated.
          pattern: ^[0-9]{3,10}$
          example: '123456'
        externalId:
          type: string
          description: 'Customer-defined transaction ID. Max length: 100 characters.'
          maxLength: 100
          example: '12312'
        messageTemplate:
          type: object
          description: Optional template details for this verification.
          properties:
            name:
              type: string
              description: Template name (lowercase letters and underscores only).
              pattern: ^[a-z_]+$
              example: welcome_otp
            verificationTemplate:
              type: string
              description: Template content to be used for this verification.
              example: Your code is {{code}}. It expires in 5 minutes.
          additionalProperties: false
        voiceLang:
          type: string
          description: >-
            Language code for OTP delivery (e.g., 'en-US'). Defaults to English
            if not provided.
          example: en-US
      allOf:
        - oneOf:
            - properties:
                method:
                  const: sms
              required:
                - phoneNumber
            - properties:
                method:
                  const: email
              required:
                - email
      additionalProperties: false
    VerificationResponse:
      type: object
      required:
        - status
        - data
      properties:
        status:
          type: boolean
          description: Indicates whether the request was successful (true/false).
          example: true
        data:
          type: object
          required:
            - recipient
            - referenceId
            - state
            - status
          properties:
            mobileAppToken:
              type: string
              description: Token used to authenticate the mobile app session.
              example: a1378b455f3048059a7be9df6a9da3aa
              minLength: 16
              maxLength: 128
            recipient:
              type: object
              required:
                - phoneNumber
              properties:
                phoneNumber:
                  type: string
                  description: Recipient's phone number in international format.
                  example: '436501234567'
              additionalProperties: false
            referenceId:
              type: string
              description: >-
                Unique 32-character hex string that identifies the verification
                process.
              example: 366691874BD00250933424F72F7C50CB
              pattern: ^[A-F0-9]{32}$
            state:
              type: string
              description: Current state of the verification process.
              enum:
                - CREATED
                - ONGOING
                - REJECTED
                - FAILED
                - VERIFIED
                - CANCELED
              example: CREATED
            status:
              type: object
              required:
                - code
                - description
                - updatedOn
              properties:
                code:
                  type: integer
                  description: Numeric code representing the transaction status.
                  example: 3901
                description:
                  type: string
                  description: Human-readable description of the transaction status.
                  example: Request in progress
                updatedOn:
                  type: string
                  format: date-time
                  description: >-
                    ISO 8601 timestamp indicating when the status was last
                    updated.
                  example: '2025-10-02T10:04:58.505000Z'
              additionalProperties: false
          additionalProperties: false
      additionalProperties: false
    Error400:
      required:
        - message
      type: object
      properties:
        message:
          type: string
          example: Invalid request payload
    Error401:
      required:
        - message
      type: object
      properties:
        message:
          type: string
          example: Unauthorized request
    Error404:
      type: object
      properties:
        message:
          type: string
          example: Journey not found
    Error429:
      type: object
      properties:
        error:
          type: string
          example: Too Many Requests
        message:
          type: string
          example: Rate limit exceeded.
        code:
          type: string
          example: '429'
    Error500:
      required:
        - message
      type: object
      properties:
        message:
          type: string
          example: Internal Server Error
    Error503:
      type: object
      properties:
        error:
          type: string
          example: Service Unavailable
        message:
          type: string
          example: Service is unavailable.
        code:
          type: string
          example: '503'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token obtained from POST /auth. Valid for 60 minutes.

````