Skip to main content
Version: v1

API V1

DSPTCH API public endpoints.

User-Agent required​

Every request must include a User-Agent header. Requests without one are rejected at the edge with a 403 before reaching the API. Any non-empty value works; ideally identify your integration (e.g. acme-payroll-sync/1.0) so traffic is attributable in support investigations.

PATCH semantics​

Unless an endpoint says otherwise, PATCH requests use merge-style update semantics:

  • Omitted fields are left unchanged.
  • Included scalar fields replace existing values.
  • Included array fields replace the entire existing array.
  • To clear an array, send an explicit empty array ([]).
  • To clear a nullable scalar field, send null when that field supports null values.

This means clients can safely send partial updates without unintentionally overwriting unrelated fields.

Examples​

Preserve manager assignments and timecodes while updating only a name:

{ "name": "Updated Job Name" }

Replace all managers on a job:

{ "manager_user_ids": ["user_123", "user_456"] }

Clear all managers on a job:

{ "manager_user_ids": [] }

Temporal resources​

Some resources are versioned instead of edited in place, so changes never destroy history. The API has two versioning flavors; each temporal resource's schema and tag description say which one applies. Most resources are neither — plain rows where updated_at is the only change signal.

Bitemporal resources — External Maps, Timecodes​

Bitemporal resources track two independent time dimensions on every version:

  • Valid time (valid_from / valid_to) — when the version is true in business reality. A change effective July 1 closes the prior version's valid time and starts a new version with valid_from = July 1, even if it was entered in June (a scheduled change) or August (a retroactive correction).
  • Transaction time (transaction_from / transaction_to) — when the version was recorded in DSPTCH. A correction closes the superseded version in transaction time and records the corrected one, preserving the full audit trail of what was believed when.

Every version of a resource shares one stable identity, exposed as bitemporal_id. The id field of a bitemporal resource always carries that same stable identity — never a per-version row id — so it is safe to store, safe to GET /{id}, and it is the value other resources hold to reference one (a Paystub Line Item's external_map_id is an External Map's bitemporal_id). Reads return the version that is currently valid and currently recorded: valid_from <= now < valid_to with open transaction time. Open-ended valid_to and transaction_to serialize as the far-future sentinel 9999-12-31T00:00:00.000000Z.

Unitemporal resources — Pay Schedules, User Companies​

Earlier versioned resources track a single time dimension: one valid_from/valid_to window per version and no transaction-time record of when changes were entered, so a retroactive correction rewrites history rather than layering on top of it. Their stable cross-version identity is a separate uid field — which is why other resources reference a Pay Schedule by pay_period_config_uid — and reads likewise return the currently-valid version.

Authentication​

Security Scheme Type:apiKey
Header parameter name:X-Api-Key