Endpoint reference

Prove a key and read its limits

The first call an integrator makes. It proves the credential, shows which environment the key belongs to, which scopes it carries and what it is allowed per minute — and it returns a verification id, so the envelope is seen before anything real happens.

• No scope required: any active key may call it.

{
    "client": "CLI-2026-004417",
    "mda": "20008001",
    "env": "sandbox",
    "scopes": [
        "verify",
        "transact",
        "documents"
    ],
    "signed": false,
    "rate_per_minute": 120,
    "server_time": "2026-09-14T09:12:44+01:00",
    "version": "v1"
}

Resolve a taxpayer and read their compliance position

Resolves ONE identifier to a party on the state register and returns the clearance position of the entity and, for a company, of every active director (BR-10); for a business name, of the proprietor (BR-11). This is a POST and not a GET because the identifier may be a national identity number, and those must never appear in a URL, a proxy log or an access log.

• Send ONE identifier. If more than one is present the first of abssin, nin, rc, tin, party_ref is the one used — so do not send two and expect them to be cross-checked.
• A party that resolves but is NOT compliant is not an error: ok=true, data.compliant=false, and data.reason_codes names every published code that applies, with data.remediation_url pointing at the page that fixes the first of them. The refusal with a reason code happens where a decision is actually being asked for — a transaction, an award or a voucher.
• The NIN is never returned, not even masked; data.party.has_nin only says whether the register holds one. An individual's phone and email are masked unless the calling agency created or last touched the record (a corporate contact is public and is never masked).
• The clearance position is always read for the CURRENT year. There is no year parameter on this endpoint; a voucher or a transaction is where a specific fiscal year is judged.

{
    "abssin": "SBX0000102"
}

{
    "party": {
        "party_ref": "BPR-2026-000914",
        "kind": "llc",
        "display_name": "Sandbox Blocked Ventures Limited",
        "abssin": "SBX0000102",
        "rc_number": "RC9900102",
        "tin": null,
        "lga_id": null,
        "status": "active",
        "has_nin": false,
        "cac_verified_at": null,
        "contact": {
            "phone": null,
            "email": "sandbox@abiaone.test",
            "redacted": false
        },
        "tax_clearance": {
            "held": true,
            "reference": "TCC/2026/004418",
            "year": 2026,
            "valid_until": "2026-12-31"
        },
        "outstanding": {
            "count": 0,
            "total": 0,
            "available": true
        },
        "directors": [
            {
                "party_ref": "BPR-2026-000915",
                "name": "Ngozi Sandbox Director",
                "role": "director",
                "tcc_held": true,
                "tcc_ref": "TCC/2026/004419",
                "valid_until": "2026-12-31"
            },
            {
                "party_ref": "BPR-2026-000916",
                "name": "Uche Sandbox Nocert",
                "role": "director",
                "tcc_held": false,
                "tcc_ref": null,
                "valid_until": null
            }
        ]
    },
    "compliant": false,
    "reason_codes": [
        "DIRECTOR_NONCOMPLIANT"
    ],
    "remediation_url": "https://services.abiastate.gov.ng/me/tcc"
}

Ask whether an applicant may proceed, on a fee-less process

The expression-of-interest check (FR-10.3): a real transaction on a fee-less process, judged by the same gate engine an officer would use, so an applicant's journey cannot show a different answer from the counter's. It answers one question — may this ABSSIN proceed — and names every gate that says otherwise.

• This runs the gates, so it creates a transaction and returns its reference. It is not a read; do not call it in a loop.
• Two verification ids are in play: the envelope's own, and gate_verification_id for the gate run. A later dispute cites the second.
• A blocked applicant comes back ok=false with the first blocking code — and data is still present, carrying the transaction reference and the full blocking list.

{
    "abssin": "SBX0000101",
    "process": "HSG/EOI"
}

{
    "may_proceed": true,
    "process": "HSG/EOI",
    "transaction_ref": "BTX-2026-004870",
    "gate_verification_id": "VRF-2026-7C1A9E4D2B08",
    "blocking": [],
    "message": null
}

Register a party the state register does not hold

