NIN TRUST - Portal

Overview & Base Architecture

The NIN Services REST API enables partners, fintech platforms, and verified agents to submit, automate, and track complex National Identity Management Commission (NIMC) service requests programmatically. Every submission is assigned a unique reference code and tracked in real-time.

Base Endpoint (Production)

https://irust.ng/api/v1/nin

Data Format & Protocols

Strict HTTPS, JSON Request & Response bodies

Atomic Ledger Guarantee: When a request is submitted, your wallet is debited atomically according to your tier rate. If a service submission fails upstream or is rejected by NIMC, your account balance is instantly auto-refunded and recorded in your transaction history.

Authentication & Standard Headers

All API requests must include your Secret API Token passed as a standard HTTP Authorization: Bearer header. Requests without valid authentication will return HTTP 401 Unauthorized.

Header	Value	Required	Description
Authorization	Bearer <YOUR_API_TOKEN>	Required	Your personal secret developer token.
Content-Type	application/json	Required	Declares JSON payload body for POST requests.
Accept	application/json	Required	Ensures JSON formatted response from server.

// Sample Header Specification
POST /api/v1/nin/ipe HTTP/1.1
Host: irust.ng
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Accept: application/json

Service Fees & Pricing Matrix

Live database rates resolved dynamically per user tier

Fees are charged based on your user tier (personal, agent, partner, api). When submitting requests via API, your configured tier rate is applied automatically and debited atomically from your wallet.

View Pricing For:

