API Reference

Base URL: https://maicro.ng

Authentication

Pass your API key in the X-API-Key request header. Keys are prefixed with mk_live_ or mk_test_ depending on the environment. Generate keys in Settings › API Keys.

curl https://maicro.ng/api/v1/customers \
  -H "X-API-Key: mk_live_your_key_here"

↑ Back to top

Rate limits

Limits are enforced per tenant and depend on your subscription plan.

Plan	Per minute	Per day
Free	30	1,000
Starter	60	5,000
Growth	120	20,000
Business	300	100,000

Rate limit headers: X-RateLimit-Remaining and X-RateLimit-Reset (ISO 8601).

↑ Back to top

Errors

Error responses use the shape below.

{ "success": false, "error": { "code": "UNAUTHORIZED", "message": "Invalid or missing API key." } }

Code	HTTP status	Meaning
UNAUTHORIZED	401	Missing or invalid API key.
FORBIDDEN	403	Insufficient key scope (write attempted with read-only key).
NOT_FOUND	404	Resource not found or not owned by your tenant.
RATE_LIMITED	429	Rate limit exceeded.
VALIDATION_ERROR	400	Request body or parameter is invalid.
INTERNAL_ERROR	500	Unexpected server error.

↑ Back to top

Customers

GET/api/v1/customers

List all customers for your tenant. Supports pagination and search.

Query parameters

Name	Type	Required	Description
page	integer	No	Zero-based page number (default 0).
limit	integer	No	Records per page, 1 to 100 (default 25).
search	string	No	Filter by name, phone or customer number.
status	string	No	Filter by status, e.g. active.

curl https://maicro.ng/api/v1/customers?page=0&limit=25 \
  -H "X-API-Key: mk_live_…"

Response

{
  "success": true,
  "data": [{ "id": "…", "customer_number": "C-0001", "name": "Amina Yusuf", "phone": "+234…" }],
  "meta": { "page": 0, "limit": 25, "total": 412 }
}

POST/api/v1/customers

Create a new customer. Requires a read_write API key.

Request body

Field	Type	Required	Description
name	string	Yes	Full name of the customer.
phone	string	No	Phone number.
email	string	No	Email address.
kyc_status	string	No	pending, verified, or failed.

curl -X POST https://maicro.ng/api/v1/customers \
  -H "X-API-Key: mk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Amina Yusuf","phone":"+234800…"}'

Response

{ "success": true, "data": { "id": "…", "customer_number": "C-0413", "name": "Amina Yusuf" }, "meta": {} }

GET/api/v1/customers/{id}

Retrieve a single customer by ID.

curl https://maicro.ng/api/v1/customers/cus_01j… -H "X-API-Key: mk_live_…"

Response

{ "success": true, "data": { "id": "cus_01j…", "name": "Amina Yusuf", … }, "meta": {} }

GET/api/v1/customers/{id}/credit-score

Compute and return the algorithmic credit score for a customer.

curl https://maicro.ng/api/v1/customers/cus_01j…/credit-score -H "X-API-Key: mk_live_…"

Response

{ "success": true, "data": { "customer_id": "…", "score": 720, "rating": "Very Good", "components": { "savings": 150, "adashi": 200, "installment": 70 }, "method": "algorithmic" }, "meta": {} }

↑ Back to top

Savings

GET/api/v1/savings/accounts

List savings accounts for your tenant, including current balance.

Query parameters

Name	Type	Required	Description
page	integer	No	Zero-based page number.
limit	integer	No	Records per page, up to 100.
status	string	No	Filter by status, e.g. active.

curl https://maicro.ng/api/v1/savings/accounts -H "X-API-Key: mk_live_…"

Response

{ "success": true, "data": [{ "id": "…", "account_number": "SA-0001", "status": "active", "balance": 50000 }], "meta": { "page": 0, "limit": 25, "total": 88 } }

GET/api/v1/savings/accounts/{id}/transactions

List transaction history for a savings account.

Query parameters

Name	Type	Required	Description
page	integer	No	Zero-based page number.
limit	integer	No	Records per page, up to 100.

curl "https://maicro.ng/api/v1/savings/accounts/sa_01j…/transactions" -H "X-API-Key: mk_live_…"

Response

{ "success": true, "data": [{ "id": "…", "txn_type": "credit", "amount": 5000, "txn_date": "2026-10-01" }], "meta": { "page": 0, "limit": 25, "total": 34 } }

↑ Back to top

Adashi

GET/api/v1/adashi/groups

List adashi groups with live member counts.

Query parameters

Name	Type	Required	Description
page	integer	No	Zero-based page number.
limit	integer	No	Records per page, up to 100.
status	string	No	Filter by status, e.g. active.

curl https://maicro.ng/api/v1/adashi/groups -H "X-API-Key: mk_live_…"

Response

{ "success": true, "data": [{ "id": "…", "group_number": "AG-0001", "name": "Market Women Group", "status": "active", "member_count": 12 }], "meta": { "page": 0, "limit": 25, "total": 7 } }

↑ Back to top

Easy Buy (Installment)

GET/api/v1/installment/contracts

List Easy Buy purchase contracts.

Query parameters

Name	Type	Required	Description
page	integer	No	Zero-based page number.
limit	integer	No	Records per page, up to 100.
status	string	No	Filter by status.

curl https://maicro.ng/api/v1/installment/contracts -H "X-API-Key: mk_live_…"

Response

{ "success": true, "data": [{ "id": "…", "contract_number": "PC-0001", "status": "active", "agreed_total_amount": 150000 }], "meta": { "page": 0, "limit": 25, "total": 23 } }

↑ Back to top

Agreements

GET/api/v1/agreements

List agreements for your tenant.

Query parameters

Name	Type	Required	Description
page	integer	No	Zero-based page number.
limit	integer	No	Records per page, up to 100.
status	string	No	Filter by status.
type	string	No	Filter by agreement_type.
search	string	No	Search by title or number.

curl https://maicro.ng/api/v1/agreements -H "X-API-Key: mk_live_…"

Response

{ "success": true, "data": [{ "id": "…", "agreement_number": "AGR-0001", "title": "Lease agreement", "status": "signed" }], "meta": { "page": 0, "limit": 25, "total": 5 } }

↑ Back to top

Disputes

GET/api/v1/disputes

List disputes for your tenant.

Query parameters

Name	Type	Required	Description
page	integer	No	Zero-based page number.
limit	integer	No	Records per page, up to 100.
status	string	No	Filter by status, e.g. open.
priority	string	No	Filter by priority.
category	string	No	Filter by category.

curl https://maicro.ng/api/v1/disputes -H "X-API-Key: mk_live_…"

Response

{ "success": true, "data": [{ "id": "…", "dispute_number": "DS-0001", "status": "open", "priority": "high" }], "meta": { "page": 0, "limit": 25, "total": 3 } }

↑ Back to top

Reports

GET/api/v1/reports/summary

Retrieve a high-level summary of your tenant's activity.

curl https://maicro.ng/api/v1/reports/summary -H "X-API-Key: mk_live_…"

Response

{ "success": true, "data": { "total_customers": 412, "active_savings_accounts": 88, "total_savings_balance": 4870000, "active_adashi_groups": 7, "active_contracts": 23, "total_agreements": 5, "open_disputes": 3 }, "meta": {} }

↑ Back to top

Try the interactive playground