Pharmacy Router API

Centralized pharmacy submission API for routing prescriptions to the correct 503B compounding pharmacy.

Overview

The Pharmacy Router is a centralized API that accepts prescription submissions, determines the correct compounding pharmacy based on the patient's state, translates the order into the pharmacy's native format, and tracks the order through fulfillment.

Instead of each service integrating directly with multiple pharmacies, callers submit a single standardized payload and let the router handle pharmacy selection, format translation, submission, and status tracking.

Base URL

https://api.yourera.com/rx

How It Works

1. Caller submits a PrescriptionSubmission to POST /rx/prescriptions/submit
2. Router resolves the target pharmacy based on patient state and routing config
3. Router translates the payload into the pharmacy's native format and submits
4. Synchronous response includes submissionId, pharmacy, and status
5. Router sends an HMAC-signed callback to the caller's callbackUrl
6. When pharmacy webhooks arrive (shipping updates, status changes), router updates the submission and sends another callback

Authentication

All /rx/prescriptions/* endpoints require HMAC-SHA256 authentication. Each API client is issued an API key (public identifier) and an API secret (used for signing).

Required Headers

Signature Formula

The signing string is the timestamp, a dot, and the JSON-stringified request body:

HMAC-SHA256(apiSecret, timestamp + '.' + JSON.stringify(body))

The result is encoded as a lowercase hex string.

Node.js Example

import crypto from 'node:crypto';

const API_KEY = 'your-api-key';
const API_SECRET = 'your-api-secret';

function signRequest(body) {
  const timestamp = new Date().toISOString();
  const bodyStr = JSON.stringify(body);
  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(timestamp + '.' + bodyStr)
    .digest('hex');

  return { timestamp, signature };
}

// Usage
const body = { /* PrescriptionSubmission */ };
const { timestamp, signature } = signRequest(body);

const response = await fetch('https://api.yourera.com/rx/prescriptions/submit', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': API_KEY,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
  },
  body: JSON.stringify(body),
});

Submit Prescription

Request Headers

Request Body: PrescriptionSubmission

Top-level Fields

patient Object

shipTo Object

prescriber Object

medication Object

routing Object

clinical Object

Example Request

{
  "source": "guide-glp",
  "sourceOrderId": "ord_abc123",
  "callbackUrl": "https://api.example.com/webhooks/pharmacy-router",
  "patient": {
    "firstName": "Jane",
    "lastName": "Smith",
    "dob": "1990-03-15",
    "gender": "female",
    "phone": "(555) 123-4567",
    "email": "jane.smith@example.com"
  },
  "shipTo": {
    "firstName": "Jane",
    "lastName": "Smith",
    "phone": "(555) 123-4567",
    "addressLine1": "123 Main St",
    "addressLine2": "Apt 4B",
    "city": "Austin",
    "state": "TX",
    "zip": "78701"
  },
  "prescriber": {
    "firstName": "Ali",
    "lastName": "Nolan",
    "npi": "1982609764",
    "phone": "(555) 987-6543",
    "email": "dr.nolan@example.com",
    "address": {
      "line1": "456 Medical Pkwy",
      "city": "Dallas",
      "state": "TX",
      "zip": "75201"
    }
  },
  "medication": {
    "name": "Semaglutide 2.5mg/mL",
    "sig": "Inject 0.25mL subcutaneously once weekly for 4 weeks",
    "quantity": 1,
    "daysSupply": 28,
    "refills": 0,
    "clinicalJustification": "BMI 32, type 2 diabetes"
  },
  "routing": {
    "patientState": "TX"
  },
  "test": false
}

Response

Success (201)

{
  "submissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "pharmacy": "strive",
  "status": "submitted",
  "pharmacyOrderId": "STV-ORD-12345"
}

Validation Error (400)

{
  "error": "Validation failed",
  "details": {
    "fieldErrors": {
      "patient.dob": ["Required"]
    },
    "formErrors": []
  }
}

Authentication Error (401)

{
  "error": "Invalid signature"
}

No Route (422)

{
  "error": "No pharmacy route configured for state: MN"
}

Pharmacy Error (502)

{
  "submissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "pharmacy": "boothwyn",
  "status": "failed",
  "pharmacyOrderId": null,
  "error": "Boothwyn API error 500: Internal Server Error"
}

Get Submission

Path Parameters

Request Headers

Requires the same HMAC authentication headers as the submit endpoint. For GET requests, the body is empty, so the signing string is:

HMAC-SHA256(apiSecret, timestamp + '.' + '{}')

Response (200)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "apiKeyId": "key-uuid",
  "source": "guide-glp",
  "sourceOrderId": "ord_abc123",
  "callbackUrl": "https://api.example.com/webhooks/pharmacy-router",
  "patientState": "TX",
  "medicationName": "Semaglutide 2.5mg/mL",
  "pharmacy": "strive",
  "pharmacyOrderId": "STV-ORD-12345",
  "status": "shipped",
  "trackingNumber": "1Z999AA10123456784",
  "carrier": "UPS",
  "errorMessage": null,
  "requestPayload": { /* original PrescriptionSubmission */ },
  "responsePayload": { /* pharmacy raw response */ },
  "submittedAt": "2026-03-19T14:30:00.000Z",
  "createdAt": "2026-03-19T14:30:00.000Z",
  "updatedAt": "2026-03-20T09:15:00.000Z"
}

