Developers

API v3 · Current

OPDC API Documentation

The OPDC API exposes secure, opinionated endpoints for working with Sage 100 Contractor data. v3 is the current contract, and this guide is the whole of it: authentication, one read contract, one error shape, maintenance locking, and the seven endpoints that write to Sage. The field-level reference is available at the bottom of the page.

Section 1

Getting started#

Every endpoint is a POST that takes JSON and returns JSON. Paths are resource-first and plural, and the whole API is two shapes plus a list of nouns: one read envelope, one write envelope, and one error body. Learn those three and the rest is field names.

If you have used v2

What v3 changes, in one box

Status codes mean what they say. responseType is gone. A business failure is a 4xx or a 5xx, so res.ok is a correct check and every HTTP client, proxy and retry library already understands the answer.
One error body. application/problem+json (RFC 9457) on every status, with a stable machine-matchable code. v2 mixed JSON with bare text/plain sentences depending on the status.
One read envelope and one write envelope. Every query returns {asOf, page, data}; every write returns the document plus its journal, job costs and inventory movements under the same keys. v2 had six write shapes across six endpoints.
Idempotency keys on writes. Retry a timed-out post with the same key and get the original response back instead of a second invoice.
Dry run. Add ?dryRun=true to any write to execute the whole cascade against live data inside a transaction that is rolled back, and see exactly what would have posted.
Unknown fields are rejected. A misspelled field is a 400 naming it, not a silent drop that hands you the unfiltered table.

v3 ships beside v2, not instead of it./api/v2 stays available as a frozen compatibility surface and is not deleted, so no existing integration has to move to keep working. Switch this page to v2 with the selector at the top if that is the surface you are on.

Migration checklist

Move one read at a time

Keep your existing /api/v2 client running while you add a v3 client beside it.
Change the path to /api/v3/{entity}/query and use the v3 resource name.
Translate page.count to page.totalCount; v3 page numbers start at 1.
Parse non-2xx responses as the documented problem body and log X-Correlation-Id.
Run both clients against the same filter and compare counts before switching traffic.

v2 is scheduled for removal in December 2026. New integrations should start on v3; existing integrations have time to migrate deliberately.

Base URL

https://{your-opdc-host}/api/v3

Your host is issued during onboarding. Endpoint paths in this guide are relative to this base URL.

Set your credentials

Put the host and API key in your shell once, then reuse them in the examples below. Keep the key in an environment variable or secret manager; never commit it to source control.

# macOS / Linux
export OPDC_HOST="https://{your-opdc-host}"
export OPDC_API_KEY="{your-api-key}"

# PowerShell
$env:OPDC_HOST = "https://{your-opdc-host}"
$env:OPDC_API_KEY = "{your-api-key}"

Headers

Header	Required	Notes
x-api-key	Yes	Your API key, a UUID. Missing, non-UUID and unrecognised keys all return 401 UNAUTHORIZED.
Content-Type	Yes	application/json
Idempotency-Key	Writes	Up to 128 printable characters, unique per logical write. Required on /purchase-order-receipts, recommended on the other six. See section 5.
traceparent	No	W3C trace context. Propagated to the on-premise service and into the server logs for the request. Most tracing SDKs send it for you.

v2's bespoke correlation headers are gone.x-context-id and x-integration-id are not part of v3. Send the W3C standard traceparent instead, which most HTTP clients and tracing SDKs already emit for you. Every response, including the ones that never reach a handler, carries X-Correlation-Id; quote that one token when you raise a ticket.

Your first call

The cheapest proof that your key works and that your Sage data is reachable is a one-row query. Any of the entities in section 2 will do.

{ "select": ["partCode", "partName"], "page": { "pageSize": 1 } }

Response

{
  "asOf": "2026-08-09T09:14:02Z",
  "page": { "pageNumber": 1, "pageSize": 1, "totalCount": 4182, "returnedCount": 1 },
  "data": [
    { "id": "3f9c...-uuid", "recordNumber": 4471,
      "partCode": "PIPE-001", "partName": "PVC Pipe 4\"" }
  ]
}

page.totalCount is the number of rows matching your filter, so a query with no filter tells you how large the entity is in one call.

Then add a real filter

Once the connection works, select only the fields you need and narrow the result with a filter. This example finds two part codes whose cost is at least 10, newest changes first.

{
  "select": ["partCode", "partName", "partCost"],
  "filters": {
    "and": [
      { "match": { "field": "partCode", "operator": "IN", "values": ["PIPE-001", "VALVE-200"] } },
      { "match": { "field": "partCost", "operator": ">=", "value": 10 } }
    ]
  },
  "orderBy": ["partCost DESC"],
  "page": { "pageNumber": 1, "pageSize": 25 },
  "lastUpdated": "2026-01-15"
}

Response

{
  "asOf": "2026-08-09T09:14:02Z",
  "page": { "pageNumber": 1, "pageSize": 25, "totalCount": 2, "returnedCount": 2 },
  "data": [
    { "id": "3f9c...-uuid", "recordNumber": 4471,
      "partCode": "PIPE-001", "partName": "PVC Pipe 4\"", "partCost": 12.50 },
    { "id": "7a21...-uuid", "recordNumber": 4498,
      "partCode": "VALVE-200", "partName": "Ball Valve 1\"", "partCost": 18.75 }
  ]
}

Use data for the returned records, returnedCount for this page, and totalCount for the full match count.

Utility routes are available under v3

Ping, and the maintenance lock in section 4, are operator tooling rather than data entities, but v3 exposes them so a new integration can use one base URL. Call POST /api/v3/utility/ping with the same API key to measure the round trip to your on-premise service. Existing v2 clients may continue using their original utility paths.

Section 2

Reading: one contract, 82 entities#

Every readable entity answers the same two operations with the same request body and the same envelope. Only the objects inside data differ. Learn the contract here and you have learned the whole read surface.

Endpoints

POST/api/v3/{entities}/query

POST/api/v3/{entities}/match

Plural, resource-first, verb last: /parts/query, /jobs/query, /purchase-orders/query, /vendors/match. v2 spelled these /query/part, singular noun, verb first. A mistyped entity is now a 404 naming it, rather than an empty result set that looks exactly like an empty result set.

Request body: every field

{
  "select": ["partCode", "partName", "partCost"],
  "filters": {
    "and": [
      { "match": { "field": "partCode", "operator": "IN", "values": ["PIPE-001", "VALVE-200"] } },
      { "match": { "field": "partCost", "operator": ">=", "value": 10 } }
    ]
  },
  "orderBy": ["partCost DESC"],
  "page": { "pageNumber": 1, "pageSize": 25 },
  "lastUpdated": "2026-01-15"
}

Field	Behaviour
select	Fields to return. Omit for every field on the entity. Dotted paths (lines.extendedTotal) address child collections and are validated against the child model.
children	Child collections to include, by name. Replaces v2’s withChildren boolean; the valid values are enumerated per entity, so an unknown one is a 400 that lists them.
filters	A recursive boolean tree of and, or and match nodes. Omit it to return everything.
orderBy	Array of "field ASC\|DESC" clauses. The server always appends a unique tiebreak, so paging is stable even with no sort key.
page	pageNumber (1-indexed, default 1) and pageSize (default 100, maximum 1000). A pageSize above the maximum, or below 1, is rejected rather than clamped.
lastUpdated	YYYY-MM-DD. Rows whose modification date is at or after it, on the 7 entities that record one. 501 elsewhere.
createdSince	YYYY-MM-DD. Rows whose entered date is at or after it, on the 14 entities that record one. Finds new records; never finds edits to older ones.

Three v2 fields no longer exist and are rejected rather than ignored: withChildren (use children), offset (use page.pageNumber), and the legacy singular filter (use filters). selectFields is now select.

Response envelope

