Hrmony Embedded API — Client (EN) (1.0.0)

User JWT via the token-exchange grant: the partner backend trades its own employee identifier for a Hrmony token scoped to that one employee. Tokens are not issued by this gateway but by its own subdomain, auth.<partner>.hrmony.rest.

Authorization server endpoints

All three live on the auth subdomain rather than on this gateway, so they do not appear in the endpoint list below — the examples here are their complete description.

Step 1 — token exchange (sign-in)

curl --request POST \
  --url https://auth.<partner>.hrmony.rest/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  --data client_id=<CLIENT_ID> \
  --data client_secret=<CLIENT_SECRET> \
  --data subject_token=ext-emp-0001

The response carries access_token, token_type: Bearer, expires_in and refresh_token. Send the access token as Authorization: Bearer <access_token>. Because the exchange needs the client secret, it belongs in the partner backend, not in the app — the app only ever receives the finished access token.

Step 2 — renewing the access token

When the access token expires, the partner backend obtains a new one without exchanging the employee identifier again:

curl --request POST \
  --url https://auth.<partner>.hrmony.rest/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=refresh_token \
  --data client_id=<CLIENT_ID> \
  --data client_secret=<CLIENT_SECRET> \
  --data refresh_token=<REFRESH_TOKEN>

A refresh token is valid for 30 days after its last use, but never longer than 90 days after the original token exchange. An expired or revoked token is answered with 400 and error: invalid_grant.

Three rules an integration otherwise gets wrong:

• Every refresh token is valid exactly once. The response carries a new refresh_token; the old one is spent. Always store the new one.
• Never send a spent token again. If one is sent anyway, Hrmony treats it as theft and revokes every refresh token of that session — including the currently valid one. Access tokens already issued stay valid until they expire. The employee then has to be signed in again via token exchange.
• After a timeout, do not retry — exchange again. If the response to a refresh never arrives, the new token is lost and the old one is spent; a retry triggers the lock-out above.

Step 3 — signing out

When an employee signs out, the partner backend revokes the session:

curl --request POST \
  --url https://auth.<partner>.hrmony.rest/oauth/revoke \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=<CLIENT_ID> \
  --data client_secret=<CLIENT_SECRET> \
  --data token=<REFRESH_TOKEN>

The response is always 200 with no body — for unknown tokens too. Access tokens already issued stay valid until they expire; that is why they are short-lived.

Credentials and scopes

Hrmony issues one client_id/client_secret pair per partner installation. That pair is deliberately valid on all three tiers — it is not an access right in itself, only the permission to have tokens issued. What a call may do is decided by the issued access token alone:

• A token belongs to exactly one tier. The admin and partner gateways reject a client token with 401.
• Client tokens always carry client:read client:write. The token exchange takes no scope parameter; what limits a client token is the employee it was issued for, not its scope. Read-only tokens exist on the two client_credentials tiers (admin, partner).
• The required scope is stated on every operation in this specification as x-required-scope.

On request Hrmony issues several client_id/client_secret pairs for the same installation — one per connecting system, say, so that one can be replaced without touching the others. A credential cannot be restricted to particular tiers or scopes; the separation happens on the token.

Backend operations use a backend token (client_credentials) instead; that flow is documented on the admin and partner tiers.

The token's sub claim is the externalEmployeeId — the id the partner knows the employee by. Hrmony resolves employeeId and organizationId from it when issuing the token and carries them inside it, so they do not belong in requests on this tier. One token addresses exactly one employee, and only that employee's own data is reachable through this tier. This tier carries no X-Hrmony-Tenant-ID header.

Write endpoints carry a verb in the path: POST …/employees/create rather than POST …/employees. This is deliberate.

The style is hybrid by design:

• Writes are RPC. The path names the action, the body carries the data.
• Reads are REST. GET …/{id}, parameters in the URL, no body.

Behind every write endpoint is a command-based model, not a CRUD one. Enabling the meal subsidy or fetching payroll data are not updates to a field on a resource; expressing them as PUT or PATCH would force an unnatural mapping. Many actions are also scheduled rather than immediate: a benefit is activated for an upcoming service month, not right now, and a PATCH on the current state cannot say that.

Reads stay on GET because GET buys something real: responses are cacheable in CDNs and proxies, retries are safe, and a plain lookup needs no request body.

The result is RPC for actions, REST for data.

All errors follow RFC 9457 Problem Details. Only the type URI is stable and worth branching on — title and detail are for humans and may change. They follow the request language, with one exception: for /errors/unauthorized, /errors/forbidden, /errors/not-found, /errors/throttled, /errors/client-error and /errors/server-error they are always English, for /errors/internal-server-error they can be English. Every error carries a requestId; quote it when raising something with Hrmony.

403 or 404. 403 means the token lacks the required scope, or the current business state forbids the action — a benefit that is not enabled for the organization, for instance.

404 means the resource addressed does not exist or is not yours: another employee's receipt, another partner's organization. We answer both the same way, deliberately indistinguishable — otherwise the status codes would let you probe which ids exist. A 404 therefore does not tell you that the id is unknown.

One error is listed under no single endpoint: /errors/not-found (404) for a path this API does not know, or an HTTP method an endpoint does not offer.

Framework errors and domain errors alike carry type URIs under /errors/….

Responses the API gateway produces itself, and that are none of the cases above, carry the catch-all types /errors/client-error (4xx) and /errors/server-error (5xx). Neither carries a status field: they span several status codes, and the gateway cannot read the actual code inside its template. Branch on the HTTP status code of the response instead.

