Developers

OPDC API Documentation

The OPDC API exposes secure, opinionated endpoints for working with Sage 100 Contractor data. This guide covers the parts worth reading once: authentication, the shared query contract, error handling, maintenance locking, and the write endpoints. The exhaustive, field-level reference lives at the bottom of the page.

Section 1

Getting started

Every endpoint is a POST that takes a JSON body and returns JSON. There are no path or query parameters. The entity you are working with is part of the URL, and everything else goes in the body.

Base URL

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

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

Headers

Header	Required	Notes
x-api-key	Yes	Your API key, a UUID. Missing, non-UUID, or unrecognised keys all return `401`.
Content-Type	Yes	`application/json`
x-context-id	No	Correlation UUID attached to traces and audit records. Pass your own request or session identifier. A value that is not a valid UUID returns `400`.
x-integration-id	No	Identifies the calling integration, also a UUID. A malformed value returns `400`.

Verify your key

/utility/ping is the cheapest proof that your key works and that the on-premise service is reachable. It sends a no-op message to your server and reports the round-trip time.

curl -X POST https://{your-opdc-host}/api/v2/utility/ping \
  -H "x-api-key: {your-api-key}" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "status": "ok",
  "latencyMs": 148,
  "response": { ... }        // acknowledgement from your on-premise service
}

latencyMs is the full round trip out to your on-premise service and back, which makes it a useful health check before starting a batch. A 504 here means the on-premise service is down or unreachable, not that your key is bad.

Section 2

Querying: read this once