Mints a state identification number on the spot so a transaction is never blocked by the absence of an identity (FR-1.6). A company or a business name is registered outright. An individual is registered in the SANDBOX only: in live an ABSSIN is issued only against a photograph captured live, which a server-to-server call cannot perform, so the call is refused with PARTY_UNREGISTERED and a link to the public registration journey.

• The answer is the same body /parties/verify returns — party, compliant, reason_codes, remediation_url — so one parser handles both.
• An RC number already on the register is a REFUSAL (VALIDATION_ERROR, field rc_number) that carries the existing party in data.party. Continue with that party; do not retry.
• Degraded mode: while the taxpayer register or the ABSSIN registration service are unavailable, a well-formed request is answered QUEUED_DEGRADED with HTTP 202 instead — no identity is claimed or minted meanwhile. The error details and data carry queue_ref (QUE-YYYY-XXXXXX) and queue_url; follow it with GET /queue/{ref} or the queue.processed webhook. Queued is not approved: when service resumes the request goes through exactly the checks a live call does, and may still be refused. A malformed request is refused at once, as it would be live; the same Idempotency-Key with a different body is IDEMPOTENCY_KEY_REUSED.
• Only a company or business name is ever queued. An individual's registration rests on a liveness capture valid only in the moment it is taken, so it is never held: while upstream is down it is refused, and should be retried later.
• The queue never stores an identity number. A director named only by NIN is queued by the ABSSIN the platform already holds for that person; if it holds none, the call answers a retryable INTERNAL_ERROR — retry later, or name the director by abssin.

{
    "kind": "llc",
    "name": "Umuahia Civil Works Limited",
    "rc_number": "RC1284410",
    "phone": "08030000002",
    "email": "accounts@ucw.example.ng",
    "lga_id": 12,
    "address": "4 Bende Road, Umuahia"
}

Read a party you already hold a reference for

The same record /parties/verify returns, addressed by the reference the platform issued. Safe in a URL because a party reference is not an identity number — that is precisely why the platform hands you one.

• Store the party_ref against your own applicant record and use this endpoint afterwards; there is then no reason for a national identity number to be in your system at all.
• A reference belonging to the other environment reads as PARTY_NOT_FOUND: sandbox and live must not be able to prove each other's rows exist.

Submit a case and run the compliance gates

The machine twin of an officer capturing a case in the agency console. The platform resolves the party, pins the published version of the process, runs every configured gate and answers with the position. A blocked case names the gate, the subject and the remediation link; an eligible case is ready for a document.

• The transaction is created whether or not it clears — you need the transaction_ref to pay and come back.
• When a gate blocks, the answer is ok=false with the first blocking reason code and its remediation link, AND data still carries the whole transaction view. Read data even on a refusal.
• declared_value is required for a value-bearing process; a value above the basis of the clearance held raises an automatic additional assessment (BR-08) rather than a silent pass.
• The process must belong to the calling agency. Both a bare code (COFO) and the labelled form (LND/COFO) are accepted — anything before the last slash is discarded.
• Degraded mode: while the taxpayer register or the collection rails are unavailable, a well-formed request is answered QUEUED_DEGRADED with HTTP 202 instead — no case is opened and no gate runs until service resumes, so there is no transaction_ref yet; the processed queue entry carries it. The error details and data carry queue_ref (QUE-YYYY-XXXXXX) and queue_url; follow it with GET /queue/{ref} or the queue.processed webhook. Queued is not approved: when service resumes the request goes through exactly the checks a live call does, and may still be refused. A malformed request is refused at once, as it would be live; the same Idempotency-Key with a different body is IDEMPOTENCY_KEY_REUSED.
• The queue never stores an identity number. A party named by NIN is queued by the party reference the platform already holds for that person; if it holds none, the call answers a retryable INTERNAL_ERROR — retry later, or name the party by abssin or party_ref.

{
    "process": "LND/COFO",
    "party": {
        "abssin": "SBX0000102"
    },
    "declared_value": 25000000,
    "external_ref": "LND/2026/00821",
    "payload": {
        "instrument": "deed_of_assignment",
        "property_address": "Plot U/1147, Umuahia North"
    }
}