{
  "asOf": "2026-08-09T09:14:02Z",
  "page": { "pageNumber": 1, "pageSize": 25, "totalCount": 142, "returnedCount": 25 },
  "data": [
    { "id": "3f9c...-uuid", "recordNumber": 4471,
      "partCode": "PIPE-001", "partName": "PVC Pipe 4\"", "partCost": 12.50 }
  ]
  }

asOf is the server's clock at the moment the result set was produced, in UTC. Store it as the watermark for your next call: your own clock is not a safe watermark, and v2 gave you nowhere else to get one.

The v2 footgun is gone

Branch on the HTTP status. There is no `responseType`

v2 returned business failures as HTTP 200 with responseType: "ERROR" on reads, and HTTP 500 with the same envelope on writes, so a client that checked res.ok treated every business failure as a success on one side and as an infrastructure fault on the other. That page needed a full-width red warning to explain it.

v3 retires the field entirely. A 2xx means it worked. A 4xx means fix the request. A 5xx means the server or Sage failed. Every failure carries an RFC 9457 problem document, on every status, with the same keys.

The whole client

const res = await fetch(url, { method: "POST", headers, body })

if (!res.ok) {
  // application/problem+json, on every status, with the same keys.
  const p = await res.json()
  throw new Error(`${p.title}: ${p.detail} [${p.correlationId}]`)
}

const body = await res.json()
return body.data          // reads. Writes return the envelope itself.

Unknown fields are rejected, not dropped

A typo like selectFeilds is a 400 naming the offending field in errors[]. In v2 it was silently dropped, which left select unset and returned every field on the entity, a misspelled filters returned the unfiltered table with a 200. Both are now loud.

Pagination

pageNumber is 1-indexed: page 1 is the first page and page 2 is the second. The executor's zero-based offset is an internal implementation detail.
totalCount is the total number of matching rows; returnedCount is how many are in data on this response. v2 had one field called count that meant the first, and every integrator had to be told so.
The default page size is 100 and the maximum is 1000. Both are reported back on every response, so you can see what you got without knowing the server's defaults. A pageSize above the maximum is rejected, never clamped, a clamped request returns a tenth of what you asked for and no way to know it. pageSize: 0 is a 400, not "everything".
Paging is stable without an orderBy. The server always appends a unique tiebreak to whatever you supply, so orderBy is a prefix of the real ordering rather than the whole of it. In v2, paging a large entity without a sort key could hand you the same row twice and never hand you another.

Child collections: ask for the ones you want

v2 had withChildren: true, which meant "all of them" and never said what "all of them" was, the published spec documented six collections while seventeen were being returned at runtime. children is a list, and the valid values are enumerated per entity in the contract, so an unknown one is a 400 that tells you what is valid.

// POST /api/v3/purchase-orders/query
{
  "select": ["orderNumber", "vendorNumber", "lines.extendedTotal"],
  "children": ["lines"],
  "filters": { "match": { "field": "jobNumber", "operator": "=", "value": 1450 } },
  "page": { "pageNumber": 1, "pageSize": 25 }
}

The alias is lines on every parent but one: assemblies uses parts. It was not renamed, because that would break every live caller for a cosmetic gain; it is enumerated instead, which fixes the real problem.
Children are fetched with one query per relation over the parent page's ids, so there is no N+1. There is also no bound: a page of 100 purchase orders pulls every line of all 100. Ask only for the collections you need.
Dotted paths in select are validated but do not yet narrow the child rows.lines.extendedTotal is checked against the child model, a typo, or a path naming a collection you did not ask for, is a 400, and then the child rows come back with every field on them regardless. The contract is ahead of the query executor on this one field, and it is stated here rather than left to be discovered.
Children cannot be filtered.

Incremental sync: check that your entity supports a watermark

Sage keeps no modification timestamp on most of its tables, so there is no single "give me everything that changed" filter that works across all 82 entities. There are two fields instead, and each is honoured only on the entities whose table carries the column it needs. Send one to an entity that has no such column and the request is rejected with a 501 (CHANGE_STAMP_UNSUPPORTED) naming the field, rather than quietly returning everything, which is what v2 did, on all 79 of its entities, while its documentation called the field "the one to build incremental syncs on". The two fields are independent: an entity can support one and reject the other.

lastUpdated

Answers "what changed", including edits.

Filters on the date Sage rewrites whenever the row is edited. These are the only entities that have one.

Supported on 7

/parts, /vendor-part-prices, /budgets, /cost-to-completes, /hours-to-completes, /proposals, /units-completes

createdSince

Answers "what is new". Never reports an edit.

Filters on the date the record was entered, which Sage writes once and never revises. This is what the transaction tables carry instead of a modification date.

Supported on 14

/ledger-transactions, /ap-invoices, /ar-invoices, /purchase-orders, /subcontracts, /change-orders, /job-costs, /payroll-records, /service-inventories, /service-contracts, /equipment, /equipment-costs, /inventory-allocations, /inventory-histories

Both fields are dates, not timestamps. Every column behind them is a Sage date with no time of day, so v3 types them as YYYY-MM-DD rather than inventing a time that has no meaning. The comparison is inclusive, deliberately: a watermark re-delivers a row rather than skipping one. Expect the last batch again, and use an idempotency key on the writes you make from it.
createdSince is not a substitute for lastUpdated. Sage never rewrites the entered date, so an invoice raised last week and corrected today does not come back. If you need corrections on those entities, re-read a trailing window rather than trusting a watermark.
Pair either field with orderBy and asOf: store the server's asOf from a completed run and send it as the next run's watermark.

Resolving names? Use match, not LIKE

For a human-entered name, a vendor off an invoice, a job from a spreadsheet, do not reach for LIKE '%...%'. Use POST /api/v3/{entities}/match, available on clients, vendors, jobs, parts and employees. It scores candidates by Levenshtein edit distance against the fields you name, normalising both sides first, and returns everything within maxDistance closest-first with its distance attached.

{
  "matchString": "Acme Corp",
  "matchFields": ["vendorName", "shortName"],
  "select": ["recordNumber", "vendorName"],
  "maxDistance": 3
}

{
  "asOf": "2026-08-09T09:14:02Z",
  "data": [
    { "recordNumber": 124, "vendorName": "ACME CORPORATION", "distance": 2 }
  ]
}

All four fields are required, select, matchFields, matchString and maxDistance, which must be 1 or greater. v2 enforced the same rules and documented none of them, so the first call an integrator copied out of the documentation failed. filters is accepted as an optional pre-filter to narrow the candidate set before scoring. There is no page block on the response: matching has to score every candidate before it can rank them, so maxDistance is the bound.

Filter operators

Operator	Description	Value key	Notes
=	Equal to	value	Exact match.
!=	Not equal to	value	Compiles to SQL <>.
>	Greater than	value	Numeric or date fields.
<	Less than	value	Numeric or date fields.
>=	Greater than or equal	value	Inclusive lower bound.
<=	Less than or equal	value	Inclusive upper bound.
LIKE	Pattern match	value	Use % as the wildcard. For human-entered names, prefer match.
NOT LIKE	Negated pattern match	value	Excludes rows matching the pattern.
IN	Matches any value in a list	values	Takes the values array, not value.
inPairs	Matches any of a set of composite keys	fields + pairs	Different shape; see the example below.

Operators are case-insensitive. The query builder normalises case before matching, so like and LIKE are both accepted. Uppercase is a convention here, not a requirement.

IN takes values (an array) instead of value. Every other operator except inPairs takes a single field plus value.

inPairs: composite-key lookup

inPairs is the one operator with a different shape: it takes fields and pairs instead of field and value. Use it to fetch a set of rows by composite key in one round trip instead of N single-key queries. Each object in pairs must have a key for every name listed in fields.

{
  "match": {
    "operator": "inPairs",
    "fields": ["jobNumber", "costCode"],
    "pairs": [
      { "jobNumber": 1021, "costCode": 2.100 },
      { "jobNumber": 1044, "costCode": 3.100 }
    ]
  }
}

