Issue a passport on order, in one call.

• Lot

  The batch a document set belongs to. A lot clears on its whole SET of documents for that subject and dosage form, not on the newest file, which is why a single-panel certificate cannot clear one on its own. Everything else hangs off the lot.

• Order

  One customer's purchase, written against a lot and carrying your own order reference. A customer reference that reads like patient information is rejected outright rather than stored and scrubbed later.

• Policy

  Your documentation rules: a preset, eleven named toggles and one threshold. The version in force is pinned inside every decision, so a decision replays to the same answer years later.

• Passport

  The released, order-bound proof. It mints only from a cleared lot and its lot binding is permanent, which is the only reason a recall published months later can still reach a record already issued.

1. 01

   Take a test key

   Create a vk_test_ key in Settings. No call and no approval queue, on a Facility or Platform workspace: key creation checks the API entitlement before it looks at test or live, so a workspace without it is refused either way. Sandbox records answer with their environment attached so a test result can never be mistaken for a production one downstream.

2. 02

   Check a document

   POST the document to the check endpoint and read the four lanes back. Each lane reports whether it ran, did not apply, or could not verify, and a lane that produced no result never reads as one that passed.

3. 03

   Ask the gate

   POST the order to ClearGate and read Allow, Review, or Hold with the reasons that fired and your policy version pinned inside the decision.

4. 04

   Issue the passport

   POST to the passport endpoint with the lot and an order reference. An uncleared lot answers 409 with the reason, never a passport, which is the whole point of the release floor.

5. 05

   Subscribe to the signal

   Point a webhook at your endpoint and verify the HMAC signature on every delivery. A recall matching one of your lots arrives here, months after the paperwork was filed.

• The endpoint list below is the complete key-authed /v1 surface. The four that carry a worked request, response, and error table on this page are the integration path; the rest are listed with their contract summarised. Workspace administration, billing, and the operator console are not exposed and are not documented here.
• Every response describes DOCUMENTATION. Nothing on this surface asserts that a product is safe, effective, authentic, legal, or approved, and no endpoint returns a product judgment.
• Sandbox and production are separated by key prefix and every record answers with the environment it was created in. A sandbox passport can never be presented as a released one.

POST/v1/passports

Issue from a cleared lot with an order reference.

POST/v1/cleargate

One decision per order against the policy you set.

POST/v1/eligibility

Allow, Review, or Hold on whether a substance is eligible to compound for a facility type against the current FDA lists.

POST/v1/check

The document check, as an embeddable call.

POST/v1/seal-batches

Mint up to 500 serialized vial seals for one lot, optionally bound one-to-one to your own order numbers. Same plan entitlement as sealing from the dashboard.

GET/v1/seal-batches/{id}/labels

Fetch the labels for a minted batch as format=avery, thermal, or zpl. Avery and thermal return a PDF; zpl returns raw printer text for a direct feed.

GET/v1/network/directory

The public verified-source directory, ordered by the published documentation-coverage grade. Read-only, documented status only, never a recommendation.

GET/v1/network/source

One source's portable grade and its trust signals, by source id. Read-only.

POST/v1/network/route

A ship-to-state routing decision: Allow, Review, or Hold against the eligibility rules, for platforms embedding the network in their own ordering flow.

Unattended release is bounded per sweep and per account and bills through the same idempotent ledger, so a backlog of parked orders clearing at once cannot produce a wave of duplicate charges.

curl -X POST https://veritura.co/v1/passports \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"lot_id":"LOT-...","order_id":"ORD-1042"}'

# 200 -> a released, verifiable passport bound to the order
# 409 -> lot_pending_review (the lot is not cleared yet)

HTTP/1.1 200 OK

{
  "ok": true,
  "reused": false,
  "passport": {
    "id": "PASS-...",
    "environment": "production",
    "orderId": "ORD-1042",
    "supplierName": "...",
    "productName": "...",
    "lotNumber": "...",
    "coaId": "...",
    "reportId": "...",
    "reviewer": "Automated clear-gate",
    "releaseGate": "Released by account policy (API mint)",
    "status": "released",
    "publicShareId": "...",
    "lookupCode": "...",
    "evidenceRows": [...],
    "auditTrail": [...]
  }
}

# Abridged. The same record carries the supplier qualification
# snapshot, the verification links, and the output standard.

• Address the lot two ways

  Send lot_id for an explicit match, or send supplier plus product plus lot and the call resolves the logged lot by identity. Neither one matching answers 404 with the same instruction: provide lot_id, or supplier plus product plus lot to match a logged lot.

• order_id or customer_ref is required

  A passport with nothing to bind to is not a passport. One of the two must be present, and the reference you send is echoed on the record and on the page the buyer opens.

• Opaque references only

  customer_ref is screened before anything is written. A reference that reads as patient information is refused with phi_in_customer_ref and the instruction to use an order or PO number instead. There is no field on this call that carries a patient, a prescriber, or clinical content.

• A repeat is not a second passport

  The same order and lot called twice returns the record that already exists with reused set to true. A sandbox replay of an order that already holds a production passport returns that production record untouched, so a test run can never downgrade a customer's real one.

