Integration API, version 1

Read-only, versioned REST for BI tools and other government systems (D-04, D-06). Everything the web app computes, the API serves from the same engine: amounts are naira with two decimal places, as strings, never floating point.

Getting started

Ask a BIMMS administrator for a client. They choose the scopes you may read, optionally restrict you to one MDA, and can issue a test credential for integration work. The token is shown once.
Send it on every request: Authorization: Bearer bimms_live_….
Read the machine-readable reference at /api/v1/openapi.json (OpenAPI 3.1) or the tables below.

curl -H "Authorization: Bearer $BIMMS_TOKEN" \
  "https://bimms.gov.ng/api/v1/ceilings?year=2026&mdaId=12"

{
  "data": { "items": [ { "mdaId": "12", "year": 2026, "allowancePct": "50.00", "igr": "1200000000.00",
    "gru": "150000000.00", "crf": "0.00", "subvention": "500000000.00", "totalFunding": "1250000000.00",
    "budget": "1210000000.00", "headroom": "40000000.00", "isOverdrawn": false, "excess": "0.00" } ], "next": null },
  "meta": { "requestId": "…", "version": "v1" }
}

Conventions

Envelope. Every success is { data: { items, next, … }, meta: { requestId, version } }. Quote requestId when you ask for support.
Pagination. Paginated endpoints take limit (1 to 500) and cursor; pass the previous page’s next until it is null. Other endpoints return the whole result for the filter you give, so pass mdaId or year to keep responses small (FR-API-8).
Errors. { error: { code, message, requestId } } with the HTTP status: 401 no or invalid token, 403 missing scope or MDA not allowed, 404 unknown endpoint or year, 405 any write (the API is read-only), 422 a validation message from the engine, 429 rate limit reached (see Retry-After), 500 with a request id.
Rate limit. Per client per minute (default 120); X-RateLimit-Limit and X-RateLimit-Remaining are on every response.
Versioning and deprecation. The version is in the path. Fields are only added within a version; a field or endpoint is removed only in a new version, and the previous version keeps serving for at least twelve months after the next one ships, with the date announced in the changelog and in the Deprecation header.
Audit. Every read is recorded in the audit log with the client as the actor (FR-API-5).

Scopes

referencerevenueexpenditureceilingssubmissionsmtref

Endpoints

`GET /api/v1/mdas`

Every published MDA (the tenants of the federated installation). Scope reference. Paginated.

Parameter	In	Type	Description
`limit`	query	integer	1 to 500, default 100
`cursor`	query	string	The `next` value of the previous page

Field	Type	Description
`id`	string	MDA id
`code`	string	Code
`name`	string	Name
`fundingType`	string	self_funded, partially_funded or fully_funded

`GET /api/v1/years`

Fiscal years with the state of each exercise (Budget, MTREF, Performance) from the cycle calendar. Scope reference.

Field Type Description

year integer Fiscal year

exercises

array

The exercises of the year

Field	Type	Description
`exercise`	string	budget, mtref or performance
`isOpen`	boolean	Open for entry
`phase`	string	Phase label
`deadline`	string (ISO 8601)	Deadline, if set

`GET /api/v1/accounts`

Expenditure accounts with their sub-head, or the revenue accounts of each MDA. Scope reference. Paginated.

Parameter	In	Type	Description
`kind`	query	string	expenditure (default) or revenue
`mdaId`	query	string	Restrict to one MDA (clients scoped to an MDA need not pass it)
`limit`	query	integer	1 to 500, default 100
`cursor`	query	string	The `next` value of the previous page

Field	Type	Description
`id`	string	Account id
`code`	string	Code
`name`	string	Name
`type`	string	personnel, overhead, capital; or the revenue class igr, gru, crf
`subhead`	string	Sub-head name
`mdaId`	string	MDA (revenue accounts only)

`GET /api/v1/revenue/projections`

Monthly revenue projections per account for a year. Scope revenue. Paginated.

Parameter	In	Type	Description
`year`	query	integer	Fiscal year (default: the open Budget year)
`mdaId`	query	string	Restrict to one MDA (clients scoped to an MDA need not pass it)
`limit`	query	integer	1 to 500, default 100
`cursor`	query	string	The `next` value of the previous page

Field	Type	Description
`id`	string	Row id
`mdaId`	string	MDA
`accountId`	string	Revenue account
`accountCode`	string	Account code
`month`	integer	1 to 12
`year`	integer	Fiscal year
`amount`	string (₦, 2 dp)	Projected amount (₦, two decimal places, as a string)

`GET /api/v1/revenue/actuals`

Monthly revenue actuals per account for a year. Scope revenue. Paginated.

Parameter	In	Type	Description
`year`	query	integer	Fiscal year (default: the open Budget year)
`mdaId`	query	string	Restrict to one MDA (clients scoped to an MDA need not pass it)
`limit`	query	integer	1 to 500, default 100
`cursor`	query	string	The `next` value of the previous page

Field	Type	Description
`id`	string	Row id
`mdaId`	string	MDA
`accountId`	string	Revenue account
`accountCode`	string	Account code
`month`	integer	1 to 12
`year`	integer	Fiscal year
`amount`	string (₦, 2 dp)	Actual amount (₦, two decimal places, as a string)

`GET /api/v1/expenditure/lines`

Personnel, overhead and capital lines (account-based) of one MDA for a year. Scope expenditure.

