Provider API
The Provider API base address is https://dispensaryapi.famasi.africa/api/v1/providers. Authenticate requests with a provider API key in x-api-key.
Operations
| Method | Path | Description |
|---|---|---|
GET | /me | Fetch the authenticated provider’s details |
POST | /me/token | Refresh the provider’s API token |
GET | /customers | Fetch customers for a provider |
POST | /customers | Create a new customer/patient for a provider |
GET | /plans | Fetch plans for a provider |
GET | /formulary | Search products in the formulary |
GET | /analytics | Fetch analytics data for a provider |
GET | /provider-orders/analytics | Fetch analytics data for provider orders |
GET | /orders-stats | Fetch statistics for provider orders |
POST | /users | Add a user to a provider |
PUT | /customers/{unique_customer_id} | Edit a customer in the provider’s organization |
POST | /customers/{unique_customer_id}/plans | Add a customer to a plan |
GET | /profiles | Fetch user profiles |
POST | /update-payment-type | Update the preferred payment type for a provider |
POST | /set-low-balance-threshold | Set the low wallet balance threshold for a provider |
POST | /toggle-auto-debit | Toggle auto-debit functionality for a provider |
GET | /view-customer/{customer_id} | View details of a specific customer/patient |
POST | /upload_logo | Upload a logo for a provider |
PUT | /edit | Edit provider information |
GET | /wallet-balance | Fetch the wallet balance of a provider |
GET | /transactions | Fetch the transaction history of a provider |
GET | /orders | Fetch all orders for a provider |
POST | /orders | Create a new order for a provider |
GET | /virtual-accounts | Fetch all virtual accounts for a provider |
Fields and examples for each operation are on these pages: Customers, Orders, Formulary, Analytics, Wallet, Users and Settings.
Responses
Every response is JSON with success and message. Most successful responses put the result in data.
{ "success": true, "message": "...", "data": {} }Each operation’s page lists the fields it returns and the errors it can send back. Common errors are 400 for a bad request, 404 when something isn’t found, 429 when you’ve sent too many requests and 500 for an error on our side. Some operation pages list 401, but a missing or wrong key currently comes back as 500 with the message Invalid credentials.
Rate limits
You can send 200 requests every 3 minutes from one IP address. After that you get a 429 until the window resets. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers, and the reset value is in seconds.
Paging
GET /customers, GET /formulary, GET /orders and GET /orders-stats take a page value, starting at 1. GET /customers and GET /orders also take limit, which defaults to 10.
Test environment
GET /me returns both your api_key and your test_api_key. Use the test key at the same address: a key starting FAMASI-TEST-KEY- works on test data, and test orders don’t reach pharmacies.
Quick example
curl "https://dispensaryapi.famasi.africa/api/v1/providers/formulary?search=amoxicillin" \ -H "x-api-key: YOUR_PROVIDER_API_KEY"