{ "openapi": "3.0.3", "info": { "title": "Ledra Pay API", "version": "0.1.0", "description": "The governed payroll layer. Conventions:\n- **Auth**: `Authorization: Bearer` — partner key (`lp_sandbox_…`/`lp_live_…`), embed token, or user token.\n- **Envelopes**: success `{ data, evidence_id? }`; lists add `{ has_more, next_cursor }`; every error is `{ error: { code, message, status, ...detail } }`.\n- **Money** is always a 2-decimal string (`\"1140.00\"`), never a JSON number.\n- **Ids** carry prefixes: `ten_` tenant · `emp_` employee · `pr_` pay run (`pr_eng_` engine-native) · `cev_` governed evidence.\n- **Governed writes** require a reason: `governance_reason` in the body or the `x-governance-reason` header; it is bound into the evidence chain.\n- **Effective dating**: `as_of` (reads) / `effective_from` (writes) — 501 `CAPABILITY_NOT_SUPPORTED` when the bound engine lacks native support.\n- **Idempotency**: send `Idempotency-Key` on POSTs. A replay of the same key with the same body returns the ORIGINAL response and sets `idempotent-replay: true`; the same key with a DIFFERENT body is `409 idempotency_replay_mismatch`. Keys are scoped to your partner (yours cannot collide with anyone else’s) and are retained 24h — after that the same key is a new request. **In LIVE mode it is REQUIRED**, not optional, on money-moving writes (pay runs, employees, leave, adjustments, submissions, super, payment files): without it they are `400`. Sandbox does not enforce this, so build with the header from the start rather than discovering it at go-live. Caveat: a second call arriving while the original is still IN FLIGHT is allowed to proceed rather than queueing or replaying — retry after a response, not during one.\n- **Capabilities**: a pack/engine that cannot do something answers 501 with `{capability, pack, alternatives}` — never a wrong number." }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer" } }, "schemas": {} }, "paths": { "/health": { "get": { "responses": { "200": { "description": "Default Response" } } } }, "/sdk-demo": { "get": { "responses": { "200": { "description": "Default Response" } } } }, "/sdk/ledrapay-components.js": { "get": { "responses": { "200": { "description": "Default Response" } } } }, "/{*}": { "options": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "*", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/partners/tenants": { "post": { "summary": "Provision a tenant (employer) + engine binding under the calling partner", "tags": [ "partners" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "jurisdiction": { "type": "string", "enum": [ "AU", "DE", "NZ", "UK", "US" ], "description": "jurisdiction", "default": "AU" }, "engine": { "type": "string", "description": "engine to bind: payroll_engine_au (AU), payroll_engine (DE), myaccountant, mock (dev only)", "default": "mock" }, "pack_version": { "type": "string", "description": "pin a specific regulation-pack version (defaults to the pack current_version)" }, "connection_id": { "type": "string", "description": "cin_* governance-cell connection (required for myaccountant bindings)" }, "connector_pack": { "type": "string", "description": "connector pack backing the connection. Defaults to myaccountant_company — the per-customer pack, where the company is pinned on the connection and book-level operations are absent. Pass myaccountant_partner only for a legacy shared partner connection." }, "engine_tenant_ref": { "type": "string", "description": "existing engine-side tenant reference to bind to" } }, "required": [ "name" ], "additionalProperties": false } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tenant": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string", "description": "unique human handle (e.g. \"acme-labour-hire\"); usable anywhere :tenantId is" }, "name": { "type": "string" }, "jurisdiction": { "type": "string" }, "group": { "type": [ "null", "object" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string", "description": "quotable handle, e.g. \"health-and-beauty-group\"" }, "name": { "type": "string" } }, "additionalProperties": true, "description": "parent group this entity belongs to, or null when it stands alone" } }, "required": [ "id", "name" ], "additionalProperties": true }, "binding": { "type": "object", "additionalProperties": true, "description": "engine binding (id bnd_…, role hub|substrate, engine, pack_version, status, capabilities…)" } }, "required": [ "tenant", "binding" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "get": { "summary": "List the calling partner's tenants (paginated)", "tags": [ "partners" ], "parameters": [ { "schema": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 200 }, { "type": "string", "pattern": "^\\d{1,3}$" } ] }, "in": "query", "name": "limit", "required": false, "description": "page size, 1–200 (default 50)" }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "opaque cursor from a previous response" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string", "description": "unique human handle (e.g. \"acme-labour-hire\"); usable anywhere :tenantId is" }, "name": { "type": "string" }, "jurisdiction": { "type": "string" }, "group": { "type": [ "null", "object" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string", "description": "quotable handle, e.g. \"health-and-beauty-group\"" }, "name": { "type": "string" } }, "additionalProperties": true, "description": "parent group this entity belongs to, or null when it stands alone" } }, "required": [ "id", "name" ], "additionalProperties": true } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "null", "string" ], "description": "opaque cursor for the next page; null when has_more is false" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/partners/tenants/{tenantId}": { "get": { "summary": "Fetch one tenant with its engine bindings", "tags": [ "partners" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tenant": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string", "description": "unique human handle (e.g. \"acme-labour-hire\"); usable anywhere :tenantId is" }, "name": { "type": "string" }, "jurisdiction": { "type": "string" }, "group": { "type": [ "null", "object" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string", "description": "quotable handle, e.g. \"health-and-beauty-group\"" }, "name": { "type": "string" } }, "additionalProperties": true, "description": "parent group this entity belongs to, or null when it stands alone" } }, "required": [ "id", "name" ], "additionalProperties": true }, "bindings": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "engine binding (id bnd_…, role hub|substrate, engine, pack_version, status, capabilities…)" } } }, "required": [ "tenant", "bindings" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/packs": { "get": { "summary": "List the regulation-pack registry", "tags": [ "packs" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "jurisdiction": { "type": "string" }, "name": { "type": "string" }, "current_version": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/packs/{packCode}": { "get": { "summary": "Fetch one regulation pack by code", "tags": [ "packs" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "packCode", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "code": { "type": "string" }, "jurisdiction": { "type": "string" }, "name": { "type": "string" }, "current_version": { "type": "string" } }, "additionalProperties": true } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/packs": { "get": { "summary": "List the tenant's active bindings with their pinned pack + capability matrix", "tags": [ "packs" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "active engine binding + the regulation pack it pins", "properties": { "binding_id": { "type": "string" }, "engine": { "type": "string" }, "role": { "type": "string" }, "pinned_version": { "type": "string" }, "pack": { "type": "object", "properties": { "code": { "type": "string" }, "jurisdiction": { "type": "string" }, "name": { "type": "string" }, "current_version": { "type": "string" } }, "additionalProperties": true }, "capabilities": { "type": [ "null", "object" ], "additionalProperties": true, "description": "capability matrix, or null when the engine adapter could not be constructed" }, "capability_basis": { "type": [ "null", "object" ], "additionalProperties": { "type": "string", "enum": [ "grant_verified", "grant_denied", "pack_only", "unknown" ] }, "description": "per-capability provenance: grant_verified (checked against the credential's actual scopes and covered), grant_denied (checked and NOT covered — the matrix may still read native while the system is in observe mode), pack_only (decided by the connector pack, no scope mapping exists), unknown (no grant recorded or it is stale — treat as unverified, not as available)" }, "capability_grant_state": { "type": [ "null", "string" ], "enum": [ "fresh", "stale", "absent", null ], "description": "freshness of the recorded grant behind capability_basis" } }, "additionalProperties": true } } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/employees": { "get": { "summary": "List employees (cursor-paginated; scoped users see only in-scope rows)", "tags": [ "employees" ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "as_of", "required": false, "description": "ISO date YYYY-MM-DD" }, { "schema": { "type": [ "integer", "string" ], "pattern": "^[0-9]+$" }, "in": "query", "name": "limit", "required": false, "description": "page size (default 50, max 200)" }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "opaque cursor from a previous response" }, { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "query", "name": "page", "required": false, "description": "legacy page number — ignored; use cursor" }, { "schema": { "type": "string" }, "in": "query", "name": "cost_centre", "required": false, "description": "filter to employees allocated to this cost-centre code (exact, or a parent prefix code-*)" }, { "schema": { "type": "string" }, "in": "query", "name": "site", "required": false, "description": "filter to employees at this site" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Canonical cross-country employee. Statutory fields are namespaced under statutory.au / statutory.de; raw PII (TFN, full bank numbers) NEVER appears — attested flags only.", "properties": { "id": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$", "description": "employee id (emp_<16 hex>)" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "terminated" ] }, "employment": { "type": "object", "additionalProperties": true, "description": "employment terms (type, annual_salary as 2dp string, start/end dates)" }, "statutory": { "type": "object", "properties": { "au": { "type": "object", "additionalProperties": true, "description": "AU statutory block (super fund attestation, tax attestations — never a raw TFN)" }, "de": { "type": "object", "additionalProperties": true, "description": "DE statutory block (Steuerklasse, social-insurance attestations)" } }, "additionalProperties": true }, "jurisdiction_data": { "type": "object", "additionalProperties": true, "description": "per-country extension fields captured by the tax/bank/pension forms" } }, "required": [ "id" ], "additionalProperties": true, "title": "ledrapay#employee" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "null", "string" ], "description": "opaque cursor for the next page; null when has_more is false" }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" }, "scope_not_enforceable": { "type": "boolean", "description": "true when a data-scoped caller listed against rows carrying no scope dimensions — the page is empty rather than leaky" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "post": { "summary": "Create an employee (governed write)", "tags": [ "employees" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "employment": { "type": "object", "additionalProperties": true, "description": "employment terms (type, annual_salary, pay_frequency, start/end dates)" }, "status": { "type": "string", "enum": [ "active", "terminated" ] }, "effective_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "effective-dated write (engines with native effective_dating only)" }, "jurisdiction_data": { "type": "object", "additionalProperties": true, "description": "per-country extension fields captured by the tax/bank/pension forms" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "required": [ "first_name", "last_name" ], "additionalProperties": { "type": [ "string", "number", "boolean", "object" ] } } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "as_of", "required": false, "description": "ISO date YYYY-MM-DD" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Canonical cross-country employee. Statutory fields are namespaced under statutory.au / statutory.de; raw PII (TFN, full bank numbers) NEVER appears — attested flags only.", "properties": { "id": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$", "description": "employee id (emp_<16 hex>)" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "terminated" ] }, "employment": { "type": "object", "additionalProperties": true, "description": "employment terms (type, annual_salary as 2dp string, start/end dates)" }, "statutory": { "type": "object", "properties": { "au": { "type": "object", "additionalProperties": true, "description": "AU statutory block (super fund attestation, tax attestations — never a raw TFN)" }, "de": { "type": "object", "additionalProperties": true, "description": "DE statutory block (Steuerklasse, social-insurance attestations)" } }, "additionalProperties": true }, "jurisdiction_data": { "type": "object", "additionalProperties": true, "description": "per-country extension fields captured by the tax/bank/pension forms" } }, "required": [ "id" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/employees/headcount": { "get": { "summary": "Headcount grouped by cost-centre or site", "tags": [ "employees" ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "as_of", "required": false, "description": "ISO date YYYY-MM-DD" }, { "schema": { "type": "string", "enum": [ "cost_centre", "site" ] }, "in": "query", "name": "group_by", "required": false, "description": "grouping dimension (default cost_centre)" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": [ "null", "string" ] }, "headcount": { "type": "integer" }, "sample": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "total": { "type": "integer" }, "evidence_id": { "type": [ "null", "string" ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/employees/{employeeId}": { "get": { "summary": "Get one employee (statutory fields attested, never raw PII)", "tags": [ "employees" ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "as_of", "required": false, "description": "ISO date YYYY-MM-DD" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "employeeId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Canonical cross-country employee. Statutory fields are namespaced under statutory.au / statutory.de; raw PII (TFN, full bank numbers) NEVER appears — attested flags only.", "properties": { "id": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$", "description": "employee id (emp_<16 hex>)" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "terminated" ] }, "employment": { "type": "object", "additionalProperties": true, "description": "employment terms (type, annual_salary as 2dp string, start/end dates)" }, "statutory": { "type": "object", "properties": { "au": { "type": "object", "additionalProperties": true, "description": "AU statutory block (super fund attestation, tax attestations — never a raw TFN)" }, "de": { "type": "object", "additionalProperties": true, "description": "DE statutory block (Steuerklasse, social-insurance attestations)" } }, "additionalProperties": true }, "jurisdiction_data": { "type": "object", "additionalProperties": true, "description": "per-country extension fields captured by the tax/bank/pension forms" } }, "required": [ "id" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "patch": { "summary": "Update an employee (governed write)", "tags": [ "employees" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "employment": { "type": "object", "additionalProperties": true, "description": "employment terms (type, annual_salary, pay_frequency, start/end dates)" }, "status": { "type": "string", "enum": [ "active", "terminated" ] }, "effective_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "effective-dated write (engines with native effective_dating only)" }, "jurisdiction_data": { "type": "object", "additionalProperties": true, "description": "per-country extension fields captured by the tax/bank/pension forms" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "required": [], "additionalProperties": { "type": [ "string", "number", "boolean", "object" ] } } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "as_of", "required": false, "description": "ISO date YYYY-MM-DD" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "employeeId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Canonical cross-country employee. Statutory fields are namespaced under statutory.au / statutory.de; raw PII (TFN, full bank numbers) NEVER appears — attested flags only.", "properties": { "id": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$", "description": "employee id (emp_<16 hex>)" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "terminated" ] }, "employment": { "type": "object", "additionalProperties": true, "description": "employment terms (type, annual_salary as 2dp string, start/end dates)" }, "statutory": { "type": "object", "properties": { "au": { "type": "object", "additionalProperties": true, "description": "AU statutory block (super fund attestation, tax attestations — never a raw TFN)" }, "de": { "type": "object", "additionalProperties": true, "description": "DE statutory block (Steuerklasse, social-insurance attestations)" } }, "additionalProperties": true }, "jurisdiction_data": { "type": "object", "additionalProperties": true, "description": "per-country extension fields captured by the tax/bank/pension forms" } }, "required": [ "id" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Terminate an employee (hard soft-delete, irreversible via the API)", "tags": [ "employees" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "employeeId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Canonical cross-country employee. Statutory fields are namespaced under statutory.au / statutory.de; raw PII (TFN, full bank numbers) NEVER appears — attested flags only.", "properties": { "id": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$", "description": "employee id (emp_<16 hex>)" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "terminated" ] }, "employment": { "type": "object", "additionalProperties": true, "description": "employment terms (type, annual_salary as 2dp string, start/end dates)" }, "statutory": { "type": "object", "properties": { "au": { "type": "object", "additionalProperties": true, "description": "AU statutory block (super fund attestation, tax attestations — never a raw TFN)" }, "de": { "type": "object", "additionalProperties": true, "description": "DE statutory block (Steuerklasse, social-insurance attestations)" } }, "additionalProperties": true }, "jurisdiction_data": { "type": "object", "additionalProperties": true, "description": "per-country extension fields captured by the tax/bank/pension forms" } }, "required": [ "id" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/employees/{employeeId}/end-employment": { "post": { "summary": "End employment by date (reversible offboard)", "tags": [ "employees" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "effective_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "end date (defaults to today; a future date schedules a leaver)" }, "reason_code": { "type": "string", "description": "optional STP cessation reason code" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "employeeId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Canonical cross-country employee. Statutory fields are namespaced under statutory.au / statutory.de; raw PII (TFN, full bank numbers) NEVER appears — attested flags only.", "properties": { "id": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$", "description": "employee id (emp_<16 hex>)" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "terminated" ] }, "employment": { "type": "object", "additionalProperties": true, "description": "employment terms (type, annual_salary as 2dp string, start/end dates)" }, "statutory": { "type": "object", "properties": { "au": { "type": "object", "additionalProperties": true, "description": "AU statutory block (super fund attestation, tax attestations — never a raw TFN)" }, "de": { "type": "object", "additionalProperties": true, "description": "DE statutory block (Steuerklasse, social-insurance attestations)" } }, "additionalProperties": true }, "jurisdiction_data": { "type": "object", "additionalProperties": true, "description": "per-country extension fields captured by the tax/bank/pension forms" } }, "required": [ "id" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/employees/{employeeId}/reactivate": { "post": { "summary": "Reactivate an end-dated employee", "tags": [ "employees" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "employeeId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Canonical cross-country employee. Statutory fields are namespaced under statutory.au / statutory.de; raw PII (TFN, full bank numbers) NEVER appears — attested flags only.", "properties": { "id": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$", "description": "employee id (emp_<16 hex>)" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "terminated" ] }, "employment": { "type": "object", "additionalProperties": true, "description": "employment terms (type, annual_salary as 2dp string, start/end dates)" }, "statutory": { "type": "object", "properties": { "au": { "type": "object", "additionalProperties": true, "description": "AU statutory block (super fund attestation, tax attestations — never a raw TFN)" }, "de": { "type": "object", "additionalProperties": true, "description": "DE statutory block (Steuerklasse, social-insurance attestations)" } }, "additionalProperties": true }, "jurisdiction_data": { "type": "object", "additionalProperties": true, "description": "per-country extension fields captured by the tax/bank/pension forms" } }, "required": [ "id" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/employees/{employeeId}/tax-settings": { "get": { "summary": "Read an employee's tax settings section", "tags": [ "employees" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "employeeId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "tax section as the engine holds it (attested flags, never raw PII)" }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "patch": { "summary": "Save an employee's tax settings (flat form fields; governed write)", "tags": [ "employees" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "flat tax form fields; PII fields become inline attestations, the rest flow to jurisdiction_data..tax", "properties": { "tfn": { "type": "string", "description": "PII — transmitted as an inline attestation, never stored raw" }, "country": { "type": "string", "description": "jurisdiction code for the write (defaults 'au'); lowercased server-side" }, "employee_type": { "type": "string", "description": "engine employee type (tax metadata; defaults 'Employee')" }, "effective_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "effective-dated write (engines with native effective_dating only)" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": { "type": [ "string", "number", "boolean" ] } } } }, "description": "flat tax form fields; PII fields become inline attestations, the rest flow to jurisdiction_data..tax" }, "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "as_of", "required": false, "description": "ISO date YYYY-MM-DD" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "employeeId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Canonical cross-country employee. Statutory fields are namespaced under statutory.au / statutory.de; raw PII (TFN, full bank numbers) NEVER appears — attested flags only.", "properties": { "id": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$", "description": "employee id (emp_<16 hex>)" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "terminated" ] }, "employment": { "type": "object", "additionalProperties": true, "description": "employment terms (type, annual_salary as 2dp string, start/end dates)" }, "statutory": { "type": "object", "properties": { "au": { "type": "object", "additionalProperties": true, "description": "AU statutory block (super fund attestation, tax attestations — never a raw TFN)" }, "de": { "type": "object", "additionalProperties": true, "description": "DE statutory block (Steuerklasse, social-insurance attestations)" } }, "additionalProperties": true }, "jurisdiction_data": { "type": "object", "additionalProperties": true, "description": "per-country extension fields captured by the tax/bank/pension forms" } }, "required": [ "id" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/employees/{employeeId}/bank-accounts": { "get": { "summary": "Read an employee's bank details section", "tags": [ "employees" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "employeeId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "bank section as the engine holds it (attested flags, never raw account numbers)" }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "patch": { "summary": "Save an employee's bank details (flat form fields; governed write)", "tags": [ "employees" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "flat bank form fields; PII fields become inline attestations, the rest flow to jurisdiction_data..bank", "properties": { "bank_bsb": { "type": "string", "description": "PII — transmitted as an inline attestation, never stored raw" }, "bank_account_number": { "type": "string", "description": "PII — transmitted as an inline attestation, never stored raw" }, "bank_account_name": { "type": "string", "description": "PII — transmitted as an inline attestation, never stored raw" }, "country": { "type": "string", "description": "jurisdiction code for the write (defaults 'au'); lowercased server-side" }, "employee_type": { "type": "string", "description": "engine employee type (tax metadata; defaults 'Employee')" }, "effective_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "effective-dated write (engines with native effective_dating only)" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": { "type": [ "string", "number", "boolean" ] } } } }, "description": "flat bank form fields; PII fields become inline attestations, the rest flow to jurisdiction_data..bank" }, "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "as_of", "required": false, "description": "ISO date YYYY-MM-DD" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "employeeId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Canonical cross-country employee. Statutory fields are namespaced under statutory.au / statutory.de; raw PII (TFN, full bank numbers) NEVER appears — attested flags only.", "properties": { "id": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$", "description": "employee id (emp_<16 hex>)" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "terminated" ] }, "employment": { "type": "object", "additionalProperties": true, "description": "employment terms (type, annual_salary as 2dp string, start/end dates)" }, "statutory": { "type": "object", "properties": { "au": { "type": "object", "additionalProperties": true, "description": "AU statutory block (super fund attestation, tax attestations — never a raw TFN)" }, "de": { "type": "object", "additionalProperties": true, "description": "DE statutory block (Steuerklasse, social-insurance attestations)" } }, "additionalProperties": true }, "jurisdiction_data": { "type": "object", "additionalProperties": true, "description": "per-country extension fields captured by the tax/bank/pension forms" } }, "required": [ "id" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/employees/{employeeId}/pension": { "get": { "summary": "Read an employee's super/pension section", "tags": [ "employees" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "employeeId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "super/pension section as the engine holds it" }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "patch": { "summary": "Save an employee's super/pension details (flat form fields; governed write)", "tags": [ "employees" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "flat super form fields; PII fields become inline attestations, the rest flow to jurisdiction_data..super", "properties": { "super_fund_name": { "type": "string", "description": "PII — transmitted as an inline attestation, never stored raw" }, "super_usi": { "type": "string", "description": "PII — transmitted as an inline attestation, never stored raw" }, "super_member_number": { "type": "string", "description": "PII — transmitted as an inline attestation, never stored raw" }, "smsf_account_name": { "type": "string", "description": "PII — transmitted as an inline attestation, never stored raw" }, "smsf_bsb": { "type": "string", "description": "PII — transmitted as an inline attestation, never stored raw" }, "smsf_account_number": { "type": "string", "description": "PII — transmitted as an inline attestation, never stored raw" }, "country": { "type": "string", "description": "jurisdiction code for the write (defaults 'au'); lowercased server-side" }, "employee_type": { "type": "string", "description": "engine employee type (tax metadata; defaults 'Employee')" }, "effective_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "effective-dated write (engines with native effective_dating only)" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": { "type": [ "string", "number", "boolean" ] } } } }, "description": "flat super form fields; PII fields become inline attestations, the rest flow to jurisdiction_data..super" }, "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "as_of", "required": false, "description": "ISO date YYYY-MM-DD" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "employeeId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Canonical cross-country employee. Statutory fields are namespaced under statutory.au / statutory.de; raw PII (TFN, full bank numbers) NEVER appears — attested flags only.", "properties": { "id": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$", "description": "employee id (emp_<16 hex>)" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "terminated" ] }, "employment": { "type": "object", "additionalProperties": true, "description": "employment terms (type, annual_salary as 2dp string, start/end dates)" }, "statutory": { "type": "object", "properties": { "au": { "type": "object", "additionalProperties": true, "description": "AU statutory block (super fund attestation, tax attestations — never a raw TFN)" }, "de": { "type": "object", "additionalProperties": true, "description": "DE statutory block (Steuerklasse, social-insurance attestations)" } }, "additionalProperties": true }, "jurisdiction_data": { "type": "object", "additionalProperties": true, "description": "per-country extension fields captured by the tax/bank/pension forms" } }, "required": [ "id" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/employees/{employeeId}/readiness": { "get": { "summary": "Per-tab payroll readiness (verdicts only, never field values)", "tags": [ "employees" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "employeeId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "jurisdiction": { "type": "string" }, "tabs": { "type": "array", "items": { "type": "object", "properties": { "tab": { "type": "string" }, "complete": { "type": "boolean" }, "missing": { "type": "array", "items": { "type": "string" } }, "missing_required": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "reason": { "type": "string", "enum": [ "missing", "invalid" ] } }, "additionalProperties": true }, "description": "requirements we checked and found absent or malformed — these BLOCK finalisation" }, "unverifiable": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "reason": { "type": "string", "enum": [ "unverifiable" ] } }, "additionalProperties": true }, "description": "requirements the ENGINE CANNOT EXPOSE — no claim is made either way. They keep the tab from reading complete, and deliberately do NOT block finalisation: blocking on a fact the engine will never disclose would halt every employee on that engine indefinitely." }, "warnings": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true } }, "blocks_finalise": { "type": "boolean", "description": "true when a requirement was checked and found missing or invalid — never merely unproven" }, "unverified_requirements": { "type": "array", "items": { "type": "string" }, "description": "flattened tab.field list of requirements no check could settle, so a caller can see what \"complete\" is NOT covering" } }, "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/employees/{employeeId}/completeness": { "get": { "summary": "Per-tab payroll readiness (legacy alias of /readiness)", "tags": [ "employees" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "employeeId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "jurisdiction": { "type": "string" }, "tabs": { "type": "array", "items": { "type": "object", "properties": { "tab": { "type": "string" }, "complete": { "type": "boolean" }, "missing": { "type": "array", "items": { "type": "string" } }, "missing_required": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "reason": { "type": "string", "enum": [ "missing", "invalid" ] } }, "additionalProperties": true }, "description": "requirements we checked and found absent or malformed — these BLOCK finalisation" }, "unverifiable": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "reason": { "type": "string", "enum": [ "unverifiable" ] } }, "additionalProperties": true }, "description": "requirements the ENGINE CANNOT EXPOSE — no claim is made either way. They keep the tab from reading complete, and deliberately do NOT block finalisation: blocking on a fact the engine will never disclose would halt every employee on that engine indefinitely." }, "warnings": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true } }, "blocks_finalise": { "type": "boolean", "description": "true when a requirement was checked and found missing or invalid — never merely unproven" }, "unverified_requirements": { "type": "array", "items": { "type": "string" }, "description": "flattened tab.field list of requirements no check could settle, so a caller can see what \"complete\" is NOT covering" } }, "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-schedules": { "get": { "summary": "List pay schedules (the tenant's pay cycles)", "tags": [ "pay-runs" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "frequency": { "type": "string" }, "anchor_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "payment_offset_days": { "type": "integer" }, "status": { "type": "string" }, "next_period_start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "next_period_end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "post": { "summary": "Create a pay schedule (weekly/fortnightly/monthly cadence)", "tags": [ "pay-runs" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "frequency": { "type": "string", "enum": [ "weekly", "fortnightly", "monthly" ] }, "anchor_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "payment_offset_days": { "type": "integer", "minimum": 0, "maximum": 30 }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "required": [ "name", "frequency", "anchor_date" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "frequency": { "type": "string" }, "anchor_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "payment_offset_days": { "type": "integer" }, "status": { "type": "string" }, "next_period_start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "next_period_end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "additionalProperties": false }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-schedules/{scheduleId}": { "patch": { "summary": "Update a pay schedule (rename / pause / resume / re-anchor)", "tags": [ "pay-runs" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "anchor_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "payment_offset_days": { "type": "integer", "minimum": 0, "maximum": 30 }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "scheduleId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "frequency": { "type": "string" }, "anchor_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "payment_offset_days": { "type": "integer" }, "status": { "type": "string" }, "next_period_start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "next_period_end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "additionalProperties": false }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Delete a pay schedule (runs it already generated are unaffected)", "tags": [ "pay-runs" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "scheduleId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": false }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-schedules/{scheduleId}/generate-run": { "post": { "summary": "Generate the next pay run from a schedule (advances the cadence)", "tags": [ "pay-runs" ], "requestBody": { "content": { "application/json": { "schema": { "type": [ "object", "null" ], "properties": { "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "scheduleId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "pay_run": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "regular", "adhoc", "reversal" ] }, "status": { "type": "string", "enum": [ "draft", "previewed", "approved", "finalised", "lodged", "voided" ] }, "period_start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "period_end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "payment_date": { "type": [ "null", "string" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "source": { "type": "string", "enum": [ "ledra", "engine", "merged" ], "description": "which system of record this row came from" }, "engine_status": { "type": "string", "description": "the engine-native status when source is engine/merged" }, "totals": { "type": [ "null", "object" ], "additionalProperties": true, "description": "run totals (null until previewed): employee_count int, gross/net/tax 2dp strings, statutory.{au.super,de.social}, currency, provenance" } }, "required": [ "id", "status" ], "additionalProperties": true, "title": "ledrapay#pay-run" }, "schedule": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "frequency": { "type": "string" }, "anchor_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "payment_offset_days": { "type": "integer" }, "status": { "type": "string" }, "next_period_start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "next_period_end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "additionalProperties": false }, "matched_employees": { "type": "integer" }, "total_employees": { "type": "integer" } }, "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-runs": { "post": { "summary": "Create a draft pay run", "tags": [ "pay-runs" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "regular", "adhoc", "reversal" ] }, "period_start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "period_end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "payment_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "required": [ "period_start", "period_end" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "regular", "adhoc", "reversal" ] }, "status": { "type": "string", "enum": [ "draft", "previewed", "approved", "finalised", "lodged", "voided" ] }, "period_start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "period_end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "payment_date": { "type": [ "null", "string" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "source": { "type": "string", "enum": [ "ledra", "engine", "merged" ], "description": "which system of record this row came from" }, "engine_status": { "type": "string", "description": "the engine-native status when source is engine/merged" }, "totals": { "type": [ "null", "object" ], "additionalProperties": true, "description": "run totals (null until previewed): employee_count int, gross/net/tax 2dp strings, statutory.{au.super,de.social}, currency, provenance" } }, "required": [ "id", "status" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "get": { "summary": "List pay runs (engine-primary merge of engine runs + Ledra-governed run_index)", "tags": [ "pay-runs" ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d+$" }, "in": "query", "name": "limit", "required": false, "description": "page size (1–200, default 50)" }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "opaque cursor from a previous response" }, { "schema": { "type": "string", "enum": [ "draft", "previewed", "approved", "finalised", "lodged", "voided", "deleted" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "regular", "adhoc", "reversal" ] }, "status": { "type": "string", "enum": [ "draft", "previewed", "approved", "finalised", "lodged", "voided" ] }, "period_start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "period_end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "payment_date": { "type": [ "null", "string" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "source": { "type": "string", "enum": [ "ledra", "engine", "merged" ], "description": "which system of record this row came from" }, "engine_status": { "type": "string", "description": "the engine-native status when source is engine/merged" }, "totals": { "type": [ "null", "object" ], "additionalProperties": true, "description": "run totals (null until previewed): employee_count int, gross/net/tax 2dp strings, statutory.{au.super,de.social}, currency, provenance" } }, "required": [ "id", "status" ], "additionalProperties": true } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "null", "string" ], "description": "opaque cursor for the next page; null when has_more is false" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-runs/{payRunId}": { "get": { "summary": "Get one pay run (Ledra-governed or engine-native pr_eng_ id)", "tags": [ "pay-runs" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "regular", "adhoc", "reversal" ] }, "status": { "type": "string", "enum": [ "draft", "previewed", "approved", "finalised", "lodged", "voided" ] }, "period_start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "period_end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "payment_date": { "type": [ "null", "string" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "source": { "type": "string", "enum": [ "ledra", "engine", "merged" ], "description": "which system of record this row came from" }, "engine_status": { "type": "string", "description": "the engine-native status when source is engine/merged" }, "totals": { "type": [ "null", "object" ], "additionalProperties": true, "description": "run totals (null until previewed): employee_count int, gross/net/tax 2dp strings, statutory.{au.super,de.social}, currency, provenance" } }, "required": [ "id", "status" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Delete a draft/previewed run (engine delete; run_index row marked deleted)", "tags": [ "pay-runs" ], "requestBody": { "content": { "application/json": { "schema": { "type": [ "object", "null" ], "properties": { "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-runs/{payRunId}/exceptions": { "get": { "summary": "Governed R2P exceptions for a run (block/warn/info findings + verdict + freshness)", "tags": [ "pay-runs" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "findings": { "type": "array", "items": { "type": "object", "properties": { "worker_id": { "type": "string" }, "worker_name": { "type": "string" }, "severity": { "type": "string", "enum": [ "block", "warn", "info" ] }, "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } }, "summary": { "type": "object", "properties": { "workers": { "type": "integer" }, "blocks": { "type": "integer" }, "warnings": { "type": "integer" }, "infos": { "type": "integer" }, "verdict": { "type": "string", "enum": [ "do_not_run", "review", "clean" ] } }, "additionalProperties": true }, "source": { "type": "string" }, "source_freshness": { "type": "object", "additionalProperties": true, "description": "per-source watermark map (sync-recon #390)" }, "freshness": { "type": "object", "additionalProperties": true, "description": "run-level freshness aggregate (sync-recon #400)" } }, "required": [ "findings", "summary" ], "additionalProperties": true } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-runs/{payRunId}/entries/{entryId}/adjust": { "post": { "summary": "Governed pay-item adjustment for one entry (preview verdict or committed write)", "tags": [ "pay-runs" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "preview", "commit" ], "description": "preview = zero-write verdict; commit = governed write" }, "adjustments": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "pay_item_type_id": { "type": "string" }, "code": { "type": "string" }, "type": { "type": "string" }, "amount": { "type": [ "string", "number" ] }, "quantity": { "type": [ "string", "number" ] }, "rate": { "type": [ "string", "number" ] }, "note": { "type": "string" } }, "additionalProperties": true } }, "ack": { "type": "boolean" }, "rule_ref": { "type": "string", "description": "the R2P control this adjustment resolves (e.g. R2P-5)" }, "control_id": { "type": "string", "description": "alias for rule_ref" }, "before_gross": { "type": [ "string", "number" ] }, "expected_gross": { "type": [ "string", "number" ] }, "thresholds": { "type": "object", "additionalProperties": true, "description": "R2P threshold scaffold inputs (profile auto-resolve is a server-side TODO)" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "required": [ "adjustments" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "entryId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "governed-adjustment result — platform verdict (pass / needs_ack / block), per-item outcomes, evidence refs" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-runs/{payRunId}/adjust/bulk": { "post": { "summary": "Governed bulk adjustment (selector → action, expanded and gated server-side)", "tags": [ "pay-runs" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "preview", "commit" ], "description": "preview = zero-write verdict; commit = governed write" }, "selector": { "type": "object", "description": "match spec — expanded server-side against the run's authoritative pay_items", "properties": { "employee_ids": { "type": "array", "items": { "type": "string" } }, "pay_item_type_id": { "type": "string" }, "code": { "type": "string" }, "classification": { "type": "string" } }, "additionalProperties": true }, "action": { "type": "object", "description": "what to apply to each matched item", "properties": { "op": { "type": "string" }, "type": { "type": "string" }, "pay_item_type_id": { "type": "string" }, "amount": { "type": [ "string", "number" ] }, "quantity": { "type": [ "string", "number" ] } }, "additionalProperties": true }, "ack": { "type": "boolean" }, "rule_ref": { "type": "string" }, "control_id": { "type": "string" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "required": [ "selector", "action" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "governed-adjustment result — platform verdict (pass / needs_ack / block), per-item outcomes, evidence refs" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-runs/{payRunId}/entries": { "get": { "summary": "List the entries (one per employee) on a run", "tags": [ "pay-runs" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "One employee line on a run. Core fields flat + jurisdiction-neutral; pack-variant extras under statutory.{au,de} (additive, never required).", "properties": { "id": { "type": "string" }, "employee_id": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$", "description": "employee id (emp_<16 hex>)" }, "employee_name": { "type": "string" }, "gross": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "decimal string, always 2dp (never a JSON number)" }, "tax": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "decimal string, always 2dp (never a JSON number)" }, "net": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "decimal string, always 2dp (never a JSON number)" }, "statutory": { "type": "object", "properties": { "au": { "type": "object", "properties": { "super": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "decimal string, always 2dp (never a JSON number) (optional)" } }, "additionalProperties": true }, "de": { "type": "object", "properties": { "social": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "decimal string, always 2dp (never a JSON number) (optional)" }, "wage_types": { "type": "array" } }, "additionalProperties": true } }, "additionalProperties": true }, "pay_items": { "type": "array", "description": "per-line pay items when the engine exposes them" } }, "required": [ "id", "employee_id", "gross", "tax", "net" ], "additionalProperties": true, "title": "ledrapay#entry" } }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "post": { "summary": "Add an employee entry to a draft run", "tags": [ "pay-runs" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "employee_id": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$", "description": "employee id (emp_<16 hex>)" }, "pay_items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "pay-item line (name / hours / rate / amount…)" } }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "pay-item line (adapter-native alias of pay_items)" } }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "required": [ "employee_id" ], "additionalProperties": true } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-runs/{payRunId}/entries/{entryId}": { "patch": { "summary": "Edit an entry's pay items on a draft/previewed run", "tags": [ "pay-runs" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "pay_items": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": true, "description": "pay-item edit — pay_item_type_id, quantity, amount (+ engine-specific fields, forwarded)" } }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": true } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "entryId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Remove an entry from a draft run", "tags": [ "pay-runs" ], "requestBody": { "content": { "application/json": { "schema": { "type": [ "object", "null" ], "properties": { "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "entryId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-runs/{payRunId}/preview": { "post": { "summary": "Preview a run (compute entries + totals; draft/previewed → previewed)", "tags": [ "pay-runs" ], "requestBody": { "content": { "application/json": { "schema": { "type": [ "object", "null" ], "properties": { "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "pay_run": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "regular", "adhoc", "reversal" ] }, "status": { "type": "string", "enum": [ "draft", "previewed", "approved", "finalised", "lodged", "voided" ] }, "period_start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "period_end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "payment_date": { "type": [ "null", "string" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "source": { "type": "string", "enum": [ "ledra", "engine", "merged" ], "description": "which system of record this row came from" }, "engine_status": { "type": "string", "description": "the engine-native status when source is engine/merged" }, "totals": { "type": [ "null", "object" ], "additionalProperties": true, "description": "run totals (null until previewed): employee_count int, gross/net/tax 2dp strings, statutory.{au.super,de.social}, currency, provenance" } }, "required": [ "id", "status" ], "additionalProperties": true }, "entries": { "type": [ "null", "array" ], "items": { "type": "object", "description": "One employee line on a run. Core fields flat + jurisdiction-neutral; pack-variant extras under statutory.{au,de} (additive, never required).", "properties": { "id": { "type": "string" }, "employee_id": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$", "description": "employee id (emp_<16 hex>)" }, "employee_name": { "type": "string" }, "gross": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "decimal string, always 2dp (never a JSON number)" }, "tax": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "decimal string, always 2dp (never a JSON number)" }, "net": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "decimal string, always 2dp (never a JSON number)" }, "statutory": { "type": "object", "properties": { "au": { "type": "object", "properties": { "super": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "decimal string, always 2dp (never a JSON number) (optional)" } }, "additionalProperties": true }, "de": { "type": "object", "properties": { "social": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "decimal string, always 2dp (never a JSON number) (optional)" }, "wage_types": { "type": "array" } }, "additionalProperties": true } }, "additionalProperties": true }, "pay_items": { "type": "array", "description": "per-line pay items when the engine exposes them" } }, "required": [ "id", "employee_id", "gross", "tax", "net" ], "additionalProperties": true } }, "validation": { "type": [ "null", "object" ], "additionalProperties": true } }, "required": [ "pay_run" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-runs/{payRunId}/approve": { "post": { "summary": "Approve a previewed run (control-plane transition; evidence envelope only)", "tags": [ "pay-runs" ], "requestBody": { "content": { "application/json": { "schema": { "type": [ "object", "null" ], "properties": { "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "regular", "adhoc", "reversal" ] }, "status": { "type": "string", "enum": [ "draft", "previewed", "approved", "finalised", "lodged", "voided" ] }, "period_start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "period_end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "payment_date": { "type": [ "null", "string" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "source": { "type": "string", "enum": [ "ledra", "engine", "merged" ], "description": "which system of record this row came from" }, "engine_status": { "type": "string", "description": "the engine-native status when source is engine/merged" }, "totals": { "type": [ "null", "object" ], "additionalProperties": true, "description": "run totals (null until previewed): employee_count int, gross/net/tax 2dp strings, statutory.{au.super,de.social}, currency, provenance" } }, "required": [ "id", "status" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-runs/{payRunId}/finalise": { "post": { "summary": "Finalise an approved run (engine commit; freezes the cost-centre allocation)", "tags": [ "pay-runs" ], "requestBody": { "content": { "application/json": { "schema": { "type": [ "object", "null" ], "properties": { "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "regular", "adhoc", "reversal" ] }, "status": { "type": "string", "enum": [ "draft", "previewed", "approved", "finalised", "lodged", "voided" ] }, "period_start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "period_end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "payment_date": { "type": [ "null", "string" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "source": { "type": "string", "enum": [ "ledra", "engine", "merged" ], "description": "which system of record this row came from" }, "engine_status": { "type": "string", "description": "the engine-native status when source is engine/merged" }, "totals": { "type": [ "null", "object" ], "additionalProperties": true, "description": "run totals (null until previewed): employee_count int, gross/net/tax 2dp strings, statutory.{au.super,de.social}, currency, provenance" } }, "required": [ "id", "status" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-runs/{payRunId}/void": { "post": { "summary": "Void a run (terminal control-plane status; row stays, engine untouched)", "tags": [ "pay-runs" ], "requestBody": { "content": { "application/json": { "schema": { "type": [ "object", "null" ], "properties": { "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." }, "reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "alias for governance_reason (SDK void dialog sends { reason })" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "regular", "adhoc", "reversal" ] }, "status": { "type": "string", "enum": [ "draft", "previewed", "approved", "finalised", "lodged", "voided" ] }, "period_start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "period_end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "payment_date": { "type": [ "null", "string" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "source": { "type": "string", "enum": [ "ledra", "engine", "merged" ], "description": "which system of record this row came from" }, "engine_status": { "type": "string", "description": "the engine-native status when source is engine/merged" }, "totals": { "type": [ "null", "object" ], "additionalProperties": true, "description": "run totals (null until previewed): employee_count int, gross/net/tax 2dp strings, statutory.{au.super,de.social}, currency, provenance" } }, "required": [ "id", "status" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-runs/{payRunId}/clone": { "post": { "summary": "Clone a run into a new draft for a new period", "tags": [ "pay-runs" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "period_start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "period_end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "payment_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "as_reversal": { "type": "boolean" }, "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "pay_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "reversal": { "type": "boolean" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "anyOf": [ { "required": [ "period_start", "period_end" ] }, { "required": [ "start_date", "end_date" ] } ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "regular", "adhoc", "reversal" ] }, "status": { "type": "string", "enum": [ "draft", "previewed", "approved", "finalised", "lodged", "voided" ] }, "period_start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "period_end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "payment_date": { "type": [ "null", "string" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "source": { "type": "string", "enum": [ "ledra", "engine", "merged" ], "description": "which system of record this row came from" }, "engine_status": { "type": "string", "description": "the engine-native status when source is engine/merged" }, "totals": { "type": [ "null", "object" ], "additionalProperties": true, "description": "run totals (null until previewed): employee_count int, gross/net/tax 2dp strings, statutory.{au.super,de.social}, currency, provenance" } }, "required": [ "id", "status" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-runs/{payRunId}/payslips": { "get": { "summary": "List payslips for a run (post-preview/finalise; pinned tokens see only their own)", "tags": [ "pay-runs" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "employee_id": { "type": "string" }, "employee_name": { "type": "string" }, "gross": { "type": "string" }, "net": { "type": "string" }, "cost_centre": { "type": [ "null", "string" ] }, "lines": { "type": "array" }, "pdf": { "type": [ "null", "string" ] } }, "additionalProperties": true } }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-runs/{payRunId}/payment-file": { "get": { "summary": "Engine payment file (ABA) for a finalised run", "tags": [ "pay-runs" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "null", "object", "string" ], "description": "vendor payment-file payload — ABA file text or a structured object; null when the engine has no payment-file capability", "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-runs/{payRunId}/super": { "post": { "summary": "Create a super batch from a finalised run (SuperStream remittance is engine-side)", "tags": [ "pay-runs" ], "requestBody": { "content": { "application/json": { "schema": { "type": [ "object", "null" ], "properties": { "description": { "type": "string" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "null", "object" ], "additionalProperties": true, "description": "super batch record (engine shape)" }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-runs/{payRunId}/submit": { "post": { "summary": "Lodge STP to the ATO for a finalised run (signatory required)", "tags": [ "pay-runs" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "event_type": { "type": "string", "enum": [ "pay", "update" ] }, "submission_type": { "type": "string", "enum": [ "pay", "update" ], "description": "alias for event_type" }, "is_final": { "type": "boolean", "description": "marks the EOFY finalisation declaration" }, "signature_user": { "type": "string", "minLength": 1, "description": "ATO declaration signatory — full name" }, "signatory": { "type": "string", "minLength": 1, "description": "alias for signature_user" }, "signature_name": { "type": "string", "minLength": 1, "description": "alias for signature_user" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "anyOf": [ { "required": [ "signature_user" ] }, { "required": [ "signatory" ] }, { "required": [ "signature_name" ] } ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "statutory lodgement record (submission id, status, authority response)" }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-runs/{payRunId}/entries/{entryId}/set-payitem": { "post": { "summary": "Set one earnings line (hours + amount) on a draft-run employee — REPLACES any existing line of the same pay-item type", "tags": [ "pay-runs" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "pay_item_type_id": { "type": "string", "minLength": 1, "description": "company-specific pay-item type id (resolve from GET /pay-items — a free-text name will NOT resolve). One line per type per employee: re-setting the same type REPLACES the previous line." }, "quantity": { "type": [ "string", "number", "null" ], "description": "hours for the line" }, "amount": { "type": [ "string", "number", "null" ], "description": "RATE per unit for the line (engine multiplies by quantity: 38h x 30 -> 1140). Omitting it does NOT make the engine resolve a rate from the employee record — the line computes at 0." }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "required": [ "pay_item_type_id" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "entryId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-runs/{payRunId}/submissions": { "get": { "summary": "List STP submissions lodged for a run", "tags": [ "pay-runs" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "statutory lodgement record (submission id, status, authority response)" } }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-runs/{payRunId}/submissions/{submissionId}": { "get": { "summary": "Poll ATO lodgement status for one STP submission", "tags": [ "pay-runs" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "payRunId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "submissionId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "null", "object" ], "additionalProperties": true, "description": "statutory lodgement record (submission id, status, authority response)" }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/governance/evidence/{evidenceId}": { "get": { "summary": "Fetch one governed-evidence record", "tags": [ "governance" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "evidenceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "governed-evidence envelope (cev_ id, actor, operation, hash chain)" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/governance/audit-trail": { "get": { "summary": "Governance-plane audit events (paginated) + this tenant's run-level evidence refs", "tags": [ "governance" ], "parameters": [ { "schema": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 200 }, { "type": "string", "pattern": "^\\d{1,3}$" } ] }, "in": "query", "name": "limit", "required": false, "description": "page size, 1–200 (default 50)" }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "opaque cursor from a previous response" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "governance-plane audit event" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "null", "string" ], "description": "opaque cursor for the next page; null when has_more is false" }, "runs": { "type": "array", "items": { "type": "object", "description": "run-level evidence pointer", "properties": { "pay_run": { "type": "string" }, "status": { "type": "string" }, "evidence_refs": { "type": [ "null", "array" ], "items": { "type": "string" } }, "updated_at": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/governance/verify": { "post": { "summary": "Verify the tenant's evidence hash chain with the governance provider", "tags": [ "governance" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false, "description": "no body fields — send {}" } } }, "description": "no body fields — send {}" }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "provider chain-verification result: valid (boolean), length, broken_at?" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/calculate": { "post": { "summary": "Stateless gross-to-net calculation via the bound engine (capability-gated)", "tags": [ "calculate" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "calculation input, forwarded to the engine adapter. Expected fields: employee.annual_salary (number, required), plus jurisdiction extras such as employee.church_tax / employee.children (DE). Flat annual_salary/church_tax/children are also accepted." } } }, "description": "calculation input, forwarded to the engine adapter. Expected fields: employee.annual_salary (number, required), plus jurisdiction extras such as employee.church_tax / employee.children (DE). Flat annual_salary/church_tax/children are also accepted." }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "stateless calculation result", "properties": { "pack": { "type": "string" }, "gross": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "decimal string, always 2dp (never a JSON number)" }, "currency": { "type": "string" } }, "additionalProperties": true }, "net": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "decimal string, always 2dp (never a JSON number)" }, "currency": { "type": "string" } }, "additionalProperties": true }, "provenance": { "type": "string" } }, "required": [ "pack", "gross", "net", "provenance" ], "additionalProperties": true } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/calculate": { "post": { "summary": "Unbound stateless calculation — always 501 with the capability matrix (use the tenant-bound route)", "tags": [ "calculate" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "ignored — this endpoint always answers 501 CAPABILITY_NOT_SUPPORTED with alternatives" } } }, "description": "ignored — this endpoint always answers 501 CAPABILITY_NOT_SUPPORTED with alternatives" }, "responses": { "501": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/embed/token": { "post": { "summary": "Mint a short-lived embed token for SDK components (partner-key only)", "tags": [ "embed" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "components": { "type": "array", "items": { "type": "string" }, "description": "component allowlist, or [\"*\"] (default)" }, "employee_id": { "type": "string", "description": "pin the token to one employee (employee-facing surfaces)" }, "origin": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9+.-]*://[^/]+$", "description": "browser origin the token is bound to, e.g. https://app.example.com (scheme://host[:port], no path)" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "string" }, "expires_in": { "type": "integer", "description": "seconds until expiry" } }, "required": [ "token", "expires_in" ], "additionalProperties": true } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/users/token": { "post": { "summary": "Mint a user-scoped token (role + data scope) — partner key or admin delegation", "tags": [ "user-tokens" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "viewer", "preparer", "approver", "admin" ], "default": "viewer" }, "scope": { "type": "object", "properties": { "cost_centres": { "type": [ "string", "array" ], "items": { "type": "string" }, "description": "\"*\" for unrestricted, one code as a string, or an array of codes" }, "sites": { "type": [ "string", "array" ], "items": { "type": "string" }, "description": "\"*\" for unrestricted, one code as a string, or an array of codes" } }, "additionalProperties": false, "description": "data scope; omitted keys default to \"*\" (partner keys) / must stay within the delegating admin's own scope" }, "components": { "type": "array", "items": { "type": "string" }, "description": "component allowlist, or [\"*\"] (default)" }, "employee_id": { "type": "string", "description": "pin the token to one employee" }, "origin": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9+.-]*://[^/]+$", "description": "browser origin the token is bound to, e.g. https://app.example.com (scheme://host[:port], no path)" }, "user_id": { "type": "string" }, "user_name": { "type": "string" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "string" }, "expires_in": { "type": "integer", "description": "seconds until expiry" }, "role": { "type": "string", "enum": [ "viewer", "preparer", "approver", "admin" ] }, "scope": { "type": "object", "properties": { "cost_centres": { "type": [ "string", "array" ], "items": { "type": "string" }, "description": "\"*\" for unrestricted, one code as a string, or an array of codes" }, "sites": { "type": [ "string", "array" ], "items": { "type": "string" }, "description": "\"*\" for unrestricted, one code as a string, or an array of codes" } }, "additionalProperties": true } }, "required": [ "token", "expires_in", "role", "scope" ], "additionalProperties": true } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/projection/refresh": { "post": { "summary": "Refresh the resource projection from the engine (governed reads; evidence-stamped)", "tags": [ "projection" ], "requestBody": { "content": { "application/json": { "schema": { "type": [ "object", "null" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "projection summary: {at, source, resources:{type:count}, errors:{type:msg}}" }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/projection": { "get": { "summary": "Read the resource projection (no engine call) — resources by type, each with evidence_ref + projected_at", "tags": [ "projection" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "resources grouped by type; each row {plane, source, key, attrs, evidence_ref, projected_at, present}" }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/partners/portfolio/summary": { "get": { "summary": "Aggregate KPI stats across the partner's client tenants", "tags": [ "portfolio" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "stats": { "type": "object", "additionalProperties": true, "description": "portfolio KPIs: total_gross, active_workers, risk_flags, active_pay_runs, clients (numbers)" }, "tenant_count": { "type": "integer" }, "generated_at": { "type": "string", "description": "ISO 8601 timestamp" }, "errored_tenants": { "type": "array", "items": { "type": "string" } } }, "required": [ "stats", "tenant_count", "generated_at", "errored_tenants" ], "additionalProperties": true } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/partners/portfolio/pipeline": { "get": { "summary": "Pay-runs across the portfolio grouped by lifecycle (kanban)", "tags": [ "portfolio" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "draft": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "pipeline card: client_id/name, pay_run_id, status, period + payment dates, employee_count, total_gross, currency, risk" } }, "approved": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "pipeline card: client_id/name, pay_run_id, status, period + payment dates, employee_count, total_gross, currency, risk" } }, "blocked": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "pipeline card: client_id/name, pay_run_id, status, period + payment dates, employee_count, total_gross, currency, risk" } }, "finalised": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "pipeline card: client_id/name, pay_run_id, status, period + payment dates, employee_count, total_gross, currency, risk" } } }, "required": [ "draft", "approved", "blocked", "finalised" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/partners/portfolio/clients": { "get": { "summary": "Per-client status rows across the portfolio", "tags": [ "portfolio" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "per-client status row: id, name, country, site_count, workers, gross_mtd, currency, risk, health, in_flight, next_pay_date, days_until_pay" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/me": { "get": { "summary": "Caller context (mode, role, data scope, components, pinned employee)", "tags": [ "reference" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "caller context decoded from the token (no DB read) — backs the SDK scope-aware UX", "properties": { "mode": { "type": "string", "description": "token mode (e.g. 'user', 'embed'; partner keys report their mode)" }, "user": { "type": [ "null", "object" ], "properties": { "id": { "type": [ "null", "string" ] }, "name": { "type": [ "null", "string" ] } }, "additionalProperties": true, "description": "identity for user-mode tokens; null otherwise" }, "role": { "type": "string", "description": "RBAC role; partner keys / plain embed tokens report 'admin'" }, "scope": { "type": "object", "additionalProperties": true, "description": "data scope: cost_centres / sites — '*' or arrays of codes" }, "components": { "type": "array", "items": { "type": "string" }, "description": "embeddable-component allowlist; ['*'] = all" }, "employee_id": { "type": [ "null", "string" ], "description": "pinned employee for employee-pinned embed tokens" } }, "additionalProperties": true } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/reference/awards": { "get": { "summary": "Modern Award rate scales (kernel-sourced; read-only consumer view)", "tags": [ "reference" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "award rate scale (code, name, country, industry, levels[] with base/penalty rates)" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/company": { "get": { "summary": "Company / organisation details", "tags": [ "reference" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "null", "object" ], "additionalProperties": true, "description": "company/organisation details (engine-shaped)" }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/company/bank": { "get": { "summary": "Employer disbursement bank account", "tags": [ "reference" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "null", "object" ], "additionalProperties": true, "description": "employer disbursement account (engine-shaped: account name, BSB, account number…)" }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "patch": { "summary": "Set the employer disbursement bank account (governed write)", "tags": [ "reference" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "account_name": { "type": "string" }, "bsb": { "type": "string" }, "account_number": { "type": "string" }, "bank_name": { "type": "string" }, "fi_code": { "type": "string" }, "apca_user_id": { "type": "string" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": { "type": [ "string", "number", "boolean" ] } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "null", "object" ], "additionalProperties": true, "description": "engine write result" }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-item-types": { "get": { "summary": "L1 master pay-item type templates", "tags": [ "reference" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "L1 master pay-item type template (engine-shaped)" } }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-items": { "get": { "summary": "Company pay items (L2 canonical)", "tags": [ "reference" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "taxable": { "type": "boolean" }, "accrues_super": { "type": "boolean" }, "active": { "type": "boolean" }, "pay_item_type_id": { "type": [ "null", "string" ] } }, "required": [ "id", "name", "taxable", "accrues_super", "active" ], "additionalProperties": true } }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/reports/summary": { "get": { "summary": "Payroll activity summary (KPIs + per-cost-centre breakdown)", "tags": [ "reference" ], "parameters": [ { "schema": { "type": "string", "enum": [ "this_pay_run", "this_month", "this_quarter", "this_fy" ] }, "in": "query", "name": "period", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "null", "object" ], "additionalProperties": true, "description": "activity summary (gross/net/tax/super totals, pay_runs, by_cost_centre[] breakdown)" }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/reports/activity": { "get": { "summary": "Payroll activity time-series (trend charts)", "tags": [ "reference" ], "parameters": [ { "schema": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 200 }, { "type": "string", "pattern": "^\\d{1,3}$" } ] }, "in": "query", "name": "limit", "required": false, "description": "page size, 1–200 (default 50)" }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "opaque cursor from a previous response" }, { "schema": { "type": "string", "enum": [ "this_pay_run", "this_month", "this_quarter", "this_fy" ] }, "in": "query", "name": "period", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "activity period point (period_start/end, payment_date, status, gross/net/tax/super, currency, employee_count)" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "null", "string" ], "description": "opaque cursor for the next page; null when has_more is false" }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/superannuation/overview": { "get": { "summary": "Superannuation obligations overview for a financial year", "tags": [ "reference" ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}$" }, "in": "query", "name": "financialYear", "required": false, "description": "AU financial year END year (2026 = FY2025-26)" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "null", "object" ], "additionalProperties": true, "description": "super obligations overview (header, summary, per-employee rows)" }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/superannuation": { "get": { "summary": "List superannuation (SuperStream) batches", "tags": [ "reference" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "super batch (engine-shaped: id, description, period, totalAmount, status)" } }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/superannuation/{superId}/history": { "get": { "summary": "Status history for a super batch", "tags": [ "reference" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "superId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "status-history entry (engine-shaped)" } }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/superannuation/{superId}/status": { "patch": { "summary": "Transition a super batch's status (governed write)", "tags": [ "reference" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "minLength": 1, "description": "engine-native batch status (e.g. 'Lodged', 'Paid')" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "required": [ "status" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "superId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "null", "object" ], "additionalProperties": true, "description": "the transitioned batch (engine-shaped)" }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/pay-runs/{payRunId}/stp": { "get": { "summary": "STP lodgement history for a pay run", "tags": [ "reference" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "payRunId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "statutory lodgement record (submission id, status, authority response)" } }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/reference/leave-types": { "get": { "summary": "Leave-type catalogue (engine-sourced + statutory)", "tags": [ "reference" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string", "enum": [ "annual", "personal", "sick", "compassionate", "long_service", "family_domestic_violence", "community", "parental", "maternity", "short_time", "special", "unpaid", "cash_out", "other" ] }, "paid": { "type": "boolean" }, "unit": { "type": "string", "enum": [ "hours", "days" ] }, "source": { "type": "string", "enum": [ "engine", "statutory" ] } }, "required": [ "code", "name", "category", "paid", "unit", "source" ], "additionalProperties": true } }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "post": { "summary": "Create/assign a company leave type (governed write; AU only)", "tags": [ "reference" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "leave_type": { "type": "string", "description": "master leave type hint (typeCode or name, e.g. \"Annual Leave\")" }, "name": { "type": "string", "description": "alias hint for leave_type" }, "master_id": { "type": [ "string", "number" ], "description": "exact master pay-item type id (skips the hint lookup)" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "null", "object" ], "additionalProperties": true, "description": "created/assigned company leave type (id, name, master_id)" }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/leave-balances": { "get": { "summary": "Leave balances (accrued/taken/balance per employee per type)", "tags": [ "reference" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "employee_id": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$", "description": "employee id (emp_<16 hex>)" }, "employee_name": { "type": "string" }, "leave_type": { "type": "string" }, "accrued": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "decimal string, always 2dp (never a JSON number)" }, "taken": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "decimal string, always 2dp (never a JSON number)" }, "balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "decimal string, always 2dp (never a JSON number)" }, "unit": { "type": "string", "enum": [ "hours", "days" ] } }, "required": [ "employee_id", "employee_name", "leave_type", "accrued", "taken", "balance", "unit" ], "additionalProperties": true } }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/reference/regulation-catalogue": { "get": { "summary": "Full engine regulation case catalogue (pack authoring)", "tags": [ "reference" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "regulation case definition (name, fields, type-codes)" } }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" }, "note": { "type": [ "null", "string" ], "description": "adapter capability note (why the payload may be empty)" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/reference/case-fields": { "get": { "summary": "Per-case field definitions (pack authoring)", "tags": [ "reference" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "cases", "required": false, "description": "comma-separated case names (e.g. DE.MinijobGleitzone,DE.Einmalzahlungen)" }, { "schema": { "type": "string" }, "in": "query", "name": "case", "required": false, "description": "alias for cases" }, { "schema": { "type": "string" }, "in": "query", "name": "cluster", "required": false, "description": "engine cluster set name" }, { "schema": { "type": "string" }, "in": "query", "name": "clusterSetName", "required": false, "description": "alias for cluster" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "case name → field definitions map" }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" }, "note": { "type": [ "null", "string" ], "description": "adapter capability note (why the payload may be empty)" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/reference/case-detail": { "get": { "summary": "Single-case detail read (carries caseFields[])", "tags": [ "reference" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "cases", "required": false, "description": "comma-separated case names" }, { "schema": { "type": "string" }, "in": "query", "name": "case", "required": false, "description": "alias for cases" }, { "schema": { "type": "string" }, "in": "query", "name": "op", "required": false, "description": "override the executor op name" }, { "schema": { "type": "string" }, "in": "query", "name": "operation", "required": false, "description": "alias for op" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "case name → case detail map" }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" }, "note": { "type": [ "null", "string" ], "description": "adapter capability note (why the payload may be empty)" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/reference/case-values-scan": { "get": { "summary": "Learn case field names from live employee case values", "tags": [ "reference" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "cases", "required": false, "description": "comma-separated case names" }, { "schema": { "type": "string" }, "in": "query", "name": "case", "required": false, "description": "alias for cases" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "matches": { "type": "object", "additionalProperties": true, "description": "caseFieldName → observed live values" }, "all_case_fields": { "type": "array", "description": "every caseFieldName seen in the scan" }, "employees_scanned": { "type": "integer" } }, "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" }, "note": { "type": [ "null", "string" ], "description": "adapter capability note (why the payload may be empty)" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/leave/configure": { "post": { "summary": "Configure leave entitlements/accrual (governed write; AU only)", "tags": [ "reference" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "vendorId": { "type": [ "string", "number" ], "description": "engine employee ref the entitlement applies to" }, "accrual_method": { "type": "string", "description": "accrual method (default 'Monthly')" }, "annual_entitlement_hours": { "type": "number" }, "personal_entitlement_hours": { "type": "number" }, "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": { "type": [ "string", "number", "boolean" ] } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/leave/book": { "post": { "summary": "Book leave taken / a pay-affecting absence (governed write)", "tags": [ "reference" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "employee_id": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$", "description": "employee id (emp_<16 hex>)" }, "vendorId": { "type": [ "string", "number" ], "description": "legacy/explicit engine employee ref (prefer employee_id)" }, "payRunEmployeeId": { "type": [ "string", "number" ], "description": "legacy alias for vendorId" }, "leave_type": { "type": "string", "enum": [ "annual", "personal", "sick", "compassionate", "long_service", "family_domestic_violence", "community", "parental", "maternity", "short_time", "special", "unpaid", "cash_out", "other" ], "description": "canonical leave category" }, "category": { "type": "string", "description": "legacy loose label alias for leave_type (engine names/synonyms tolerated)" }, "leave_type_code": { "type": [ "string", "number" ], "description": "specific engine type code — disambiguates same-category types" }, "quantity": { "type": "number", "minimum": 0, "description": "hours (AU) | days (DE)" }, "hours": { "type": "number", "minimum": 0, "description": "legacy alias for quantity (unit=hours)" }, "days": { "type": "number", "minimum": 0, "description": "legacy alias for quantity (unit=days)" }, "unit": { "type": "string", "enum": [ "hours", "days" ] }, "start_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "end_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "pay_run_id": { "type": "string", "description": "AU: pin the target draft run (else discovered)" }, "amount": { "type": "number", "description": "AU: explicit line amount (defaults 0 — engine computes)" }, "effective_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "null", "object" ], "description": "The canonical booking receipt — identical across engines (AU pay-item line, DE absence case).", "properties": { "booked": { "type": "boolean", "enum": [ true ] }, "employee_id": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$", "description": "employee id (emp_<16 hex>)" }, "leave_type": { "type": "string", "enum": [ "annual", "personal", "sick", "compassionate", "long_service", "family_domestic_violence", "community", "parental", "maternity", "short_time", "special", "unpaid", "cash_out", "other" ] }, "unit": { "type": "string", "enum": [ "hours", "days" ] }, "quantity": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "decimal string, always 2dp (never a JSON number)" }, "start_date": { "type": [ "null", "string" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "end_date": { "type": [ "null", "string" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "evidence_id": { "type": "string" } }, "required": [ "booked", "employee_id", "leave_type", "unit", "quantity", "evidence_id" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/leave": { "get": { "summary": "Booked-leave history (leave taken)", "tags": [ "reference" ], "parameters": [ { "schema": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$" }, "in": "query", "name": "employee_id", "required": false, "description": "employee id (emp_<16 hex>)" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "engine handle (used to cancel/amend)" }, "employee_id": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$", "description": "employee id (emp_<16 hex>)" }, "employee_name": { "type": "string" }, "leave_type": { "type": "string", "enum": [ "annual", "personal", "sick", "compassionate", "long_service", "family_domestic_violence", "community", "parental", "maternity", "short_time", "special", "unpaid", "cash_out", "other" ] }, "unit": { "type": "string", "enum": [ "hours", "days" ] }, "quantity": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "decimal string, always 2dp (never a JSON number)" }, "start_date": { "type": [ "null", "string" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "end_date": { "type": [ "null", "string" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "status": { "type": "string", "enum": [ "booked", "cancelled" ] } }, "required": [ "id", "employee_id", "employee_name", "leave_type", "unit", "quantity", "status" ], "additionalProperties": true } }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/leave/{recordId}/cancel": { "post": { "summary": "Cancel a booked leave record (governed write)", "tags": [ "reference" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "pay_run_id": { "type": "string", "description": "AU: pin the target draft run (else discovered)" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "recordId", "required": true, "description": "engine handle from the leave-taken list" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "null", "object" ], "additionalProperties": true, "description": "cancellation result (id, status)" }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/leave/{recordId}/amend": { "post": { "summary": "Amend a booked leave record (governed write)", "tags": [ "reference" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "quantity": { "type": "number", "minimum": 0 }, "amount": { "type": "number", "description": "AU: explicit line amount" }, "start_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "end_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "pay_run_id": { "type": "string", "description": "AU: pin the target draft run (else discovered)" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "recordId", "required": true, "description": "engine handle from the leave-taken list" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "null", "object" ], "description": "The canonical booking receipt — identical across engines (AU pay-item line, DE absence case).", "properties": { "booked": { "type": "boolean", "enum": [ true ] }, "employee_id": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$", "description": "employee id (emp_<16 hex>)" }, "leave_type": { "type": "string", "enum": [ "annual", "personal", "sick", "compassionate", "long_service", "family_domestic_violence", "community", "parental", "maternity", "short_time", "special", "unpaid", "cash_out", "other" ] }, "unit": { "type": "string", "enum": [ "hours", "days" ] }, "quantity": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "description": "decimal string, always 2dp (never a JSON number)" }, "start_date": { "type": [ "null", "string" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "end_date": { "type": [ "null", "string" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "evidence_id": { "type": "string" } }, "required": [ "booked", "employee_id", "leave_type", "unit", "quantity", "evidence_id" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/leave/requests": { "post": { "summary": "Apply for leave (creates a pending control-plane request; no engine write)", "tags": [ "leave-requests" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "employee_id": { "type": "string", "minLength": 1 }, "leave_type": { "type": "string", "minLength": 1 }, "employee_name": { "type": "string" }, "start_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "end_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "ISO date YYYY-MM-DD" }, "quantity": { "type": "number" }, "unit": { "type": "string", "enum": [ "hours", "days" ] }, "reason": { "type": "string", "maxLength": 2000 } }, "required": [ "employee_id", "leave_type" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Control-plane leave request (never touches the engine until approved).", "properties": { "id": { "type": "string" }, "employee_id": { "type": "string" }, "employee_name": { "type": [ "null", "string" ] }, "leave_type": { "type": "string" }, "start_date": { "type": [ "null", "string" ] }, "end_date": { "type": [ "null", "string" ] }, "quantity": { "type": [ "null", "number" ] }, "unit": { "type": [ "null", "string" ] }, "reason": { "type": [ "null", "string" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "cancelled" ] }, "note": { "type": [ "null", "string" ] }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" }, "created_at": { "type": "string" }, "decided_at": { "type": [ "null", "string" ] } }, "required": [ "id", "employee_id", "leave_type", "status" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "get": { "summary": "List leave requests (status / employee filters, cursor-paginated)", "tags": [ "leave-requests" ], "parameters": [ { "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "cancelled" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "employee_id", "required": false }, { "schema": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 200 }, { "type": "string", "pattern": "^\\d{1,3}$" } ] }, "in": "query", "name": "limit", "required": false, "description": "page size, 1–200 (default 50)" }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "opaque cursor from a previous response" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Control-plane leave request (never touches the engine until approved).", "properties": { "id": { "type": "string" }, "employee_id": { "type": "string" }, "employee_name": { "type": [ "null", "string" ] }, "leave_type": { "type": "string" }, "start_date": { "type": [ "null", "string" ] }, "end_date": { "type": [ "null", "string" ] }, "quantity": { "type": [ "null", "number" ] }, "unit": { "type": [ "null", "string" ] }, "reason": { "type": [ "null", "string" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "cancelled" ] }, "note": { "type": [ "null", "string" ] }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" }, "created_at": { "type": "string" }, "decided_at": { "type": [ "null", "string" ] } }, "required": [ "id", "employee_id", "leave_type", "status" ], "additionalProperties": true } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "null", "string" ], "description": "opaque cursor for the next page; null when has_more is false" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/leave/requests/{id}": { "get": { "summary": "Get one leave request", "tags": [ "leave-requests" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true, "description": "leave-request id (req_…)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Control-plane leave request (never touches the engine until approved).", "properties": { "id": { "type": "string" }, "employee_id": { "type": "string" }, "employee_name": { "type": [ "null", "string" ] }, "leave_type": { "type": "string" }, "start_date": { "type": [ "null", "string" ] }, "end_date": { "type": [ "null", "string" ] }, "quantity": { "type": [ "null", "number" ] }, "unit": { "type": [ "null", "string" ] }, "reason": { "type": [ "null", "string" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "cancelled" ] }, "note": { "type": [ "null", "string" ] }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" }, "created_at": { "type": "string" }, "decided_at": { "type": [ "null", "string" ] } }, "required": [ "id", "employee_id", "leave_type", "status" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/leave/requests/{id}/approve": { "post": { "summary": "Approve a pending request (governed engine booking — reason required)", "tags": [ "leave-requests" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "maxLength": 500, "description": "decision note stored on the request" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true, "description": "leave-request id (req_…)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Control-plane leave request (never touches the engine until approved).", "properties": { "id": { "type": "string" }, "employee_id": { "type": "string" }, "employee_name": { "type": [ "null", "string" ] }, "leave_type": { "type": "string" }, "start_date": { "type": [ "null", "string" ] }, "end_date": { "type": [ "null", "string" ] }, "quantity": { "type": [ "null", "number" ] }, "unit": { "type": [ "null", "string" ] }, "reason": { "type": [ "null", "string" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "cancelled" ] }, "note": { "type": [ "null", "string" ] }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" }, "created_at": { "type": "string" }, "decided_at": { "type": [ "null", "string" ] } }, "required": [ "id", "employee_id", "leave_type", "status" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/leave/requests/{id}/reject": { "post": { "summary": "Reject a pending request (no engine write)", "tags": [ "leave-requests" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "maxLength": 500, "description": "decision note stored on the request" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true, "description": "leave-request id (req_…)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Control-plane leave request (never touches the engine until approved).", "properties": { "id": { "type": "string" }, "employee_id": { "type": "string" }, "employee_name": { "type": [ "null", "string" ] }, "leave_type": { "type": "string" }, "start_date": { "type": [ "null", "string" ] }, "end_date": { "type": [ "null", "string" ] }, "quantity": { "type": [ "null", "number" ] }, "unit": { "type": [ "null", "string" ] }, "reason": { "type": [ "null", "string" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "cancelled" ] }, "note": { "type": [ "null", "string" ] }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" }, "created_at": { "type": "string" }, "decided_at": { "type": [ "null", "string" ] } }, "required": [ "id", "employee_id", "leave_type", "status" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/leave/requests/{id}/cancel": { "post": { "summary": "Cancel (withdraw) a pending request (no engine write)", "tags": [ "leave-requests" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "maxLength": 500, "description": "withdrawal note stored on the request" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true, "description": "leave-request id (req_…)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Control-plane leave request (never touches the engine until approved).", "properties": { "id": { "type": "string" }, "employee_id": { "type": "string" }, "employee_name": { "type": [ "null", "string" ] }, "leave_type": { "type": "string" }, "start_date": { "type": [ "null", "string" ] }, "end_date": { "type": [ "null", "string" ] }, "quantity": { "type": [ "null", "number" ] }, "unit": { "type": [ "null", "string" ] }, "reason": { "type": [ "null", "string" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "cancelled" ] }, "note": { "type": [ "null", "string" ] }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" }, "created_at": { "type": "string" }, "decided_at": { "type": [ "null", "string" ] } }, "required": [ "id", "employee_id", "leave_type", "status" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/cost-centres": { "get": { "summary": "List cost centres (active by default)", "tags": [ "cost-centres" ], "parameters": [ { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "include_archived", "required": false, "description": "include archived cost centres" }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Z0-9][A-Z0-9-]*$", "description": "cost-centre code (UPPERCASE alphanumeric + dashes)" }, "name": { "type": "string" }, "parent_code": { "type": [ "null", "string" ] }, "gl_account": { "type": [ "null", "string" ] }, "site": { "type": [ "null", "string" ] }, "status": { "type": "string", "enum": [ "active", "archived" ] } }, "required": [ "code", "name" ], "additionalProperties": true } } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "post": { "summary": "Create a cost centre (governed — reason required)", "tags": [ "cost-centres" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Z0-9][A-Z0-9-]*$", "description": "cost-centre code (UPPERCASE alphanumeric + dashes)" }, "name": { "type": "string", "minLength": 1 }, "parent_code": { "type": [ "string", "null" ] }, "gl_account": { "type": [ "string", "null" ] }, "site": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "required": [ "code", "name" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Z0-9][A-Z0-9-]*$", "description": "cost-centre code (UPPERCASE alphanumeric + dashes)" }, "name": { "type": "string" }, "parent_code": { "type": [ "null", "string" ] }, "gl_account": { "type": [ "null", "string" ] }, "site": { "type": [ "null", "string" ] }, "status": { "type": "string", "enum": [ "active", "archived" ] } }, "required": [ "code", "name" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/cost-centres/{code}": { "patch": { "summary": "Update a cost centre (declared fields only; governed — reason required)", "tags": [ "cost-centres" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "parent_code": { "type": [ "string", "null" ] }, "gl_account": { "type": [ "string", "null" ] }, "site": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string", "pattern": "^[A-Z0-9][A-Z0-9-]*$" }, "in": "path", "name": "code", "required": true, "description": "cost-centre code (UPPERCASE alphanumeric + dashes)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Z0-9][A-Z0-9-]*$", "description": "cost-centre code (UPPERCASE alphanumeric + dashes)" }, "name": { "type": "string" }, "parent_code": { "type": [ "null", "string" ] }, "gl_account": { "type": [ "null", "string" ] }, "site": { "type": [ "null", "string" ] }, "status": { "type": "string", "enum": [ "active", "archived" ] } }, "required": [ "code", "name" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Archive a cost centre (governed — reason via x-governance-reason header)", "tags": [ "cost-centres" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string", "pattern": "^[A-Z0-9][A-Z0-9-]*$" }, "in": "path", "name": "code", "required": true, "description": "cost-centre code (UPPERCASE alphanumeric + dashes)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Z0-9][A-Z0-9-]*$", "description": "cost-centre code (UPPERCASE alphanumeric + dashes)" }, "status": { "type": "string", "enum": [ "archived" ] } }, "required": [ "code", "status" ], "additionalProperties": false }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/employees/{employeeId}/cost-centre": { "put": { "summary": "Assign an employee's primary cost centre (governed — reason required)", "tags": [ "cost-centres" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "cost_centre_code": { "type": "string", "pattern": "^[A-Z0-9][A-Z0-9-]*$", "description": "cost-centre code (UPPERCASE alphanumeric + dashes)" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "required": [ "cost_centre_code" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$" }, "in": "path", "name": "employeeId", "required": true, "description": "employee id (emp_<16 hex>)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "employee_id": { "type": "string" }, "cost_centre_code": { "type": "string", "pattern": "^[A-Z0-9][A-Z0-9-]*$", "description": "cost-centre code (UPPERCASE alphanumeric + dashes)" } }, "required": [ "employee_id", "cost_centre_code" ], "additionalProperties": false }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Clear an employee's cost-centre allocation (governed — reason via header)", "tags": [ "cost-centres" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string", "pattern": "^emp_[A-Za-z0-9_-]+$" }, "in": "path", "name": "employeeId", "required": true, "description": "employee id (emp_<16 hex>)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "employee_id": { "type": "string" }, "cost_centre_code": { "type": "null" } }, "required": [ "employee_id", "cost_centre_code" ], "additionalProperties": false }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/cost-centre-mappings": { "get": { "summary": "List attribute → cost-centre mapping rules", "tags": [ "cost-centres" ], "parameters": [ { "schema": { "type": "string", "enum": [ "employee", "pay_item" ] }, "in": "query", "name": "source", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "integer" ] }, "source": { "type": "string", "enum": [ "employee", "pay_item" ] }, "attribute": { "type": "string" }, "match_value": { "type": "string" }, "cost_centre_code": { "type": "string", "pattern": "^[A-Z0-9][A-Z0-9-]*$", "description": "cost-centre code (UPPERCASE alphanumeric + dashes)" }, "priority": { "type": "integer" } }, "required": [ "source", "attribute", "match_value", "cost_centre_code" ], "additionalProperties": true } } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "post": { "summary": "Create a mapping rule (governed — reason required)", "tags": [ "cost-centres" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "employee", "pay_item" ] }, "attribute": { "type": "string", "minLength": 1, "description": "dot-path on the entity (e.g. 'employment.type'); matched against match_value" }, "match_value": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "value to match; '*' is the catch-all" }, "cost_centre_code": { "type": "string", "pattern": "^[A-Z0-9][A-Z0-9-]*$", "description": "cost-centre code (UPPERCASE alphanumeric + dashes)" }, "priority": { "type": "integer", "minimum": 0, "default": 100, "description": "lower wins; rules evaluated priority-ordered" }, "governance_reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "why this write is happening — bound into the evidence actor. Alternatively supply the x-governance-reason header." } }, "required": [ "source", "attribute", "match_value", "cost_centre_code" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": [ "string", "integer" ] }, "source": { "type": "string", "enum": [ "employee", "pay_item" ] }, "attribute": { "type": "string" }, "match_value": { "type": "string" }, "cost_centre_code": { "type": "string", "pattern": "^[A-Z0-9][A-Z0-9-]*$", "description": "cost-centre code (UPPERCASE alphanumeric + dashes)" }, "priority": { "type": "integer" } }, "required": [ "source", "attribute", "match_value", "cost_centre_code" ], "additionalProperties": true }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tenants/{tenantId}/cost-centre-mappings/{id}": { "delete": { "summary": "Delete a mapping rule (governed — reason via x-governance-reason header)", "tags": [ "cost-centres" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "tenantId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true, "description": "mapping id (ccm_…)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ], "additionalProperties": false }, "evidence_id": { "type": [ "null", "string" ], "description": "governed-evidence id (cev_…); null when the governance provider recorded nothing" } }, "required": [ "data" ], "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "stable machine code (lower_snake; legacy exception: CAPABILITY_NOT_SUPPORTED)" }, "message": { "type": "string" }, "status": { "type": "integer" }, "errors": { "type": "array", "description": "field-level validation failures (400 bad_request only)", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } } } } }, "security": [ { "bearer": [] } ], "servers": [ { "url": "https://sandbox.ledrapay.com/v1", "description": "sandbox (same API, sandbox keys)" }, { "url": "https://api.ledrapay.com/v1", "description": "production" } ] }