API reference

Version 2. Live at https://api.provkeep.com/v2, sandbox at https://sandbox.provkeep.com/v2. The same as a file: openapi.json.

Endpoints

CallWhat it doesKey
POST /v2/checksCheck an order. Always answers 200 with an answer, including when we could not check it, so a checkout never waits on us. Records the order unless preview is true.Yes
GET /v2/checks/{id}The answer a check gave, by its check ID, for this account only.Yes
POST /v2/orders/{reference}/eventsWhat happened after the check: shipped (with a lot per line), refunded, cancelled or edited, named by your own order number. Appended, never written over the answer.Yes
GET /v2/rulesets/currentThe version and build time of the rules every answer is read from today.No
GET /v2/statusWhether the service can reach its data, how old the rules are, and how many records are waiting to be written.No

Keys come from Settings, Keys, or from a customer signing in through Connect Provkeep. A pk_test_ key works only on the sandbox, which has its own database; a pk_live_ key works only on live.

The order you send

JSON. There is no field for a patient's name, birth date, address or record number. A field we do not know is dropped and counted, and its value is not kept.

FieldTypeWhat it is
codestringYour own order or prescription reference. A value shaped like personal information (an email address, a date, a Social Security number pattern, or a phone length number) is replaced by the check ID and not kept.
eventstringWhat happened: order_created, prescription_signed, order_shipped, order_updated. Anything else is read as order_created.
linesarrayThe products on the order, at most 50. Each line is described below.
patient_statestringThe two letter US state the order goes to. Only the state is read: there is no field for a city, ZIP code or address, and an unknown field is dropped without its value being kept.
prescriber_statestringThe two letter state the prescriber is in, when it differs.
pharmacy_statestringThe two letter state the pharmacy ships from.
pharmacy_typestringHow the product is dispensed, in your own words (for example 503A or 503B). Read against a vocabulary; an unknown value falls back to the account's setting.
consult_typestringHow the patient was seen: in_person, video, phone, async_questionnaire. Used to match rules limited to one kind of consult.
purposestringWhat the product is for, as a code: treatment, weight_management, athletic_performance, wellness, other. Never free text.
previewbooleantrue checks the order without recording it.
placed_atstring (date-time)When the order was placed. Refused if more than a day ahead.
consentobjectThe consent shown at checkout: the wording or its sha256 as terms_sha256, terms_version, gate (block, observe, record_only), shown_at and accepted_at. Never the customer.

Each line

FieldTypeWhat it is
line_idstringYour own line reference. Defaults to the line's position.
peptidestringThe product, by any name or alias we hold. Required.
namestringThe product name as you sell it, kept for your record.
dosage_formstringFor example injectable, oral, nasal, topical.
routestringRoute of administration, when it matters to a rule.
blendbooleantrue when the line is a blend of more than one product.
ingredientsarray of stringA blend's or stack's ingredients, each read on its own. At most 20.
lot_numberstringThe lot it ships from, for your record. A value shaped like personal information is dropped.
device_suppliedbooleantrue when a device such as a pen or syringe ships with it. Kept for your record.
quantitynumberHow many units. A positive number.

A real request and the answer it gets, run through the engine as this page loads, are on the developer page.

Headers

You sendWhat it does
AuthorizationBearer and your key. pk_test_ keys work only on the sandbox; pk_live_ keys only on live.
Idempotency-KeyYour own order ID. A retry with the same key and body replays the first answer and cannot record twice; the same key with a different body is refused with 422.
Provkeep-AccountFor a platform key linked to several brands: the account this check is for.
We send backWhat it says
Provkeep-VersionThe API version that answered: 2.
Provkeep-Environmentlive or sandbox.
X-Request-IdQuote it when you write to us.
X-RateLimit-Limit, -Remaining, -ResetYour key's allowance on POST /checks.

When an order was not checked

The answer says checked: false, with a reason_code and a sentence in why. hold_requested is false: our failure never holds an order.

reason_codeHTTPWhat it means
no_api_key401No key was sent.
unknown_api_key401The key is not ours, or was revoked.
wrong_environment401A test key on live, or a live key on the sandbox.
account_not_linked200Provkeep-Account names an account this key may not act for.
rate_limited200Too many checks at once. Retry with the same Idempotency-Key.
body_not_json200The body was not a JSON object.
not_on_this_plan200The account's plan does not include order checking.
account_inactive200The subscription is not active.
service_unavailable200We could not check it. Nothing is held.

Rate limit

200 checks a second per key, with bursts up to 500. Over the limit, the answer is a 200 with reason_code: rate_limited, so retry with the same Idempotency-Key.

Webhook events

Add an address in Settings, Connections. Each delivery is signed in the Svix format (webhook-id, webhook-timestamp, webhook-signature) and tried again for about a day and a half.

EventWhenSent today
rule.changedA state or federal page we watch changed, and the change names a product you sell.Yes
order.answer_changedAn order we already answered would be answered differently today.Not yet. Nothing sends this one yet. It needs a nightly re-read of answered orders, which is not built.
record.postmarkedYour records were timestamped by the outside authorities, with the day's fingerprint.Yes

How the API changes

The version is in the address
Every call goes to /v2. Every answer carries Provkeep-Version: 2.
What we add without notice
New optional request fields, new response fields, new values in a list such as a new reason_code or a new webhook event, and new endpoints. Your code should ignore what it does not know.
What we never change inside a version
We do not remove or rename a field, change a field's type or meaning, make an optional field required, or change an endpoint's address. Those changes only arrive as a new version.
Notice before an old version stops
When a new version ships, the old one keeps answering for at least 12 months. We announce the date on the changelog and email every account that called the old version in the previous 90 days.
The rules themselves change every night
That is the product, not a change to the API. Each answer names the ruleset_version it was read from, and GET /v2/rulesets/current says which is current.
Security fixes
If a change is needed to protect data, it can ship sooner. We say so on the changelog the same day.

Changelog

2026-11-19Published this reference, the change policy, /openapi.json and the status page. Added Connect Provkeep: platforms register an app in Settings, Connections, and their customers sign in to their own accounts.

Whether the service is answering now: the status page. What we receive and keep: security and data.