Build on the Offrd ESS API
The Employee Self-Service REST API behind the Offrd mobile and web ESS portal. An authenticated caller acts on behalf of one employee at a time — their own documents, payslips, profile, probation status, increments and notifications. No cross-employee access, no admin/HR surface.
One base path per tenant
https://<offrd-host>/api/ess — the X-Tenant-Id header selects the tenant, not the URL.
Token + 2 headers
A long-lived Bearer token plus X-Tenant-Id and X-EmployeeEmail on every call. No login or token-exchange endpoint.
JSON, one error shape
Every error returns { "error": { "code", "message" } } — consistent across all 12 endpoints.
Self-scoped by design
One employee at a time, their own data only — no cross-employee access, no admin/HR surface.
Authentication
Unlike a typical employee-scoped OAuth/session flow, the ESS API uses a single long-lived, tenant-scoped Bearer token plus two identity headers carried on every call — there’s no token-exchange or login endpoint. The token is generated offline by an admin, in Offrd under Settings → Integrations → Employee Mobile App (ESS API) — the same page also shows the Tenant ID. The token authorizes the integration itself; the acting employee is supplied per request via a header, not baked into the token.
| Header | Example | Description |
|---|---|---|
Authorization | Bearer {{token}} | The long-lived integration token. |
X-Tenant-Id | {{tenantId}} | Tenant schema_name the token was issued for. |
X-EmployeeEmail | {{employeeEmail}} | Email of the employee the call acts on behalf of. |
Security note: because identity is per-request rather than signed into the token, the host application (not Offrd) is the system of record for “who is this employee” — keep the token server-side and never ship it to a browser or mobile client directly.
| Status | Code | Cause |
|---|---|---|
| 401 | unauthorized | Missing or invalid Authorization bearer token. |
| 400 | tenant_header_missing | X-Tenant-Id header absent. |
| 404 | employee_not_found | X-Employee-Email matches no employee in that tenant. |
Base URL & Configuration
One Offrd host serves every tenant deployed on it — the base URL doesn’t change per tenant. Every endpoint below is relative to that host, e.g. {baseUrl}/api/ess/profile; the X-Tenant-Id header, not the URL, is what selects which tenant a request acts against.
| Value | Example | Where it comes from |
|---|---|---|
| Base URL | https://<offrd-host> | The Offrd deployment host |
| Token | (opaque string) | Issued by an admin in Offrd → Settings → Integrations → Employee Mobile App (ESS API) |
| Tenant ID | (tenant schema_name) | Shown on the same Integrations page |
| Employee email | The signed-in employee's email | Sent as X-EmployeeEmail on every call |
Endpoints
12 endpoints grouped into Documents, Profile, Notifications and Files, plus one unauthenticated-by-design endpoint for downloading a signed file link.
Documents
Employment, tax and exit documents, onboarding paperwork, and the full payslip history — every file the portal's Documents screen lists.
/api/ess/documentsThe Documents screen's main list — employment, tax (Form 16) and exit documents, newest first.
Optional query ?include=onboarding,payslips adds onboarding docs and payslip history to the same response.
Response
{
"items": [ { "id", "type", "title", "url" (signed), "expiresIn" } ],
"onboarding": [ /* with ?include=onboarding */ ],
"payslips": { /* same shape as Payslips, with ?include=payslips */ }
}/api/ess/documents/onboardingCertificates, passport, driving licence and previous-employment documents collected during onboarding.
Response
{ "items": [ { "id", "type", "title", "url", "expiresIn" } ] }/api/ess/documents/payslipsThe payslip list, newest first, capped at 24 months.
Optional query ?payslipsFrom=YYYY-MM lifts the cap.
Response
{
"items": [ { "id", "year", "month", "title", "url", "expiresIn" } ],
"hasMore": false,
"latest": { /* same shape as Payslip for a month */ }
}/api/ess/documents/payslip?year={year}&month={month}One payslip's full earnings/deductions breakdown.
month is 1–12 (a month name also works).
Response
{
"year", "month", "grossPay",
"earnings": [ { "label", "amount" } ],
"deductions": [ { "label", "amount" } ],
"totalDeductions", "netPay",
"employerContributions": [ { "label", "amount" } ],
"url"
}/api/ess/documents/{id}Getting a fresh signed link for any document id returned by the endpoints above.
Response
{ "id", "url", "expiresIn" }Profile
The employee's own profile, probation status, increment history, and the eye-icon reveal for masked identity and bank fields.
/api/ess/profileThe Profile screen and Home header — full employee profile, with identity/bank numbers masked.
Response
{
"personal", "employment", "identity", "bank", "photo",
"emergencyContact", "revealableFields",
"probation", "unreadNotifications", "completeness", "editableFields"
}/api/ess/profileSaving edits made on the Profile screen.
Send only the fields being changed. A changed pincode also updates city and state automatically. Bank, identity and employment fields are managed by HR, not self-editable here.
Request body
{
"phonePrimary", "phoneAlternate",
"addressLine1", "addressLine2", "pincode", "city", "state",
"birthDate", "fathersName", "maritalStatus", "bloodGroup",
"emergencyContactName", "emergencyContactRelation", "emergencyContactPhone"
}Response
{ "updated": [ "phonePrimary" ], "profile": { /* same shape as Get profile */ } }/api/ess/profile/probationThe probation-status card on the Profile screen.
status is one of not_applicable, not_started, on_probation, extended, confirmation_due, confirmed, rejected.
Response
{
"onProbation", "status",
"startedOn", "endsOn",
"totalDays", "extensionDays", "daysRemaining",
"confirmedOn"
}/api/ess/profile/incrementsThe Salary & Payroll tab's increment timeline.
previousAnnualCtc / revisedAnnualCtc are null for increments recorded before CTC history tracking began.
Response
{
"currentAnnualCtc": 0,
"increments": [
{ "effectiveDate", "previousAnnualCtc", "revisedAnnualCtc", "letterUrl" }
]
}/api/ess/profile/revealThe eye-icon button that shows a masked field's full value, one field at a time.
field is one of pan, aadhaar, uan, bankAccount, ifsc. Sent with Cache-Control: no-store — the client must not persist the value. Every reveal is logged server-side.
Request body
{ "field": "pan" }Response
{ "field": "pan", "value": "string" }Notifications
The Notifications screen and its unread badge.
/api/ess/notifications?limit=20&offset=0The Notifications screen and unread badge.
Paging via limit (1–100, default 50) and offset.
Response
{
"unreadCount": 0,
"items": [
{ "id", "type", "title", "message", "isRead", "createdAt",
"target": { "type": "document", "document": { "id", "title", "mimeType", "url", "expiresIn" } } }
]
}/api/ess/notifications/{id}Marking one notification read when it's opened.
Response
{ "unreadCount": 0 }Files
Signed, time-boxed links for the actual file bytes behind every document, payslip and notification attachment — the one unauthenticated endpoint in the API, by design.
<url> — any url field returned aboveOpening or downloading the actual file.
No Authorization, X-Tenant-Id or X-EmployeeEmail header is needed — the signature in the URL is the credential. Links expire 300 seconds after being issued.
Response
The raw file bytes (PDF, image, etc.), not JSON.
Error reference
Every error is { "error": { "code", "message", ...extra fields } }.
| Status | Code | Where it occurs | Notes |
|---|---|---|---|
| 400 | tenant_header_missing | Any endpoint | X-Tenant-Id header absent |
| 400 | invalid_request | Reveal full value | Unknown or missing field; response lists allowed |
| 401 | unauthorized | Any endpoint | Missing or invalid bearer token |
| 403 | link_invalid | Signed file link | Link was tampered with |
| 404 | employee_not_found | Any endpoint | X-EmployeeEmail matches no employee |
| 404 | document_not_found | Document by id | Unknown id, or belongs to another employee |
| 404 | payslip_not_found | Payslip for a month | No payslip sent for that month |
| 404 | notification_not_found | Mark notification read | Unknown notification id |
| 404 | value_not_available | Reveal full value | Field not on file, or unreadable |
| 410 | link_expired | Signed file link | Opened more than 300s after issue |
| 422 | field_not_editable | Update profile | Keys outside the editable list |
| 422 | validation_failed | Update profile | Invalid values; lists per-field errors |
| 429 | rate_limited | Reveal full value | More than 30 reveals per employee per hour |
Want to integrate with Offrd ESS?
Talk to our team about getting an integration token and tenant ID for your organization.
