POSTEmployee Verification (Advance)

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

POST/tools/kyc/advance-employment

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.

Body parameters

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

initiator_idstringRequired

Registered mobile number of the API user (see Platform Credentials).

example: 9962981729

user_codestringRequired

User code of the retailer/agent the service is run for.

example: 20810200

client_ref_idstringoptional

Unique reference id per API call, generated by your system.

example: REQ-20260101-001

phonestringRequired

Employee's registered mobile number used to look up UAN records from EPFO.

example: 9876543210

Headers

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

developer_keystringRequired

Static API key issued to your account after KYC.

secret-keystringRequired

Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).

secret-key-timestampstringRequired

Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.

content-typestringRequired

application/json

example: application/json

Responses

statusnumber
Primary success indicator (0 = success).
messagestring
Human-readable response / error message.
response_status_idnumber
Granular status id; see the shared error-codes table.
response_type_idnumber
A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.
dataobject
API-specific response payload.
- inputobject
  Echo of the input parameters sent in the request.
- uan_detailsarray
  List of UAN records associated with the employee's phone number. One entry per UAN.
  - uanstring
    Universal Account Number assigned to the employee by EPFO.
  - sourcestring
    Data source from which the UAN record was fetched.
  - source_scorenumber
    Confidence score of the data source match (0–100).
  - basic_detailsobject
    Core identity details of the employee linked to this UAN.
    - employee_namestring
      Full name of the employee as registered with EPFO.
    - genderstring
      Gender of the employee.
    - dobstring
      Date of birth of the employee in YYYY-MM-DD format.
    - phonestring
      Phone number linked to this UAN.
    - aadhaar_verifiedboolean
      Whether the employee's Aadhaar is linked and verified against this UAN.
    - employee_confidence_scorenumber
      Model confidence score for the employee identity match (0–100).
  - employment_detailsobject
    Employment record associated with this UAN entry.
    - member_idstring
      PF Member ID for this employment record (state/region/establishment/account format).
    - establishment_idstring
      EPFO establishment ID of the employer.
    - establishment_namestring
      Name of the employer/establishment as registered with EPFO.
    - joining_datestring
      Date the employee joined this establishment (YYYY-MM-DD).
    - exit_datestring
      Date the employee exited this establishment (YYYY-MM-DD). Null if currently employed.
    - leave_reasonstring
      Reason for exit as recorded in EPFO (e.g., Resignation, Superannuation).
    - employer_confidence_scorenumber
      Confidence score for the employer identity match (0–100).
  - additional_detailsobject
    Supplementary PII and financial details linked to the UAN (may be partially populated).
    - panstring
      PAN number linked to the employee.
    - aadhaarstring
      Masked or partial Aadhaar number.
    - emailstring
      Email address linked to the UAN.
    - ifscstring
      IFSC code of the linked bank account.
    - bank_accountstring
      Masked bank account number linked to the UAN.
    - bank_addressstring
      Address of the linked bank branch.
    - relative_namestring
      Name of the declared relative/nominee.
    - relationstring
      Relationship of the nominee to the employee.
- recent_employment_detailsobject
  Structured summary of the most recent employment, including EPFO health indicators and employer PF filing history.
  - employee_detailsobject
    Latest employment record for the employee with EPFO flags.
    - uanstring
      UAN for the most recent employment.
    - member_idstring
      PF Member ID for the most recent establishment.
    - joining_datestring
      Joining date for the most recent employment (YYYY-MM-DD).
    - exit_datestring
      Exit date for the most recent employment (YYYY-MM-DD). Null if currently active.
    - employedboolean
      Whether the employee is currently active in this establishment per EPFO records.
    - exit_date_markedboolean
      Whether the employer has formally marked an exit date in EPFO.
    - employee_name_matchboolean
      Whether the name in EPFO matches the name provided or derived from the phone lookup.
    - epfoobject
      EPFO-level flags indicating data quality and filing health.
      - recentboolean
        Whether EPFO data for this employee was recently updated.
      - name_uniqueboolean
        Whether the employee's name appears uniquely in EPFO (no duplicates).
      - pf_filings_detailsboolean
        Whether PF filing details are available for this employee.
  - employer_detailsobject
    Details of the most recent employer including setup date, ownership type, and monthly PF contribution history.
    - establishment_idstring
      EPFO establishment ID of the most recent employer.
    - establishment_namestring
      Name of the most recent employer as registered with EPFO.
    - setup_datestring
      Date the employer establishment was set up/registered with EPFO.
    - ownership_typestring
      Ownership type of the establishment (e.g., Private, Government, Public Sector).
    - employer_confidence_scorenumber
      Model confidence score for employer identity resolution (0–100).
    - employer_name_matchboolean
      Whether the resolved employer name matches the expected employer name.
    - pf_filing_detailsarray
      Monthly PF contribution records filed by the employer. Each entry represents one wage month.
      - wage_monthstring
        The wage month for this PF filing entry (YYYY-MM format).
      - total_amountnumber
        Total PF amount contributed by the employer for this wage month.
      - employees_countnumber
        Number of employees covered under this PF filing for the wage month.