Service Category	Service Field	Code	Personal (₦)	Agent (₦)	Partner (₦)	API (₦)	Turnaround	Audit Status
FIRST BANK	Correction of name	`003`	₦12,000.00 You	₦12,000.00	₦12,000.00	₦12,000.00	15 - 60 minutes	Automated
FIRST BANK	Date of birth update	`004`	₦10,000.00 You	₦10,000.00	₦10,000.00	₦10,000.00	15 - 60 minutes	Automated
FIRST BANK	Correction of name and date of birth	`006`	₦15,000.00 You	₦15,000.00	₦15,000.00	₦15,000.00	15 - 60 minutes	Automated
FIRST BANK	Complete change of name	`007`	₦50,000.00 You	₦50,000.00	₦50,000.00	₦50,000.00	15 - 60 minutes	Automated
FIRST BANK	Gender Update	`008`	₦5,000.00 You	₦5,000.00	₦5,000.00	₦5,000.00	15 - 60 minutes	Automated
FIRST BANK	Bvn Revalidation	`009`	₦10,000.00 You	₦10,000.00	₦10,000.00	₦10,000.00	15 - 60 minutes	Automated
FIRST BANK	Whitelist BVN	`010`	₦15,000.00 You	₦15,000.00	₦15,000.00	₦15,000.00	15 - 60 minutes	Automated
FIRST BANK	BVN Deletion Request	`060`	₦20,000.00 You	₦20,000.00	₦20,000.00	₦20,000.00	15 - 60 minutes	Automated
FIRST BANK	Correction of Name, DOB and phone NO	`050`	₦18,000.00 You	₦18,000.00	₦18,000.00	₦18,000.00	15 - 60 minutes	Automated
ECO BANK	Correction of Name	`E001`	₦10,000.00 You	₦10,000.00	₦10,000.00	₦10,000.00	24 - 72 business hours	Automated
ECO BANK	Date of birth update	`E002`	₦10,000.00 You	₦10,000.00	₦10,000.00	₦10,000.00	24 - 72 business hours	Automated
ECO BANK	Gender Update	`E003`	₦10,000.00 You	₦10,000.00	₦10,000.00	₦10,000.00	24 - 72 business hours	Automated
ECO BANK	Phone number and email update	`E004`	₦10,000.00 You	₦10,000.00	₦10,000.00	₦10,000.00	24 - 72 business hours	Automated
ECO BANK	Correction of name and date of birth	`E005`	₦15,000.00 You	₦15,000.00	₦15,000.00	₦15,000.00	24 - 72 business hours	Automated
ECO BANK	Complete Change of name	`E006`	₦120,000.00 You	₦120,000.00	₦120,000.00	₦120,000.00	24 - 72 business hours	Automated
ECO BANK	Multiful Update on BVN	`E007`	₦20,000.00 You	₦20,000.00	₦20,000.00	₦20,000.00	24 - 72 business hours	Automated
ECO BANK	Correction of name and P/N	`E008`	₦15,000.00 You	₦15,000.00	₦15,000.00	₦15,000.00	24 - 72 business hours	Automated
Data	mtn-data	`104`	₦0.00 You	₦0.00	₦0.00	₦0.00	1 - 4 hours	Automated
Data	airtel-data	`105`	₦0.00 You	₦0.00	₦0.00	₦0.00	1 - 4 hours	Automated
Data	glo-data	`106`	₦0.00 You	₦0.00	₦0.00	₦0.00	1 - 4 hours	Automated
Data	Etisalat	`107`	₦0.00 You	₦0.00	₦0.00	₦0.00	1 - 4 hours	Automated
NIN Modification	Correction of name	`032`	₦12,000.00 You	₦12,000.00	₦12,000.00	₦12,000.00	24 - 48 hours	Automated
NIN Modification	Phone Number Update	`033`	₦12,000.00 You	₦12,000.00	₦12,000.00	₦12,000.00	24 - 48 hours	Automated
NIN Modification	Gender Update	`034`	₦12,000.00 You	₦12,000.00	₦12,000.00	₦12,000.00	24 - 48 hours	Automated
NIN Modification	Date of birth update below 5 year	`035`	₦65,000.00 You	₦65,000.00	₦65,000.00	₦65,000.00	24 - 48 hours	Automated
NIN Modification	Date of birth Update above 5 year	`036`	₦150,000.00 You	₦150,000.00	₦150,000.00	₦150,000.00	24 - 48 hours	Automated
NIN Modification	Change of Ressidence Address	`037`	₦12,000.00 You	₦12,000.00	₦12,000.00	₦12,000.00	24 - 48 hours	Automated
NIN Modification	Change of state of Origin	`0141`	₦12,000.00 You	₦12,000.00	₦12,000.00	₦12,000.00	24 - 48 hours	Automated
NIN Modification	Marriage Status Update	`NIN100`	₦12,000.00 You	₦12,000.00	₦12,000.00	₦12,000.00	24 - 48 hours	Automated
NIN Modification	Change of Origin Address	`NIN1001`	₦12,000.00 You	₦12,000.00	₦12,000.00	₦12,000.00	24 - 48 hours	Automated
IPE	IPE	`002`	₦1,500.00 You	₦1,500.00	₦1,500.00	₦1,500.00	5 - 30 minutes	Automated
IPE	Modification IPE	`500`	₦1,500.00 You	₦1,500.00	₦1,500.00	₦1,500.00	5 - 30 minutes	Automated

