> ## 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 Match Service

> Verification Match Service API Documentation

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

## Endpoint

**PATCH** `/phone-service/verification/{referenceId}`

## Swagger

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


## OpenAPI

````yaml PATCH /phone-service/verification/{referenceId}
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/{referenceId}:
    patch:
      summary: Verification Match
      description: >-
        Validate the one-time passcode (OTP) provided by the end user and update
        the state of an active verification process. If the OTP is correct, the
        process is marked as VERIFIED; otherwise an error is returned and the
        process may remain ONGOING, FAILED, or another relevant state.
      parameters:
        - name: referenceId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier for the verification process.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationMatchRequest'
            examples:
              finalize:
                value:
                  securityFactor: '12345'
      responses:
        '200':
          description: Verification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationMatchResponse'
              examples:
                verified:
                  value:
                    status: true
                    data:
                      status:
                        code: 3900
                        description: Verified
        '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'
      security:
        - BearerAuth: []
components:
  schemas:
    VerificationMatchRequest:
      type: object
      required:
        - securityFactor
      properties:
        securityFactor:
          type: string
          description: The OTP provided by the end user (3–10 digits).
          pattern: ^\d{3,10}$
          example: '12345'
      additionalProperties: false
    VerificationMatchResponse:
      type: object
      required:
        - status
        - data
      properties:
        status:
          type: boolean
          description: Indicates whether the request was successful (true or false).
          example: true
        data:
          type: object
          required:
            - status
          properties:
            status:
              type: object
              required:
                - code
                - description
              properties:
                code:
                  type: integer
                  description: Numeric code representing the verification result.
                  example: 3900
                description:
                  type: string
                  description: Human-readable description of the verification result.
                  example: Verified
              additionalProperties: false
          additionalProperties: false
      additionalProperties: false
      example:
        status: true
        data:
          status:
            code: 3900
            description: Verified
    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.

````