Getting started
The Priorly API lets your own system work with a business's Priorly account. This page covers what every call needs: the base URL, an API key and the headers, sandbox and live, and what to do when a call fails. Then follow the guide for what you're building.
You need two things, both from the business's Priorly account.
- Base URL
https://api.priorly.io/v1 - The same for every business.
- API key
prly_test_…prly_live_… - A business admin makes it in Priorly › Settings › API keys, for one location, with the scopes your system needs. Each guide says which scopes its calls need. Use a sandbox key, starting
prly_test_, until you go live.
Each key is shown once, so put it straight into your secret manager. Start with a sandbox key: see Live and sandbox, below.
The rules that matter most
- Call the API from your server only. Never put a key or token in a browser, an app, a URL, a log line or a prompt to an AI tool.
- Send an
Idempotency-Keyheader on every POST. Reuse a key only to retry the same request after a timeout or a5xx. - Branch on
error.code, never onerror.message. Messages are written for people and may change.
Headers
What you send
AuthorizationBearer and your API key, on every request.
Content-Typeapplication/json, with every request that has a body.
Idempotency-KeyOn every POST. Reuse it only to retry the same request after a timeout or a 5xx.
Priorly-Prescriber-TokenThe prescriber's signing token, on sign requests.
What you get back
Priorly-Request-IdOn every answer. Send it to Priorly when something doesn't work.
Idempotent-Replayedtrue when a retry gets the first answer back.
Retry-AfterOn a 429, how many seconds to wait before you retry.
Every API key is either live or sandbox. Build and test with a sandbox key, then swap in a live key: the calls, fields and answers are the same.
| What | Sandbox key | Live key |
|---|---|---|
| Starts with | prly_test_ | prly_live_ |
| How to get one | A business admin, in Priorly › Settings › API keys › Create key, Mode: Sandbox | The same, Mode: Live |
| Base URL | https://api.priorly.io/v1 | The same |
| What you add | Test records at the business, kept apart from its real ones. Staff see them in Priorly's test mode | The business's real records |
| Webhooks | Sent to your endpoints with "livemode": false | Sent with "livemode": true |
Each guide says what the sandbox does with its own calls, like where a test prescription goes.
The two never mix
A sandbox key can't see live records, and a live key can't see sandbox ones. The same externalId or externalReference can be used in each, so test data never clashes with real data.
Use made-up patients in the sandbox
Never put real patient details there.
Going live
Ask the business for a live key, put it in your secret manager in place of the sandbox key, and check your webhook handler treats "livemode": false events as tests. Sandbox records don't move across: add real ones with the live key. You can keep the sandbox key for your test environment.
Every error has the same shape, {"error":{"code","message",…,"requestId"}}. Each guide lists the codes its calls can return and what to do with each. These apply to every call:
Too many requests, or a fault at Priorly.
Retry with backoff and the same Idempotency-Key. A 429 says how long to wait in Retry-After.
The call timed out, so you can't tell whether it worked.
Send it again with the same Idempotency-Key. If the first one got through, you get its answer back with Idempotent-Replayed: true, and it isn't done twice.
Any other 4xx means the request needs fixing, so don't repeat it unchanged.
When something doesn't work, send Priorly the requestId from the error, or the Priorly-Request-Id header on any answer. Never send a key, token, PIN or patient details.