Nesting and / or

and and or nodes hold arrays of further nodes, so they nest to any depth. A leaf node is a match.

{
  "filters": {
    "and": [
      { "match": { "field": "jobNumber", "operator": "=", "value": 1021 } },
      { "or": [
          { "match": { "field": "costType", "operator": "=", "value": 1 } },
          { "match": { "field": "costType", "operator": "=", "value": 2 } }
        ]
      }
    ]
  }
}

Where field names come from

Field names in select, orderBy, matchFields and every match.field are the JSON names OPDC publishes, not the underlying Sage column names: partCode, not the cryptic column it maps to. OPDC translates them for you in both directions.

A name that does not exist on the entity is a 400 naming it in errors[], in v2 it was a 200 carrying an error envelope, which on a read is indistinguishable from an empty result. The full per-entity field lists live in the reference at the bottom of this page.

Some codes are per-company: read them, do not hardcode them

Most numeric codes in Sage are fixed by the product, and v3 publishes them as enumerations with their meanings attached. Three are not: they are configured per company, so the values in your customer's install may not match anyone else's. Query them rather than shipping constants.

Field	Read it from	Notes
costType	/cost-types/query	Sage presets 1 Material, 2 Labor, 3 Equipment, 4 Subcontract, 5 Other. Values 6 to 9 are defined by each company and differ between installs.
costCode	/cost-codes/query	Entirely company-defined, and decimal: 2.100 and 3.100 are ordinary values.
sourceNumber	/transaction-sources/query	The GL transaction source. Sage creates a standard set when the company is built, and sites can add their own above it.

Section 3

Errors: one shape, on every status#

Every data-read and write failure in v3 is application/problem+json (RFC 9457), on every route and every status code. v2 mixed JSON on some statuses with bare text/plain sentences on others, so a client that called JSON.parse unconditionally threw on the error path and lost the message. One shape, always parseable. The utility operations share their implementation with v2, but their v3 routes use this same problem serializer. Existing v2 clients retain the legacy body.

The problem document

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
X-Error-Code: PERIOD_CLOSED
X-Correlation-Id: 7d1c8e40-...

{
  "type":     "https://twinn.engineering/errors/period-closed",
  "title":    "Posting period is closed",
  "status":   422,
  "detail":   "transactionDate 2026-11-04 resolves to period 11/2026; the open period is 3/2026",
  "instance": "/api/v3/ledger-transactions",
  "errors":   [ { "field": "transactionDate", "code": "PERIOD_CLOSED" } ],
  "correlationId": "7d1c8e40-..."
}

Field	Meaning
type	A URI identifying the problem type. Stable and machine-matchable; the last segment is the error code.
title	Short, stable, human-readable summary. Does not vary between occurrences.
status	The HTTP status code, repeated in the body for clients that lose it.
detail	Human-readable detail for this occurrence. Names specifics, the date, the account, the two figures that did not agree.
instance	The request path.
errors[]	Present when specific input fields are to blame. Each entry is a JSON path (lines[2].debitAmount) plus its own code.
correlationId	The X-Correlation-Id of the request. Server errors are redacted before they reach you; this is the handle to the unredacted record. Quote it on a ticket.

The stable machine-readable part is the code at the end of type, which is also sent as the X-Error-Code response header. Codes are append-only: a code's spelling and meaning never change once published, and a failure mode that stops existing keeps its code reserved rather than having it reused. Branch on the code; do not pattern-match detail.

Statuses, and what to retry

Status	When	Retry?
`200`	It worked. Reads return the query envelope; writes return the write envelope.	n/a
`400`	The request is malformed: unreadable body, an unknown or misspelled field, a required field missing, a value outside its rule, an invalid Idempotency-Key.	No. Fix the request.
`401`	No x-api-key header, a key that is not a UUID, or a key the server does not recognise.	No. Fix the credential.
`404`	An unknown entity on a read, or a referenced record that does not exist on a write. New in v3: v2 had no 404 anywhere.	No.
`409`	An Idempotency-Key reused for a different request, a request with that key still in flight, or a transaction number already posted with different lines.	Only IDEMPOTENCY_KEY_IN_FLIGHT, after Retry-After.
`422`	Well-formed but not applicable: a closed posting period, an unbalanced journal, amounts that do not agree with their lines, a column this Sage build does not have.	No. The payload or the accounting state needs fixing.
`423`	The database is locked for maintenance. The body names the holder.	Yes. Honour Retry-After.
`429`	Rate limited. Reserved by the contract whether or not limits are enforced on your instance today.	Yes. Honour Retry-After.
`500`	An unexpected server-side failure. The message is redacted; the detail is in the server log under your correlationId.	Not blindly. Quote correlationId.
`501`	lastUpdated or createdSince on an entity that records no such date, or a posting path deliberately not wired up. The body names the field.	No.
`502`	Sage itself refused: a constraint, a deadlock, a permission, a dropped connection. The gateway is fine; the database said no.	Yes, with backoff. No Retry-After, there is no honest number.
`503`	The service is switched off for this API key, with the operator’s reason in the body.	Retry-After 300, but contact support.
`504`	The on-premise service did not answer in time. The outcome of a write is unknown.	Yes, with the same Idempotency-Key, never without one.

The full error code table

Code	Status	Meaning
Transport, auth and request
UNAUTHORIZED	401	API key missing, malformed or unknown.
FORBIDDEN	403	The key authenticated but is not permitted on this route.
SERVICE_DISABLED	503	The service is switched off for this key. Retry-After 300.
MAINTENANCE_LOCK	423	Operator-held maintenance lock; the holder is named. Retry-After 60.
LOCK_CONFLICT	409	Unlock attempted against a lock another user holds. Raised by the utility route.
REQUEST_INVALID	400	Body unreadable, empty, or carrying an unknown field. The offending names are in errors[].
HEADER_INVALID	400	A correlation header present but not a UUID.
FIELD_REQUIRED	400	A required input field was absent or empty.
FIELD_INVALID	400	A field is present but its value breaks the field’s rule, an enum member outside the declared set, a page size over the maximum, a broken invariant.
CHANGE_STAMP_UNSUPPORTED	501	lastUpdated or createdSince named on an entity with no such column.
NOT_IMPLEMENTED	501	A route or posting path that exists but is deliberately not wired up.
RECORD_NOT_FOUND	404	A referenced record does not exist. On a read, also the unknown-entity case.
Idempotency
IDEMPOTENCY_KEY_REUSED	409	The same key was already used for a different request, a different body, or a different route. Use a new key.
IDEMPOTENCY_KEY_IN_FLIGHT	409	A request with this key is still running. Retry-After 5.
IDEMPOTENCY_KEY_INVALID	400	The key is empty, over 128 characters, or carries non-printable characters, or is absent where it is required.
Ledger and period
PERIOD_CLOSED	422	The target period is beyond the ledger’s current period, or outside the postable window.
PERIOD_UNRESOLVED	422	The posting date resolves to no period or year at all.
LEDGER_SETUP_MISSING	422	No readable ledger setup row: the ledger is not set up, or the connected schema is not the intended one.
JOURNAL_UNBALANCED	422	Debits do not equal credits. The comparison is exact decimal arithmetic.
JOURNAL_EMPTY	422	A journal with no lines.
JOURNAL_LINE_INVALID	422	A line is missing something structural, typically an account.
LEDGER_ACCOUNT_UNKNOWN	422	An account number that does not exist in the chart of accounts.
DUPLICATE_TRANSACTION	409	A transaction number already posted with different lines. An identical replay is not an error, it returns the prior result.
Document-specific
SERVICE_INVOICE_NOT_POSTABLE	422	A service invoice whose status or totals do not permit a GL post.
PAYROLL_BATCH_EMPTY	422	A payroll batch carrying no checks.
PAYROLL_CHECK_INVALID	422	A check failed the arithmetic or pay-rate checks.
PAYROLL_EARNING_UNSUPPORTED	422	An earning whose payType is outside Sage’s 1-9.
PAYROLL_DEDUCTION_INVALID	422	A deduction with no calculation number, which would post to the GL but not the subledger.
Server and Sage
UPSTREAM_TIMEOUT	504	No reply from the on-premise service. On a write the outcome is unknown, this is the case Idempotency-Key exists for. Retry-After 30.
SAGE_SCHEMA_MISMATCH	422	A column or table this Sage build does not have. Schemas drift between installations.
SAGE_ERROR	502	Any other database-side failure: constraint, deadlock, permission, connection.
SCRIPT_FAILED	500	A posting script failed with nothing more specific to say. The detail is in the log under your correlationId.
SCRIPT_NOT_FOUND	500	A route with no posting script behind it. A deployment fault, never the caller’s.
RESPONSE_INVALID	500	The on-premise reply did not fit the expected envelope.
INTERNAL_ERROR	500	The default. Anything unclassified.

