Atndnz
Developer API

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.

HeaderExampleDescription
AuthorizationBearer {{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.

StatusCodeCause
401unauthorizedMissing or invalid Authorization bearer token.
400tenant_header_missingX-Tenant-Id header absent.
404employee_not_foundX-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.

ValueExampleWhere it comes from
Base URLhttps://<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 emailThe signed-in employee's emailSent 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.

GET/api/ess/documents

The 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 */ }
}
GET/api/ess/documents/onboarding

Certificates, passport, driving licence and previous-employment documents collected during onboarding.

Response

{ "items": [ { "id", "type", "title", "url", "expiresIn" } ] }
GET/api/ess/documents/payslips

The 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 */ }
}
GET/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"
}
404 payslip_not_found
GET/api/ess/documents/{id}

Getting a fresh signed link for any document id returned by the endpoints above.

Response

{ "id", "url", "expiresIn" }
404 document_not_found

Profile

The employee's own profile, probation status, increment history, and the eye-icon reveal for masked identity and bank fields.

GET/api/ess/profile

The 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"
}
PUT/api/ess/profile

Saving 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 */ } }
422 field_not_editable422 validation_failed
GET/api/ess/profile/probation

The 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"
}
GET/api/ess/profile/increments

The 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" }
  ]
}
POST/api/ess/profile/reveal

The 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" }
400 invalid_request404 value_not_available429 rate_limited

Notifications

The Notifications screen and its unread badge.

GET/api/ess/notifications?limit=20&offset=0

The 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" } } }
  ]
}
PUT/api/ess/notifications/{id}

Marking one notification read when it's opened.

Response

{ "unreadCount": 0 }
404 notification_not_found

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.

GET<url> — any url field returned above

Opening 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.
410 link_expired403 link_invalid

Error reference

Every error is { "error": { "code", "message", ...extra fields } }.

StatusCodeWhere it occursNotes
400tenant_header_missingAny endpointX-Tenant-Id header absent
400invalid_requestReveal full valueUnknown or missing field; response lists allowed
401unauthorizedAny endpointMissing or invalid bearer token
403link_invalidSigned file linkLink was tampered with
404employee_not_foundAny endpointX-EmployeeEmail matches no employee
404document_not_foundDocument by idUnknown id, or belongs to another employee
404payslip_not_foundPayslip for a monthNo payslip sent for that month
404notification_not_foundMark notification readUnknown notification id
404value_not_availableReveal full valueField not on file, or unreadable
410link_expiredSigned file linkOpened more than 300s after issue
422field_not_editableUpdate profileKeys outside the editable list
422validation_failedUpdate profileInvalid values; lists per-field errors
429rate_limitedReveal full valueMore 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.