Service Category	Service Field	Field Code	Tier Price (₦)	Turnaround Time	Status Tracking
FIRST BANK	Correction of name	`003`	₦12,000.00 ₦12,000.00 ₦12,000.00 ₦12,000.00	15 - 60 minutes	Automated Audit
FIRST BANK	Date of birth update	`004`	₦10,000.00 ₦10,000.00 ₦10,000.00 ₦10,000.00	15 - 60 minutes	Automated Audit
FIRST BANK	Correction of name and date of birth	`006`	₦15,000.00 ₦15,000.00 ₦15,000.00 ₦15,000.00	15 - 60 minutes	Automated Audit
FIRST BANK	Complete change of name	`007`	₦50,000.00 ₦50,000.00 ₦50,000.00 ₦50,000.00	15 - 60 minutes	Automated Audit
FIRST BANK	Gender Update	`008`	₦5,000.00 ₦5,000.00 ₦5,000.00 ₦5,000.00	15 - 60 minutes	Automated Audit
FIRST BANK	Bvn Revalidation	`009`	₦10,000.00 ₦10,000.00 ₦10,000.00 ₦10,000.00	15 - 60 minutes	Automated Audit
FIRST BANK	Whitelist BVN	`010`	₦15,000.00 ₦15,000.00 ₦15,000.00 ₦15,000.00	15 - 60 minutes	Automated Audit
FIRST BANK	BVN Deletion Request	`060`	₦20,000.00 ₦20,000.00 ₦20,000.00 ₦20,000.00	15 - 60 minutes	Automated Audit
FIRST BANK	Correction of Name, DOB and phone NO	`050`	₦18,000.00 ₦18,000.00 ₦18,000.00 ₦18,000.00	15 - 60 minutes	Automated Audit
ECO BANK	Correction of Name	`E001`	₦10,000.00 ₦10,000.00 ₦10,000.00 ₦10,000.00	24 - 72 business hours	Automated Audit
ECO BANK	Date of birth update	`E002`	₦10,000.00 ₦10,000.00 ₦10,000.00 ₦10,000.00	24 - 72 business hours	Automated Audit
ECO BANK	Gender Update	`E003`	₦10,000.00 ₦10,000.00 ₦10,000.00 ₦10,000.00	24 - 72 business hours	Automated Audit
ECO BANK	Phone number and email update	`E004`	₦10,000.00 ₦10,000.00 ₦10,000.00 ₦10,000.00	24 - 72 business hours	Automated Audit
ECO BANK	Correction of name and date of birth	`E005`	₦15,000.00 ₦15,000.00 ₦15,000.00 ₦15,000.00	24 - 72 business hours	Automated Audit
ECO BANK	Complete Change of name	`E006`	₦120,000.00 ₦120,000.00 ₦120,000.00 ₦120,000.00	24 - 72 business hours	Automated Audit
ECO BANK	Multiful Update on BVN	`E007`	₦20,000.00 ₦20,000.00 ₦20,000.00 ₦20,000.00	24 - 72 business hours	Automated Audit
ECO BANK	Correction of name and P/N	`E008`	₦15,000.00 ₦15,000.00 ₦15,000.00 ₦15,000.00	24 - 72 business hours	Automated Audit
Data	mtn-data	`104`	₦0.00 ₦0.00 ₦0.00 ₦0.00	1 - 4 hours	Automated Audit
Data	airtel-data	`105`	₦0.00 ₦0.00 ₦0.00 ₦0.00	1 - 4 hours	Automated Audit
Data	glo-data	`106`	₦0.00 ₦0.00 ₦0.00 ₦0.00	1 - 4 hours	Automated Audit
Data	Etisalat	`107`	₦0.00 ₦0.00 ₦0.00 ₦0.00	1 - 4 hours	Automated Audit
NIN Modification	Correction of name	`032`	₦12,000.00 ₦12,000.00 ₦12,000.00 ₦12,000.00	24 - 48 hours	Automated Audit
NIN Modification	Phone Number Update	`033`	₦12,000.00 ₦12,000.00 ₦12,000.00 ₦12,000.00	24 - 48 hours	Automated Audit
NIN Modification	Gender Update	`034`	₦12,000.00 ₦12,000.00 ₦12,000.00 ₦12,000.00	24 - 48 hours	Automated Audit
NIN Modification	Date of birth update below 5 year	`035`	₦65,000.00 ₦65,000.00 ₦65,000.00 ₦65,000.00	24 - 48 hours	Automated Audit
NIN Modification	Date of birth Update above 5 year	`036`	₦150,000.00 ₦150,000.00 ₦150,000.00 ₦150,000.00	24 - 48 hours	Automated Audit
NIN Modification	Change of Ressidence Address	`037`	₦12,000.00 ₦12,000.00 ₦12,000.00 ₦12,000.00	24 - 48 hours	Automated Audit
NIN Modification	Change of state of Origin	`0141`	₦12,000.00 ₦12,000.00 ₦12,000.00 ₦12,000.00	24 - 48 hours	Automated Audit
NIN Modification	Marriage Status Update	`NIN100`	₦12,000.00 ₦12,000.00 ₦12,000.00 ₦12,000.00	24 - 48 hours	Automated Audit
NIN Modification	Change of Origin Address	`NIN1001`	₦12,000.00 ₦12,000.00 ₦12,000.00 ₦12,000.00	24 - 48 hours	Automated Audit
IPE	IPE	`002`	₦1,500.00 ₦1,500.00 ₦1,500.00 ₦1,500.00	5 - 30 minutes	Automated Audit
IPE	Modification IPE	`500`	₦1,500.00 ₦1,500.00 ₦1,500.00 ₦1,500.00	5 - 30 minutes	Automated Audit