A call can also answer 404 when no lot matches, 400 on a missing order reference or on PHI in the customer ref, 401, and 429. The full table is below.

HTTP/1.1 409 Conflict

{
  "error": "This lot is not cleared.",
  "code": "lot_pending_review",
  "state": "pending_review"
}

ClearGate: Allow

Meets your policy

ClearGate: Review

Needs review

ClearGate: Hold

Does not meet policy

A ClearGate decision always means the documentation meets your policy. It never means Veritura approves the supplier.

curl -X POST https://veritura.co/v1/cleargate \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"supplier":"...","product":"...","lot":"...","order_id":"ORD-1042"}'

HTTP/1.1 200 OK

{
  "ok": true,
  "decision": {
    "decisionId": "cgd_...",
    "decision": "review",
    "label": "Needs review",
    "policy": { "id": "pol_...", "version": 3, "preset": "standard" },
    "supplier": "...",
    "lotId": "lot_...",
    "orderRef": "ORD-1042",
    "reasons": [
      { "level": "review",
        "code": "lot_pending",
        "detail": "The lot is pending review." }
    ],
    "evidence": {...},
    "environment": "production",
    "timestamp": "<ISO 8601>",
    "signature": "sha256=..."
  }
}

• Every reason names the rule that fired

  reasons is a list, not a score. Each entry carries the level that produced it, the policy rule's own code, and the sentence a person reads. Hold beats review, and review beats allow.

• The policy version is pinned into the record

  The decision stores the policy id, its version, and the preset it resolved from, so a decision made last quarter can be read against the policy that actually governed it rather than today's.

• A tamper-evident signed decision log

  Each decision is HMAC-signed and appended to a per-account hash chain that binds the previous decision's hash to this one's bytes. Altering any past decision breaks every later link.

• Presets, then bounded custom rules

  Strict, Standard, and Lenient are the presets. Custom policy is a bounded set of toggles and thresholds mapped to fields ClearGate actually evaluates, not a free-form rule language.

All three presets re-run the gate automatically when new evidence lands. Standard and Lenient also release the Passport on a policy Allow; Strict keeps the release with a person.

• Retrying a passport is safe

  Issuing against a lot that already has a passport returns the existing record with reused set to true, rather than minting a second one. A timeout you did not see the response to can be retried without creating a duplicate.

• The rate-limit bucket is your address, then the route

  On the five call-heavy routes the key narrows it further, so two keys from one address get their own allowance there. On eligibility and the three network routes it does not, so two keys behind one egress address share that route's bucket. Plan for the shared case if you call from fixed egress, and expect 429 with Retry-After at the ceiling.

• A lot resolves two ways

  Pass lot_id when you have it, or supplier plus product plus lot to match a lot you already logged. Neither matching answers 404 with the reason, never a guess.

• Test and live cannot mix

  A vk_test_ key resolves to sandbox and a vk_live_ key to production, and every record answers with the environment it was created in. A sandbox passport can never be presented downstream as a released one.

• Two keys, two environments

  A vk_test_ key resolves to sandbox and a vk_live_ key to production. Every record answers with the environment it was created in, so a sandbox result can never be mistaken for a production one downstream.

• The secret is shown once, and revocation is instant

  A key's secret is displayed at creation and never again. Rotate a key by creating a new one and revoking the old, which is a two-step you can do without talking to anyone, and a revoked key stops working immediately.

• Two gates, and a test key clears neither for free

  Key creation checks the API entitlement before it looks at the mode, so a workspace without it is refused for a test key on exactly the same terms as for a live one. A live key is then checked a second time for a production workspace, so a workspace not yet set up for production cannot issue a billable passport by accident.

• Sandbox first

  Sandbox records are non-billable, so an integration can be built end to end, including the webhook path, before a single production passport exists. The key itself comes with the plan; the sandbox records it writes cost nothing.

supplier.alert only emails on a hard match: a lot-level hit, or a confirmed or strong firm-name match. A weak name-only match still surfaces in the workspace for review, but never triggers an email off a name collision.

POST /veritura-webhook HTTP/1.1
Content-Type: application/json
User-Agent: Veritura-Webhooks/1.0
X-Veritura-Event: passport.issued
X-Veritura-Signature: sha256=<hex digest>

{
  "event": "passport.issued",
  "created": "<ISO 8601>",
  "data": {
    "passportId": "PASS-...",
    "orderId": "ORD-1042",
    "lotId": "lot_...",
    "environment": "production",
    "verifyUrl": "/verify/..."
  }
}

• Verify the signature, not the source address

  X-Veritura-Signature is sha256= followed by an HMAC-SHA256 of the exact request body, computed with the signing secret for that endpoint. Recompute it over the raw bytes before you parse them.

• The signing secret is returned exactly once

  It is shown when the webhook is registered and never again. A lost secret is replaced by registering the endpoint again, the same rule the API keys follow.

• Answer 2xx, quickly

  Any 2xx marks the delivery successful. A delivery that has not been answered in five seconds is recorded as failed, so acknowledge first and do your work afterwards.

• Prove it works before it matters

  Settings sends a signed sample event to a single endpoint on demand, so the receiving side can be confirmed against a real signature before a real event ever fires.