{
    "transaction_ref": "BTX-2026-004871",
    "status": "blocked",
    "mda": "20008001",
    "process": "COFO",
    "process_name": "Certificate of Occupancy (sandbox)",
    "party": {
        "party_ref": "BPR-2026-000914",
        "display_name": "Sandbox Blocked Ventures Limited",
        "kind": "llc",
        "abssin": "SBX0000102"
    },
    "declared_value": 25000000,
    "instrument": "deed_of_assignment",
    "external_ref": "LND/2026/00821",
    "gates": [
        {
            "gate": "TCC",
            "status": "PENDING",
            "subject": "Uche Sandbox Nocert",
            "role": "director",
            "reason_code": "DIRECTOR_NONCOMPLIANT",
            "computed_amount": null,
            "paid_amount": null,
            "na_reason": null,
            "evaluated_at": "2026-09-14T09:12:44+01:00"
        },
        {
            "gate": "CGT",
            "status": "ASSESSED",
            "subject": null,
            "role": "entity",
            "reason_code": "CGT_UNPAID",
            "computed_amount": 2500000,
            "paid_amount": 0,
            "na_reason": null,
            "evaluated_at": "2026-09-14T09:12:44+01:00"
        }
    ],
    "blocking": [
        {
            "gate": "TCC",
            "status": "PENDING",
            "reason_code": "DIRECTOR_NONCOMPLIANT",
            "subject": "Uche Sandbox Nocert",
            "role": "director",
            "amount_due": null,
            "assessment_ref": null,
            "message": "Director Uche Sandbox Nocert has no current tax clearance certificate."
        }
    ],
    "assessments": [
        {
            "reference": "ASM-2026-011204",
            "head": "CGT",
            "basis": "10% of 25,000,000.00 declared value, rate card 2026-01-01",
            "computed": 2500000,
            "paid_before": 0,
            "amount_due": 2500000,
            "state": "raised",
            "bill_ref": "SBX-BAS-000418",
            "pay_url": null,
            "paid_ref": null
        }
    ],
    "document": null,
    "remediation_url": "https://services.abiastate.gov.ng/remediate/9f3c1d7a4b2e"
}

Read a transaction and its current gate position

The same body as the submission, as the register holds it now. Poll this after your taxpayer pays if you have not subscribed to transaction.gate_changed — settlement is discovered by a sweep, so a gate can clear minutes after the money moves.

• A transaction belonging to another agency is a not-found, not a forbidden: an integrator may not enumerate another agency's cases.

Cite a payment against a transaction

Tells the platform that a reference in the central collection ledger belongs to this transaction and this head. Nothing is taken on trust: the reference must exist, be settled, belong to this taxpayer, sit under the right revenue head and not already have been spent on another case.

• Gates are re-run immediately, so data.transaction already shows whether the payment cleared the gate.
• A refusal still returns data, carrying matched=false and the ledger's own verdict in data.validation.
• Degraded mode: while the taxpayer register or the collection rails are unavailable, a well-formed request is answered QUEUED_DEGRADED with HTTP 202 instead — the reference is neither matched nor refused until the ledger can be read. The error details and data carry queue_ref (QUE-YYYY-XXXXXX) and queue_url; follow it with GET /queue/{ref} or the queue.processed webhook. Queued is not approved: when service resumes the request goes through exactly the checks a live call does, and may still be refused. A malformed request is refused at once, as it would be live; the same Idempotency-Key with a different body is IDEMPOTENCY_KEY_REUSED.

{
    "reference": "ABP-2026-77120043",
    "head": "CGT",
    "amount": 2500000
}

Re-run the gates and read everything that is owed

Re-evaluates the case against the rules as they stand now and hands back what the party owes on every head, with the bill reference and the payment link for each (FR-4.6, FR-11.2). The platform computes every figure from the effective rate card and freezes the basis: a caller never supplies an amount, because a figure supplied by the payer is not an assessment.

• It is a POST because it re-evaluates: a certificate may have been issued, a bill settled or a rate corrected since the last look.
• The body is empty. There is no per-head parameter — the gates decide which heads apply.
• An amount above the automatic ceiling is routed to an assessment officer and the gate reads ASSESSMENT_PENDING_APPROVAL — retryable, not a failure.

Issue the final document

Mints the final document number for an eligible transaction (FR-5). The number embeds the tax clearance it was issued against, so the document can never be separated from the compliance that earned it. Refused while any applicable gate is open; asking twice returns the same number, never a second one.

