{"openapi":"3.1.0","info":{"title":"BIMMS integration API","version":"v1","description":"Read-only access to MDAs, the chart of accounts, fiscal years, revenue projections and actuals, expenditure lines and totals, ceilings and headroom, submission status and MTREF projections. Amounts are naira with two decimal places, as strings. Authenticate with a client token issued by a BIMMS administrator: `Authorization: Bearer <token>`."},"servers":[{"url":"https://0.0.0.0:3400/api/v1"}],"components":{"securitySchemes":{"clientToken":{"type":"http","scheme":"bearer"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}}}}}}},"security":[{"clientToken":[]}],"paths":{"/mdas":{"get":{"summary":"MDAs","description":"Every published MDA (the tenants of the federated installation). Scope: `reference`. Paginated: pass `cursor` from the previous page’s `next`.","parameters":[{"name":"limit","in":"query","required":false,"description":"1 to 500, default 100","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"The `next` value of the previous page","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"MDA id"},"code":{"type":"string","description":"Code"},"name":{"type":"string","description":"Name"},"fundingType":{"type":"string","description":"self_funded, partially_funded or fully_funded"}}}},"next":{"type":["string","null"]}}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"version":{"type":"string"}}}}}}}},"401":{"description":"No or invalid client token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or MDA not allowed"},"429":{"description":"Rate limit reached; see Retry-After"}}}},"/years":{"get":{"summary":"Fiscal years and exercises","description":"Fiscal years with the state of each exercise (Budget, MTREF, Performance) from the cycle calendar. Scope: `reference`.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","description":"Fiscal year"},"exercises":{"type":"array","items":{"type":"object","properties":{"exercise":{"type":"string","description":"budget, mtref or performance"},"isOpen":{"type":"boolean","description":"Open for entry"},"phase":{"type":"string","description":"Phase label"},"deadline":{"type":"string","description":"Deadline, if set","format":"date-time"}}},"description":"The exercises of the year"}}}},"next":{"type":["string","null"]}}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"version":{"type":"string"}}}}}}}},"401":{"description":"No or invalid client token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or MDA not allowed"},"429":{"description":"Rate limit reached; see Retry-After"}}}},"/accounts":{"get":{"summary":"Chart of accounts","description":"Expenditure accounts with their sub-head, or the revenue accounts of each MDA. Scope: `reference`. Paginated: pass `cursor` from the previous page’s `next`.","parameters":[{"name":"kind","in":"query","required":false,"description":"expenditure (default) or revenue","schema":{"type":"string"}},{"name":"mdaId","in":"query","required":false,"description":"Restrict to one MDA (clients scoped to an MDA need not pass it)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1 to 500, default 100","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"The `next` value of the previous page","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Account id"},"code":{"type":"string","description":"Code"},"name":{"type":"string","description":"Name"},"type":{"type":"string","description":"personnel, overhead, capital; or the revenue class igr, gru, crf"},"subhead":{"type":"string","description":"Sub-head name"},"mdaId":{"type":"string","description":"MDA (revenue accounts only)"}}}},"next":{"type":["string","null"]}}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"version":{"type":"string"}}}}}}}},"401":{"description":"No or invalid client token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or MDA not allowed"},"429":{"description":"Rate limit reached; see Retry-After"}}}},"/revenue/projections":{"get":{"summary":"Revenue projections","description":"Monthly revenue projections per account for a year. Scope: `revenue`. Paginated: pass `cursor` from the previous page’s `next`.","parameters":[{"name":"year","in":"query","required":false,"description":"Fiscal year (default: the open Budget year)","schema":{"type":"integer"}},{"name":"mdaId","in":"query","required":false,"description":"Restrict to one MDA (clients scoped to an MDA need not pass it)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1 to 500, default 100","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"The `next` value of the previous page","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Row id"},"mdaId":{"type":"string","description":"MDA"},"accountId":{"type":"string","description":"Revenue account"},"accountCode":{"type":"string","description":"Account code"},"month":{"type":"integer","description":"1 to 12"},"year":{"type":"integer","description":"Fiscal year"},"amount":{"type":"string","description":"Projected amount (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"}}}},"next":{"type":["string","null"]}}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"version":{"type":"string"}}}}}}}},"401":{"description":"No or invalid client token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or MDA not allowed"},"429":{"description":"Rate limit reached; see Retry-After"}}}},"/revenue/actuals":{"get":{"summary":"Revenue actuals","description":"Monthly revenue actuals per account for a year. Scope: `revenue`. Paginated: pass `cursor` from the previous page’s `next`.","parameters":[{"name":"year","in":"query","required":false,"description":"Fiscal year (default: the open Budget year)","schema":{"type":"integer"}},{"name":"mdaId","in":"query","required":false,"description":"Restrict to one MDA (clients scoped to an MDA need not pass it)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1 to 500, default 100","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"The `next` value of the previous page","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Row id"},"mdaId":{"type":"string","description":"MDA"},"accountId":{"type":"string","description":"Revenue account"},"accountCode":{"type":"string","description":"Account code"},"month":{"type":"integer","description":"1 to 12"},"year":{"type":"integer","description":"Fiscal year"},"amount":{"type":"string","description":"Actual amount (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"}}}},"next":{"type":["string","null"]}}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"version":{"type":"string"}}}}}}}},"401":{"description":"No or invalid client token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or MDA not allowed"},"429":{"description":"Rate limit reached; see Retry-After"}}}},"/expenditure/lines":{"get":{"summary":"Expenditure lines","description":"Personnel, overhead and capital lines (account-based) of one MDA for a year. Scope: `expenditure`.","parameters":[{"name":"year","in":"query","required":false,"description":"Fiscal year (default: the open Budget year)","schema":{"type":"integer"}},{"name":"mdaId","in":"query","required":true,"description":"The MDA","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"personnel, overhead or capital (default: all)","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Row id (unique with type)"},"type":{"type":"string","description":"personnel, overhead or capital"},"mdaId":{"type":"string","description":"MDA"},"accountId":{"type":"string","description":"Account"},"accountCode":{"type":"string","description":"Account code"},"item":{"type":"string","description":"Item"},"category":{"type":"string","description":"administrative or developmental"},"amount":{"type":"string","description":"Line amount (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"}}}},"next":{"type":["string","null"]}}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"version":{"type":"string"}}}}}}}},"401":{"description":"No or invalid client token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or MDA not allowed"},"429":{"description":"Rate limit reached; see Retry-After"}}}},"/expenditure/totals":{"get":{"summary":"Expenditure totals","description":"Per MDA and year: personnel, overhead, capital, programme items and the total budget, from the one ceiling service. Scope: `expenditure`.","parameters":[{"name":"year","in":"query","required":false,"description":"Fiscal year (default: the open Budget year)","schema":{"type":"integer"}},{"name":"mdaId","in":"query","required":false,"description":"Restrict to one MDA (clients scoped to an MDA need not pass it)","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"mdaId":{"type":"string","description":"MDA"},"year":{"type":"integer","description":"Fiscal year"},"personnel":{"type":"string","description":"Personnel lines (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"},"overhead":{"type":"string","description":"Overhead lines (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"},"capital":{"type":"string","description":"Capital lines (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"},"programmes":{"type":"string","description":"Programme items (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"},"budget":{"type":"string","description":"Total budget B (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"}}}},"next":{"type":["string","null"]}}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"version":{"type":"string"}}}}}}}},"401":{"description":"No or invalid client token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or MDA not allowed"},"429":{"description":"Rate limit reached; see Retry-After"}}}},"/ceilings":{"get":{"summary":"Ceilings and headroom","description":"Per MDA and year: the ceiling inputs, total funding, budget, headroom and overrun, computed live by the engine. Scope: `ceilings`.","parameters":[{"name":"year","in":"query","required":false,"description":"Fiscal year (default: the open Budget year)","schema":{"type":"integer"}},{"name":"mdaId","in":"query","required":false,"description":"Restrict to one MDA (clients scoped to an MDA need not pass it)","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"mdaId":{"type":"string","description":"MDA"},"year":{"type":"integer","description":"Fiscal year"},"allowancePct":{"type":"string","description":"p, the allowance percentage (two places)"},"igr":{"type":"string","description":"Projected IGR (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"},"gru":{"type":"string","description":"Projected GRU (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"},"crf":{"type":"string","description":"Projected CRF (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"},"subvention":{"type":"string","description":"Government subvention (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"},"totalFunding":{"type":"string","description":"T, the ceiling (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"},"budget":{"type":"string","description":"B (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"},"headroom":{"type":"string","description":"max(T − B, 0) (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"},"isOverdrawn":{"type":"boolean","description":"B > T"},"excess":{"type":"string","description":"B − T when over (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"}}}},"next":{"type":["string","null"]}}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"version":{"type":"string"}}}}}}}},"401":{"description":"No or invalid client token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or MDA not allowed"},"429":{"description":"Rate limit reached; see Retry-After"}}}},"/submissions":{"get":{"summary":"Submission status","description":"Per MDA and year: the four submission flags and the frozen state. Scope: `submissions`.","parameters":[{"name":"year","in":"query","required":false,"description":"Fiscal year (default: the open Budget year)","schema":{"type":"integer"}},{"name":"mdaId","in":"query","required":false,"description":"Restrict to one MDA (clients scoped to an MDA need not pass it)","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"mdaId":{"type":"string","description":"MDA"},"year":{"type":"integer","description":"Fiscal year"},"revenueProjection":{"type":"boolean","description":"Submitted"},"revenuePerformance":{"type":"boolean","description":"Submitted"},"budgetProjection":{"type":"boolean","description":"Submitted"},"budgetPerformance":{"type":"boolean","description":"Submitted"},"frozen":{"type":"boolean","description":"Frozen by the Budget Office"}}}},"next":{"type":["string","null"]}}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"version":{"type":"string"}}}}}}}},"401":{"description":"No or invalid client token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or MDA not allowed"},"429":{"description":"Rate limit reached; see Retry-After"}}}},"/mtref/projections":{"get":{"summary":"MTREF projections","description":"For a framework year: revenue, personnel, overhead and capital projections per MDA and projected year, with the workflow state. Scope: `mtref`.","parameters":[{"name":"frameworkYear","in":"query","required":false,"description":"Framework year (default: the current one)","schema":{"type":"integer"}},{"name":"mdaId","in":"query","required":false,"description":"Restrict to one MDA (clients scoped to an MDA need not pass it)","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"mdaId":{"type":"string","description":"MDA"},"frameworkYear":{"type":"integer","description":"Framework year"},"workflow":{"type":"string","description":"pending, submitted, received or archived"},"years":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","description":"Projected year"},"revenue":{"type":"string","description":"Σ revenue projections (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"},"personnel":{"type":"string","description":"Σ personnel (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"},"overhead":{"type":"string","description":"Σ overhead (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"},"capital":{"type":"string","description":"Σ capital (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"},"totalFunding":{"type":"string","description":"MTREF ceiling (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"},"budget":{"type":"string","description":"Projected expenditure (₦, two decimal places, as a string)","pattern":"^-?\\d+\\.\\d{2}$"}}},"description":"One per projected year"}}}},"next":{"type":["string","null"]}}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"version":{"type":"string"}}}}}}}},"401":{"description":"No or invalid client token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope or MDA not allowed"},"429":{"description":"Rate limit reached; see Retry-After"}}}}}}