---
title: "Employee Verification (Advance) API Reference"
description: "Verify employment history and employee identity by phone number via EPFO/UAN data."
canonical: "https://eps.eko.in/docs/advance-employment"
---


> **Canonical URL:** https://eps.eko.in/docs/advance-employment
> This is a machine-readable Markdown version of the page for AI agents and LLMs. The primary (HTML) version lives at the canonical URL above.

# Employee Verification (Advance) API Reference

`POST https://staging.eko.in/ekoapi/v3/tools/kyc/advance-employment`

Verify employment history and employee identity by phone number via EPFO/UAN data.

Returns a rich, nested profile linked to the employee's Universal Account Number (UAN): basic identity details (name, gender, DOB, Aadhaar link), full employment history per UAN (member ID, establishment, joining/exit dates, leave reason), additional PII (PAN, bank account, email), and a structured recent-employment block that includes EPFO filing health, employer setup date, ownership type, and monthly PF contribution records. Designed for pre-employment checks, lending underwriting, and HR compliance workflows.

> View product & pricing details: [Employee Verification](https://eps.eko.in/products/employee-verification-api.md)

## Body parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| initiator_id | string | yes | Registered mobile number of the API user (see Platform Credentials). e.g. 9962981729 |
| user_code | string | yes | User code of the retailer/agent the service is run for. e.g. 20810200 |
| client_ref_id | string | no | Unique reference id per API call, generated by your system. e.g. REQ-20260101-001 |
| phone | string | yes | Employee's registered mobile number used to look up UAN records from EPFO. e.g. 9876543210 |

## Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| developer_key | string | yes | Static API key issued to your account after KYC. |
| secret-key | string | yes | Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))). |
| secret-key-timestamp | string | yes | Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time. |
| content-type | string | yes | application/json e.g. application/json |

## Response

⭐ marks fields highlighted as verifiable.

| Field | Type | Description |
| --- | --- | --- |
| status | number | Primary success indicator (0 = success). |
| message | string | Human-readable response / error message. |
| response_status_id | number | Granular status id; see the shared error-codes table. |
| response_type_id | number | A unique id for every possible response shape (success or error) — useful for client logic branching and analytics. |
| data | object | API-specific response payload. |
| data.input | object | Echo of the input parameters sent in the request. |
| data.uan_details ⭐ | array | List of UAN records associated with the employee's phone number. One entry per UAN. |
| data.uan_details.uan ⭐ | string | Universal Account Number assigned to the employee by EPFO. |
| data.uan_details.source | string | Data source from which the UAN record was fetched. |
| data.uan_details.source_score | number | Confidence score of the data source match (0–100). |
| data.uan_details.basic_details ⭐ | object | Core identity details of the employee linked to this UAN. |
| data.uan_details.basic_details.employee_name ⭐ | string | Full name of the employee as registered with EPFO. |
| data.uan_details.basic_details.gender ⭐ | string | Gender of the employee. |
| data.uan_details.basic_details.dob ⭐ | string | Date of birth of the employee in YYYY-MM-DD format. |
| data.uan_details.basic_details.phone | string | Phone number linked to this UAN. |
| data.uan_details.basic_details.aadhaar_verified ⭐ | boolean | Whether the employee's Aadhaar is linked and verified against this UAN. |
| data.uan_details.basic_details.employee_confidence_score | number | Model confidence score for the employee identity match (0–100). |
| data.uan_details.employment_details ⭐ | object | Employment record associated with this UAN entry. |
| data.uan_details.employment_details.member_id ⭐ | string | PF Member ID for this employment record (state/region/establishment/account format). |
| data.uan_details.employment_details.establishment_id ⭐ | string | EPFO establishment ID of the employer. |
| data.uan_details.employment_details.establishment_name ⭐ | string | Name of the employer/establishment as registered with EPFO. |
| data.uan_details.employment_details.joining_date ⭐ | string | Date the employee joined this establishment (YYYY-MM-DD). |
| data.uan_details.employment_details.exit_date ⭐ | string | Date the employee exited this establishment (YYYY-MM-DD). Null if currently employed. |
| data.uan_details.employment_details.leave_reason ⭐ | string | Reason for exit as recorded in EPFO (e.g., Resignation, Superannuation). |
| data.uan_details.employment_details.employer_confidence_score | number | Confidence score for the employer identity match (0–100). |
| data.uan_details.additional_details | object | Supplementary PII and financial details linked to the UAN (may be partially populated). |
| data.uan_details.additional_details.pan ⭐ | string | PAN number linked to the employee. |
| data.uan_details.additional_details.aadhaar | string | Masked or partial Aadhaar number. |
| data.uan_details.additional_details.email | string | Email address linked to the UAN. |
| data.uan_details.additional_details.ifsc | string | IFSC code of the linked bank account. |
| data.uan_details.additional_details.bank_account | string | Masked bank account number linked to the UAN. |
| data.uan_details.additional_details.bank_address | string | Address of the linked bank branch. |
| data.uan_details.additional_details.relative_name | string | Name of the declared relative/nominee. |
| data.uan_details.additional_details.relation | string | Relationship of the nominee to the employee. |
| data.recent_employment_details ⭐ | object | Structured summary of the most recent employment, including EPFO health indicators and employer PF filing history. |
| data.recent_employment_details.employee_details ⭐ | object | Latest employment record for the employee with EPFO flags. |
| data.recent_employment_details.employee_details.uan ⭐ | string | UAN for the most recent employment. |
| data.recent_employment_details.employee_details.member_id ⭐ | string | PF Member ID for the most recent establishment. |
| data.recent_employment_details.employee_details.joining_date ⭐ | string | Joining date for the most recent employment (YYYY-MM-DD). |
| data.recent_employment_details.employee_details.exit_date ⭐ | string | Exit date for the most recent employment (YYYY-MM-DD). Null if currently active. |
| data.recent_employment_details.employee_details.employed ⭐ | boolean | Whether the employee is currently active in this establishment per EPFO records. |
| data.recent_employment_details.employee_details.exit_date_marked ⭐ | boolean | Whether the employer has formally marked an exit date in EPFO. |
| data.recent_employment_details.employee_details.employee_name_match ⭐ | boolean | Whether the name in EPFO matches the name provided or derived from the phone lookup. |
| data.recent_employment_details.employee_details.epfo ⭐ | object | EPFO-level flags indicating data quality and filing health. |
| data.recent_employment_details.employee_details.epfo.recent ⭐ | boolean | Whether EPFO data for this employee was recently updated. |
| data.recent_employment_details.employee_details.epfo.name_unique ⭐ | boolean | Whether the employee's name appears uniquely in EPFO (no duplicates). |
| data.recent_employment_details.employee_details.epfo.pf_filings_details ⭐ | boolean | Whether PF filing details are available for this employee. |
| data.recent_employment_details.employer_details ⭐ | object | Details of the most recent employer including setup date, ownership type, and monthly PF contribution history. |
| data.recent_employment_details.employer_details.establishment_id ⭐ | string | EPFO establishment ID of the most recent employer. |
| data.recent_employment_details.employer_details.establishment_name ⭐ | string | Name of the most recent employer as registered with EPFO. |
| data.recent_employment_details.employer_details.setup_date ⭐ | string | Date the employer establishment was set up/registered with EPFO. |
| data.recent_employment_details.employer_details.ownership_type ⭐ | string | Ownership type of the establishment (e.g., Private, Government, Public Sector). |
| data.recent_employment_details.employer_details.employer_confidence_score | number | Model confidence score for employer identity resolution (0–100). |
| data.recent_employment_details.employer_details.employer_name_match ⭐ | boolean | Whether the resolved employer name matches the expected employer name. |
| data.recent_employment_details.employer_details.pf_filing_details ⭐ | array | Monthly PF contribution records filed by the employer. Each entry represents one wage month. |
| data.recent_employment_details.employer_details.pf_filing_details.wage_month ⭐ | string | The wage month for this PF filing entry (YYYY-MM format). |
| data.recent_employment_details.employer_details.pf_filing_details.total_amount ⭐ | number | Total PF amount contributed by the employer for this wage month. |
| data.recent_employment_details.employer_details.pf_filing_details.employees_count ⭐ | number | Number of employees covered under this PF filing for the wage month. |