• The body is empty: the issuing system is taken from the key, not from the request.
• Degraded mode: while the taxpayer register or the collection rails are unavailable, a well-formed request is answered QUEUED_DEGRADED with HTTP 202 instead — no number is minted meanwhile, and none may be written on a document. The error details and data carry queue_ref (QUE-YYYY-XXXXXX) and queue_url; follow it with GET /queue/{ref} or the queue.processed webhook. Queued is not approved: when service resumes the request goes through exactly the checks a live call does, and may still be refused. A malformed request is refused at once, as it would be live; the same Idempotency-Key with a different body is IDEMPOTENCY_KEY_REUSED.
• A refusal carries data.blocking — the gates that are still open — so one call tells you both that it did not issue and what to do about it.

{
    "document": {
        "document_number": "AB/LND/COFO/2026/4F2K7C/TCC-2026-004418",
        "short_number": "AB-LND26-4F2K7C",
        "status": "valid",
        "tcc_ref": "TCC/2026/004418",
        "tcc_valid_until": "2026-12-31",
        "issued_at": "2026-09-14T10:02:11+01:00",
        "verification_id": "VRF-2026-9F3C1D7A4B2E",
        "verify_url": "https://services.abiastate.gov.ng/verify/document/AB-LND26-4F2K7C",
        "void_reason": null
    }
}

Look a document up by its long number

The long document number contains forward slashes and a route parameter never spans one, so the full number is carried in the body instead. The answer is the same record GET /documents/{no} returns.

• Nothing is minted, so no Idempotency-Key is required.

{
    "number": "AB/LND/COFO/2026/4F2K7C/TCC-2026-004418"
}

Read a final document from the register

The owning agency sees the whole record. Any other key sees the limited public set — issuer, process, reduced party name, clearance reference and status — because a document number is a verification instrument, not a licence to read another agency's case file.

• {no} is the SHORT number. The long form contains "/" and a route parameter never spans one, so post the long number to /documents/verify instead.
• A VOID document still answers, with its whole record in data — but as a refusal carrying DOCUMENT_VOID, because "this number is void" is not a favourable answer.

The evidence bundle behind a document

Every gate as it stood at issuance — status, the frozen basis, the rule version, the assessments raised and the payments matched, and the clearance certificate cited (FR-14.4). This is what an auditor reads a year later, and it is available to the owning agency only.

• The bundle is versioned and hashed. Store the sha256 with your copy: it is how a printed bundle is proved identical to the one the platform holds.

Verify a document number without a key

The machine twin of the public verification page. No credential, no personal data: the issuer, what was issued, a reduced name, the clearance reference and whether the document is genuine and still valid. Throttled per address, and every lookup is written to the verification ledger with the caller's address.

• Use this to verify a document presented to you; use GET /documents/{no} to read one you issued. For a number printed in its long form, post it to /public/documents/verify.
• A number that is not on the register answers ok=false with DOCUMENT_NOT_FOUND and no data. A number that is VOID answers ok=false with DOCUMENT_VOID and the record in data — being told it is void is the point.
• request.client, request.mda and request.env are null on this route: there is no key, so there is nothing to name.

Verify a long document number without a key

The unauthenticated twin of /documents/verify, for a number printed in its long form. Same limited answer as the public GET: issuer, process, reduced name, clearance reference and status. Throttled per address.

{
    "number": "AB-LND26-4F2K7C"
}

Onboard a contractor

Registers a contractor for award and payment (FR-6.1). The entity and every director are checked against the clearance registry and that answer is frozen into the record with its verification ids, so a later dispute can see what was known on the day. Bank details are encrypted at rest and only the last four digits are ever returned.

• The record lands pending_verification. A second officer verifies it in the procurement console, and the officer who onboarded may never be the officer who verifies (SEC-8) — which is why there is no verify endpoint here.
• Changing bank details bumps a version; a voucher pins the version it was approved against.
• Identifier and bank fields sit at the TOP LEVEL of the body. There is no nested party or bank object.
• This endpoint is part of the procurement surface. When that surface is switched off on a deployment every call here answers API_DISABLED.