Prices are retrieved directly from the live service catalog and service field configurations. All requests are charged atomically upon submission.

1

IPE Clearance Service

Field Code: 002

Submits an IPE (Internal Pre-Enrollment) Clearance request to unlock stuck citizen records with NIMC using the unique 15-character enrollment tracking ID, and query clearing progress in real-time.

POST /api/v1/nin/ipe

Automated Queue

Simplified Payload: description is not required for IPE Clearance. Only your tracking_id is needed.

Request Body (JSON)

Field	Type	Required	Description
tracking_id	string	Required	15-character IPE Tracking ID (e.g. `0T3NU7RSKMCHTT4`).
field_code	string	Optional	Default: `002`. Service field identifier.
description	string	Not Required	Optional custom reference note from your application.

// Sample cURL: Submit IPE Clearance
curl -X POST "https://irust.ng/api/v1/nin/ipe" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "tracking_id": "0T3NU7RSKMCHTT4"
  }'

// 200 OK Response (Submission Confirmed)

{
    "success": true,
    "message": "IPE clearance request submitted successfully.",
    "reference": "IPE-1727702819-ABC1",
    "tracking_id": "0T3NU7RSKMCHTT4",
    "status": "processing",
    "amount_charged": 1500.00,
    "comment": "Request queued for automated clearing"
}

GET /api/v1/nin/ipe/status/{reference}

Real-Time Audit

Check the live clearance status, NIMC remarks, clearing comments, or retrieve the official clearance slip download URL. Also supports POST with {"reference": "..."} or {"tracking_id": "..."}.

Path / Query Parameters

Parameter	Type	Required	Description
{reference}	string	Required	Transaction reference returned upon submission (or passed in query/body).
tracking_id	string	Alternative	Can also query by the 15-character IPE Tracking ID.

// Sample cURL: Check IPE Clearance Status
curl -X GET "https://irust.ng/api/v1/nin/ipe/status/IPE-1727702819-ABC1" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"

// 200 OK Response (Cleared Successfully)

{
    "success": true,
    "reference": "IPE-1727702819-ABC1",
    "service_type": "IPE",
    "service_field": "IPE Clearance",
    "tracking_id": "0T3NU7RSKMCHTT4",
    "status": "successful",
    "comment": "IPE Cleared successfully by NIMC portal",
    "file_url": "https://irust.ng/storage/project-files/nin-ipe/clearance_slip.pdf",
    "amount": 1500.00,
    "submission_date": "2026-09-30T13:40:00Z",
    "updated_at": "2026-09-30T13:55:12Z"
}

2

NIN Modification Service

Field Codes: 003, 004, 006, 007

Submits official NIN modification requests for Date of Birth (DOB), Name, Address, or Phone Number, and track modification attestation review status in real-time.

POST /api/v1/nin/modification

Manual Attestation

Request Body (JSON)

Field	Type	Required	Description
nin	string	Required	11-digit numeric National Identity Number.
field_code	string	Required	`003` (DOB), `004` (Name), `006` (Address), `007` (Phone).
description	string	Required	Brief explanation of modification details.
modification_data	object	Conditional	Required for DOB modifications (includes personal details, parents info, origin).

// Sample cURL: Submit Name Modification
curl -X POST "https://irust.ng/api/v1/nin/modification" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "nin": "12345678901",
    "field_code": "004",
    "description": "Correct surname spelling to Musa"
  }'

// 200 OK Response (Submission Confirmed)

{
    "success": true,
    "message": "NIN modification request submitted successfully.",
    "reference": "NM20260930143210ABC1",
    "nin": "12345678901",
    "service_field": "Name Modification",
    "status": "pending",
    "amount_charged": 3000.00,
    "comment": "Request submitted and pending admin review"
}

GET /api/v1/nin/modification/status/{reference}

Attestation Audit

Check the attestation status, NIMC approval stage, or download the updated NIN modification slip. Also supports POST with {"reference": "..."} or {"nin": "..."}.