There are no application-level rate limits: no quota per client, per token, per endpoint or per time window, and therefore no RateLimit-* headers either.

The 429 /errors/throttled documented on every operation occurs only when the environment's capacity limit is reached. That limit sits high enough that regular operation never touches it, and it responds to total load across all endpoints — not to a single endpoint or a particular access pattern.

A 429 carries no Retry-After. Treat it as transient and retry with exponentially growing delays plus jitter, not at a fixed interval. The usual retry rules apply: GET is safe to repeat, write endpoints only with the same Idempotency-Key as the first attempt — otherwise you create a second operation.

A 429 says nothing about permissions and does not indicate a blocked account: it means only that this request was not processed and that the same request may succeed later.

For your partner account, the API serves the English variant only: English paths, English field names, English error text. Accept-Language is optional; when sent it must be en. This variant is supported permanently.

The benefit product names are translated like every other term: mealSubsidy and mobility.

Benefits available to the calling employee.

Configuration, reimbursements and employee status for the meal subsidy.

Configuration, reimbursements and employee status for mobility.

Submitting a receipt takes two steps.

1. Create an upload URL: POST /v1/receipts/submit.
2. Send the file as multipart/form-data straight to the uploadUrl you got back, not through this API.

The receiptId from step 1 identifies the receipt in every later call.

Upload

curl -X POST "$UPLOAD_URL" \
  -F key=…                 # uploadFields first, unchanged
  -F policy=… \
  -F x-amz-signature=… \
  -F "file=@receipt.jpg"   # file last

The responses come from storage, not from this API: XML instead of Problem Details, described in the S3 documentation on presigned URLs.

fileType

Accepted are image/jpeg, image/jpg, image/png, image/heic, image/heif, image/gif, image/bmp and application/pdf. Any other value makes step 1 answer 400 /errors/invalid-request-body.

The value is part of the signed policy and appears as Content-Type in uploadFields; the upload has to send it unchanged. Only the declared value is checked, never the file's content — a file declared image/jpeg that holds no image is stored, but the image pipeline cannot read it and the receipt is left in review without an outcome.

Status

The receipt is registered asynchronously after the upload. Until that has happened, GET /v1/receipts/{receiptId} answers 404 /errors/receipt-not-found — that is not a failed upload.

Transitions and webhooks

After the upload the receipt is in_review; receipt.in_review says so, exactly once. Every review outcome arrives as receipt.status_changed, the arrow is the cause:

• cause: initial_review — the first review: recorded with reimbursementAmount, or rejected with rejection.reason.
• cause: dispute_upheld — the re-review of a disputed receipt changed the outcome; the body carries the new values.
• cause: dispute_dismissed — the re-review confirmed the outcome; the status stays and the body carries neither reimbursementAmount nor rejection.

Rules

• recorded and rejected are not final states. A receipt's status always reflects its latest review, so both recorded → rejected and rejected → recorded are possible.
• A dispute (POST /v1/receipts/dispute) has no status of its own: the receipt keeps the outcome it has until the new one is decided.
• Entering in_review produces no receipt.status_changed. That the review has started is what receipt.in_review says, exactly once per receipt — how many review steps it takes stays internal.
• Every re-review produces another event for the same receipt id, even when the outcome is unchanged.
• A reimbursementAmount in a webhook holds as of the delivery time and is never back-filled. It is a share of an allocation period — the day for the meal subsidy, the month for mobility — and changes with the other receipts in that period:
  • When a further receipt for the same period arrives, the amount on the receipts already recorded might go down.
  • When one falls away — deleted, or rejected by a re-review — the amount on the remaining ones might go up.
  • No webhook follows for the receipts changed that way; only the receipt that was itself re-reviewed triggers one, and there are no correction events.
  • Only GET /v1/receipts/{receiptId} gives you the current value.
• The order in which deliveries arrive is not guaranteed; deduplicate on X-Hrmony-Event-Id. Within one receipt, occurredAt orders the events: discard a delivery whose occurredAt is older than the state you have already applied for that receipt. There is no sequence number; occurredAt does the same job.
• A deleted receipt (POST /v1/receipts/delete) has no status any more, and the deletion produces no webhook.

Webhook endpoints are registered on the partner tier; the events and their bodies are documented there under Webhook Events.

Collecting the outcome

Either through the receipt.status_changed webhook or by polling GET /v1/receipts/{receiptId} — spaced out rather than in a tight loop. A receipt with status: recorded carries its reimbursementAmount — the amount currently credited to it. The daily and monthly totals remain in the reimbursement endpoints under Benefits · Meal Subsidy and Benefits · Mobility.

When a service month is done

409 /errors/employee-month-closed is a fixed calendar boundary: from the first day of the following month the employee can neither delete nor dispute a receipt of that service month.

The service month itself is not finished at that point. It is done once every receipt the organization submitted in time has been reviewed. When that is depends on the organization: for one it can be the first of the month, for another the second. Receipts submitted in time are reviewed past the turn of the month, and status, reimbursement amount and monthly total can still change afterwards. Treat a monthly total as final only once no receipt of that month is on in_review any more.

Meal subsidy and mobility

• A receipt's fields are identical for both benefit types; only benefitType tells them apart.
• Deletion exists only for the meal subsidy; for mobility POST /v1/receipts/delete answers 422.
• The dispute reason wrong_date is valid only for the meal subsidy — mobility receipts record no receiptDate (POST /v1/receipts/dispute).