{
    "rc_number": "RC9900101",
    "legal_name": "Sandbox Compliant Holdings Limited",
    "entity_type": "llc",
    "vat_registered": true,
    "classes_of_work": [
        "civil"
    ],
    "bank_code": "058",
    "account_no": "0123456789",
    "account_name": "Sandbox Compliant Holdings Limited"
}

Read a contractor

The record as held, including the frozen director snapshot and the bank details reduced to their last four digits.

• The account number is not in this answer and will not be added to it: an API that can echo an account number is an API that can be used to harvest them.

Call a contract up by its full award number

The award number is a final document number and contains forward slashes, so the long form travels in the body. This is the call the voucher screen makes: it returns the award date, the sum, approved variations, paid to date, retention and the stamp and capital gains position — everything needed to raise a payment, and no bank details.

• Nothing is minted, so no Idempotency-Key is required.

{
    "final_doc_no": "AB-DPO26-9K41XA"
}

Request a contract award and run the award gate

Creates the contract and runs the award gate with the contract sum as the declared value. Stamp duty is due ON AWARD (BR-12), so the answer carries the stamp bill and what is outstanding on it; capital gains is recorded cleared with a reference or not applicable with a named reason (BR-23). The award itself is taken by a Due Process officer in the console once the gates are terminal — there is no force path, and no API path to an unearned award.

• The award number IS the final document number. There is no separate certificate to issue.
• Blocking gates are the EXPECTED answer here, not a refusal: ok=true with may_be_awarded=false and the outstanding stamp duty named. BR-12 means the duty has not been paid yet by definition.

{
    "contractor_ref": "CTR-2026-000318",
    "title": "Reconstruction of Bende Road, Phase 2",
    "contract_type": "construction",
    "contract_sum": 184500000,
    "vat_treatment": "exclusive",
    "retention_pct": 5
}

Read a contract by its contract reference

Everything a paying agency needs before raising a voucher: award date, sum, approved variations, paid to date, retention held and released, the stamp and capital gains position, and the contractor it was awarded to.

• {ref} is the CONTRACT reference, CON-YYYY-XXXXXX — the award number is not accepted in a path, in either form. Post the award number to /contracts/lookup instead.

Raise a variation on the increment

Records an increment to the contract. The increment goes through the same award gate as the original sum, so stamp duty is assessed on the increase — a variation is not a way to enlarge a contract behind the duty that was paid on it.

• The increment joins the contract only when a second officer approves the variation in the console (SEC-8), and its own stamp duty is gated first — so a variation is never instantly spendable.
• Cumulative voucher gross is checked against the sum plus APPROVED variations, so a variation must be recorded and approved before the voucher that relies on it.

{
    "amount": 18450000,
    "reason": "Additional drainage, approved by EXCO reference EXCO/2026/114"
}

Raise a payment voucher against a contract

The machine twin of the agency voucher screen. There is no payee, no bank account and no net figure in the request: the contract supplies the first two and the deduction engine computes the third. The voucher is created against the contract's award number and the full deduction breakdown comes back with the basis sentence for every line.

• net_amount is null until every deductible line has been ticked (BR-17). That is not a redaction: the column is NULL, because a net that has not been agreed does not exist. net_available says which it is.
• A contract that has not been AWARDED carries no award number and is refused with CONTRACT_NOT_FOUND: no voucher exists without a final document number (BR-14).
• Send payee_name, bank_code, account_no, net_amount or withheld_total and the call is refused with VALIDATION_ERROR naming the field. They are not ignored — an integrator who believes they set the net has a bug they need to see.
• The clearance is re-checked for the voucher's fiscal year by POST /pvs/{pv_no}/validate, which is the next call to make.
• Degraded mode: while the taxpayer register or the collection rails are unavailable, a well-formed request is answered QUEUED_DEGRADED with HTTP 202 instead — no voucher is raised meanwhile; the period is fixed at the moment of the request. The error details and data carry queue_ref (QUE-YYYY-XXXXXX) and queue_url; follow it with GET /queue/{ref} or the queue.processed webhook. Queued is not approved: when service resumes the request goes through exactly the checks a live call does, and may still be refused. A malformed request is refused at once, as it would be live; the same Idempotency-Key with a different body is IDEMPOTENCY_KEY_REUSED.

{
    "pv_type": "part",
    "gross_amount": 42000000,
    "description": "Interim valuation 2",
    "invoice_ref": "INV-0442"
}

