# Create Plant
Source: https://docs.pharmachains.ai/api-reference/endpoint/create

POST /plants
Creates a new plant in the store



# Delete Plant
Source: https://docs.pharmachains.ai/api-reference/endpoint/delete

DELETE /plants/{id}
Deletes a single plant based on the ID supplied



# Search medicines
Source: https://docs.pharmachains.ai/api-reference/endpoint/get

Find a medicine and get a ranked list of pharmacies that have it in stock

## POST /medicines/search

Returns a ranked list of verified pharmacies that have the specified medicine in stock within the given radius of the patient's location. Results are sorted by proximity by default.

## Request

<CodeGroup>
  ```javascript fetch theme={null}
  const response = await fetch(
    "https://api.pharmachains.ai/v1/medicines/search",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_API_KEY"
      },
      body: JSON.stringify({
        query: "Metformin 500mg",
        location: { lat: 6.5244, lng: 3.3792 },
        radius_km: 10,
        limit: 10
      })
    }
  );

  const { data } = await response.json();
  console.log(data.results);
  ```

  ```javascript axios theme={null}
  import axios from "axios";

  const { data } = await axios.post(
    "https://api.pharmachains.ai/v1/medicines/search",
    {
      query: "Metformin 500mg",
      location: { lat: 6.5244, lng: 3.3792 },
      radius_km: 10,
      limit: 10
    },
    {
      headers: {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  );

  console.log(data.results);
  ```
</CodeGroup>

### Body parameters

| Parameter   | Type    | Required | Description                                                |
| ----------- | ------- | -------- | ---------------------------------------------------------- |
| `query`     | string  | Yes      | Medicine name, generic or brand. Minimum 2 characters.     |
| `location`  | object  | Yes      | Patient's `lat` and `lng` coordinates.                     |
| `radius_km` | integer | No       | Search radius in kilometres. Default: `10`. Max: `50`.     |
| `limit`     | integer | No       | Max number of results to return. Default: `10`. Max: `50`. |

## Response

### 200 — Success

```json theme={null}
{
  "success": true,
  "data": {
    "query": "Metformin 500mg",
    "total": 2,
    "results": [
      {
        "pharmacy_id": "ph_01J...",
        "name": "HealthPlus Pharmacy, Lekki",
        "address": "14 Admiralty Way, Lekki Phase 1, Lagos",
        "in_stock": true,
        "price_ngn": 2400,
        "distance_km": 1.2,
        "estimated_delivery_minutes": 35
      },
      {
        "pharmacy_id": "ph_02K...",
        "name": "MedPlus Pharmacy, VI",
        "address": "23 Adeola Odeku Street, Victoria Island, Lagos",
        "in_stock": true,
        "price_ngn": 2550,
        "distance_km": 3.1,
        "estimated_delivery_minutes": 55
      }
    ]
  }
}
```

### Response fields

| Field                        | Type    | Description                                                   |
| ---------------------------- | ------- | ------------------------------------------------------------- |
| `pharmacy_id`                | string  | Unique pharmacy identifier. Use this when creating a request. |
| `name`                       | string  | Pharmacy display name and branch location.                    |
| `address`                    | string  | Full street address of the pharmacy.                          |
| `in_stock`                   | boolean | Whether the medicine is currently available.                  |
| `price_ngn`                  | integer | Price in Nigerian Naira.                                      |
| `distance_km`                | float   | Distance from the provided patient location.                  |
| `estimated_delivery_minutes` | integer | Estimated time from order to patient delivery.                |

### 400 — Bad request

```json theme={null}
{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "The 'query' field is required.",
    "status": 400
  }
}
```

### 404 — No results

```json theme={null}
{
  "success": false,
  "error": {
    "code": "medicine_not_found",
    "message": "No pharmacies found for the specified query and location.",
    "status": 404
  }
}
```

<Tip>
  Save the `pharmacy_id` from your preferred result and pass it directly to [POST /requests](/api-reference/endpoint/create) to kick off fulfilment.
</Tip>


# New Plant
Source: https://docs.pharmachains.ai/api-reference/endpoint/webhook

WEBHOOK /plant/webhook
Information about a new plant added to the store



# Introduction
Source: https://docs.pharmachains.ai/api-reference/introduction

Everything you need to know before making your first API call

## Overview

The Pharmachain Partner API is a RESTful API. All requests and responses
use JSON. It is designed for HMO platforms and healthtech products that
need to search for medicines, submit fulfilment requests, and track orders
on behalf of enrollees.

