> ## 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.

# 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 cols={2}>
  <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>