Path / Query Parameters

Parameter	Type	Required	Description
{reference}	string	Required	The unique reference string received upon submission (e.g. `NM20260930143210ABC1`).
nin	string	Alternative	Can also query by the 11-digit citizen NIN.

// Sample cURL: Check Modification Status
curl -X GET "https://irust.ng/api/v1/nin/modification/status/NM20260930143210ABC1" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"

// 200 OK Response (Processing Status)

{
    "success": true,
    "reference": "NM20260930143210ABC1",
    "service_type": "nin_modification",
    "service_field": "Name Modification",
    "nin": "12345678901",
    "status": "processing",
    "comment": "Attestation data verified; awaiting NIMC backend authorization",
    "file_url": null,
    "amount": 3000.00,
    "submission_date": "2026-09-30T14:32:10Z",
    "updated_at": "2026-09-30T14:35:00Z"
}

3

NIN Personalisation Service

Field Code: 005

Submits NIN Personalisation requests for rapid manual review, digital card generation, or slip production, and verify fulfillment status.

POST /api/v1/nin/personalisation

Card Slip Production

Request Body (JSON)

Field	Type	Required	Description
tracking_id	string	Required	Tracking ID from the enrolment slip (e.g. `WN0987654321XYZ`).
description	string	Optional	Optional reference description or slip preference.

// Sample cURL: Submit Personalisation
curl -X POST "https://irust.ng/api/v1/nin/personalisation" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "tracking_id": "WN0987654321XYZ",
    "description": "Premium standard plastic slip print"
  }'

// 200 OK Response (Submission Confirmed)

{
    "success": true,
    "message": "NIN personalisation request submitted successfully.",
    "reference": "NINP260930143210ABC1",
    "tracking_id": "WN0987654321XYZ",
    "status": "pending",
    "amount_charged": 1500.00,
    "comment": "Submitted for verification"
}

GET /api/v1/nin/personalisation/status/{reference}

Card Slip Audit

Check the personalisation progress, or download the rendered digital ID card/slip PDF via file_url. Also supports POST with {"reference": "..."} or {"tracking_id": "..."}.

Path / Query Parameters

Parameter	Type	Required	Description
{reference}	string	Required	Personalisation reference code (e.g. `NINP260930143210ABC1`).
tracking_id	string	Alternative	Can also query by the enrolment tracking ID.

// Sample cURL: Check Personalisation Status
curl -X GET "https://irust.ng/api/v1/nin/personalisation/status/NINP260930143210ABC1" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"

// 200 OK Response (Slip Ready)

{
    "success": true,
    "reference": "NINP260930143210ABC1",
    "service_type": "nin_personalization",
    "service_field": "NIN Personalisation",
    "tracking_id": "WN0987654321XYZ",
    "status": "successful",
    "comment": "Personalisation slip generated successfully",
    "file_url": "https://irust.ng/storage/project-files/nin-personalisation/slip_card.pdf",
    "amount": 1500.00,
    "submission_date": "2026-09-30T14:32:10Z",
    "updated_at": "2026-09-30T15:00:22Z"
}

4

NIN Suspension Service

Field Code: 041

Submits a formal citizen NIN suspension request to NIMC investigation desks, and track legal resolution or unlock decisions. Requires explicit citizen consent.

POST /api/v1/nin/suspension

Investigation Desk

Request Body (JSON)

Field	Type	Required	Description
nin	string	Required	11-digit National Identity Number.
first_name	string	Required	Citizen first name.
last_name	string	Required	Citizen surname.
middle_name	string	Optional	Citizen middle name.
phone_number	string	Required	11-digit citizen contact phone number.
consent	boolean	Required	Must be `true` or `1` to confirm authorization.

// Sample cURL: Submit Suspension Request
curl -X POST "https://irust.ng/api/v1/nin/suspension" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "nin": "12345678901",
    "first_name": "Ibrahim",
    "last_name": "Garba",
    "phone_number": "08012345678",
    "consent": true
  }'

// 200 OK Response (Submission Confirmed)

