> For the complete documentation index, see [llms.txt](https://refill-1.gitbook.io/refill/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://refill-1.gitbook.io/refill/introduction.md).

# Introduction

Introduction to the FindMyMed medicine request API

The FindMyMed API lets approved partners — insurers, employers, clinics, chat and voice assistants, and other health-service providers — submit medicine requests into Refill Health Tech's fulfilment pipeline and follow each request through to delivery.

A request created through the API is picked up by Refill's operations team, sourced from partner pharmacies, and delivered to (or collected by) the patient. You receive a tracking ID at submission and can poll it for delivery status at any time.

### Endpoints

| Endpoint                                             | What it does                                                                                                                                                                                                             | Lifecycle     |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| **Bulk Request** — `POST /findmymed/bulk/`           | Submit one request with one or more structured medicine items (name, strength, quantity, dosage, preferred brand), plus patient, requester, fulfilment and partner-reference details. **Use this for new integrations.** | Preferred     |
| **Single Request** — `POST /findmymed/single/`       | Submit one free-text medicine request with the patient's number and an optional prescription image.                                                                                                                      | Compatibility |
| **Track Requests** — `POST /findmymed/track/`        | Look up the medicine name and current delivery status of a request by its tracking ID.                                                                                                                                   | Active        |
| **Approve a Request** — `POST /esr/request/confirm/` | Review the quoted medicine and delivery cost, then authorise the request for delivery. Nothing is dispatched until it is approved.                                                                                       | Active        |

Instead of polling, you can have these lifecycle changes pushed to your own HTTPS endpoint — see Webhooks.

Additional endpoint:

| Endpoint                       | What it does                                                                           | Lifecycle |
| ------------------------------ | -------------------------------------------------------------------------------------- | --------- |
| **RDDE v1** — `POST /rdde/v1/` | Refill Drug Definition Engine: returns a plain-language definition for a drug keyword. | Beta      |

All endpoints accept and return JSON over HTTPS. Submission endpoints and RDDE are authenticated with a partner API key; tracking needs only the tracking ID.

### How to read this guide

1. **Before you dive in** — base URL, request conventions, and what to expect from responses.
2. **Authorization** — how to send your API key.
3. **Single / Bulk / Track / Approve** — one page per endpoint, with field tables, sample requests, and sample responses.
4. **Webhooks** — receive lifecycle events instead of polling.
5. **Codes** — the `status` values the API returns in its JSON body.

Last updated: September 2026. This guide reflects the endpoints as deployed in production.