Retry policy in one paragraph

Retry 423, 502, 503 and 504 with backoff. Three of them carry Retry-After, so a client library can honour it without reading this page; 502 deliberately does not, because there is no honest number, a deadlock clears in milliseconds and a revoked permission never clears. Never retry 400, 401, 404, 422 or 501 unchanged: the request itself is what needs fixing. On a write, retry with the same Idempotency-Key, that is the whole reason the header exists, and a 504 means the outcome is genuinely unknown.

Section 4

Maintenance locking#

Some Sage maintenance, closing and rotating an accounting period, for instance, needs every other connection to the database gone. Locking is how an operator gets that, and it is why your integration will occasionally see a 423. The lock is set through the v3 utility routes, and it applies to every /api/v3 route.

The full flow

1
bill locks the database for maintenance
POST /api/v3/utility/lock
{ "userName": "bill" }
-> 200{ "status": "locked", "lockUser": "bill", "response": { ... } }
2
Every v3 call is rejected while the lock holds
Not just /parts/query shown here, every read and every write on /api/v3 fails the same way until the lock clears.
POST /api/v3/parts/query
-> 423{ "type": ".../maintenance-lock", "title": "Locked for maintenance", "detail": "Locked for maintenance by bill" } [problem+json, Retry-After: 60]
3
bill releases the lock when he's done
POST /api/v3/utility/un-lock
{ "userName": "bill" }
-> 200{ "status": "unlocked", "response": { ... } }
4
A different user can't release bill's lock by accident
ann is not the holder, so her un-lock is rejected. She has to explicitly opt in to override it.
POST /api/v3/utility/un-lock
{ "userName": "ann" }
-> 409locked by different user: bill (use override=true to force) [problem+json, same v3 error contract]
Retry with { "userName": "ann", "override": true } to force it through.

What a lock actually does

Locking disconnects every database connection the on-premise service is holding, so Sage can do exclusive work. It is a deliberate, operator-initiated action, not something the API does on its own.

Lock state is persistent

The lock is stored server-side, not held in memory, so it survives a restart of the on-premise service. A lock that is never released stays in force, so always pair a lock with an un-lock.

v3 tells your client how long to wait

The 423 is a problem document with MAINTENANCE_LOCK and a Retry-After header, so a standard retry library backs off correctly with no code from you. v2 documented the back-off in prose only.

Ownership is per API key

A lock is recorded against the API key that set it, together with the userName that took it out. Un-locking validates that holder and returns 409 if someone else has it, unless you pass "override": true.

Integrators: back off on 423, do not fail the batch

A 423 is not an error in your payload. It means an accountant is mid-maintenance and will be done in minutes. Treat it exactly like a 504: pause, honour Retry-After, and resume where you left off. Aborting a payroll or invoice batch because of a lock turns a two-minute maintenance window into a manual re-run.

Section 5

Writes#

Seven endpoints write to Sage. Each is a single transaction that cascades: you post a document, and OPDC creates the header, the lines, and every derived record Sage expects, ledger transactions, balance propagation, job costs, inventory movements. All seven return the same envelope, all seven accept an idempotency key, and all seven can be dry-run.

One write envelope, for all seven

v2 produced six different response shapes for the same five artefacts across six endpoints: the document was sometimes top-level and sometimes named, job costs were jobCosts[] on two endpoints and jobCost on another, and service inventory returned its ledger transaction twice. v3 returns this, every time:

HTTP/1.1 200 OK
Idempotency-Status: applied

{
  "document":          { ... },   // the document itself, with its lines
  "ledgerTransaction": { ... },   // absent when the document did not post
  "jobCosts":          [ ... ],   // always an array, empty when none
  "inventory":         [ ... ],   // always an array, empty when nothing moved
  "dryRun":            false,
  "period":            3,
  "year":              2026
}

Arrays are always arrays, and always present, empty rather than missing when the cascade produced nothing.
ledgerTransaction is absent, not null, when the document did not post to the general ledger.
period and year are always reported, because the server resolved them and you have no other way to learn where the document landed. (Service inventory is the one exception: a stored-only record posts nothing, so it resolves no period.)
The status is 200, not 201: there is no Location to send you, not every write creates (a receipt updates), and an idempotent replay is not a creation.

New in v3

`Idempotency-Key`: retry a write without wondering whether it committed

A 504 is a documented, retryable outcome, and without a key a caller cannot tell whether Sage committed. Send a unique key per logical write and the server stores it with its response for 24 hours, replaying that response on any repeat.

curl -X POST https://{your-opdc-host}/api/v3/ledger-transactions \
  -H "x-api-key: {your-api-key}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {your-unique-key}" \
  -d '{
  "transactionNumber": "JE-4401",
  "transactionDate": "2026-03-16",
  "enteredDate": "2026-03-16",
  "description": "March accrual - subcontractor retainage",
  "sourceNumber": 3,
  "lines": [
    { "lineNumber": 1, "ledgerAccount": 5025, "debitAmount": 4500.00 },
    { "lineNumber": 2, "ledgerAccount": 2100, "creditAmount": 4500.00 }
  ]
}'

The key is scoped to your API key. Two integrations at one customer that both mint keys from a natural identifier cannot collide with each other.
The route and the body are part of the fingerprint, not the key. The same key sent with a different body, or to a different endpoint, is a 409 IDEMPOTENCY_KEY_REUSED rather than a wrong-shaped replay. Re-serialising the same payload with different whitespace or key order is the same request.
What is stored is the response that was sent, if and only if the request reached Sage. A 422 or a 502 is stored too, so a caller who corrects the body must use a new key. Nothing decided before dispatch, an unknown field, a validation failure, burns the key, so the corrected retry just runs.
Replays are labelled. Idempotency-Status: applied on the first write, replayed when the body is a recording of an earlier response and nothing was written again, and unavailable when the store could not answer and the write went ahead un-deduplicated. That last one is told to you rather than only logged.
A concurrent duplicate is refused, not executed twice. 409 IDEMPOTENCY_KEY_IN_FLIGHT with a short Retry-After.
A 504 under a key is recorded as unknown, and replayed as unknown. Retrying does not hand you a second write. If the on-premise service answers later, that answer is recorded against the key and the next retry returns it.

It is required on /purchase-order-receipts and recommended everywhere else. A receipt's updateQuantity is added to what the line has already received, and nothing on the Sage side refuses a second identical receipt, so accepting a key-less receipt would publish a promise of replay safety that endpoint cannot keep. A request without one is refused with 400 IDEMPOTENCY_KEY_INVALID.

`?dryRun=true`: see what a post would do, against real data

The document is validated, the whole cascade executes against your live Sage data inside one transaction, the journal, the balance propagation, the job costs, the inventory movement, and then the transaction is rolled back. You get the same result body a real post would have returned, including the amounts and the accounts it would have touched, with "dryRun": true on it so a stored body can never be mistaken for a committed write.

