Skip to main content

​
API 2.0.0: active contract required

POST /incidents requires a contract with status active. Status approved is insufficient. Without an active contract, the request fails with HTTP 422 and EMPLOYEE_HAS_NO_ACTIVE_CONTRACT, including when dryRun=true; no incident is created. Resolve the contract state through the responsible business process before submitting a new request with a new X-Request-ID. Existing incidents remain editable under their existing lifecycle and field restrictions. This new prerequisite applies to creation. The employee activation prerequisite remains documented separately; no precedence between validation errors is specified.

​
API 2.0.0: blocking changes and active contracts

For PATCH /employees/{id}, an active contract prohibits both blocked: true and blocked: false. If blocked is included, the API rejects the entire patch with HTTP 422 and EMPLOYEE_HAS_ACTIVE_CONTRACT, including when dryRun=true. Other fields in that rejected request are not applied. Sending the employee’s existing blocked value does not avoid this rule. For profile-only updates, omit blocked entirely. Configure serializers and synchronization mappings so they do not add blocked: false as a default. For example:
Do not retry an unchanged rejected patch. Resolve the blocking request through the responsible business process, or, for an independently intended profile update, send a new patch containing only the intended supported profile fields. A successful dry run does not reserve contract state; handle the same validation on the real write. Use this checklist before enabling an automated production schedule.

​
Access and secrets

  • A dedicated API key exists for this integration
  • The key name identifies system, purpose, and environment
  • The key has the least-privilege company and division scope
  • The key is stored in a managed secret store
  • The key is not present in source code, logs, tickets, or screenshots
  • A key rotation and emergency deactivation procedure has been tested

​
Request behavior

  • Every request has an explicit timeout
  • X-Request-ID is generated for each logical attempt and logged
  • X-Tenant-ID is supplied wherever placement would otherwise be ambiguous
  • Unknown fields are not sent
  • JSON requests use application/json
  • Attachment uploads use the documented multipart field, type, count, and size constraints

​
Synchronization correctness

  • Stable cross-system identifiers are stored
  • Pagination continues until the documented last page
  • A fixed filter window or checkpoint prevents accidental gaps
  • null, omitted properties, and empty strings are handled distinctly
  • New enum values and unknown response properties do not crash the client
  • Partial failures are recorded and can be resumed safely

​
Writes and retries

  • Supported writes are validated with dryRun=true where appropriate
  • Dry runs are not treated as reservations or a separate environment
  • POST and state-transition requests are never retried blindly after a timeout
  • Ambiguous write outcomes are reconciled by re-reading the resource
  • 409 and 422 are handled as business or validation outcomes, not transient failures
  • 429 honors Retry-After
  • Read retries use bounded exponential backoff and a retry budget

​
Observability

  • Logs include operation, HTTP status, error code, tenant context, and request ID
  • Logs exclude API keys and unnecessary personal data
  • Alerts exist for sustained authentication, authorization, validation, rate-limit, and 5xx failures
  • A dashboard or report shows synchronization checkpoints and unresolved records
  • The OpenAPI contract version used by the client is recorded

​
Operations and support

  • An owner is assigned for the integration
  • A runbook covers restart, rollback, key rotation, and incident response
  • Support requests include UTC time, method, path, status, error code, and request ID
  • Downloaded payroll and incident files are protected by appropriate local access controls
  • Retention and deletion rules are defined for local logs and files
  • The current Changelog and Capabilities and limitations have been reviewed
Passing this checklist does not replace customer-specific acceptance testing. Validate mappings, permissions, side effects, and downstream imports with the responsible business owners.
Last modified on October 20, 2026