out, low, in_stock or unknown), always with the time it was true. See
Stock bands for what each one means.
Which pharmacies can you see?
You never see “all pharmacies”. You see the pharmacies that have chosen to be listed and have agreed to a connection with your organization that includes the permission you are using. How a connection is made, and what a pharmacy can grant, is on Connections. In short:- A live organization key sees the pharmacies connected to it.
- A test key sees your workspace’s own seeded, fictional pharmacies, so you can build before any real pharmacy has connected.
- A clinic’s own key gets an empty result from the network routes (
/v1/listings/pharmaciesand/v1/listings/search). A clinic reads its own data, not a network of other clinics. - A pharmacy that is not listed, or an item it has excluded from its listing, never appears. There is no way to ask for it.
bandisout,low,in_stockorunknown.unknownmeans the pharmacy’s own till has not reported recently enough to trust, so we say so rather than show a stale answer. Show it as its own state, never asout. See Stock bands.as_ofis when that band was last known to be true. Show it. A band without its age looks fresher than it is.
Bring pharmacies to the network: your referral link
Every verified workspace has its own referral link in the developer portal, under Referrals. Share it with a pharmacy: when the pharmacy signs up through it, we remember that you introduced it. Admins and owners see the link; a workspace that is not verified yet is told that verification comes first. A referral gives you nothing on its own: no access, no connection and no listing. The pharmacy decides. At first run it sees your listing request pre-filled, with Approve and Not now as equal choices, and a Not now leaves a quiet reminder in its settings. The Referrals page lists the pharmacies you referred by status only: signed up, subscribed or listed. A listed pharmacy also shows a coverage band (Not started, Partial, Good or Strong), which says how much of its
catalogue is linked to the shared medicine index. You never see stock, sales or customers, and a pharmacy that declined to
be listed shows as signed up, nothing more.
The reward. A referred pharmacy that becomes a paying customer within 90 days of signing up connects to your workspace
free for 6 months, counted from its first payment. During those months it is not counted in your connected-clinic
usage, and the Referrals page shows Free until and the date. See Usage and billing.
List listed pharmacies
listing.profile:read. Returns each pharmacy’s profile (no stock), a page at a time.
Search for a medicine
listing.availability:read. One request searches only the pharmacies you can reach. Results are capped
at 50 and are not paginated: narrow the search instead.
Any other field in the body is refused with
400 and the field’s name.
- With
near, nearest pharmacies come first. A pharmacy with no pin is not removed byradius_km: it hasdistance_km: nulland comes last. - A test key matches identifiers
gtinandnafdac, and names (q).ndc,rxcuiandpartneridentifiers find nothing in the sandbox and return an emptydatalist.
Tell us whether a result was right
listing.availability:read. After you (or your user) find out whether a search result was true, report it. The
report holds no user data: only the item you searched for, optionally the pharmacy, and the outcome.
id is the id of your report. With a test key the request is checked and answered with an id, but nothing is stored,
because a sandbox pharmacy is not a real one. An unknown outcome, or a missing item, is refused with 400.
One pharmacy’s items
listing.availability:read. Use this when you already hold a connection to the pharmacy and want all of its
listed items with their bands, for example to fill a local cache. It goes through the same per-clinic checks as
Inventory. Only items the pharmacy has chosen to list appear.
store_url as on a search result: this product’s page in the pharmacy’s online store, or null.
A test key reaches only your sandbox’s own pharmacy: the clinic_id that GET /v1/me reports.
One pharmacy’s profile
listing.profile:read. The same profile fields as the pharmacy list, for one pharmacy. The response is the
profile itself, with no data wrapper.
open_now, plus:
Store links
Pharmacies can run an online store.store_url is how you send a person to it, and it is null unless a link is safe to
show. A pharmacy-level store_url (the directory and the profile) is the store’s front page. A product-level store_url
(a search result or an item) is that product’s own page.
A link is returned only when all of these hold:
- the pharmacy has switched its store on, and the store can take payment;
- the pharmacy is not on the listing-only plan, and keeps its stock in ClinikEHR (a pharmacy that sends a stock report from another system does not advertise a store, because the store sells from ClinikEHR’s own stock);
- for a product link, the item is listed and not withheld by the pharmacy, and an active, public store product is built on exactly that item.
null.
Things to know
- You get what the pharmacy allowed, and no more. There is no exact quantity, price, cost or customer information on any of these routes.
- A pharmacy you cannot reach looks like a pharmacy that does not exist. On the two per-pharmacy routes the answer is
404withcode: "not_found": no connection, a revoked connection, or a wrong id are never told apart. - A missing permission is
403withcode: "scope_missing". The pharmacy granted your connection some permissions but not this one. See Permissions. - Bad input is
400withcode: "invalid_request", with anerrorslist naming each field. An unknown query parameter is refused too. All error codes are on Errors. - Rate limits are per key. Network searches count like any other request. Read
RateLimit-Remainingand see Rate limits. - When something changes you can be told instead of asking again. See Events.
Recipes
Show “pharmacies near me that have this medicine”.POST /v1/listings/searchwith the medicine’s barcode ({ "system": "gtin", … }) if you have one, otherwise its name, plus the user’snearpoint.- Show
in_stockandlowfirst, and showunknownas “may be out of date”, never as out of stock. Showas_ofnext to each. - When the user confirms or contradicts a result, send
POST /v1/listings/feedbackwith the matchingoutcome.
GET /v1/listings/pharmacies until has_more is false, and store each pharmacy by clinic_id. To refresh one pharmacy later, read its profile and compare updated_at.
Keep a local copy of one pharmacy’s catalogue. Read GET /v1/clinics/{clinic_id}/listing/items once, then call it again with updated_since set to the time of your last read. Treat each band as only as fresh as its as_of.