Every identifier in a dry-run response is provisional and will never exist. recordNumber, id, the ledger transaction's record number: all real inside the transaction, all gone after it. Do not store them and do not use them to correlate a later real post.

Two things are still consumed. Ledger reference numbers come from a database sequence and identity columns from the tables themselves, and neither is transactional, a rolled-back transaction does not give them back, so a dry run leaves permanent gaps exactly as a genuinely failed post does. If gapless numbering matters to your auditors, do not dry-run in bulk against production. An Idempotency-Key sent with a dry run is ignored rather than rejected, and is never burned.

The posting period

By default OPDC derives the accounting period from a date field on the document, which one depends on the endpoint, and each card below names it, under your Sage ledger-setup policy. Three endpoints (/ledger-transactions, /ap-invoices, /inventory-allocations) also accept an explicit period and year pair and honour it when it is valid, rejecting it with a 422 when it is not. In v2 those fields were accepted, documented as ignored, and ignored.

A post that resolves to a period later than the open one is rejected (422 PERIOD_CLOSED), with a message naming both. A post that resolves to an earlier period is accepted and lands there, so a stale document date puts the entry somewhere you may not intend. Whichever period was used comes back on the response, every time.

Each card has its own link. Expand them all before using your browser's find, since the gotchas are the part worth searching.

What it creates in Sage

The AP invoice header and one line per entry in lines.
At status 1 (Open): a posted journal debiting each line’s expense account and crediting the AP control account your ledger setup names, with account, period and sub-account balance propagation.
One job cost per posting line when the header carries a jobNumber.
The due date and any early-pay discount, derived from the vendor’s payment terms unless you state a due date.

Posting period derived from enteredDate.

Minimal request body

{
  "userName": "bill",
  "invoiceNumber": "INV-10021",
  "description": "Flooring materials - job 1450",
  "vendorNumber": 201,
  "jobNumber": 1450,
  "invoiceDate": "2026-03-15",
  "enteredDate": "2026-03-15",
  "invoiceType": 1,
  "status": 1,
  "invoiceTotal": 1250.80,
  "subTotal": 1180.00,
  "invoiceAmount": 1250.80,
  "invoiceBalance": 1250.80,
  "invoiceNet": 1180.00,
  "lines": [
    {
      "lineNumber": 1,
      "partDescription": "SHAW CARPET 12FT ROLL",
      "lineQuantity": 40,
      "linePrice": 29.50,
      "extendedTotal": 1180.00,
      "accountNumber": 5100,
      "subAccountNumber": 11,
      "costCode": 2.100,
      "costType": 1
    },
    {
      "lineNumber": 2,
      "partDescription": "SALES TAX",
      "lineQuantity": 1,
      "linePrice": 70.80,
      "extendedTotal": 70.80,
      "accountNumber": 5990
    }
  ]
}

Response shape

{
  "document": {
    "id": "9c1f...-uuid", "recordNumber": 88213,
    "invoiceNumber": "INV-10021", "invoiceTotal": 1250.80,
    "dueDate": "2026-04-14", "discountDate": "2026-03-25", "discountAmount": 23.60,
    "lines": [ { "id": "...", "recordNumber": 41120, "lineNumber": 1, "extendedTotal": 1180.00 } ]
  },
  "ledgerTransaction": {
    "id": "...", "recordNumber": 55201, "transactionNumber": "INV-10021",
    "status": 1, "sourceNumber": 11,
    "lines": [
      { "lineNumber": 1, "ledgerAccount": 5100, "subAccount": 11, "debitAmount": 1180.00, "creditAmount": 0.00 },
      { "lineNumber": 2, "ledgerAccount": 5990, "debitAmount": 70.80, "creditAmount": 0.00 },
      { "lineNumber": 3, "ledgerAccount": 2000, "debitAmount": 0.00, "creditAmount": 1250.80 }
    ]
  },
  "jobCosts": [
    { "id": "...", "recordNumber": 66300, "jobNumber": 1450, "costCode": 2.100, "costAmount": 1180.00 },
    { "id": "...", "recordNumber": 66301, "jobNumber": 1450, "costCode": 1, "costAmount": 70.80 }
  ],
  "inventory": [],
  "dryRun": false,
  "period": 3,
  "year": 2026
}

Gotchas

status is the switch for the GL cascade. Only 1 (Open) posts a journal, propagates balances and writes job costs. At any other status the header and lines are stored and nothing else happens. Sage defines 1 Open as a record posted to the general ledger, which is why that is the gate: 1 Open, 2 Review, 3 Dispute are yours to set; Sage sets 4 Paid and 5 Void.
The header is reconciled against its lines before anything is written. invoiceTotal must equal the exact decimal sum of every line’s extendedTotal, and the comparison has no rounding tolerance. v2 stored the header total and credited AP with the sum of the lines without comparing them, so a mismatch surfaced months later as AP aging that would not tie to the trial balance.
There is no fallback AP control account. If ledger setup cannot be read the invoice is refused with 422 LEDGER_SETUP_MISSING. v2 posted the credit to a literal account 2000 in that case, which is a real liability to a real vendor booked against a guess.
Credit memos post. Every leg picks its debit or credit column from the sign, so a negative invoice posts as a clean reversal; v2 rejected it as unbalanced.
invoiceType is 1 Contract or 2 Memo. Contract means the invoice affects the job billing for the contract; Memo means it does not, which is what you want for deposits and bad debts. v2 documented these as "Standard" and "Credit memo", which are not Sage’s names and hid the job-billing effect.
A line with no accountNumber is still stored, posts no GL debit, and produces no job cost. v2 wrote job costs for those lines anyway, so job-cost detail over-reported against the GL.
costCode reaches the job cost, and it is decimal: 2.100 passes through as 2.100. v2 accepted the field and then wrote the literal 1 on every job cost.
A caller-supplied dueDate is honoured; omit it and the vendor’s payment terms decide, falling back to invoiceDate. period and year are honoured too when they form a valid pair. All three were ignored in v2.
partNumber on a line is the Sage part record number, not the alphanumeric part code. That code goes in alphaNumber.
No replay guard: this endpoint does not recognise a repeat from the invoice number, and will post the same invoice and journal twice quite happily. Send an Idempotency-Key.

What it creates in Sage

The ledger transaction header and one line per debit or credit.
Account, period and sub-account balance propagation for every account on the transaction, at status 1 only.
A job cost per entry in the optional jobCosts array.

Posting period derived from transactionDate.

Minimal request body

{
  "userName": "bill",
  "transactionNumber": "JE-4401",
  "transactionDate": "2026-03-16",
  "enteredDate": "2026-03-16",
  "description": "March accrual - subcontractor retainage",
  "status": 1,
  "sourceNumber": 3,
  "lines": [
    { "lineNumber": 1, "description": "Subcontract expense accrual",
      "ledgerAccount": 5025, "debitAmount": 4500.00 },
    { "lineNumber": 2, "description": "Accrued retainage payable",
      "ledgerAccount": 2100, "creditAmount": 4500.00 }
  ],
  "jobCosts": [
    { "jobNumber": 1450, "description": "Retainage accrual",
      "costCode": 3.100, "costType": 2, "costAmount": 4500.00 }
  ]
}

Response shape

{
  "document": {
    "id": "7ab3...-uuid", "recordNumber": 55202,
    "transactionNumber": "JE-4401", "status": 1, "sourceNumber": 3,
    "lines": [
      { "id": "...", "recordNumber": 91011, "lineNumber": 1,
        "ledgerAccount": 5025, "debitAmount": 4500.00, "creditAmount": 0.00 },
      { "id": "...", "recordNumber": 91012, "lineNumber": 2,
        "ledgerAccount": 2100, "debitAmount": 0.00, "creditAmount": 4500.00 }
    ]
  },
  "jobCosts": [ { "id": "...", "recordNumber": 66301, "jobNumber": 1450, "costAmount": 4500.00 } ],
  "inventory": [],
  "dryRun": false,
  "period": 3,
  "year": 2026
}

