API Reference

The Famasi Provider API is a REST API that powers all provider operations. The MCP server wraps this API — every provider tool maps to one of these endpoints.

Base URL: https://api.famasi.ai/api/v1/providers

Version: 1.1.5

Authentication: All endpoints require an API key via the x-api-key header. See provider authentication.

---

Endpoints by category

Authentication (2 endpoints)

Method	Path	Description
GET	/me	Fetch the authenticated provider’s details
POST	/me/token	Refresh the provider’s API token

Customer Management (4 endpoints)

Method	Path	Description
GET	/customers	Fetch customers for a provider
POST	/customers	Create a new customer for a provider
PUT	/customers/{unique_customer_id}	Edit a customer in the provider’s organisation
GET	/view-customer/{customer_id}	View details of a specific customer

Plan Management (2 endpoints)

Method	Path	Description
GET	/plans	Fetch plans for a provider
POST	/customers/{unique_customer_id}/plans	Add a customer to a plan

Product Management (1 endpoint)

Method	Path	Description
GET	/formulary	Search products in the formulary

Order Management (2 endpoints)

Method	Path	Description
GET	/orders	Fetch all orders for a provider
POST	/orders	Create a new order for a provider

Analytics (3 endpoints)

Method	Path	Description
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

User Management (2 endpoints)

Method	Path	Description
POST	/users	Add a user to a provider
GET	/profiles	Fetch user profiles

Provider Management (5 endpoints)

Method	Path	Description
PUT	/edit	Edit provider information
POST	/upload_logo	Upload a logo for a provider
POST	/update-payment-type	Update the preferred payment type
POST	/set-low-balance-threshold	Set the low wallet balance threshold
POST	/toggle-auto-debit	Toggle auto-debit functionality

Wallet & Transactions (3 endpoints)

Method	Path	Description
GET	/wallet-balance	Fetch the wallet balance of a provider
GET	/virtual-accounts	Fetch all virtual accounts for a provider
GET	/transactions	Fetch the transaction history of a provider

---

Using the API directly vs MCP

Most providers should use the MCP server rather than calling the API directly. The MCP server:

• Handles authentication and session management
• Provides natural language access via AI assistants
• Wraps each endpoint as a typed tool with validation

Direct API access is available for custom integrations where you need full control over request/response handling.

---

Interactive API reference

The full OpenAPI specification with request/response schemas, parameters, and example payloads is available as an interactive reference:

• OpenAPI spec: openapi.json
• Postman collection: postman-collection.json

Import either file into your preferred API client (Postman, Insomnia, Bruno, etc.) to explore endpoints interactively.

---

Quick example

# Fetch your provider profile
curl -X GET https://api.famasi.ai/api/v1/providers/me \
  -H "x-api-key: pk_live_..."

# Search the formulary
curl -X GET "https://api.famasi.ai/api/v1/providers/formulary?search=amoxicillin" \
  -H "x-api-key: pk_live_..."

# Create a customer
curl -X POST https://api.famasi.ai/api/v1/providers/customers \
  -H "x-api-key: pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"phone": "+2348012345678", "first_name": "Jane", "last_name": "Doe"}'

Rate limits

The API enforces rate limits per API key. If you receive a 429 Too Many Requests response, back off and retry after the Retry-After header value.

Provider tools reference → · Authentication → · Troubleshooting →