Hrmony Embedded API — Partner (EN) (1.0.0)

Backend JWT via the client_credentials grant. Tokens are not issued by this gateway but by its own subdomain, auth.<partner>.hrmony.rest:

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

<partner> is the subdomain assigned to the partner; Hrmony provides client_id and client_secret during onboarding.

The response carries access_token, token_type: Bearer and expires_in. Send the token as Authorization: Bearer <access_token>. This tier has no refresh tokens — once a token expires, request a new one through the same grant; cache it server-side and renew it before it expires.

For this tier the authorization server has exactly two endpoints: the POST /oauth/token above, and GET /.well-known/jwks.json carrying the public key that issued tokens can be verified against. Both live on the auth subdomain rather than on this gateway, so they do not appear in the endpoint list below — the example above is their complete description.

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. Scopes from two tiers in one request are rejected with 400 invalid_scope, and the other two tiers' gateways reject a token of this tier with 401.
• A token carries exactly the scopes requested. scope=partner:read yields a read-only token: write endpoints then answer 403 (/errors/forbidden). Every GET is a read, every POST a write. For use cases that only read — a back office, say — this is the intended route: a token of its own with the smallest sufficient scope rather than one token holding every right.
• 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.

Requests on this tier do not run in the context of an organization and therefore carry no X-Hrmony-Tenant-ID header. Where an organization is relevant at all, it is named as a path parameter (GET) or in the body (POST). Everything that happens inside one organization lives on the admin tier.

The events documented under webhooks describe requests Hrmony sends to the partner, not endpoints of this API. Receiver URLs are registered through this tier's /v1/webhooks endpoints; every delivery is signed so the receiver can verify it.

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.

Create, list and rename organizations.

An organization is permanent. There is no endpoint to delete one. Its display name, by contrast, you can change at any time via POST /v1/organizations/updateName; the new name then also appears in generated documents, while documents already generated keep the previous one. A customer is wound down rather than deleted: its employees via POST /v1/employees/deactivate, its benefits via POST /v1/organization/<benefit>/disable (both on the admin tier). The organization itself remains, its externalCustomerId stays taken, and its data is retained to meet statutory retention obligations. If you have a case where an organization genuinely needs deleting rather than winding down, raise it with us and we will work out the process together.

Register, deregister, list and test webhook endpoints.

Events delivered to registered webhook endpoints.

Both receipt events describe the same lifecycle from different angles. Which transition triggers which event is stated here once, in full; each event's own description then only says what its body carries.

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.