{
    "voucher": {
        "pv_no": "PV-PAR-2026-11010001-000318",
        "pv_type": "part",
        "status": "DRAFT",
        "mda": "11010001",
        "award_number": "AB/DPO/AWRD/2026/9K41XA/TCC-2026-004418",
        "payee": "Sandbox Compliant Holdings Limited",
        "entity_type": "llc",
        "description": "Interim valuation 2",
        "invoice_ref": "INV-0442",
        "gross_amount": 42000000,
        "withheld_total": 4515000,
        "net_amount": null,
        "net_available": false,
        "pending_ticks": 4,
        "deductions": [
            {
                "line_no": 1,
                "head": "STAMP",
                "authority": "ABIA_BIR",
                "rev_code": null,
                "revenue_item": null,
                "rate_value": null,
                "rate_kind": "none",
                "basis": "Stamp duty settled on award under payment ABP-2026-77003318; not withheld again (BR-12)",
                "base_amount": 0,
                "amount": 0,
                "applicability": "settled_at_award",
                "na_reason": null,
                "status": "settled",
                "settled_ref": "ABP-2026-77003318",
                "provisional": false
            },
            {
                "line_no": 2,
                "head": "WHT",
                "authority": "NRS",
                "rev_code": null,
                "revenue_item": null,
                "rate_value": 2.5,
                "rate_kind": "percent",
                "basis": "2.5% withholding on construction by a limited company, on gross exclusive of VAT (BR-15)",
                "base_amount": 42000000,
                "amount": 1050000,
                "applicability": "deductible",
                "na_reason": null,
                "status": "pending",
                "settled_ref": null,
                "provisional": true
            }
        ],
        "fiscal_year": 2026,
        "period": "2026-09",
        "payment_code": null,
        "paid_at": null
    },
    "message": "Raised. Validate it to re-check the clearance, then the deductions are ticked in the console."
}

Raise a voucher against an award or payment authority number

The same act with the number in the body rather than the contract in the path. It takes an award number directly, and it is the only way to raise a voucher against a PAYMENT AUTHORITY — imprest, an advance, a non-contract payment. An authority is the final-document equivalent for those, so BR-14 holds here too.

• Cumulative gross is checked against the authority's ceiling and its validity dates.
• Degraded mode: while the taxpayer register or the collection rails are unavailable, a well-formed request is answered QUEUED_DEGRADED with HTTP 202 instead — no voucher is raised meanwhile; the period is fixed at the moment of the request. The error details and data carry queue_ref (QUE-YYYY-XXXXXX) and queue_url; follow it with GET /queue/{ref} or the queue.processed webhook. Queued is not approved: when service resumes the request goes through exactly the checks a live call does, and may still be refused. A malformed request is refused at once, as it would be live; the same Idempotency-Key with a different body is IDEMPOTENCY_KEY_REUSED.

{
    "final_doc_no": "AB-AGT26-2M8P4D",
    "pv_type": "non_contract",
    "gross_amount": 1250000,
    "description": "Quarterly office supplies"
}

Validate a draft voucher

Re-checks the clearance for the voucher's fiscal year — the entity and every director (BR-03/04) — recomputes the deduction lines and moves the voucher from DRAFT to VALIDATED. A clearance that is not current leaves it in DRAFT with the reason and a remediation link, so the voucher is never lost, only waiting.

• A stale clearance is a REFUSAL that still carries data: data.voucher is the voucher as it stands (still DRAFT) and data.blocking names the subject.
• Everything after this point — ticking, controller approval, warrant, treasury approval — is done by named officers in the consoles, because each step is a different person and SEC-8 will not let one credential be all of them.

Read a payment voucher

The voucher with its deduction breakdown and its position in the approval chain. Once paid it carries the payment code — the one string that ties voucher, schedule line, covering letter, bank narration and credit note together (FR-7.16).

• net_amount stays null until the voucher reaches TICKED, on this endpoint as everywhere else.

Advise a collection against a verification

An agency system telling the platform that money was collected for an answer the platform gave. The verification id is mandatory and must exist (SEC-5, FR-11.5): a payment that cites no verification is refused, because a collection with no verification behind it is exactly the leak this platform exists to close.