Gotchas

ledgerTransaction is always absent on this endpoint: the document is the journal, so returning it twice under two names would make one write read as two.
Omitting status now means 1 (Open), and the balances move. The contract always said so; v2 read an absent status as 0, which is not a member of the status set, and the posting engine only propagates balances at 1. A caller who left the field out exactly as the documentation invited got a journal on file with not one account moved, behind a 200 describing a complete posting.
Status decides whether balances move at all. 1 Open propagates; 2 Cleared is set by Sage during bank reconciliation; 3 Void cannot be set directly, void the record in Sage instead.
Total debits must equal total credits, and each line must carry exactly one of debitAmount or creditAmount greater than zero. Both zero, or both non-zero, is rejected. The comparison is exact decimal arithmetic.
sourceNumber is required and is refused rather than guessed. v2 defaulted it to 1, which is the source code for a GL cheque rather than a journal entry, so a journal could be filed under the wrong module and appear in the wrong report. Use 3 (Journal) for a journal entry, and query /transaction-sources for anything install-specific.
description is required and an empty one is refused. It is the field a person reads in Sage to tell one entry from another.
transactionNumber is caller-supplied and not checked for uniqueness, uniqueness is a property of a numbering discipline this service cannot see. Reusing one replays the prior post when the payload is identical, and is a 409 DUPLICATE_TRANSACTION when it is not.
This endpoint writes no AP or AR subledger record. A journal that credits the AP control account moves that account’s balance and creates no vendor invoice, so it will not appear in an aged-payables report.
period and year are optional and honoured when valid. Omit them and the period comes from transactionDate under your ledger-setup policy.

What it creates in Sage

The purchase order header and one line per entry in lines.
Nothing else. No journal, no job cost, no inventory movement, all of that happens on receipt.

Posting period derived from orderDate (reported, not enforced).

Minimal request body

{
  "userName": "bill",
  "orderNumber": "PO-88214",
  "vendorNumber": 201,
  "jobNumber": 1450,
  "orderDate": "2026-03-16",
  "description": "Oak flooring - Maple Street rebuild",
  "status": 1,
  "lines": [
    {
      "lineNumber": 1,
      "partRecordNumber": 9931,
      "partDescription": "Oak plank 3/4in",
      "lineQuantity": 120,
      "linePrice": 12.50,
      "extendedTotal": 1500.00,
      "accountNumber": 1200,
      "subAccountNumber": 11,
      "inventoryLocation": 2,
      "costCode": 3.100,
      "costType": 1
    },
    {
      "lineNumber": 2,
      "partDescription": "Delivery surcharge",
      "lineQuantity": 1,
      "linePrice": 85.00,
      "extendedTotal": 85.00,
      "accountNumber": 5100
    }
  ]
}

Response shape

{
  "document": {
    "id": "b104...-uuid", "recordNumber": 9001,
    "orderNumber": "PO-88214", "vendorNumber": 201, "jobNumber": 1450, "status": 1,
    "lines": [
      { "id": "...", "recordNumber": 9101, "lineNumber": 1,
        "partRecordNumber": 9931, "lineQuantity": 120, "linePrice": 12.50, "extendedTotal": 1500.00 }
    ]
  },
  "jobCosts": [],
  "inventory": [],
  "dryRun": false,
  "period": 3,
  "year": 2026
}

Gotchas

This endpoint had no working implementation before v3. In v2 it is a stub that refuses every call, and the v3 contract published a 501 on every call until the implementation landed. If you are working from an older copy of the contract, that is the difference.
It posts no general ledger entry, and that is the design rather than a gap. A purchase order is a commitment to buy: nothing has been delivered, nothing is owed, no stock has arrived and no cost has landed on a job. The accounting happens at /purchase-order-receipts.
It is the one write endpoint not gated on the open accounting period. Purchase orders are routinely dated forward, so an order dated six months out is accepted. period and year on the response are the fiscal period the order date falls in, reported rather than posted into.
A resubmission is safe, a collision is refused: an identical retry under the same order number returns the first result, and a reused order number with different lines is refused. Without that, a retry would raise a second order for the same goods and the receipts endpoint would have two orders to receive one delivery against.
Your arithmetic is authoritative. extendedTotal is stored as sent and the order subtotal is the sum of those figures; internal consistency between the lines and the total matters more than agreement with a rounding rule this service would have had to invent.
Tax cannot be expressed. There is no tax field, header or line, so the order total is pre-tax and the sales-tax column is zero. That is a gap in the request contract, and closing it means adding a field.
Several purchase-order total fields are deliberately left empty rather than derived, because nothing maintains them after creation.
inventoryLocation on a line records where the goods are intended to draw from. It moves no stock; the receipt reads it later.

What it creates in Sage

The received quantities accumulated onto the PO lines, and the PO header’s received value and status restated.
An AP invoice with one line per line received, always exactly one per receipt. The shipping number stands in for the vendor’s invoice number, because at receipt time nobody has one.
A posted journal: expense and inventory debits consolidated by account, one AP-control credit sub-accounted by the vendor, plus balance propagation.
Inventory movement for lines that carry a part and post to a dedicated-inventory account.
A job cost per direct-expense line when the receipt carries a jobNumber.

Posting period derived from transactionDate.

Minimal request body

{
  "userName": "bill",
  "purchaseOrderRecnum": 9001,
  "shippingNumber": "SHP-7741",
  "vendorNumber": 201,
  "jobNumber": 1450,
  "transactionDate": "2026-03-16",
  "description": "Receive PO-88214 shipment 1",
  "status": 1,
  "lines": [
    {
      "poLineId": "5c1f...-uuid",
      "lineNumber": 1,
      "updateQuantity": 40,
      "partNumber": 4471,
      "partDescription": "SHAW CARPET 12FT ROLL",
      "linePrice": 29.50,
      "accountNumber": 1200,
      "inventoryLocation": 11
    },
    {
      "poLineId": "9ab2...-uuid",
      "lineNumber": 2,
      "updateQuantity": 1,
      "partDescription": "Freight",
      "linePrice": 85.00,
      "accountNumber": 5100,
      "costCode": 8.300,
      "costType": 1
    }
  ]
}

Response shape

{
  "document": {
    "purchaseOrder": { "id": "...", "recordNumber": 9001, "status": 1, "receivedTotal": 1265.00 },
    "invoice": {
      "id": "...", "recordNumber": 88214, "invoiceTotal": 1265.00,
      "lines": [ { "lineNumber": 1, "quantity": 40.00, "linePrice": 29.50, "extendedTotal": 1180.00 } ]
    }
  },
  "ledgerTransaction": {
    "id": "...", "recordNumber": 55204, "sourceNumber": 13,
    "lines": [ { "lineNumber": 1, "ledgerAccount": 1200, "debitAmount": 1180.00, "creditAmount": 0.00 } ]
  },
  "jobCosts": [ { "id": "...", "recordNumber": 66302, "jobNumber": 1450, "costAmount": 85.00 } ],
  "inventory": [
    { "partNumber": 4471, "location": 11, "quantityAvailableDelta": 40.00,
      "quantityOnHandDelta": 40.00, "historyRecordNumber": 74110 }
  ],
  "dryRun": false,
  "period": 3,
  "year": 2026
}

Gotchas