{
    "success": true,
    "message": "NIN suspension request submitted successfully.",
    "reference": "SUS-1727702825-XYZ9",
    "nin": "12345678901",
    "status": "pending",
    "amount_charged": 3000.00
}

GET /api/v1/nin/suspension/status/{reference}

Investigation Audit

Check the investigation resolution and official compliance note. Also supports POST with {"reference": "..."} or {"nin": "..."}.

Path / Query Parameters

Parameter	Type	Required	Description
{reference}	string	Required	Suspension reference string (e.g. `SUS-1727702825-XYZ9`).
nin	string	Alternative	Can also query by the citizen 11-digit NIN.

// Sample cURL: Check Suspension Status
curl -X GET "https://irust.ng/api/v1/nin/suspension/status/SUS-1727702825-XYZ9" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"

// 200 OK Response (Investigation Status)

{
    "success": true,
    "reference": "SUS-1727702825-XYZ9",
    "service_type": "NIN_SUSPENSION",
    "service_field": "NIN Suspension",
    "nin": "12345678901",
    "status": "in-progress",
    "comment": "Consent verified; case assigned to NIMC zonal audit committee",
    "file_url": null,
    "amount": 3000.00,
    "submission_date": "2026-09-30T14:40:00Z",
    "updated_at": "2026-09-30T14:50:00Z"
}

5

NIN Validation Service

Field Codes: 015, 016, 017

Submits high-speed NIN Validation requests to reconcile unindexed biometric records, resolve BVN-NIN mismatches, and audit live portal sync status.

POST /api/v1/nin/validation

High-Speed Gateway

Simplified Payload: description is not required for NIN Validation. Only your 11-digit nin is required.

Request Body (JSON)

Field	Type	Required	Description
nin	string	Required	11-digit National Identity Number to validate.
field_code	string	Optional	Validation code (Default: `015`). Options: `015`, `016`, `017`.
description	string	Not Required	Optional custom reference note (not required).

// Sample cURL: Submit NIN Validation (Only nin required)
curl -X POST "https://irust.ng/api/v1/nin/validation" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "nin": "12345678901"
  }'

// 200 OK Response (Submission Confirmed)

{
    "success": true,
    "message": "NIN validation request submitted successfully.",
    "reference": "REF-VAL2609301432ABC",
    "nin": "12345678901",
    "status": "processing",
    "amount_charged": 1000.00,
    "comment": "Validation request queued"
}

GET /api/v1/nin/validation/status/{reference}

Instant Audit

Check the validation resolution, synchronization confirmation, or error remarks. Also supports POST with {"reference": "..."} or {"nin": "..."}.

Path / Query Parameters

Parameter	Type	Required	Description
{reference}	string	Required	Validation transaction reference (e.g. `REF-VAL2609301432ABC`).
nin	string	Alternative	Can also query by the 11-digit NIN.

// Sample cURL: Check Validation Status
curl -X GET "https://irust.ng/api/v1/nin/validation/status/REF-VAL2609301432ABC" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"

// 200 OK Response (Validation Synchronized)

{
    "success": true,
    "reference": "REF-VAL2609301432ABC",
    "service_type": "NIN_VALIDATION",
    "service_field": "NIN Validation (General)",
    "nin": "12345678901",
    "status": "successful",
    "comment": "Record successfully re-indexed and validated on NIMC central database",
    "file_url": null,
    "amount": 1000.00,
    "submission_date": "2026-09-30T14:10:00Z",
    "updated_at": "2026-09-30T14:12:30Z"
}

6

Universal NIN Status Audit Endpoint

Real-Time Audit (Free)

A unified lookup endpoint capable of querying any NIN service request across all categories using the transaction reference, enrollment tracking ID, or citizen NIN.

GET / POST /api/v1/nin/status/{reference?}

Cross-Service Lookup

Request Parameters (URL Path, Query, or JSON Body)

Parameter	Type	Required	Description
reference	string	Recommended	The unique reference string received upon submission (in URL path, query string, or JSON payload).
tracking_id	string	Alternative	Enrollment tracking ID (for IPE clearance and personalisation requests).
nin	string	Alternative	11-digit citizen NIN (for modifications, suspensions, and validations).