<CardGroup>
  <Card title="Search medicines" icon="magnifying-glass" href="/api-reference/endpoint/search">
    Find drugs by name and get a ranked list of pharmacies with stock,
    pricing, and delivery estimates.
  </Card>

  <Card title="Create a request" icon="bag-shopping" href="/api-reference/endpoint/create">
    Submit a medicine fulfilment request for an enrollee and kick off
    the pharmacy workflow.
  </Card>

  <Card title="Get request status" icon="location-dot" href="/api-reference/endpoint/get">
    Poll for the current status and full timeline of any active
    medicine request.
  </Card>

  <Card title="Cancel a request" icon="ban" href="/api-reference/endpoint/delete">
    Cancel a pending request before it progresses to dispensing.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/endpoint/webhook">
    Receive real-time push notifications when a request status changes —
    no polling required.
  </Card>
</CardGroup>

## Base URLs

```
Sandbox:    https://sandbox-api.pharmachains.ai/v1
Production: https://api.pharmachains.ai/v1
```

<Tip>
  Always develop and test against the sandbox URL. Switch to production
  only when your integration is stable.
</Tip>

## Authentication

All endpoints require a Bearer token in the `Authorization` header.

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

See the [Authentication guide](/development) for how to generate keys,
manage scopes, and rotate credentials.

## Request format

All `POST` and `PUT` requests must include a JSON body and the
`Content-Type` header.

```http theme={null}
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```

`GET` and `DELETE` requests use path parameters or query strings — no body required.

## Response format

Every response follows the same envelope structure.

**Success:**

```json theme={null}
{
  "success": true,
  "data": { }
}
```

**Error:**

```json theme={null}
{
  "success": false,
  "error": {
    "code": "medicine_not_found",
    "message": "No results found for the specified query and location.",
    "status": 404
  }
}
```

## Versioning

The current API version is **v1**, included in every base URL. When
breaking changes are introduced, a new version will be released and
all partners will receive advance notice before the old version is deprecated.


# Authentication
Source: https://docs.pharmachains.ai/development

How to authenticate requests and manage sandbox vs production environments

## API keys

