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
| Field | Type | Required | Description |
|---|---|---|---|
establishment_id | string | Yes | The 15-character EPFO establishment ID, letters and digits. |
establishment_name | string | Yes | Name of the establishment, 2 to 200 characters. |
employee_name | string | Yes | Name of the employee to look for, 2 to 100 characters. |
employment_month | string | Yes | Month 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
| Field | Type | Description |
|---|---|---|
match | boolean | True when the employee appears in the establishment's records for that month. |
search_result | array | The filings searched. |
search_result[].establishment_name | string | Name of the establishment. |
search_result[].establishment_id | string | ID of the establishment. |
search_result[].office_name | string | EPFO office handling the establishment. |
search_result[].address | string | Address of the establishment. |
search_result[].payment_details | array | Contribution payments made in the month. |
search_result[].payment_details[].date_of_credit | string | Date the payment was credited. |
search_result[].payment_details[].amount | string | Amount paid. |
search_result[].payment_details[].wage_month | string | Month the payment covers. |
search_result[].payment_details[].ecr | string | Whether an ECR was filed. |
search_result[].payment_details[].employee_match | array | The employee entries that matched the name. |
search_result[].payment_details[].trrn | string | Payment 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.