API reference / Employment

Employee search in an establishment

Whether a named employee appears in an EPFO establishment's records for a month (MM/YYYY).

POST/v1/employment/employee-search
Authentication
Bearer token
Scope
kyc:verify

Request body

FieldTypeRequiredDescription
establishment_idstringYesThe 15-character EPFO establishment ID, letters and digits.
establishment_namestringYesName of the establishment, 2 to 200 characters.
employee_namestringYesName of the employee to look for, 2 to 100 characters.
employment_monthstringYesMonth to search, as MM/YYYY, for example 02/2026.

Sample code

Set your key in the GRAPPI_API_KEY environment variable. Sample values are placeholders.

curl -sS -X POST 'https://grappi.ai/v1/employment/employee-search' \
  -H "Authorization: Bearer $GRAPPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "establishment_id": "MHBAN0012345000",
  "establishment_name": "ABC Pvt Ltd",
  "employee_name": "Asha Rao",
  "employment_month": "02/2026"
}'

Sample response

{
  "request_id": "req_01HZY3K8M2",
  "result": {
    "match": true,
    "search_result": [
      {
        "establishment_name": "EXAMPLE TECHNOLOGIES PRIVATE LIMITED",
        "establishment_id": "MHBAN0012345000",
        "office_name": "BANGALORE",
        "address": "12 Example Lane, Pune",
        "payment_details": [
          {
            "date_of_credit": "14/03/2026",
            "amount": "3,75,000",
            "wage_month": "02/2026",
            "ecr": "YES",
            "employee_match": [
              "ASHA RAO"
            ],
            "trrn": "1234567890123"
          }
        ]
      }
    ]
  }
}

Response fields

FieldTypeDescription
matchbooleanTrue when the employee appears in the establishment's records for that month.
search_resultarrayThe filings searched.
search_result[].establishment_namestringName of the establishment.
search_result[].establishment_idstringID of the establishment.
search_result[].office_namestringEPFO office handling the establishment.
search_result[].addressstringAddress of the establishment.
search_result[].payment_detailsarrayContribution payments made in the month.
search_result[].payment_details[].date_of_creditstringDate the payment was credited.
search_result[].payment_details[].amountstringAmount paid.
search_result[].payment_details[].wage_monthstringMonth the payment covers.
search_result[].payment_details[].ecrstringWhether an ECR was filed.
search_result[].payment_details[].employee_matcharrayThe employee entries that matched the name.
search_result[].payment_details[].trrnstringPayment transaction reference.

Errors

Every failure has the same shape. A call that fails on our side or at the data source is refunded to your wallet; a "no record found" answer is charged. See the error reference.