Idempotency-Key is required here and optional on the other six. updateQuantity is added to what the line has already received, not set to it, and nothing on the Sage side refuses a second identical receipt, so a retry without a key silently inflates stock. A request without one is 400 IDEMPOTENCY_KEY_INVALID.
There is a second, independent protection: a replay guard on the natural key of purchase order plus shippingNumber. An identical resubmission under a fresh key returns the first result; the same shipping number with different lines is refused.
poLineId is the UUID of the existing PO line row, not a number you invent. Fetch them first with POST /api/v3/purchase-orders/query and children: ["lines"], then echo them back. v2’s parallel poLineIdRef field does not exist in v3; it was never read.
A poLineId that matches no PO line is silently skipped rather than rejected. Only lines that can be found are updated, and the response reports what was actually received, so reconcile the response against what you sent.
The AP credit is sub-accounted by the vendor, so the AP account’s sub-balances are a per-vendor payables ledger. v2 wrote sub-account 0 and silently flattened it, which surfaces at period close when AP aging stops tying out.
There is no fallback AP control account: an unreadable ledger setup is a refusal, not a post to a literal 2000.
status is the purchase order’s status after the receipt, and nothing in the cascade branches on it, it is written straight through. Sage’s six values are 1 Open, 2 Review, 3 Dispute, 4 Closed, 5 Void, 6 Master. There is no Partial and no Received status, whatever older documentation said.
Inventory is touched only for lines that have a partNumber and whose accountNumber is one of the dedicated inventory accounts in your ledger setup, which is a per-installation setting. An empty inventory[] means no line met that condition, not that the endpoint declined to report.
A ledger transaction is always generated, and always posted. There is no draft mode.
Job costs are coded from their own line, the request, then that line’s PO row, then the default. v2 coded every job cost from the first line on the purchase order, so historical job-cost coding on multi-cost-code POs differs.

What it creates in Sage

The allocation header and one line per entry in lines.
At status 3 or 4: an inventory-history row per line, and quantity updates at the source location (and at destinationLocation, for a transfer). Status 3 reduces available quantity; status 4 also reduces both on-hand columns.
Part master updates from the allocation cost.
One job cost for the whole allocation, when purpose is JOB_REQUISITION, status is 3 or 4 and a job number is present.

Posting period derived from transactionDate.

Minimal request body

{
  "userName": "bill",
  "purpose": "JOB_REQUISITION",
  "status": 4,
  "jobNumber": 1450,
  "phaseNumber": 2,
  "transactionDate": "2026-03-16",
  "description": "Carpet and adhesive to job 1450",
  "lines": [
    {
      "partNumber": 4471,
      "partDescription": "SHAW CARPET 12FT ROLL",
      "quantity": 60,
      "cost": 29.50,
      "total": 1770.00,
      "sourceLocation": 11,
      "debitAccount": 5100,
      "debitSubAccount": 11
    }
  ]
}

Response shape

{
  "document": {
    "id": "4d20...-uuid", "recordNumber": 77410,
    "status": 4, "purpose": "JOB_REQUISITION",
    "description": "Carpet and adhesive to job 1450",
    "lines": [
      { "id": "...", "recordNumber": 77411, "lineNumber": 1,
        "partRecordNumber": 4471, "quantity": 60.00, "cost": 29.50, "total": 1770.00,
        "sourceLocation": 11 }
    ]
  },
  "jobCosts": [ { "id": "...", "recordNumber": 66303, "jobNumber": 1450, "costAmount": 1770.00 } ],
  "inventory": [
    { "partNumber": 4471, "location": 11, "quantityAvailableDelta": -60.00,
      "quantityOnHandDelta": -60.00, "historyRecordNumber": 74111 }
  ],
  "dryRun": false,
  "period": 3,
  "year": 2026
}

Gotchas

purpose replaces v2’s hard-coded text value. In v2 a job cost was written only when description was exactly "To Requisition Stock to Job", a free-text field silently controlling an accounting cascade, and a relabelled dropdown once made a user ship stock they meant to cancel. purpose is required and enum-validated: JOB_REQUISITION, LOCATION_TRANSFER or OTHER. description is now free text with no behaviour.
This endpoint posts no general ledger journal. It still draws a ledger reference and stamps it on the header, the history row and the job cost, a reference pointing at a journal that does not exist. That behaviour is carried from the system it replaces, deliberately and visibly, pending a decision to either post the journal or stop stamping the reference.
Job costing is currently refused with 501 NOT_IMPLEMENTED, pending an accounting decision about where the job cost’s cost code comes from. That affects JOB_REQUISITION at status 3 or 4 only. Everything else is unaffected and stock still moves: LOCATION_TRANSFER and OTHER at any status, and any allocation at status 1 or 2.
debitAccount and debitSubAccount are written exactly as you send them. The contract always declared both; v2 ignored both and wrote a literal 5100 with the job department as the sub-account, silently, behind a success response.
Each line’s total is cross-checked against quantity × cost at the edge and a mismatch is a 422 naming both figures. v2 accepted every amount on trust.
status decides what moves. 1 Open and 2 Review record the allocation and move no stock at all; 3 Hold Stock reduces available quantity; 4 Shipped reduces available and both on-hand columns. Earlier v2 documentation called these draft, approved, delivered and invoiced, none of which is correct.
There is one job cost per allocation, not one per line, and its amount is the sum of all line totals.
Set destinationLocation to move stock between locations; leave it off to issue stock out of sourceLocation.
partNumber is the Sage part record number, and the part master fills in the descriptive fields you omit. Note the asymmetry with the read surface, which publishes the same value as partRecordNumber.

What it creates in Sage

The service inventory header and one line per entry in lines.
At status 1 (Open): a sales journal debiting the Service Receivables control account for the full total, crediting revenue per line and Sales Tax Payable for the tax, with balance propagation.
One job cost per line when the header names a job, with the amount recorded as both job cost and job billing.

Posting period derived from orderDate.

Minimal request body

{
  "userName": "bill",
  "orderNumber": "WO-88",
  "invoiceNumber": "SVC-2201",
  "clientNumber": 305,
  "jobNumber": 1450,
  "orderDate": "2026-03-16",
  "description": "Flooring repair - service call",
  "status": 1,
  "invoiceTotal": 1850.00,
  "salesTax": 100.00,
  "salesTaxAccount": 2450,
  "taxableExtended": 550.00,
  "nonTaxableExtended": 1200.00,
  "taxable": 550.00,
  "lines": [
    {
      "lineNumber": 1,
      "description": "Service labour - flooring repair",
      "extendedQuantity": 8,
      "extendedPrice": 1200.00,
      "accountNumber": 4200,
      "subAccountNumber": 11,
      "costCode": 3.100,
      "costType": 2
    },
    {
      "lineNumber": 2,
      "description": "Materials - flat rate",
      "extendedQuantity": 1,
      "extendedPrice": 550.00,
      "accountNumber": 4200,
      "costCode": 2.100,
      "costType": 1
    }
  ]
}

Response shape

{
  "document": {
    "id": "1f88...-uuid", "recordNumber": 30122,
    "orderNumber": "WO-88", "invoiceNumber": "SVC-2201", "status": 1,
    "invoiceTotal": 1850.00, "salesTax": 100.00,
    "lines": [
      { "id": "...", "recordNumber": 30201, "lineNumber": 1,
        "extendedPrice": 1200.00, "accountNumber": 4200 }
    ]
  },
  "ledgerTransaction": {
    "id": "...", "recordNumber": 55203, "sourceNumber": 22,
    "lines": [
      { "lineNumber": 1, "ledgerAccount": 1150, "debitAmount": 1850.00, "creditAmount": 0.00 },
      { "lineNumber": 2, "ledgerAccount": 4200, "debitAmount": 0.00, "creditAmount": 1750.00 },
      { "lineNumber": 4, "ledgerAccount": 2450, "debitAmount": 0.00, "creditAmount": 100.00 }
    ]
  },
  "jobCosts": [ { "id": "...", "recordNumber": 66304, "jobNumber": 1450, "costAmount": 1200.00 } ],
  "inventory": [],
  "dryRun": false,
  "period": 3,
  "year": 2026
}

Gotchas