// Sample cURL: Universal Status Query
curl -X GET "https://irust.ng/api/v1/nin/status/IPE-1727702819-ABC1" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"

200 OK Response Schema Breakdown

Response Field	Type	Description
success	boolean	`true` when the record is located and audited.
reference	string	Unique transaction reference identifier.
service_type	string	Category (`IPE`, `nin_modification`, `nin_personalization`, `NIN_SUSPENSION`, `NIN_VALIDATION`).
service_field	string	Specific sub-service name (e.g. `IPE Clearance`, `DOB Modification`).
tracking_id	string\|null	Tracking ID associated with the request (if applicable).
nin	string\|null	11-digit NIN associated with the request (if applicable).
status	string	Current lifecycle state: `pending`, `processing`, `in-progress`, `successful`, `resolved`, `rejected`, `failed`, `query`, `remark`.
comment	string\|null	Status note, official NIMC response, or resolution instruction.
file_url	string\|null	Public URL to download the processed slip, clearance certificate, or attestation document.
amount	float	Service fee deducted for the request.
submission_date	string	ISO-8601 timestamp of original submission.
updated_at	string	ISO-8601 timestamp of most recent status update.

Sample Status Responses

// 1. Successful Status Response (with file_url)

{
    "success": true,
    "reference": "IPE-1727702819-ABC1",
    "service_type": "IPE",
    "service_field": "IPE Clearance",
    "tracking_id": "0T3NU7RSKMCHTT4",
    "nin": null,
    "status": "successful",
    "comment": "IPE Cleared successfully by NIMC portal",
    "file_url": "https://irust.ng/storage/project-files/nin-ipe/clearance_slip.pdf",
    "amount": 1500.00,
    "submission_date": "2026-09-30T13:40:00Z",
    "updated_at": "2026-09-30T13:55:12Z"
}

// 2. Processing / Attestation In-Progress Response

{
    "success": true,
    "reference": "NM20260930143210ABC1",
    "service_type": "nin_modification",
    "service_field": "DOB Modification",
    "tracking_id": null,
    "nin": "12345678901",
    "status": "processing",
    "comment": "Attestation data verified; awaiting NIMC backend authorization",
    "file_url": null,
    "amount": 15000.00,
    "submission_date": "2026-09-30T14:32:10Z",
    "updated_at": "2026-09-30T14:35:00Z"
}

// 3. Failed / Rejected Response (With Auto-Refund)

{
    "success": true,
    "reference": "REF-VAL2609301432ABC",
    "service_type": "NIN_VALIDATION",
    "service_field": "NIN Validation (General)",
    "tracking_id": null,
    "nin": "12345678901",
    "status": "failed",
    "comment": "Invalid citizen NIN record on NIMC database. Amount ₦1,000.00 refunded.",
    "file_url": null,
    "amount": 1000.00,
    "submission_date": "2026-09-30T14:10:00Z",
    "updated_at": "2026-09-30T14:12:00Z"
}

Status Lifecycle & Polling Guidelines

Understanding how statuses transition through the platform enables you to build resilient, automated workflows without unnecessary server polling.

Status Value	Badge	Description & System Behavior	Recommended Action
pending	Pending	Request received, wallet debited, and queued in the dispatch broker.	Poll every 30-60 seconds.
processing / in-progress	Processing	Actively transmitted to NIMC upstream gateway or under manual attestation review.	Poll every 60-120 seconds.
successful / resolved	Successful	Request resolved. `file_url` contains the download document link if applicable.	Completed. Store result.
query / remark	Query	NIMC flagged an inconsistency (e.g. invalid document or mismatched parent name).	Review `comment` field for instructions.
failed / rejected	Failed	Request declined or rejected by NIMC. Fee is auto-credited back to your wallet.	Do not poll further. Correct data.

Recommended Polling Strategy: We suggest polling the status endpoint after 30 seconds, then doubling the interval up to 5 minutes. Do not send more than 1 status check per 10 seconds per reference.

Implementation Code Examples

# 1. Submit IPE Clearance (Only tracking_id is required)
curl -X POST "https://irust.ng/api/v1/nin/ipe" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "tracking_id": "0T3NU7RSKMCHTT4"
  }'