Parameter	In	Type	Description
`year`	query	integer	Fiscal year (default: the open Budget year)
`mdaId` *	query	string	The MDA
`type`	query	string	personnel, overhead or capital (default: all)

Field	Type	Description
`id`	string	Row id (unique with type)
`type`	string	personnel, overhead or capital
`mdaId`	string	MDA
`accountId`	string	Account
`accountCode`	string	Account code
`item`	string	Item
`category`	string	administrative or developmental
`amount`	string (₦, 2 dp)	Line amount (₦, two decimal places, as a string)

`GET /api/v1/expenditure/totals`

Per MDA and year: personnel, overhead, capital, programme items and the total budget, from the one ceiling service. Scope expenditure.

Parameter	In	Type	Description
`year`	query	integer	Fiscal year (default: the open Budget year)
`mdaId`	query	string	Restrict to one MDA (clients scoped to an MDA need not pass it)

Field	Type	Description
`mdaId`	string	MDA
`year`	integer	Fiscal year
`personnel`	string (₦, 2 dp)	Personnel lines (₦, two decimal places, as a string)
`overhead`	string (₦, 2 dp)	Overhead lines (₦, two decimal places, as a string)
`capital`	string (₦, 2 dp)	Capital lines (₦, two decimal places, as a string)
`programmes`	string (₦, 2 dp)	Programme items (₦, two decimal places, as a string)
`budget`	string (₦, 2 dp)	Total budget B (₦, two decimal places, as a string)

`GET /api/v1/ceilings`

Per MDA and year: the ceiling inputs, total funding, budget, headroom and overrun, computed live by the engine. Scope ceilings.

Parameter	In	Type	Description
`year`	query	integer	Fiscal year (default: the open Budget year)
`mdaId`	query	string	Restrict to one MDA (clients scoped to an MDA need not pass it)

Field	Type	Description
`mdaId`	string	MDA
`year`	integer	Fiscal year
`allowancePct`	string	p, the allowance percentage (two places)
`igr`	string (₦, 2 dp)	Projected IGR (₦, two decimal places, as a string)
`gru`	string (₦, 2 dp)	Projected GRU (₦, two decimal places, as a string)
`crf`	string (₦, 2 dp)	Projected CRF (₦, two decimal places, as a string)
`subvention`	string (₦, 2 dp)	Government subvention (₦, two decimal places, as a string)
`totalFunding`	string (₦, 2 dp)	T, the ceiling (₦, two decimal places, as a string)
`budget`	string (₦, 2 dp)	B (₦, two decimal places, as a string)
`headroom`	string (₦, 2 dp)	max(T − B, 0) (₦, two decimal places, as a string)
`isOverdrawn`	boolean	B > T
`excess`	string (₦, 2 dp)	B − T when over (₦, two decimal places, as a string)

`GET /api/v1/submissions`

Per MDA and year: the four submission flags and the frozen state. Scope submissions.

Parameter	In	Type	Description
`year`	query	integer	Fiscal year (default: the open Budget year)
`mdaId`	query	string	Restrict to one MDA (clients scoped to an MDA need not pass it)

Field	Type	Description
`mdaId`	string	MDA
`year`	integer	Fiscal year
`revenueProjection`	boolean	Submitted
`revenuePerformance`	boolean	Submitted
`budgetProjection`	boolean	Submitted
`budgetPerformance`	boolean	Submitted
`frozen`	boolean	Frozen by the Budget Office

`GET /api/v1/mtref/projections`

For a framework year: revenue, personnel, overhead and capital projections per MDA and projected year, with the workflow state. Scope mtref.

Parameter	In	Type	Description
`frameworkYear`	query	integer	Framework year (default: the current one)
`mdaId`	query	string	Restrict to one MDA (clients scoped to an MDA need not pass it)

Field Type Description

mdaId string MDA

frameworkYear integer Framework year

workflow string pending, submitted, received or archived

years

array

One per projected year

Field	Type	Description
`year`	integer	Projected year
`revenue`	string (₦, 2 dp)	Σ revenue projections (₦, two decimal places, as a string)
`personnel`	string (₦, 2 dp)	Σ personnel (₦, two decimal places, as a string)
`overhead`	string (₦, 2 dp)	Σ overhead (₦, two decimal places, as a string)
`capital`	string (₦, 2 dp)	Σ capital (₦, two decimal places, as a string)
`totalFunding`	string (₦, 2 dp)	MTREF ceiling (₦, two decimal places, as a string)
`budget`	string (₦, 2 dp)	Projected expenditure (₦, two decimal places, as a string)

Worked examples

A year’s submissions for every MDA

GET /api/v1/submissions?year=2026            # one row per MDA: the four flags and frozen
GET /api/v1/mdas?limit=200                   # names and codes to join on mdaId

One MDA’s ceiling and headroom

GET /api/v1/ceilings?year=2026&mdaId=12      # T, B, headroom, isOverdrawn
GET /api/v1/expenditure/totals?year=2026&mdaId=12

All revenue projections, page by page

GET /api/v1/revenue/projections?year=2026&limit=500
GET /api/v1/revenue/projections?year=2026&limit=500&cursor=<next>

Changelog

v1 · 2026-11-05 · First release: read-only MDAs, chart of accounts, years and exercises, revenue projections and actuals, expenditure lines and totals, ceilings and headroom, submission status, MTREF projections.

Back to BIMMS