Error Responses

Webhook: Boothwyn

Authentication

Request Body

Status Mapping

Response

{ "ok": true }

Webhook: Strive

Authentication

Request Body

Status Mapping

Response

{ "ok": true }

Health Check

Response (200)

{
  "status": "ok",
  "service": "pharmacy-router",
  "timestamp": "2026-03-19T14:30:00.000Z"
}

Pharmacy Routing

The router determines which pharmacy receives an order based on the patient's state. Routing rules are stored in the router_pharmacy_config database table, with each state mapped to one or more pharmacies with priority rankings.

Resolution Logic

1. If routing.preferredPharmacy is set, use it directly (bypass state routing)
2. Determine state from routing.patientState, falling back to shipTo.state
3. Query active routing configs for that state, ordered by priority (highest wins)
4. If no route exists, return 422 with an error

Current Pharmacy Assignments

Excluded States

Priority System

Each state-pharmacy mapping has a priority integer. When multiple pharmacies are configured for a state, the one with the highest priority (and isActive = true) wins. This allows easy failover by adjusting priorities without removing configurations.

Adapters

Each pharmacy has an adapter that translates the standardized PrescriptionSubmission into the pharmacy's native API format. Adapters handle authentication, format mapping, and error normalization.

Boothwyn Adapter

Submits orders to the Boothwyn Nucleus B2B REST API. Used for both direct Boothwyn orders and GMP-routed orders (GMP fulfillment goes through the same Boothwyn B2B endpoint).

API Details

• Endpoint: https://boothwynnucleus.azurewebsites.net/api/Prescriptions/B2B
• Auth: x-functions-key header with Azure function key
• Test mode: Appends ?test=true to URL
• Order type: 1 (standard)
• Shipping method: 43
• Case ID: Generated UUID per submission

SKU Mapping

The adapter matches medication names by checking if the medication.name field contains "semaglutide", "tirzepatide", or "nad" (case-insensitive). If no match is found, the SKU is set to UNKNOWN_SKU and the pharmacy will reject the order.

Gender Mapping

"male" maps to "m", "female" maps to "f".

Strive Adapter

Submits orders to the Strive / RxVortex API. Uses OAuth 2.0 client credentials for authentication.

API Details

• Production URL: Configured via STRIVE_API_URL env var
• Sandbox URL: https://sandbox.rxvortex.net
• Auth: OAuth 2.0 client credentials (POST /api/v1/generate-access-token)
• Token caching: Tokens cached for 23 hours (expire at 24h)
• Order endpoint: POST /api/v1/orders

Catalog IDs

Clinical Data Mapping

The clinical object is mapped to Strive's format: allergies maps directly, conditions maps to diseases, medications maps directly. Each entry in entries[] is wrapped as { description: "..." }.

PioneerRx Adapter

Callbacks

The router sends HMAC-signed HTTP POST callbacks to the callbackUrl you provide in the submission. Callbacks are fired at two points:

1. After initial submission -- with the pharmacy result (success or failure)
2. On webhook updates -- when a pharmacy sends a shipping/status update

Callback Authentication

Callbacks include X-Timestamp and X-Signature headers. The signature is computed using the same HMAC-SHA256 formula as request authentication, using your apiSecret:

HMAC-SHA256(apiSecret, timestamp + '.' + body)

You should verify this signature on your end to confirm the callback is authentic.

Callback Payload (Initial Submission)

{
  "submissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sourceOrderId": "ord_abc123",
  "pharmacy": "boothwyn",
  "status": "submitted",
  "pharmacyOrderId": "case-uuid-here",
  "error": null
}

Callback Payload (Webhook Update)

{
  "submissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sourceOrderId": "ord_abc123",
  "pharmacy": "boothwyn",
  "status": "shipped",
  "pharmacyOrderId": "case-uuid-here",
  "trackingNumber": "794644790132",
  "carrier": "FedEx"
}

Verifying Callbacks (Node.js)

import crypto from 'node:crypto';

function verifyCallback(req, apiSecret) {
  const timestamp = req.headers['x-timestamp'];
  const signature = req.headers['x-signature'];
  const bodyStr = JSON.stringify(req.body);

  const expected = crypto
    .createHmac('sha256', apiSecret)
    .update(timestamp + '.' + bodyStr)
    .digest('hex');

  const sigBuf = Buffer.from(signature, 'hex');
  const expBuf = Buffer.from(expected, 'hex');

  return sigBuf.length === expBuf.length
    && crypto.timingSafeEqual(sigBuf, expBuf);
}

Test Mode

Set "test": true in the request body to submit orders to pharmacy sandbox and test environments. No real prescriptions are created in test mode.

Per-Pharmacy Behavior

Example: Test Submission

const body = {
  source: 'guide-glp',
  sourceOrderId: 'test-001',
  callbackUrl: 'https://api.example.com/webhooks/pharmacy-router',
  test: true,
  // ... patient, shipTo, prescriber, medication ...
};

const { timestamp, signature } = signRequest(body);

const res = await fetch('https://api.yourera.com/rx/prescriptions/submit', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': API_KEY,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
  },
  body: JSON.stringify(body),
});

const data = await res.json();
console.log(data);
// { submissionId: "...", pharmacy: "strive", status: "submitted", ... }