All requests to the Pharmachain Partner API must include your API key as a
Bearer token in the `Authorization` header.

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Generate and manage your keys from **Settings → API keys** in the
[Partner Portal](https://partners.pharmachains.ai).

<Warning>
  Treat your API key like a password. Never commit it to version control,
  never include it in frontend or mobile code. Rotate it immediately if
  you suspect it has been exposed.
</Warning>

## Environments

Pharmachain provides two environments. Use sandbox while building and testing —
no real pharmacy orders will be placed.

<CardGroup>
  <Card title="Sandbox" icon="flask">
    `https://sandbox-api.pharmachains.ai/v1`

    Safe for development and testing. Returns realistic mock data.
    No real pharmacies or fulfilment involved.
  </Card>

  <Card title="Production" icon="circle-check">
    `https://api.pharmachains.ai/v1`

    Live environment. Requests are routed to real verified pharmacies
    and fulfilled end-to-end.
  </Card>
</CardGroup>

<Note>
  Your sandbox and production API keys are different. You'll find both
  in the Partner Portal under **Settings → API keys**.
</Note>

## Key rotation

You can generate a new key at any time without downtime.

<AccordionGroup>
  <Accordion icon="rotate" title="How to rotate your API key">
    1. In the Partner Portal, go to **Settings → API keys**.
    2. Click **Generate new key** — your existing key stays active.
    3. Update the key in your production environment variables.
    4. Confirm the new key is working.
    5. Revoke the old key.

    <Tip>
      Never delete the old key before confirming the new one is live.
      Both keys are valid simultaneously during the switchover window.
    </Tip>
  </Accordion>
</AccordionGroup>

## Scopes

Each API key can be scoped to specific permissions. When generating a key,
select only the scopes your integration requires.

| Scope              | What it allows                                |
| ------------------ | --------------------------------------------- |
| `medicines:search` | Query medicine availability across pharmacies |
| `requests:create`  | Submit new medicine fulfilment requests       |
| `requests:read`    | Read request status and timeline              |
| `requests:cancel`  | Cancel pending requests                       |
| `webhooks:manage`  | Register and manage webhook endpoints         |

## Error reference

| HTTP status | Error code            | Meaning                                             |
| ----------- | --------------------- | --------------------------------------------------- |
| `401`       | `invalid_api_key`     | Key is missing, malformed, or has been revoked      |
| `401`       | `expired_api_key`     | Key has passed its expiry date — rotate immediately |
| `403`       | `insufficient_scope`  | Key does not have permission for this action        |
| `429`       | `rate_limit_exceeded` | You've exceeded the allowed request rate            |

## Rate limits

| Environment | Requests / minute | Requests / day |
| ----------- | ----------------- | -------------- |
| Sandbox     | 60                | 5,000          |
| Production  | 300               | 100,000        |

<Note>
  If your integration requires higher production limits, contact your
  Pharmachain account manager at [support@pharmachains.ai](mailto:support@pharmachains.ai).
</Note>


# Introduction
Source: https://docs.pharmachains.ai/index

Welcome to the Pharmachain Partner API

## Setting up

The Pharmachain Partner API lets HMO platforms and healthtech products connect
directly to Nigeria's largest verified pharmacy network. Search for medicines
in real time, submit fulfilment requests on behalf of enrollees, and track
every order from submission to delivery — all through a single, clean REST API.

<Card title="Start here" icon="rocket" href="/quickstart">
  Follow our quickstart guide and make your first live API call in under 5 minutes.
</Card>

## What you can do with this API

Everything your HMO integration needs — medicine availability, order fulfilment,
real-time tracking, and prescription handling — exposed through clean, predictable endpoints.

<Columns>
  <Card title="Medicine search" icon="magnifying-glass" href="/api-reference/endpoint/search">
    Query our database of drugs and receive a ranked list of pharmacies that
    have them in stock, along with pricing and proximity to the patient's location.
  </Card>

  <Card title="Request fulfilment" icon="bag-shopping" href="/api-reference/endpoint/create">
    Submit a medicine request for an enrollee. Pharmachain routes the order to
    the closest available verified pharmacy and manages the fulfilment flow end-to-end.
  </Card>

  <Card title="Real-time status tracking" icon="location-dot" href="/api-reference/endpoint/get">
    Poll for live updates on any active request, or receive instant push
    notifications via webhooks whenever a request status changes.
  </Card>

  <Card title="Prescription management" icon="file-medical" href="/api-reference/endpoint/create">
    Attach prescriptions to requests as structured data or file uploads.
    Pharmacies receive them digitally — no faxes, no lost papers.
  </Card>
</Columns>

## Get started

<Columns>
  <Card title="Quickstart" icon="bolt" href="/quickstart">
    Make your first live medicine search request in under 5 minutes.
    No prior Pharmachain experience needed.
  </Card>

  <Card title="Authentication" icon="lock" href="/development">
    Learn how API keys and Bearer tokens work, and how to keep your
    integration secure in both sandbox and production.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/introduction">
    Browse every endpoint, inspect request and response schemas, and
    test calls directly in your browser.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/endpoint/webhook">
    Receive real-time push notifications instead of polling. Set up
    your webhook endpoint and verify signatures.
  </Card>
</Columns>

## Need help?

<Card title="Contact partner support" icon="headset" href="mailto:support@pharmachains.ai">
  Reach the Pharmachain integrations team directly. We typically respond within one business day.
</Card>


# Quickstart
Source: https://docs.pharmachains.ai/quickstart

Make your first Pharmachain API call in under 5 minutes

## Get started in three steps

Get your API key, make your first medicine search, and submit a test request.

### Step 1: Get your API key

<AccordionGroup>
  <Accordion title="Create a partner account" icon="user">
    If you don't have one yet, sign up at the [Pharmachain Partner Portal](https://partners.pharmachains.ai). Once your account is approved, you'll land on the dashboard.
  </Accordion>

  <Accordion title="Generate your API key" icon="key">
    1. In the Partner Portal, go to **Settings → API keys**.
    2. Click **Generate new key** and give it a name (e.g. `dev-integration`).
    3. Copy the key and store it somewhere safe — you won't be able to view it again.

    <Warning>
      Never expose your API key in frontend code, mobile apps, or public repositories. All Pharmachain API calls must be made server-side.
    </Warning>
  </Accordion>
</AccordionGroup>

### Step 2: Search for a medicine

<AccordionGroup>
  <Accordion title="Send your first search request" icon="magnifying-glass">
    The search endpoint takes a medicine name and a patient location, and returns a ranked list of nearby pharmacies that have the drug in stock.

    <CodeGroup>
      ```javascript fetch theme={null}
          const response = await fetch("https://api.pharmachains.ai/v1/medicines/search", {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
              "Authorization": "Bearer YOUR_API_KEY"
            },
            body: JSON.stringify({
              query: "Metformin 500mg",
              location: { lat: 6.5244, lng: 3.3792 },
              radius_km: 10
            })
          });

          const data = await response.json();
          console.log(data.results);
      ```

      ```javascript axios theme={null}
          import axios from "axios";

          const { data } = await axios.post(
            "https://api.pharmachains.ai/v1/medicines/search",
            {
              query: "Metformin 500mg",
              location: { lat: 6.5244, lng: 3.3792 },
              radius_km: 10
            },
            {
              headers: {
                "Authorization": "Bearer YOUR_API_KEY"
              }
            }
          );

          console.log(data.results);
      ```
    </CodeGroup>

    A successful response looks like this:

    ```json theme={null}
        {
          "success": true,
          "data": {
            "query": "Metformin 500mg",
            "total": 2,
            "results": [
              {
                "pharmacy_id": "ph_01J...",
                "name": "HealthPlus Pharmacy, Lekki",
                "in_stock": true,
                "price_ngn": 2400,
                "distance_km": 1.2,
                "estimated_delivery_minutes": 35
              },
              {
                "pharmacy_id": "ph_02K...",
                "name": "MedPlus Pharmacy, VI",
                "in_stock": true,
                "price_ngn": 2550,
                "distance_km": 3.1,
                "estimated_delivery_minutes": 55
              }
            ]
          }
        }
    ```

    <Tip>
      Use the sandbox base URL `https://sandbox-api.pharmachains.ai/v1` while testing — no real pharmacy orders will be placed.
    </Tip>
  </Accordion>
</AccordionGroup>

### Step 3: Submit a medicine request

<AccordionGroup>
  <Accordion title="Create a fulfilment request" icon="bag-shopping">
    Once your HMO platform has selected a pharmacy from the search results, submit a request to kick off fulfilment. Use the `pharmacy_id` returned from the search.

    <CodeGroup>
      ```javascript fetch theme={null}
          const response = await fetch("https://api.pharmachains.ai/v1/requests", {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
              "Authorization": "Bearer YOUR_API_KEY"
            },
            body: JSON.stringify({
              enrollee_id: "enr_abc123",
              pharmacy_id: "ph_01J...",
              items: [
                {
                  medicine: "Metformin 500mg",
                  quantity: 30,
                  unit: "tablets"
                }
              ],
              delivery_address: {
                street: "14 Admiralty Way",
                city: "Lekki",
                state: "Lagos"
              }
            })
          });

          const data = await response.json();
          console.log(data.request_id); // req_xyz789
          console.log(data.status);     // "pending"
      ```

      ```javascript axios theme={null}
          import axios from "axios";

          const { data } = await axios.post(
            "https://api.pharmachains.ai/v1/requests",
            {
              enrollee_id: "enr_abc123",
              pharmacy_id: "ph_01J...",
              items: [
                {
                  medicine: "Metformin 500mg",
                  quantity: 30,
                  unit: "tablets"
                }
              ],
              delivery_address: {
                street: "14 Admiralty Way",
                city: "Lekki",
                state: "Lagos"
              }
            },
            {
              headers: {
                "Authorization": "Bearer YOUR_API_KEY"
              }
            }
          );

          console.log(data.request_id); // req_xyz789
          console.log(data.status);     // "pending"
      ```
    </CodeGroup>

    <Tip>
      Save the `request_id` from the response — you'll use it to poll for status updates or match incoming webhook events.
    </Tip>
  </Accordion>

  <Accordion title="Track the request" icon="rocket">
    Poll the status endpoint with your `request_id` to check progress.

    ```javascript fetch theme={null}
        const response = await fetch(
          "https://api.pharmachains.ai/v1/requests/req_xyz789",
          {
            headers: {
              "Authorization": "Bearer YOUR_API_KEY"
            }
          }
        );

        const data = await response.json();
        console.log(data.status); // "confirmed" | "dispensing" | "delivered" ...
    ```
  </Accordion>
</AccordionGroup>

## Next steps

You're integrated. Here's what to explore next:

<CardGroup>
  <Card title="Authentication" icon="lock" href="/development">
    Understand API key scopes, key rotation, and the difference between sandbox and production.
  </Card>

  <Card title="Status & webhooks" icon="webhook" href="/api-reference/endpoint/webhook">
    Stop polling. Receive real-time push notifications whenever a request status changes.
  </Card>

  <Card title="Cancel a request" icon="ban" href="/api-reference/endpoint/delete">
    Learn when and how to cancel a pending medicine request via the API.
  </Card>

  <Card title="Full API reference" icon="code" href="/api-reference/introduction">
    Browse every endpoint with interactive request builders and full schema documentation.
  </Card>
</CardGroup>

<Note>
  **Need help?** Email us at [support@pharmachains.ai](mailto:support@pharmachains.ai) or open a ticket from your [Partner Portal](https://partners.pharmachains.ai).
</Note>