Test Order Modification API

Order modification service for adding tests to or cancelling tests from existing Labcorp orders.

Authentication

OAuth2 client credentials flow. Present a bearer access token obtained from the Labcorp token endpoint; no scope is required on the token.

Processing Model

The service processes an ordered list of commands sequentially:

1. Validation — Performed in stages, in order; the first stage to fail determines the response:

   • Parse and validate the request body. Malformed JSON, a missing or invalid required field, an empty commands array, or a cancellation reason longer than 150 bytes (UTF-8) all return 400. Unknown fields are ignored.
   • Authorize the request. If the partner's profile, subscription, CSID, and sending application combination is not provisioned, the request returns 403.
   • Locate the original order. If no order matches the supplied identifiers, or the located order does not match the request, the request returns 404.
   • Validate each command. Test codes are checked against the compendium, and adds are checked against business rules (add-on eligibility on an accessioned order, AOE requirements). If any command fails this stage, the request returns 422 and nothing is applied.

   Because every command is validated before any of them is applied, a 422 means the order was not touched: correct the request and resend it in full. If an internal Labcorp system is unavailable during these stages the request returns 502; an unexpected internal error returns 500.

2. Per-command execution — Each command is submitted in order. Commands are coalesced into batches of up to 40 test codes sharing one command type; a batch is submitted when it reaches 40, when a command of a different type arrives, or when all commands have been processed. Batches are submitted sequentially; if a batch fails, remaining batches are not attempted.

   Every command in a batch shares one outcome, and that is what makes batching visible to you. A request of up to 40 commands of a single type is all-or-nothing: either every command is submitted, or none is applied and the request can be resent in full. Mixing adds and cancels, or exceeding 40 commands of one type, produces more than one batch, and those batches succeed or fail independently — so a partial result becomes possible. An unusually large payload may be split further.

3. Outcome — Once validation passes, the response carries a status for each command, in order. Every status is one of:

   • submitted — accepted by Labcorp.
   • rejected — the service declined the command on its merits, such as a cancel against an accessioned order. Re-sending the same command will be declined again, so correct it before retrying.
   • failed — the command could not be completed. This is an operational failure and may be transient, so a retry could succeed.
   • not-submitted — the command was never attempted, because an earlier command stopped processing.

   Processing stops at the first rejected or failed command; every command after it is not-submitted. Because every command in a batch shares one outcome, more than one command can be reported failed at once.

   Read the per-command statuses rather than the HTTP status alone:

   • 200 — every command was submitted.
   • 207 — some commands were submitted and a later one was not. The order is partially modified: reconcile against the per-command statuses and resend only the commands that are not submitted.
   • 422 — no command was applied, because a command was rejected. Correct the request and resend it in full.
   • 502 — no command was applied, because a command failed. No response body is returned, so the per-command outcomes are not available; the request can be resent in full.

   A submitted add may also carry a messages array — informational notes about how the addition will be handled, such as an old specimen being pulled from storage or the test already being on the order. A note is not a refusal or a problem to correct; the test was accepted and submitted, and no follow-up is required. Notes appear only on commands that were submitted, since a note describes a test that was actually added; a command that never reached processing carries none.

   One restriction falls outside this set of outcomes: cancellation applies only to specimens collected by Labcorp at a Patient Service Center (PSC), and this API does not enforce it. A cancel for an in-house collection is reported submitted and is declined by Labcorp after the response has been sent, so it never appears as a rejected result. A submitted status confirms the cancellation was transmitted, not that it will be honored.

Response Codes

Code	Meaning
200	All commands submitted successfully.
207	Partial success — some commands submitted, then processing stopped.
400	Request body could not be parsed.
401	Authentication failed — the bearer token is missing or invalid.
403	The requesting partner is not authorized for this operation.
404	The order could not be located.
422	No command was applied — a command was rejected.
500	Internal error.
502	No command was applied — an internal Labcorp system was unavailable or did not accept the submission.