Only status 1 (Open) posts to the general ledger; per Sage that status means you have invoiced the customer. The values are not in workflow order: the lifecycle runs 6 Quote, 7 Work Order, then 8 Complete or 1 Open, then 4 Paid, so a 4 Paid invoice is a settled document that has already posted and must not post again.
The default status is 7 (Work Order), which stores and posts nothing. That is why this is the one endpoint whose response may omit period and year: they are present exactly when ledgerTransaction is.
The balance check is exact decimal arithmetic. v2’s friendly validator allowed a half-cent of drift while the posting engine compared exactly, so a rounding artefact on a tax split passed the first check and then failed deep in the engine with an unhelpful message. Both now agree on what balanced means.
The AR subledger is written in full on the posting path. v2 debited Service Receivables, the GL said the customer owed it, while leaving the invoice record’s own amount, net and outstanding-balance columns empty, so AR aging saw nothing outstanding.
salesTaxAccount is required at status 1 whenever salesTax is greater than zero; that is the account the sales tax payable credit lands in. salesTaxSubAccount is optional.
A line produces a job cost only when the header has a jobNumber and the line has a costCode. Either one alone produces nothing. costType defaults to 1 consistently on both the stored line and the job cost.
It never touches inventory. A service line cannot name a part and no on-hand quantity moves.
The taxable and non-taxable amount fields are taken as given and are not recomputed from the lines. Compute them yourself before posting.
clientNumber appears on both the header and each line, and both are used. Set them consistently.

What it creates in Sage

One payroll record per check, with hours and pay bucketed by each earning’s pay type.
A timecard line per earning, carrying its job, cost code, phase and department where supplied.
A payroll calculation row per tax or deduction on the check.
The GL debit distribution rows for the wage expense.
A separate balanced journal per check, linked back to the paycheque: wage expense debited, each deduction credited to its liability account, net pay credited to the payroll cash account.

Posting period derived from checkDate.

Minimal request body

{
  "userName": "bill",
  "provider": "paycom",
  "checkDate": "2026-03-20",
  "periodStart": "2026-03-09",
  "periodEnd": "2026-03-15",
  "payrollCashAccount": 1020,
  "wageExpenseAccount": 5300,
  "checks": [
    {
      "employeeNumber": 4071,
      "employeeCode": "A038",
      "checkNumber": "000004256",
      "stateCode": "FL",
      "earnings": [
        { "code": "REG", "payType": 1, "hours": 40, "rate": 26.00,
          "amount": 1040.00, "account": 5300, "jobNumber": 1450, "costCode": 3, "phase": 1 },
        { "code": "OT", "payType": 2, "hours": 2, "rate": 39.00,
          "amount": 78.00, "account": 5300 }
      ],
      "deductions": [
        { "calculation": 1, "code": "FWT", "amount": 112.30, "liabilityAccount": 2210 },
        { "calculation": 2, "code": "SSC", "amount": 69.32, "liabilityAccount": 2220 }
      ],
      "grossPay": 1118.00,
      "deductionTotal": 181.62,
      "netPay": 936.38
    }
  ]
}

Response shape

{
  "document": {
    "provider": "paycom", "checkDate": "2026-03-20", "checkCount": 1,
    "checks": [
      {
        "id": "...", "recordNumber": 51001, "employeeNumber": 4071,
        "checkNumber": "000004256",
        "grossPay": 1118.00, "deductionTotal": 181.62, "netPay": 936.38,
        "ledgerTransaction": {
          "id": "...", "recordNumber": 55210, "sourceNumber": 16,
          "lines": [
            { "lineNumber": 1, "ledgerAccount": 5300, "debitAmount": 1118.00, "creditAmount": 0.00 },
            { "lineNumber": 4, "ledgerAccount": 1020, "debitAmount": 0.00, "creditAmount": 936.38 }
          ]
        }
      }
    ]
  },
  "jobCosts": [],
  "inventory": [],
  "dryRun": false,
  "period": 3,
  "year": 2026
}

Gotchas

This is the only endpoint targeting Sage 100 Contractor (menu 5) rather than Sage 300, and the only one where one request writes many documents. Every check gets its own paycheque and its own separate balanced journal; nothing sums the run, so reconcile each check on its own.
The pay has already been calculated somewhere else. This endpoint calculates nothing and withholds nothing: an upstream integration normalises Paycom, ADP or whoever into this one shape, and provider is free text for audit only.
The whole batch is validated before the first write, and every problem in it is reported together. v2 validated inside the loop that was already writing, so a problem on the twelfth check was found after eleven paycheques had been posted, correctly rolled back, but you had to resubmit once per problem to discover the rest.
Every reconciliation check is exact decimal arithmetic. Earnings must sum to grossPay, and grossPay must equal deductionTotal + netPay. v2 allowed a half-cent of drift, which also decided whether a deduction counted as zero, so a deduction of four tenths of a cent was recorded on the paycheque, counted toward the deduction total, and credited to nothing in the general ledger.
A payroll run that is already posted is refused rather than posted again. v2 had no protection of any kind, so a timed-out request that had in fact committed created a second paycheque and a second journal for every employee, crediting payroll cash twice. The guard depends on the provider supplying check numbers; a check without one cannot be recognised, and the refusal message says how many it could not examine.
Each earning rate is compared against the employee master pay rates and rejected if it drifts further than rateTolerance, which defaults to 0.01. A rate mismatch usually means the wrong employee or a stale master record.
deduction.calculation is the record number of the Sage payroll calculation the amount belongs to, and any non-zero deduction needs a liabilityAccount for the GL credit.
An earning needs either its own account or a wageExpenseAccount fallback on the batch. payrollCashAccount is always required; it is the net-pay credit.
jobCosts and inventory are always empty. An earning may carry a job number, cost code, phase and department, but those land on the timecard line for reporting only and never produce a job-cost row.
Employer-side burden, the company share of taxes, workers comp, is not posted here. Only the employee-side check register is.
The paycheque now carries a working link to its journal. In v2 that link had never once been populated in production, and the test that covered it exercised a code path production could not reach.

Section 6

Full API reference#

This is the v3 contract itself, not a description of it. The document below is OpenAPI 3.1 compiled from the TypeSpec the server and the generated clients are both built from, so what it says is what the API does. The guide above covers the 82 query entities, seven writes, and the problem shape for each status. This reference includes the complete field and type definitions.

Reference domain

The complete v3 contract is loaded here. Individual domain pages load only their own reference for faster navigation.

The field-level reference for all 93 routes. Expand an entity's model to see its available properties and types. Those property names are used in select, orderBy, matchFields and every match.field.

Use it as an index rather than reading it front to back. The 82 /query entries all share the contract from section 2, and every operation's failure responses are the same twelve from section 3. Those responses are declared once and referenced, so a status on one route has the same meaning on every route.

Loading the reference domains…

Something here does not match what you see?

This guide is maintained by hand alongside the generated reference, so if a field, a status value or a cascade does not behave the way it is described here, that is worth reporting rather than working around. Tell us what you called and what came back.

OPDC API Documentation

Getting started#

What v3 changes, in one box

Move one read at a time

Utility routes are available under v3

Reading: one contract, 82 entities#

Branch on the HTTP status. There is no responseType

Unknown fields are rejected, not dropped

Child collections: ask for the ones you want

Incremental sync: check that your entity supports a watermark

Resolving names? Use match, not LIKE

Where field names come from

Some codes are per-company: read them, do not hardcode them

Errors: one shape, on every status#

Retry policy in one paragraph

Maintenance locking#

What a lock actually does

Lock state is persistent

v3 tells your client how long to wait

Ownership is per API key

Integrators: back off on 423, do not fail the batch

Writes#

Idempotency-Key: retry a write without wondering whether it committed

?dryRun=true: see what a post would do, against real data

The posting period

Full API reference#

Something here does not match what you see?

Branch on the HTTP status. There is no `responseType`

`Idempotency-Key`: retry a write without wondering whether it committed

`?dryRun=true`: see what a post would do, against real data