Read your estate

Your estate is the set of agents and merchants you onboarded through Onboard a sub-agent. Every call on this page needs the agents:read or transactions:read scope shown on it, and sub-agent access switched on for your client by the bank. Without that switch the per-agent calls answer 0012 and the listing calls refuse outright. See Ownership model.

The X-Agent-Account header

Agent routes name their subject in a header, not in the path or body:

X-Agent-Account: 0000123456

The value is the agent’s 10-digit transaction account number (txnAccountNumber from onboarding, realId on every agent read). It must be an account of an agent, merchant or corporate customer. The platform then checks that the account belongs to your own customer or to one of your sub-agents. A header naming any other agent answers 0012 with is not linked to this API client; a missing header answers 0096 with X-Agent-Account header is required.

The two listing calls, downlines and list, do not consult the header for a partner: your estate follows your credentials, not what you name.

Agent details (A2)

GET/api/legacy/agentscope: agents:read

cURL

curl https://api.bankcore.ng/api/legacy/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Agent-Account: 0000123456"

Response

{
  "id": "e41cc8ae-f521-4859-91da-d489f091a9b9",
  "realId": "0000123456",
  "businessName": "Adebayo Stores",
  "firstName": "Adebayo",
  "lastName": "Ogundimu",
  "phoneNumber": "+2348012345678",
  "email": "adebayo@example.com",
  "bvn": "22222222222",
  "state": "Lagos",
  "localgovt": "Ikeja",
  "corporate": false,
  "active": true,
  "kycLevel": "LEVEL_2",
  "balance": { "main": 250000.0000, "income": 15000.0000 },
  "createdAt": "2026-04-01T10:30:00Z"
}

Field	Description
id	Customer id.
realId	Transaction account number; the header value.
businessName	Business name for a registered business or corporate; otherwise first and last name.
corporate	true when the customer is a corporate rather than an agent.
active	true only when the transaction account can be both debited and credited: not locked, frozen, PND or dormant.
balance.main, balance.income	Available balances of the transaction and fee accounts.

Null fields are omitted.

Update agent identity

PATCH/api/legacy/agent/updatescope: agents:manage

Add or correct the BVN and/or NIN of an agent or merchant. Body: { "bvn", "nin" }, each exactly 11 digits, at least one present. Resending the number already on file is a no-op. Returns the A2 shape.

A LEVEL_1 agent that ends up holding both numbers is raised to LEVEL_2 through the tier-upgrade service, so a tier-upgrade record is written and the tier-upgrade webhook is sent. Corporates are refused (0012; identity lives on their principals). A number already held by another agent answers 0014; a watchlisted BVN answers 0012. Names and date of birth are not editable here.

Activity profile (A3)

GET/api/legacy/agent/profilescope: agents:read

{ "lifetime_income": 1250000.00, "month_income": 45000.00 }

Both figures are sums of credits to the fee account: all time, and since the first day of the current calendar month. Zero when the agent has no fee account.

Downlines (A20)

GET/api/legacy/agent/downlinesscope: agents:read

For a partner this returns your estate, newest first, as a bare array of A2 objects. Parameters page (1-based, default 1) and limit (default 20, capped at 200). The header is ignored for a partner but is harmless to send.

curl "https://api.bankcore.ng/api/legacy/agent/downlines?page=1&limit=50" \
  -H "Authorization: Bearer $TOKEN"

A sub-agent whose transaction account cannot be resolved is omitted from the listing rather than failing the page.

Without sub-agent access the call answers 0012 with This API client does not have sub-agent access enabled. The platform refuses rather than returning an empty list, so you can tell “none” from “not allowed”.

Downline balance (A21)

GET/api/legacy/agent/downlines/{realId}/balancescope: agents:read

realId is the sub-agent’s transaction account number. Returns { "main", "income" } as on Balance and statement. No header is needed. Subject to the same ownership check as any balance read.

List agents (A25)

GET/api/legacy/agent/listscope: agents:read

The same set as downlines, in the { success, total, data } envelope, so you get a total. Parameters page and limit as above.

{
  "success": true,
  "total": 2,
  "data": [ { "realId": "0000123456", "businessName": "Adebayo Stores", "active": true, "balance": { "main": 250000.0000, "income": 15000.0000 } } ]
}

Refused outright without sub-agent access, as downlines is.

Find agent by phone (A24)

GET/api/legacy/agent/find/{phoneNumber}scope: agents:read

Exact match on the stored primary phone (international form, +234...). Returns one A2 object. An agent that does not exist or that is outside your estate answers HTTP 404 with the body { "code": "0012", "desc": "Agent not found" }. This is the one legacy route on this page that uses a real HTTP status; the two cases are deliberately indistinguishable.

curl https://api.bankcore.ng/api/legacy/agent/find/%2B2348012345678 \
  -H "Authorization: Bearer $TOKEN"

Phone form

The match is exact against the stored value, which the platform normalises to international form at creation. I could not confirm that a local-form path segment (08012345678) is normalised before matching; send +234... URL-encoded as %2B234....

Transaction list (A23)

GET/api/legacy/agent/tranlistscope: transactions:read

The agent’s statement in list form. Same entry shape as the agent statement (A5) on Balance and statement.

Parameter	Description
accountType	00 transaction account (default), 01 fee account.
from, to	Calendar dates (Lagos, to inclusive). start_date, end_date are the epoch-millisecond forms.
page	1-based, default 1.
size	Default 20, capped at 200. pageSize is an alias.
wrap	Default false: bare array. true: the { success, total, data } envelope with a total, which A5 never gives.

curl "https://api.bankcore.ng/api/legacy/agent/tranlist?from=2026-03-01&to=2026-03-31&page=1&size=50&wrap=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Agent-Account: 0000123456"

Entries on a sub-agent’s list that you initiated carry initiatedByPartner in metadata; see Acting on a sub-account’s money.

Errors

Code	When
0012	Header names an account that is not yours; account not found; sub-agent access not enabled (listings); unparseable date.
0014	Identity update: another agent holds the number.
0096	Header missing; header names a non-agent account; unexpected failure.

In the portal

The Agents page is the same estate, with status, account count, available balance and last activity, and an export. The Transactions page can show a sub-agent’s entries alongside your own, flagged as belonging to an agent.