# 2. Check Request Status via Service Status Endpoint
curl -X GET "https://irust.ng/api/v1/nin/ipe/status/IPE-1727702819-ABC1" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

# 3. Or Check via Universal Status Endpoint
curl -X GET "https://irust.ng/api/v1/nin/status/IPE-1727702819-ABC1" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

<?php

use Illuminate\Support\Facades\Http;

$apiKey = 'YOUR_API_TOKEN';
$baseUrl = 'https://irust.ng/api/v1/nin';

// 1. Submit IPE Request (Only tracking_id is required)
$response = Http::withToken($apiKey)
    ->acceptJson()
    ->post("{$baseUrl}/ipe", [
        'tracking_id' => '0T3NU7RSKMCHTT4',
    ]);

if ($response->successful()) {
    $result = $response->json();
    $reference = $result['reference'];
    echo "Submitted! Reference: {$reference}\n";

    // 2. Poll Status using the service status endpoint
    $statusResponse = Http::withToken($apiKey)
        ->acceptJson()
        ->get("{$baseUrl}/ipe/status/{$reference}");

    print_r($statusResponse->json());
} else {
    echo "Error: " . $response->body();
}

const axios = require('axios');

const API_KEY = 'YOUR_API_TOKEN';
const BASE_URL = 'https://irust.ng/api/v1/nin';

const client = axios.create({
  baseURL: BASE_URL,
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  }
});

async function runNINWorkflow() {
  try {
    // 1. Submit IPE Clearance (Only tracking_id required)
    const res = await client.post('/ipe', {
      tracking_id: '0T3NU7RSKMCHTT4'
    });
    console.log('Submission:', res.data);

    // 2. Check Service Status
    const status = await client.get(`/ipe/status/${res.data.reference}`);
    console.log('Live Status Audit:', status.data);
  } catch (error) {
    console.error('Request failed:', error.response?.data || error.message);
  }
}

runNINWorkflow();

import requests

API_KEY = "YOUR_API_TOKEN"
BASE_URL = "https://irust.ng/api/v1/nin"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

# 1. Submit IPE Clearance (Only tracking_id required)
payload = {
    "tracking_id": "0T3NU7RSKMCHTT4"
}

response = requests.post(f"{BASE_URL}/ipe", json=payload, headers=headers)
data = response.json()
print("Submission Response:", data)

# 2. Check Service Status
if data.get("success"):
    ref = data["reference"]
    status_response = requests.get(f"{BASE_URL}/ipe/status/{ref}", headers=headers)
    print("Live Service Status:", status_response.json())

HTTP Status & Error Codes

HTTP Code	Status Meaning	Description / Remediation
200 OK	Success	Request accepted and processed successfully. Reference generated.
400 Bad Request	Provider / Submission Error	Provider API rejected parameters, or upstream gateway failed to accept payload.
401 Unauthorized	Invalid API Token	Missing or invalid `Authorization: Bearer` token header.
402 Payment Required	Insufficient Wallet Balance	Wallet balance is lower than the required service fee. Fund wallet to proceed.
404 Not Found	Record Not Found	The specified reference code does not exist under your user account.
422 Unprocessable	Validation Error	Missing required fields (e.g. NIN is not 11 digits, missing tracking ID, consent unaccepted).
500 Server Error	Internal Provider Outage	Temporary upstream connectivity error. Retries permitted after delay.

NIN Services API Documentation v1.0 REST

Documentation Sections

Overview & Base Architecture

Authentication & Standard Headers

Service Fees & Pricing Matrix

IPE Clearance Service

Request Body (JSON)

Path / Query Parameters

NIN Modification Service

Request Body (JSON)

Path / Query Parameters

NIN Personalisation Service

Request Body (JSON)

Path / Query Parameters

NIN Suspension Service

Request Body (JSON)

Path / Query Parameters

NIN Validation Service

Request Body (JSON)

Path / Query Parameters

Universal NIN Status Audit Endpoint

Request Parameters (URL Path, Query, or JSON Body)

200 OK Response Schema Breakdown

Status Lifecycle & Polling Guidelines

Implementation Code Examples

HTTP Status & Error Codes