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
| Call | What it does | Key |
|---|---|---|
POST /v2/checks | Check 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}/events | What 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/current | The version and build time of the rules every answer is read from today. | No |
GET /v2/status | Whether 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.
| Field | Type | What it is |
|---|---|---|
code | string | Your 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. |
event | string | What happened: order_created, prescription_signed, order_shipped, order_updated. Anything else is read as order_created. |
lines | array | The products on the order, at most 50. Each line is described below. |
patient_state | string | The 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_state | string | The two letter state the prescriber is in, when it differs. |
pharmacy_state | string | The two letter state the pharmacy ships from. |
pharmacy_type | string | How 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_type | string | How the patient was seen: in_person, video, phone, async_questionnaire. Used to match rules limited to one kind of consult. |
purpose | string | What the product is for, as a code: treatment, weight_management, athletic_performance, wellness, other. Never free text. |
preview | boolean | true checks the order without recording it. |
placed_at | string (date-time) | When the order was placed. Refused if more than a day ahead. |
consent | object | The 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
| Field | Type | What it is |
|---|---|---|
line_id | string | Your own line reference. Defaults to the line's position. |
peptide | string | The product, by any name or alias we hold. Required. |
name | string | The product name as you sell it, kept for your record. |
dosage_form | string | For example injectable, oral, nasal, topical. |
route | string | Route of administration, when it matters to a rule. |
blend | boolean | true when the line is a blend of more than one product. |
ingredients | array of string | A blend's or stack's ingredients, each read on its own. At most 20. |
lot_number | string | The lot it ships from, for your record. A value shaped like personal information is dropped. |
device_supplied | boolean | true when a device such as a pen or syringe ships with it. Kept for your record. |
quantity | number | How 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 send | What it does |
|---|---|
Authorization | Bearer and your key. pk_test_ keys work only on the sandbox; pk_live_ keys only on live. |
Idempotency-Key | Your 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-Account | For a platform key linked to several brands: the account this check is for. |
| We send back | What it says |
|---|---|
Provkeep-Version | The API version that answered: 2. |
Provkeep-Environment | live or sandbox. |
X-Request-Id | Quote it when you write to us. |
X-RateLimit-Limit, -Remaining, -Reset | Your 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_code | HTTP | What it means |
|---|---|---|
no_api_key | 401 | No key was sent. |
unknown_api_key | 401 | The key is not ours, or was revoked. |
wrong_environment | 401 | A test key on live, or a live key on the sandbox. |
account_not_linked | 200 | Provkeep-Account names an account this key may not act for. |
rate_limited | 200 | Too many checks at once. Retry with the same Idempotency-Key. |
body_not_json | 200 | The body was not a JSON object. |
not_on_this_plan | 200 | The account's plan does not include order checking. |
account_inactive | 200 | The subscription is not active. |
service_unavailable | 200 | We 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.
| Event | When | Sent today |
|---|---|---|
rule.changed | A state or federal page we watch changed, and the change names a product you sell. | Yes |
order.answer_changed | An 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.postmarked | Your 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-19 | Published 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.