Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pharmachains.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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

If you don’t have one yet, sign up at the Pharmachain Partner Portal. Once your account is approved, you’ll land on the dashboard.
  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.
Never expose your API key in frontend code, mobile apps, or public repositories. All Pharmachain API calls must be made server-side.

​
Step 2: Search for a medicine

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.
    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);
A successful response looks like this:
    {
      "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
          }
        ]
      }
    }
Use the sandbox base URL https://sandbox-api.pharmachains.ai/v1 while testing — no real pharmacy orders will be placed.

​
Step 3: Submit a medicine request

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.
    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"
Save the request_id from the response — you’ll use it to poll for status updates or match incoming webhook events.
Poll the status endpoint with your request_id to check progress.
fetch
    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" ...

​
Next steps

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

Authentication

Understand API key scopes, key rotation, and the difference between sandbox and production.

Status & webhooks

Stop polling. Receive real-time push notifications whenever a request status changes.

Cancel a request

Learn when and how to cancel a pending medicine request via the API.

Full API reference

Browse every endpoint with interactive request builders and full schema documentation.
Need help? Email us at support@pharmachains.ai or open a ticket from your Partner Portal.