• The verification must be one this client was answered with, in this environment. Someone else's verification is as good as none.
• The transaction is taken from the verification. Send transaction_ref only when the verification does not name one.
• The reference is then checked against the central ledger: unknown, unsettled, wrong amount, wrong payer or already spent are all refusals, each with its own code.
• Degraded mode: while the taxpayer register or the collection rails are unavailable, a well-formed request is answered QUEUED_DEGRADED with HTTP 202 instead — the verification citation is checked at once, but the reference is neither matched nor refused until the ledger can be read. The error details and data carry queue_ref (QUE-YYYY-XXXXXX) and queue_url; follow it with GET /queue/{ref} or the queue.processed webhook. Queued is not approved: when service resumes the request goes through exactly the checks a live call does, and may still be refused. A malformed request is refused at once, as it would be live; the same Idempotency-Key with a different body is IDEMPOTENCY_KEY_REUSED.

{
    "verification_id": "VRF-2026-9F3C1D7A4B2E",
    "reference": "ABP-2026-77120043",
    "amount": 2500000,
    "head": "CGT"
}

List your subscriptions

Every endpoint registered by this client, with its health. A subscription paused after repeated failures shows here with its failure count before it shows anywhere else.

Subscribe to events

Registers an HTTPS endpoint and returns the signing secret ONCE. Store it: it is encrypted at rest and cannot be shown again. The URL must be https, must resolve to a public address, and must not redirect — a loopback or private host is refused outright.

• Subscribe to the events you handle. An event you did not ask for is never sent, and an unknown event name is a validation error rather than a silent no-op.
• One client may hold ten endpoints. Delete one before registering an eleventh.

{
    "url": "https://lands.example.gov.ng/hooks/abia",
    "events": [
        "transaction.gate_changed",
        "document.issued"
    ]
}

Read one subscription

The subscription with its recent delivery history: what was sent, what your endpoint answered, and when the next attempt is due. The first place to look when events have stopped arriving.

• The secret is never returned. If you have lost it, delete the subscription and register it again.

Resume a paused or disabled subscription

Clears the failure count and puts the subscription back to active. Use it once your endpoint is answering again — the platform pauses rather than deletes, so nothing has to be reconfigured. The URL is re-checked against the SSRF rules first: a name that now resolves to a private address is refused.

• Resuming does not resend what was already marked dead; use the redeliver endpoint for that.

Send one failed delivery again

Puts a single failed or dead delivery back at the front of the queue, so an outage on your side does not cost you the event it spanned. It goes out with its original delivery id, so your deduplication still holds.

• One delivery per call: name it. Read GET /webhooks/{id} for the ids of the deliveries that failed.
• A delivery that is not failed or dead is refused with VALIDATION_ERROR naming its current status — a delivered event is not resent.

{
    "delivery_id": 4417
}

Stop a subscription

Stops delivery. The subscription is DISABLED rather than erased, so its delivery history — which is the evidence in a "we never received it" conversation — survives, and POST /webhooks/{id}/enable can bring it back without reconfiguring anything.

• Events already queued for it are kept but never sent while it is disabled.

Read the seeded identities

The same cast this portal publishes, from the sandbox itself — so a test harness can read it at run time instead of hard-coding what a page said.

Settle a sandbox bill

Marks a sandbox bill settled so the gate that is waiting on it can clear. There is no payment gateway in the sandbox and nothing here reaches the collection ledger: this is the stand-in for a taxpayer paying, and a live key is refused.

• It settles the assessment in full. There is no partial-payment parameter — to see a shortfall, work a case whose declared value exceeds the basis of the clearance held.
• The reference to cite afterwards comes back as data.paid_ref.

{
    "reference": "SBX-BAS-000418"
}

Reseed the sandbox

Removes the transactions, documents, contracts and vouchers the fixtures took part in and rebuilds the cast. The published ABSSINs themselves survive — they are documented, and your stored test data points at them. Three per hour, per client; it also runs nightly on its own.

• The body is empty. There is no confirmation flag: the Idempotency-Key is what stops a retry resetting twice, and the throttle is what stops a loop.
• Every transaction, document, contract and voucher you were holding is gone afterwards. That is the point: a test that depends on yesterday's data is not a test.

Follow a request accepted in degraded mode