## Example request

```json
{
  "initiator_id": "9962981729",
  "user_code": "20810200",
  "client_ref_id": "REQ-20260101-001",
  "phone": "9876543210"
}
```

## Example response

```json
{
  "status": 0,
  "response_status_id": 0,
  "message": "Employee verification successful",
  "response_type_id": 1388,
  "data": {
    "input": {
      "phone": "9876543210"
    },
    "uan_details": [
      {
        "uan": "1001234567890",
        "source": "EPFO",
        "source_score": 95,
        "basic_details": {
          "employee_name": "Rajesh Kumar",
          "gender": "Male",
          "dob": "1994-08-29",
          "phone": "9876543210",
          "aadhaar_verified": false,
          "employee_confidence_score": 88
        },
        "employment_details": {
          "member_id": "MH/BOM/12345/000/0000001",
          "establishment_id": "MHBAN0012345000",
          "establishment_name": "Acme Pvt Ltd",
          "joining_date": "2019-04-01",
          "exit_date": "2023-06-30",
          "leave_reason": "Resignation",
          "employer_confidence_score": 90
        },
        "additional_details": {
          "pan": "ABCDE1234F",
          "aadhaar": "XXXX-XXXX-1234",
          "email": "rajesh.kumar@example.com",
          "ifsc": "HDFC0001234",
          "bank_account": "XXXX1234",
          "bank_address": "HDFC Bank, Andheri West, Mumbai",
          "relative_name": "Sunita Kumar",
          "relation": "Spouse"
        }
      }
    ],
    "recent_employment_details": {
      "employee_details": {
        "uan": "1001234567890",
        "member_id": "MH/BOM/12345/000/0000001",
        "joining_date": "2019-04-01",
        "exit_date": "2023-06-30",
        "employed": false,
        "exit_date_marked": true,
        "employee_name_match": true,
        "epfo": {
          "recent": true,
          "name_unique": true,
          "pf_filings_details": true
        }
      },
      "employer_details": {
        "establishment_id": "MHBAN0012345000",
        "establishment_name": "Acme Pvt Ltd",
        "setup_date": "2005-03-15",
        "ownership_type": "Private",
        "employer_confidence_score": 90,
        "employer_name_match": true,
        "pf_filing_details": [
          {
            "wage_month": "2023-05",
            "total_amount": 1800,
            "employees_count": 120
          },
          {
            "wage_month": "2023-04",
            "total_amount": 1800,
            "employees_count": 118
          },
          {
            "wage_month": "2023-03",
            "total_amount": 1750,
            "employees_count": 115
          }
        ]
      }
    }
  }
}
```

## Error scenarios

| Status | Scenario |
| --- | --- |
| 200 | Phone number not linked to any UAN in EPFO records |
| 200 | Missing required parameter (phone) |
| 403 | Invalid or unauthorized developer key |