There are 79 /query/* endpoints in the reference below, and they are all the same endpoint with a different noun. Every one of them accepts the identical request body and returns the identical envelope. Only the objects inside response differ. Learn the contract here and you have learned all 79.

Endpoint

POST/api/v2/query/{entity}

For example /query/part, /query/job, /query/vendor, /query/purchase-order. The full list of entities is in the reference at the bottom of the page.

Request body: every field

{
  "selectFields": ["partNumber", "description", "unitCost"],
  "withChildren": false,
  "filters": {
    "and": [
      { "match": { "field": "partNumber", "operator": "in", "values": ["PIPE-001", "VALVE-200"] } },
      { "match": { "field": "unitCost", "operator": ">=", "value": 10 } }
    ]
  },
  "orderBy": ["unitCost DESC"],
  "page": { "pageNumber": 0, "pageSize": 25 },
  "lastUpdated": "2026-01-15T10:30:00Z"
}

Field	Behaviour
selectFields	Fields to return. Omit it, or leave it empty, and you get every field on the entity.
withChildren	Include the entity's child records (invoice lines, PO lines, and so on). Defaults to false. Leave it off unless you need the children; it is a materially heavier query.
filters	A recursive boolean tree of `and`, `or`, and `match` nodes. Omit it to return everything.
orderBy	Array of sort clauses, each a field name plus optional `ASC`/`DESC`.
page	`pageNumber` and `pageSize`, or `offset` as an alternative to `pageNumber`.
lastUpdated	ISO 8601 timestamp. Returns only rows modified since then, so this is the field to build incremental syncs on.

A legacy single-condition filter (singular) field is still accepted for backwards compatibility. Use filters for new work.

Response envelope

{
  "message": "",
  "responseType": "SUCCESS",
  "page": { "pageNumber": 0, "pageSize": 25, "offset": 0, "count": 142 },
  "response": [ { "partNumber": "PIPE-001", "description": "PVC Pipe 4\"", "unitCost": 12.50 } ]
}

Read this before you write a client

Branch on `responseType`, never on the HTTP status alone

A query that fails on the Sage side (an unknown field name, a SQL error, a script failure, an unbalanced journal) comes back as HTTP 200 with responseType: "ERROR" and the root cause in message. The HTTP layer only reports transport and auth problems; business outcomes live in the body.

A client that checks res.ok and moves on will silently treat every business failure as a success. On a read, that means "your filter referenced a field that does not exist" looks exactly like "there are no matching rows".

Do this

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

if (body.responseType !== "SUCCESS") {
  // The real failure is here, on a 200 as often as on a 500.
  throw new Error(body.message)
}
return body.response

Write endpoints have the same trap with the status inverted. There, a Sage-side failure arrives as HTTP 500 carrying the same JSON envelope with responseType: "ERROR". It is not an infrastructure fault, and retrying it unchanged will not help, so read message. Checking responseType first is correct on both reads and writes; checking the status is correct on neither.

Unknown request fields are ignored, not rejected

The request body is parsed leniently, and a field the API does not recognise is dropped silently. So a typo like selectFeilds does not error. It just leaves selectFields unset and returns every field on the entity. A misspelled filters behaves the same way: you get an unfiltered result set, not a 400. Diff your payload against the reference when a query returns suspiciously much.

Pagination

pageNumber is 0-indexed. The first page is 0, not 1.
page.count in the response is the total number of matching rows, not the length of the page you were handed. Use it to decide whether to fetch another page; use response.length if you want the size of the current batch.
page is an object on both the request and the response, never a bare number.

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 the match endpoints below.
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.like, LIKE, in and IN are all accepted, because the query builder normalises the case before matching. 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": "01-100" },
      { "jobNumber": 1044, "costCode": "02-200" }
    ]
  }
}

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 } }
        ]
      }
    ]
  }
}

Resolving names? Use the match endpoints, not LIKE

If you have a human-entered name, say a vendor off an invoice or a job from a spreadsheet, do not reach for LIKE '%...%'. Use POST /api/v2/match/{client|vendor|job|part|employee}. It scores candidates by Levenshtein edit distance against the fields you name, normalising both sides first (lowercased, non-alphanumeric characters stripped), and returns matches within maxDistance sorted closest-first with their distance attached.

POST /api/v2/match/vendor

{
  "matchString": "Acme Corp",
  "matchFields": ["name", "shortName"],
  "selectFields": ["recordNumber", "name"],
  "maxDistance": 3
}

{
  "message": "",
  "responseType": "SUCCESS",
  "response": [
    { "recordNumber": 124, "name": "ACME CORPORATION", "distance": 2 }
  ]
}

filters is accepted here too, as an optional pre-filter to narrow the candidate set before scoring.

Where field names come from

Field names in selectFields, orderBy, and every match.field are the JSON names OPDC exposes, the property names listed under each entity's model in the full API reference at the bottom of this page. They are not the underlying Sage column names: partNumber, not the cryptic Sage column it maps to. OPDC translates them for you on the way in and out.

A field name that does not exist on the entity is a Sage-side failure: HTTP 200 with responseType: "ERROR" and the offending name in message.

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

Most numeric codes in Sage are fixed by the product, and the reference names them. 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	/query/cost-type	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	/query/cost-code	Entirely company-defined.
sourceNumber	/query/transaction-source	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 table for the whole API

Every endpoint in the reference repeats the same handful of responses. Here they are once. These are the only statuses the API produces, and they mean the same thing on every route.

Error bodies are plain text, not JSON

The 200 envelope and the write endpoints' 500 are application/json. Everything else (400, 401, 409, 423, 503, 504) is text/plain, a bare sentence like Locked for maintenance by bill. A client that unconditionally runs JSON.parse on the response body will throw on the error path and mask the real message. Check the status first, and read those bodies as text.

Status	When	Retry?
`200 · SUCCESS`	The call succeeded. Your data is in response.	n/a
`200 · ERROR`	Reads and utility calls: the Sage side failed (unknown field, SQL error, script failure). message holds the root cause.	Depends on the message. Fix the payload, or retry if it names a transient condition.
`200 · NO_RESPONSE`	Accepted, but nothing was returned.	No, the call was processed.
`400`	Malformed or empty JSON body; an x-context-id or x-integration-id that is not a valid UUID; a missing userName on lock or un-lock.	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.
`409`	Un-lock attempted while a different user holds the lock.	Only with override: true, and only deliberately.
`423`	Any query, match, or write while the database is locked for maintenance. The body names the holder.	Yes, back off and retry. Clears when the operator un-locks.
`500`	Internal error. On write endpoints this also carries a JSON envelope with responseType: ERROR when the Sage-side post failed; read message.	Not blindly. If responseType is ERROR, the payload or the accounting state needs fixing.
`503`	The service is disabled for this API key. The body carries the reason.	No, contact support.
`504`	The round trip to your on-premise service failed or timed out, usually because the service is down, restarting, or slow.	Yes, back off and retry.

Retry policy in one paragraph

Retry 504 and 423 with backoff. Both mean "the on-premise side is not available right now", and both clear without you changing anything. Never retry 400, 401 or 503 since a malformed body, a bad key, and a disabled key will all fail identically forever. A 200 or 500 carrying responseType: "ERROR" depends entirely on the message: a closed accounting period or an unbalanced journal needs a corrected payload, a transient database problem does not. Log the message; do not blind-retry writes.

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 you get that, and it is why your integration will occasionally see a 423.

The full flow

1
bill locks the database for maintenance
POST /api/v2/utility/lock
{ "userName": "bill" }
-> 200{ "status": "locked", "lockUser": "bill", "response": { ... } }
2
Every other call is rejected while the lock holds
Not just /query/part shown here — every /query/*, /match/*, /insert/*, /update/*, and /payroll call fails the same way until the lock clears.
POST /api/v2/query/part
-> 423Locked for maintenance by bill [text/plain]
3
bill releases the lock when he's done
POST /api/v2/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/v2/utility/un-lock
{ "userName": "ann" }
-> 409locked by different user: bill (use override=true to force) [text/plain]
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.

Utility routes stay open

While locked, everything under /api/v2/utility/ keeps working, so you can still ping and you can still un-lock. Every /query/*, /match/*, /insert/*, /update/* and /payroll call returns 423.

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. userName is required on both calls, and omitting it is a 400.

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, retry with backoff, 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

Six endpoints write to Sage. Each one 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. Expand a card for its request shape and its gotchas. Auth and error handling are the same as everywhere else; see section 1 and section 3.

The posting period is resolved server-side: the header `period` and `year` are ignored

This applies to every write endpoint, so it is stated once here. Some request bodies still accept period and year at the top level, but those do not control anything. 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: either the current open period, or the period the document's date falls in.

The exception is job costs. A period and year set on an entry inside jobCosts is used exactly as you send it, with no range check and no comparison against the open period. Omit them and the job cost inherits the period resolved for the document, which is almost always what you want. Set them only if you know why.

A post that resolves to a period later than the open one is rejected, with a message naming both. A post that resolves to an earlier period is accepted and will land in that earlier period, so a stale document date puts the entry somewhere you may not intend. Check the date you send rather than relying on the API to catch it. Note this is stricter than Sage in one direction and looser in the other: Sage itself will generally accept postings anywhere in the open fiscal year.

What it creates in Sage

The AP invoice header and one line per entry in lines.
A posted ledger transaction with its lines when status is 1: expenses debited from each line accountNumber, the AP control account credited.
Ledger account, period-balance and sub-account balance propagation for every account touched.
A job cost record for each line that carries a costCode, plus the vendor balance update.

Posting period derived from enteredDate.

Minimal request body

{
  "userName": "jsmith",
  "enteredDate": "2026-01-15",
  "invoiceDate": "2026-01-15",
  "dueDate": "2026-02-15",
  "invoiceNumber": "S2020921.001",
  "description": "Grey glue - job 46-025",
  "vendorNumber": 124,
  "jobNumber": 1234,
  "invoiceType": 1,
  "status": 1,
  "invoiceTotal": 399.33,
  "subTotal": 399.33,
  "invoiceAmount": 399.33,
  "invoiceBalance": 399.33,
  "invoiceNet": 399.33,
  "lines": [
    {
      "lineNumber": 1,
      "partDescription": "GG1000 GREY GLUE GALLON",
      "lineQuantity": 11,
      "linePrice": 36.303,
      "extendedTotal": 399.33,
      "accountNumber": 5100,
      "subAccountNumber": 1234,
      "costCode": 1000,
      "costType": 1
    }
  ]
}

Response shape

{
  "message": "",
  "responseType": "SUCCESS",
  "response": {
    "id": "9c1f...-uuid",
    "recordNumber": 88213,
    "invoiceNumber": "S2020921.001",
    "invoiceTotal": 399.33,
    "period": 1,
    "year": 2026,
    "lines": [
      { "id": "...", "recordNumber": 41120, "lineNumber": 1, "extendedTotal": 399.33 }
    ],
    "ledgerTransaction": {
      "id": "...", "recordNumber": 55201,
      "lines": [ { "lineNumber": 1, "ledgerAccount": 5100, "debitAmount": 399.33, "creditAmount": 0.00 } ]
    }
  }
}

Gotchas

The GL cascade is not optional. A ledger transaction is posted on every AP invoice regardless of the status you send, and the journal itself is always written as posted. status is recorded on the invoice and copied to any job costs, but it does not gate anything.
status uses the Sage payable invoice values: 1 Open (posted to the general ledger), 2 Review, 3 Dispute, 4 Paid, 5 Void. Only 1 to 3 are yours to set; Sage sets 4 and 5.
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.
A line gets a job cost only if it carries costCode. jobNumber on the header alone does not produce job costs.
The amount fields are not cross-checked for you. invoiceTotal, subTotal, invoiceAmount, invoiceBalance, invoiceNet and the sum of line extendedTotal are all taken as given. Compute them consistently before you post.
partNumber on a line is the Sage part record number, not the alphanumeric part code. That code goes in alphaNumber.
Pass transientId on the header and on each line to correlate your own IDs with the record numbers that come back.

What it creates in Sage

The ledger transaction header and one line per debit or credit.
Ledger account balance updates, period balances, and sub-account balances for every account on the transaction.
A job cost record for each entry in the optional jobCosts array.

Posting period derived from transactionDate.

Minimal request body

{
  "userName": "jsmith",
  "transactionNumber": "GL-2026-001",
  "enteredDate": "2026-01-15",
  "transactionDate": "2026-01-15",
  "description": "Monthly accrual entry",
  "status": 1,
  "sourceNumber": 1,
  "lines": [
    { "lineNumber": 1, "description": "Office supplies expense",
      "ledgerAccount": 60100, "subAccount": 1001,
      "debitAmount": 1500.00, "creditAmount": 0 },
    { "lineNumber": 2, "description": "AP control",
      "ledgerAccount": 20100,
      "debitAmount": 0, "creditAmount": 1500.00 }
  ]
}

Response shape

{
  "message": "",
  "responseType": "SUCCESS",
  "response": {
    "id": "7ab3...-uuid",
    "recordNumber": 55202,
    "transactionNumber": "GL-2026-001",
    "period": 1,
    "year": 2026,
    "lines": [
      { "id": "...", "recordNumber": 91011, "lineNumber": 1,
        "ledgerAccount": 60100, "debitAmount": 1500.00, "creditAmount": 0.00 },
      { "id": "...", "recordNumber": 91012, "lineNumber": 2,
        "ledgerAccount": 20100, "debitAmount": 0.00, "creditAmount": 1500.00 }
    ],
    "jobCosts": []
  }
}

Gotchas

Total debits must equal total credits, and each individual line must carry exactly one of debitAmount or creditAmount greater than zero. Both zero, or both non-zero, is rejected.
lineNumber must be 1 or greater and ledgerAccount must be present on every line.
transactionNumber, enteredDate, transactionDate, status and sourceNumber are all required, and there must be at least one line.
sourceNumber is your Sage source code for the entry. The valid numbers depend on your Sage install, so check your Source Codes table rather than guessing.
The older /api/v2/insert/ledger-transaction is deprecated but fully supported, with no removal date. The request and response contracts are identical, so migrating is a URL change and nothing else. New integrations should use v2, which posts through the shared journal engine.

What it creates in Sage

One payroll record per check, with hours and pay bucketed by each earning payType.
A timecard line per earning, carrying its job, cost code and phase where supplied.
A payroll calculation row per tax or deduction on the check.
The GL debit distribution rows for the wage expense.
A balanced payroll journal per check, linked back to the paycheck: 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

{
  "provider": "paycom",
  "checkDate": "2026-06-20",
  "periodStart": "2026-06-09",
  "periodEnd": "2026-06-15",
  "payrollCashAccount": 10100,
  "wageExpenseAccount": 50100,
  "checks": [
    {
      "employeeNumber": 38,
      "employeeCode": "A038",
      "checkNumber": "000004256",
      "stateCode": "FL",
      "payType": 1,
      "status": 1,
      "earnings": [
        { "code": "REG", "payType": 1, "hours": 40, "rate": 26.00,
          "amount": 1040.00, "account": 50100,
          "jobNumber": 1021, "costCode": 1000 }
      ],
      "deductions": [
        { "calculation": 12, "code": "FWT",
          "amount": 85.53, "liabilityAccount": 20300 }
      ],
      "grossPay": 1040.00,
      "deductionTotal": 85.53,
      "netPay": 954.47
    }
  ]
}

Response shape

{
  "message": "",
  "responseType": "SUCCESS",
  "response": {
    "provider": "paycom",
    "checkDate": "2026-06-20",
    "period": 6,
    "year": 2026,
    "checkCount": 1,
    "checks": [ { ... } ]     // payroll record + its GL transaction, per check
  }
}

Gotchas

The batch is reconciled against the provider check register before anything is written, and the whole batch fails as one if any check does not foot. Earnings must sum to grossPay, and grossPay must equal deductionTotal + netPay.
Each earning rate is compared against the employee master pay rates and rejected if it drifts further than rateTolerance, which defaults to 0.01. This is the point of the reconciliation, since 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. Without one of the two, validation fails.
payrollCashAccount is required; it is the net-pay credit.
Employer-side burden (the company share of taxes, workers comp) is not posted here. Only the employee-side check register is.
sourceNumber defaults to a payroll source code that may not match your install. Set it explicitly if your Source Codes table differs.
Upstream integrations normalise Paycom, ADP and others into this one shape. The endpoint is provider-agnostic and provider is free text for audit only.

What it creates in Sage

The service inventory header and one line per entry in lines.
When the invoice posts to the GL, a ledger transaction with its lines, returned alongside the header.
A per-line job cost when the header carries a jobNumber and the line carries a costCode.

Posting period derived from orderDate.

Minimal request body

{
  "userName": "jsmith",
  "orderNumber": "WO-10432",
  "invoiceNumber": "SI-10432",
  "clientNumber": 412,
  "orderDate": "2026-01-15",
  "description": "Annual maintenance visit",
  "invoiceType": 1,
  "status": 1,
  "priority": 2,
  "taxableExtended": 0,
  "nonTaxableExtended": 250.00,
  "salesTax": 0,
  "invoiceTotal": 250.00,
  "taxDistrict": 0,
  "jobNumber": null,
  "lines": [
    {
      "lineNumber": 1,
      "description": "Service call - 2 hrs",
      "unitDescription": "HR",
      "partQuantity": 2,
      "partPrice": 125.00,
      "extendedPrice": 250.00,
      "accountNumber": 40100,
      "subAccountNumber": 0,
      "clientNumber": 412
    }
  ]
}

Response shape

{
  "message": "",
  "responseType": "SUCCESS",
  "response": {
    "recordNumber": 30122,
    "orderNumber": "WO-10432",
    "invoiceTotal": 250.00,
    "ledgerTransactionRecnum": 55203,   // only when the invoice posts to the GL
    "ledgerTransaction": { ... }
  }
}

Gotchas

Nothing hits the general ledger until status reaches 4 (invoiced). Below that you are creating a work order, not an accounting document, and ledgerTransaction comes back absent.
salesTaxAccount is required on status 4 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.
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

The allocation header and one line per entry in lines.
An inventory history row per line, and quantity updates at the source location (and at destinationLocation, for a transfer).
Part master updates from the allocation cost.
One job cost for the whole allocation, when the conditions below are met.

Posting period derived from transactionDate.

Minimal request body

{
  "userName": "jsmith",
  "transactionDate": "2026-01-15",
  "status": 3,
  "description": "To Requisition Stock to Job",
  "jobNumber": 5001,
  "deliveryVia": "Truck",
  "lines": [
    {
      "partNumber": 1001,
      "partDescription": "Widget A",
      "alphaNumber": "WDGT-A",
      "unitDescription": "EA",
      "quantity": 10,
      "cost": 25.50,
      "total": 255.00,
      "sourceLocation": 1,
      "debitAccount": 5100,
      "debitSubAccount": 0
    }
  ]
}

Response shape

{
  "message": "",
  "responseType": "SUCCESS",
  "response": {
    "id": "4d20...-uuid",
    "recordNumber": 77410,
    "status": 3,
    "description": "To Requisition Stock to Job",
    "lines": [
      { "id": "...", "recordNumber": 77411, "lineNumber": 1,
        "partNumber": 1001, "quantity": 10.00, "cost": 25.50, "total": 255.00 }
    ],
    "jobCost": { "id": "...", "recordNumber": 66300, "jobNumber": 5001, "costAmount": 255.00 }
  }
}

Gotchas

description is functional here, not free text. A job cost is created only when all three hold: status is 3 or 4, jobNumber is present, and description is exactly "To Requisition Stock to Job". Change the wording and the job cost silently does not happen.
status uses the Sage inventory values: 1 Open, 2 Review, 3 Hold Stock, 4 Shipped. In Sage, 3 reserves stock and reduces the available quantity, while 4 also reduces the on-hand quantity.
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.
Required: transactionDate, a status of 1 to 4, and at least one line. Every line needs partNumber, a quantity greater than zero, and sourceLocation.
partNumber is the Sage part record number; the alphanumeric code goes in alphaNumber. Part details are looked up from the part master by record number.

What it creates in Sage

The PO header status and each received line quantity.
An AP invoice with one line per line received, carrying the part, price and account data you supply.
A posted ledger transaction with its lines, plus balance propagation.
Inventory quantity updates for received parts held in inventory accounts.
A job cost per line for direct expense lines when the receipt carries a jobNumber.

Posting period derived from transactionDate.

Minimal request body

{
  "userName": "jsmith",
  "purchaseOrderRecnum": 12345,
  "transactionDate": "2026-01-15",
  "shippingNumber": "SHP-001",
  "description": "PO receipt - office supplies",
  "userDefined1": "Warehouse A",
  "status": 3,
  "vendorNumber": 1001,
  "jobNumber": 5001,
  "lines": [
    {
      "poLineId": "5c1f...-uuid",
      "poLineIdRef": "9ab2...-uuid",
      "lineNumber": 1,
      "updateQuantity": 5,
      "partNumber": 1001,
      "partDescription": "Widget A",
      "alphaNumber": "WDGT-A",
      "unitDescription": "EA",
      "linePrice": 25.50,
      "accountNumber": 60100,
      "subAccountNumber": 0,
      "inventoryLocation": 1,
      "costCode": 1000,
      "costType": 1
    }
  ]
}

Response shape

{
  "message": "",
  "responseType": "SUCCESS",
  "response": {
    "purchaseOrder": { "id": "...", "recordNumber": 12345, "status": 3 },
    "invoice": {
      "id": "...", "recordNumber": 88214, "invoiceTotal": 127.50,
      "lines": [ { "lineNumber": 1, "lineQuantity": 5.00, "linePrice": 25.50, "extendedTotal": 127.50 } ]
    },
    "ledgerTransaction": {
      "id": "...", "recordNumber": 55204,
      "lines": [ { "lineNumber": 1, "ledgerAccount": 60100, "debitAmount": 127.50, "creditAmount": 0.00 } ]
    },
    "jobCosts": [ { "id": "...", "recordNumber": 66301, "jobNumber": 5001, "costAmount": 127.50 } ]
  }
}

Gotchas

poLineId and poLineIdRef are the UUIDs of the existing PO line row and its parent, not numbers you invent. Fetch them first with POST /api/v2/query/purchase-order and withChildren: true, then echo them back.
updateQuantity is the quantity received on this receipt, not the running total. It is added to what the PO line has already received, so posting the same receipt twice double-counts it. This endpoint is not idempotent.
status is the new PO status after the receipt, using the Sage purchase order values: 1 Open, 2 Review, 3 Dispute, 4 Closed, 5 Void, 6 Master. There is no "partial" or "received" status. You decide the value; the endpoint writes it straight through and never infers it from the quantities, so a receipt that only partially fills the order still leaves the status at whatever you send.
A ledger transaction is always generated, posted, on every receipt. There is no draft mode.
Inventory is only touched for lines that have a partNumber and whose accountNumber is one of the dedicated inventory accounts in your ledger setup. A line expensed straight to a job updates no inventory.
Required: purchaseOrderRecnum, transactionDate, vendorNumber and at least one line. Each line needs poLineId, an updateQuantity greater than zero, a non-negative linePrice, and accountNumber.

Section 6

Full API reference

The exhaustive, field-level index of every endpoint, generated from the OpenAPI spec. Its job is the detail the guide above deliberately leaves out. This is where the per-entity field lists live. Expand an entity's model to see every property it exposes, with types. Those property names are exactly what you put in selectFields, orderBy, and match.field.

Read it as an index rather than front to back. The /query/* entries all share the contract from section 2, and the response entries on every route are the statuses from section 3, so there is no need to read either one again on each of the 94 routes.

Loading the API reference…

OPDC API Documentation

Getting started

Querying: read this once

Branch on responseType, never on the HTTP status alone

Unknown request fields are ignored, not rejected

Resolving names? Use the match endpoints, not LIKE

Where field names come from

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

Errors: one table for the whole API

Error bodies are plain text, not JSON

Retry policy in one paragraph

Maintenance locking

What a lock actually does

Lock state is persistent

Utility routes stay open

Ownership is per API key

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

Writes

The posting period is resolved server-side: the header period and year are ignored

Full API reference

Branch on `responseType`, never on the HTTP status alone

The posting period is resolved server-side: the header `period` and `year` are ignored