When a dependency the platform does not own is down, a submission, a document request, a payment citation, a voucher raise or a corporate registration is answered 202 QUEUED_DEGRADED with a queue reference instead of being judged. Queued is not approved: the request carries no verdict, and when service resumes it is processed through exactly the checks a live call goes through. This call says where it stands and, once it has been processed, what the answer was.

• Any active key may call it, but a client sees only the requests IT queued, in its own environment. Another client's reference, a counter's, or one that does not exist is NOT_FOUND alike.
• status: queued (waiting), draining (being processed now), done (the service answered — outcome.ok says whether it was accepted or refused), failed (it could not be processed at all; submit it again) or abandoned.
• Do not issue, pay or act on a queued request. A document number, voucher number or party reference exists only once outcome carries one.
• Prefer the queue.processed webhook to tight polling: the queue is drained every minute once the dependency has recovered. The webhook is sent for live requests only; in the sandbox, poll.

{
    "queue_ref": "QUE-2026-7K2M9P",
    "kind": "document_request",
    "status": "done",
    "message": "Processed.",
    "subject_ref": "BTX-2026-004871",
    "queued_at": "2026-09-14 09:12:44",
    "next_attempt_at": null,
    "completed_at": "2026-09-14 09:41:02",
    "attempts": 0,
    "outcome": {
        "ok": true,
        "outcome": "accepted",
        "txn_ref": "BTX-2026-004871",
        "doc_no": "AB/LND/COFO/2026/4F2K7C/TCC-2026-004418",
        "doc_no_short": "AB-LND26-4F2K7C",
        "message": "Issued: AB/LND/COFO/2026/4F2K7C/TCC-2026-004418"
    },
    "queue_url": "https://services.abiastate.gov.ng/api/v1/queue/QUE-2026-7K2M9P"
}

List the recent data-warehouse extracts

One extract per day: a gzipped JSON-lines file per dataset and a manifest naming each file with its row count and sha256. Each day is a delta — the rows created or changed inside that day — so a rebuilt day reproduces itself and a warehouse can replay a gap. No file carries a national identity number, bank verification number, TIN, phone or email.

• Live keys only. A sandbox key is refused with SCOPE_MISSING even when it holds dw: the warehouse is fed from live data.
• Newest first. ?limit= takes 1 to 60 days; the default is 30, which is also the retention.
• available is true when the day is ready AND its files are still on disk; only then is manifest_url set.
• complete=false marks a day extracted before it ended. It will be rebuilt, so collect it again.

{
    "env": "live",
    "retention_days": 30,
    "datasets": [
        "parties",
        "tcc",
        "transactions"
    ],
    "extracts": [
        {
            "date": "2026-09-13",
            "status": "ready",
            "available": true,
            "complete": true,
            "schema_version": 1,
            "file_count": 12,
            "total_rows": 18422,
            "total_bytes": 1204116,
            "built_at": "2026-09-14 01:15:09",
            "expires_at": "2026-10-14 01:15:09",
            "manifest_url": "https://services.abiastate.gov.ng/api/v1/dw/extracts/2026-09-13"
        }
    ]
}

Read one day's extract manifest

The manifest exactly as the extract wrote it — window, completeness, privacy statement and every file — with a download URL added to each file. The manifest is written last, so its presence is what says the day's set is whole.

• Verify each file against its sha256 after download. The platform checks it before sending as well, and never sends a file that does not match.
• Money and other decimal columns are JSON strings inside the files, so no precision is lost in transit.
• A day that was never built, has expired, or is being rebuilt right now is NOT_FOUND. Try again later for a rebuild.

Download one extract file

The file itself, as application/gzip — not a JSON envelope. The platform reads the file, checks its sha256 against the manifest and sends exactly the bytes it checked. Refusals are still the usual JSON envelope.

• The name must be one the manifest lists for that date; anything else is NOT_FOUND.
• X-Content-SHA256 carries the verified hash and X-Extract-Rows the line count. Cache-Control is private, no-store: do not put a caching proxy in front of this call.
• A file that fails its integrity check is not sent: the answer is a retryable INTERNAL_ERROR and the day is rebuilt by the Board.
• Files larger than 48 MB are not served over the API and are refused with VALIDATION_ERROR; collect those by SFTP.