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

# EPFO Verification

> Verifies EPFO employment details using UAN, PAN, or phone number

## Overview

This API verifies employment history through EPFO (Employees' Provident Fund Organisation) records. Most verifications complete immediately, but longer requests return a `request_id` for polling.

## Required Information

**At least ONE of the following:**

* UAN number (12 digits)
* PAN number (format: ABCDE1234F)
* Phone number (10 digits)

## Optional Information

Providing these details improves matching accuracy:

* Employee name
* Employer name

## Response Types

### Synchronous (Status 200)

Most verifications complete within 5 seconds and return full employment data immediately.

### Asynchronous (Status 202)

If processing takes longer, you'll receive a `request_id`. Use the Task Status endpoint to poll for results.

## Response Data

* Current employment status
* UAN details and basic information
* Employment history with dates
* Employer details and confidence scores
* Name matching results


## OpenAPI

````yaml POST /v2/verification/epfo/
openapi: 3.0.0
info:
  title: KonnectNXT API Store
  description: >-
    A sample API that uses a plant store as an example to demonstrate features
    in the OpenAPI specification
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://bgv.konnectnxt.com/api
    description: Production
  - url: https://testbgv.konnectnxt.com/api
    description: QA
security:
  - bearerAuth: []
paths:
  /v2/verification/epfo/:
    post:
      tags:
        - Employment Verification
        - EPFO
      summary: EPFO Employment Verification
      description: >-
        Verifies EPFO employment details using UAN, PAN, or phone number.
        Returns employment history and current status. May return 202 with
        request_id for async polling.
      operationId: verifyEPFO
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EPFOVerificationRequest'
            examples:
              all_identifiers:
                summary: Complete request with all identifiers
                value:
                  phone_number: '9876543210'
                  pan_number: ABCDE1234F
                  uan_number: '100234567890'
                  employer_name: Tech Solutions Pvt Ltd
                  employee_name: Priya Sharma
              uan_only:
                summary: Verification using UAN only
                value:
                  uan_number: '100234567890'
              pan_only:
                summary: Verification using PAN only
                value:
                  pan_number: ABCDE1234F
                  employee_name: Priya Sharma
              phone_only:
                summary: Verification using phone number only
                value:
                  phone_number: '9876543210'
      responses:
        '200':
          description: Verification completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EPFOVerificationSuccessResponse'
              examples:
                employed:
                  summary: Currently employed with matching records
                  value:
                    status: success
                    code: 200
                    message: Operation completed successfully
                    data:
                      is_employed: true
                      is_employee_name_match: true
                      is_employer_name_match: true
                      recent_employer_data:
                        date_of_exit: null
                        date_of_joining: '2023-03-15'
                        employer_confidence_score: 0.95
                        establishment_id: MHPUN0123456789
                        establishment_name: TECH SOLUTIONS PVT LTD
                        matching_uan: '100234567890'
                        member_id: MHPUN01234567890012345
                      status: id_found
                      uan:
                        - '100234567890'
                      uan_details:
                        '100234567890':
                          basic_details:
                            aadhaar_verification_status: 1
                            date_of_birth: '1992-07-20'
                            employee_confidence_score: 1
                            gender: FEMALE
                            mobile: '9876543210'
                            name: PRIYA SHARMA
                          employment_details:
                            date_of_exit: null
                            date_of_joining: '2023-03-15'
                            employer_confidence_score: 0.95
                            establishment_id: MHPUN0123456789
                            establishment_name: TECH SOLUTIONS PVT LTD
                            leave_reason: ''
                            member_id: MHPUN01234567890012345
                    credits_used: 20
                    credits_remaining: 9980.5
                not_employed:
                  summary: Previously employed but currently not working
                  value:
                    status: success
                    code: 200
                    message: Operation completed successfully
                    data:
                      is_employed: false
                      is_employee_name_match: true
                      is_employer_name_match: null
                      recent_employer_data:
                        date_of_exit: '2024-12-31'
                        date_of_joining: '2021-06-01'
                        employer_confidence_score: null
                        establishment_id: KABLR0987654321
                        establishment_name: INNOVATIVE SYSTEMS LLP
                        matching_uan: '100234567890'
                        member_id: KABLR09876543210098765
                      status: id_found
                      uan:
                        - '100234567890'
                      uan_details:
                        '100234567890':
                          basic_details:
                            aadhaar_verification_status: 1
                            date_of_birth: '1992-07-20'
                            employee_confidence_score: 1
                            gender: FEMALE
                            mobile: ''
                            name: PRIYA SHARMA
                          employment_details:
                            date_of_exit: '2024-12-31'
                            date_of_joining: '2021-06-01'
                            employer_confidence_score: null
                            establishment_id: KABLR0987654321
                            establishment_name: INNOVATIVE SYSTEMS LLP
                            leave_reason: Resignation
                            member_id: KABLR09876543210098765
                    credits_used: 20
                    credits_remaining: 9980.5
        '202':
          description: Verification still processing - Use request_id to poll for results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EPFOVerificationProcessingResponse'
              examples:
                processing:
                  summary: Verification in progress
                  value:
                    status: success
                    code: 202
                    message: Verification is still processing
                    data:
                      status: in_progress
                      request_id: 520c6357-c58c-431b-a376-acdb6975f895
                      message: >-
                        Verification is still processing. Please check back
                        later using the request_id.
                    credits_used: 20
                    credits_remaining: 9980.5
        '400':
          description: Bad Request - Validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_WithCredits'
              examples:
                no_identifier:
                  summary: No identifier provided
                  value:
                    status: error
                    code: 400
                    message: >-
                      At least one of phone_number, pan_number, or uan_number is
                      required
                    data: null
                invalid_uan:
                  summary: Invalid UAN format
                  value:
                    status: error
                    code: 400
                    message: UAN must be exactly 12 digits
                    data: null
                invalid_pan:
                  summary: Invalid PAN format
                  value:
                    status: error
                    code: 400
                    message: 'PAN must be in format: ABCDE1234F'
                    data: null
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '404':
          description: No matching employment record found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_WithCredits'
              examples:
                not_found:
                  summary: No employment record found
                  value:
                    status: error
                    code: 404
                    message: No matching employment record found
                    data: null
        '500':
          $ref: '#/components/responses/500_WithCredits'
components:
  schemas:
    EPFOVerificationRequest:
      type: object
      description: >-
        Request for EPFO employment verification - requires at least ONE
        identifier
      properties:
        phone_number:
          type: string
          description: 10-digit mobile number linked with UAN
          pattern: ^[6-9]\d{9}$
          example: '9876543210'
        pan_number:
          type: string
          description: PAN in format ABCDE1234F
          pattern: ^[A-Z]{5}[0-9]{4}[A-Z]$
          example: ABCDE1234F
        uan_number:
          type: string
          description: 12-digit Universal Account Number
          pattern: ^\d{12}$
          example: '100234567890'
        employer_name:
          type: string
          description: Current or recent employer name (optional, improves matching)
          maxLength: 255
          example: Tech Solutions Pvt Ltd
        employee_name:
          type: string
          description: Employee full name (optional, used for verification match)
          maxLength: 255
          example: Priya Sharma
    EPFOVerificationSuccessResponse:
      allOf:
        - $ref: '#/components/schemas/APIBaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                is_employed:
                  type: boolean
                  description: >-
                    Whether employee is currently employed (date_of_exit is
                    null)
                  example: true
                is_employee_name_match:
                  type: boolean
                  description: Whether provided employee name matches EPFO records
                is_employer_name_match:
                  type: boolean
                  nullable: true
                  description: Whether provided employer name matches recent employer
                recent_employer_data:
                  type: object
                  description: Most recent employment record
                  properties:
                    date_of_exit:
                      type: string
                      nullable: true
                      description: Last working date (null if still employed)
                      example: null
                    date_of_joining:
                      type: string
                      description: Date of joining current/last employer
                      example: '2023-03-15'
                    employer_confidence_score:
                      type: number
                      nullable: true
                      description: Confidence score for employer name match (0-1)
                      example: 0.95
                    establishment_id:
                      type: string
                      description: EPFO establishment ID
                      example: MHPUN0123456789
                    establishment_name:
                      type: string
                      description: Employer organization name as per EPFO
                      example: TECH SOLUTIONS PVT LTD
                    matching_uan:
                      type: string
                      description: UAN matched from the search
                      example: '100234567890'
                    member_id:
                      type: string
                      description: EPFO member ID for this establishment
                      example: MHPUN01234567890012345
                status:
                  type: string
                  description: Status of the verification
                  enum:
                    - id_found
                    - id_not_found
                  example: id_found
                uan:
                  type: array
                  description: List of UANs found for the employee
                  items:
                    type: string
                  example:
                    - '100234567890'
                uan_details:
                  type: object
                  description: Detailed information for each UAN found
                  additionalProperties:
                    type: object
                    properties:
                      basic_details:
                        type: object
                        properties:
                          aadhaar_verification_status:
                            type: integer
                            description: >-
                              Aadhaar seeding status (1=verified, 0=not
                              verified)
                            example: 1
                          date_of_birth:
                            type: string
                            format: date
                            description: Date of birth as per EPFO records
                            example: '1992-07-20'
                          employee_confidence_score:
                            type: number
                            description: Employee name match confidence (0-1)
                            example: 1
                          gender:
                            type: string
                            enum:
                              - MALE
                              - FEMALE
                            example: FEMALE
                          mobile:
                            type: string
                            description: Registered mobile number
                            example: '9876543210'
                          name:
                            type: string
                            description: Employee name as per EPFO
                            example: PRIYA SHARMA
                      employment_details:
                        type: object
                        properties:
                          date_of_exit:
                            type: string
                            nullable: true
                            description: Last working date (null if still employed)
                            example: null
                          date_of_joining:
                            type: string
                            example: '2023-03-15'
                          employer_confidence_score:
                            type: number
                            nullable: true
                            example: 0.95
                          establishment_id:
                            type: string
                            example: MHPUN0123456789
                          establishment_name:
                            type: string
                            example: TECH SOLUTIONS PVT LTD
                          leave_reason:
                            type: string
                            description: Reason for leaving (empty if still employed)
                            example: ''
                          member_id:
                            type: string
                            example: MHPUN01234567890012345
        - $ref: '#/components/schemas/Credits'
    EPFOVerificationProcessingResponse:
      allOf:
        - $ref: '#/components/schemas/APIBaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                status:
                  type: string
                  enum:
                    - in_progress
                  example: in_progress
                request_id:
                  type: string
                  format: uuid
                  description: UUID for polling this request
                  example: 520c6357-c58c-431b-a376-acdb6975f895
                message:
                  type: string
                  example: >-
                    Verification is still processing. Please check back later
                    using the request_id.
        - $ref: '#/components/schemas/Credits'
    Error_WithCredits:
      allOf:
        - $ref: '#/components/schemas/Error'
        - $ref: '#/components/schemas/APIErrorData'
        - $ref: '#/components/schemas/Credits'
    APIBaseResponse:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          $ref: '#/components/schemas/APIStatus'
        code:
          $ref: '#/components/schemas/HTTPCode'
        message:
          $ref: '#/components/schemas/APIMessage'
    Credits:
      type: object
      properties:
        credits_used:
          $ref: '#/components/schemas/CreditsUsed'
        credits_left:
          $ref: '#/components/schemas/CreditsLeft'
      required:
        - credits_used
        - credits_left
    Error:
      allOf:
        - $ref: '#/components/schemas/APIBaseResponse'
    APIErrorData:
      type: object
      properties:
        data:
          type: object
          nullable: true
          example: null
    APIStatus:
      type: string
      enum:
        - success
        - error
      description: Overall status of the API
    HTTPCode:
      type: integer
      description: HTTP status code
      example: 400
    APIMessage:
      type: string
      description: Description of the response or error
      example: Invalid request parameters
    CreditsUsed:
      type: integer
      description: Represents the total number of credits used in this request.
      example: 3
    CreditsLeft:
      type: integer
      description: 'Represents the remaining credits available for use. '
      example: 4040
  responses:
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/APIErrorData'
          examples:
            Missing Token:
              summary: Bearer token is missing or invalid.
              value:
                status: error
                code: 401
                message: Bearer token is missing or invalid.
                data: null
            Incorrect Token Format:
              summary: Token format is incorrect
              value:
                status: error
                code: 401
                message: Token format is incorrect
                data: null
            No Admin Found:
              summary: No admin found for this request
              value:
                status: error
                code: 401
                message: No admin user found for this organization
                data: null
            Invalid API Key:
              summary: Invalid API Key
              value:
                status: error
                code: 401
                message: Invalid API key (organization ID)
                data: null
            User not Found:
              summary: User not found
              value:
                status: error
                code: 401
                message: User not found.
                data: null
    '402':
      description: Payment Required
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/APIErrorData'
          examples:
            Credit Limit Exceed:
              summary: Credit Limit Exceeded.
              value:
                status: error
                code: 402
                message: Credit Limit Exceeded.
                data: null
            Insufficient Credits:
              summary: Insufficient credits
              value:
                status: error
                code: 402
                message: 'Insufficient credits: 2 required, 1 remaining.'
                data: null
    500_WithCredits:
      description: Internal Server Error
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/APIErrorData'
              - $ref: '#/components/schemas/Credits'
          examples:
            Internal Server Error:
              summary: Internal Server Error.
              value:
                status: error
                code: 500
                message: Internal Server Error.
                data: null
                credits_used: 3
                credits_remaining: 178
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key issued by KonnectNXT. Pass as `Authorization: Bearer
        <your_api_key>`.

````