Public API v1

Idyntic Developer Documentation

Integrate predictable Nigerian identity verification into your applications.

Open Developer DashboardRun in Postman

Quickstart Guide

1. Generate a Test API key (id_test_...) from Developer Key Management.
2. Pass your secret token in the Authorization: Bearer header.
3. Execute your first verification or wallet balance query.

curl
1
2
3
4
5
curl https://idyntic.getapexly.com/api/public/v1/verifications/nin \
-H "Authorization: Bearer id_live_your_key" \
-H "Idempotency-Key: customer-check-12345" \
-H "Content-Type: application/json" \
-d '{"nin":"12345678901"}'

Authentication & Permission Scopes

Public API calls authenticate using Bearer tokens in the HTTP Authorization header. API keys are strictly environment-specific and scope-restricted.

Scope NameDescriptionApplicable Routes
BALANCE_READRead organization wallet balance in NGN kobo.GET /api/public/v1/balance
NIN_VERIFYSubmit 11-digit NIN identity lookups via idempotency.POST /api/public/v1/verifications/nin
BVN_VERIFYSubmit 11-digit BVN identity lookups via idempotency.POST /api/public/v1/verifications/bvn

Request Identity & Idempotency

Charged operations require caller-generated Idempotency-Key headers (8 to 128 characters) to guarantee zero duplicate charges across network retries.

1

Caller UUID Key

Attach an Idempotency-Key header to identify the logical charged operation.

2

Atomic Locking

Idyntic locks the key atomically during upstream provider communication. Concurrent retries receive 409 IDEMPOTENCY_IN_PROGRESS with Retry-After: 2.

3

24h Safe Replay

Repeating the identical request body returns the cached response with Idempotency-Replayed: true and 0 kobo additional charge.

Idempotency Key Utility & Helper

Generate a sample key for testing or inspect how to generate dynamic keys in your client or application codebase.

Implementation In Code
javascript
1
2
3
4
5
6
// Node.js (v14.17+) or Modern Browsers
const idempotencyKey = crypto.randomUUID();
 
// Or using uuid package
import { v4 as uuidv4 } from "uuid";
const idempotencyKey = uuidv4();

API Pricing & Billing Rules

Category: Getting Started. Real-time per-call billing schedule for identity lookups and document generation. All rates are calculated in Nigerian Kobo (1 NGN = 100 Kobo). Sandbox test mode is free with unlimited requests.

Standard API Pricing Schedule

Operation / EndpointMethodRequired ScopeSuccessful Lookup (200)Unresolved / Not Found
NIN By NIN
/api/public/v1/verifications/nin
POSTNIN_VERIFY₦100.00 (10,000 kobo)₦100.00 (10,000 kobo)
NIN By Phone
/api/public/v1/verifications/nin/phone
POSTNIN_VERIFY₦120.00 (12,000 kobo)₦100.00 (10,000 kobo)
BVN By BVN
/api/public/v1/verifications/bvn
POSTBVN_VERIFY₦110.00 (11,000 kobo)₦100.00 (10,000 kobo)
BVN Slip Preview (Image/Base64)
/api/public/v1/verifications/bvn/slip/preview
POSTBVN_VERIFY₦0.00 (Free)₦0.00 (Free)
BVN Slip PDF Download
/api/public/v1/verifications/bvn/slip/pdf
POSTBVN_VERIFY₦100.00 (First generation; free re-downloads)₦0.00
Get Wallet Balance
/api/public/v1/balance
GETBALANCE_READ₦0.00 (Free)₦0.00 (Free)

Real-Time Balance Deduction

Real-Time

Verification fees are deducted from your organization wallet only when a request is successfully processed. If an upstream gateway is unreachable or an operation fails, no charges occur.

Zero Charges on Errors

Protected

Client errors (HTTP 400, 401, 402), rate-limiting (HTTP 429), and server errors (HTTP 500) are never charged (0 Kobo).

Idempotency Protection

Safe Retry

Replaying a request with the same Idempotency-Key returns the cached response within 24 hours with Idempotency-Replayed: true and zero additional charges.

Complimentary Re-downloads

Free Replay

Once a BVN Slip PDF is generated for a search reference, all subsequent PDF downloads using the same reference within your organization are free (₦0.00).

Structured Response Billing Object

Every API response includes a transparent billing metadata object detailing the transaction cost, currency, and wallet debit status:

jsonBilling Object Structure
1
2
3
4
5
6
7
8
9
{
"billing": {
"amount": 10000,
"currency": "NGN",
"unit": "kobo",
"charged": true,
"note": "Wallet charged 100.00 NGN"
}
}
GET

/api/public/v1/balance

Category: Wallet Balance. Returns organization wallet balance in Nigerian kobo.

Headers & Requirements

HeaderTypeRequirement
Authorizationstring (Bearer)Required (BALANCE_READ scope)

Sample Request

curlGET /api/public/v1/balance (cURL)
1
2
curl -X GET "https://idyntic.getapexly.com/api/public/v1/balance" \
-H "Authorization: Bearer id_live_your_api_key"

Response Explorer

jsonHTTP 200 OKFree (0 Kobo)
1
2
3
4
5
6
7
8
9
10
{
"success": true,
"message": "Wallet balance retrieved successfully",
"data": {
"balance": 500000,
"currency": "NGN",
"unit": "kobo",
"environment": "live"
}
}
POST

/api/public/v1/verifications/nin

Category: NIN Verification. Performs live identity verification or returns mock sandbox records.

Headers & Requirements

HeaderTypeRequirement
Authorizationstring (Bearer)Required (NIN_VERIFY scope)
Idempotency-Keystring (8-128 chars)Required
Content-Typeapplication/jsonRequired

Request Body (JSON)

FieldTypeDescription
ninstring (11 digits)The Nigerian National Identity Number to verify.

Pricing & Billing Rule

OutcomeCharge AmountKobo Unit
Verified Record Found (200 OK)₦100.0010,000 kobo
Record Not Found (200 OK) / Suspended (422)₦100.0010,000 kobo
Client Error / Auth Error / Idempotent Replay₦0.000 kobo

Sample Request

curlPOST /api/public/v1/verifications/nin (cURL)
1
2
3
4
5
6
7
curl -X POST "https://idyntic.getapexly.com/api/public/v1/verifications/nin" \
-H "Authorization: Bearer id_live_your_api_key" \
-H "Idempotency-Key: e8a01103-e69a-4160-84a1-872f3e5be264" \
-H "Content-Type: application/json" \
-d {
"nin": "12345678901"
}

Response Explorer

jsonHTTP 200 OK (Verified Record)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
"success": true,
"message": "NIN Verification (NIN) Successful",
"data": {
"reference": "clw9x01230001...",
"status": "successful",
"type": "nin",
"environment": "live",
"result": {
"surname": "NWACHUKWU",
"firstName": "CHIDINMA",
"otherNames": "ADAEZE",
"gender": "female",
"dob": "1995-04-12",
"phone": "08012345678",
"nin": "12345678901",
"trackingId": "NIN-2026-948194",
"residence_address": "24 Specimen Avenue, Off Demo Road",
"residence_state": "Lagos",
"residence_town": "Ikeja",
"residence_lga": "Ikeja",
"photo": "data:image/jpeg;base64,..."
}
},
"billing": {
"amount": 10000,
"currency": "NGN",
"unit": "kobo",
"charged": true,
"note": "Wallet charged 100.00 NGN"
}
}
POST

/api/public/v1/verifications/nin/phone

Category: NIN Verification. Resolves and returns verified National Identity Number (NIN) record details linked to a Nigerian mobile phone number.

Headers & Requirements

HeaderTypeRequirement
Authorizationstring (Bearer)Required (NIN_VERIFY scope)
Idempotency-Keystring (8-128 chars)Required
Content-Typeapplication/jsonRequired

Request Body (JSON)

FieldTypeDescription
phonestring (Required)Valid Nigerian mobile phone number (11-digit local format 08012345678 or international format +2348012345678).

Pricing & Billing Rule

OutcomeCharge AmountKobo Unit
Verified Record Found (200 OK)₦120.0012,000 kobo
Record Not Found (200 OK) / Suspended (422)₦100.0010,000 kobo
Client Error / Auth Error / Idempotent Replay₦0.000 kobo

Sample Request

curlPOST /api/public/v1/verifications/nin/phone (cURL)
1
2
3
4
5
6
7
curl -X POST "https://idyntic.getapexly.com/api/public/v1/verifications/nin/phone" \
-H "Authorization: Bearer id_live_your_api_key" \
-H "Idempotency-Key: e8a01103-e69a-4160-84a1-872f3e5be264" \
-H "Content-Type: application/json" \
-d {
"phone": "08012345678"
}

Response Explorer

jsonHTTP 200 OK (Verified Record)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
"success": true,
"message": "NIN Verification (Phone) Successful",
"data": {
"reference": "clw9x01230007...",
"status": "successful",
"type": "nin_phone",
"environment": "live",
"result": {
"surname": "NWACHUKWU",
"firstName": "CHIDINMA",
"otherNames": "ADAEZE",
"gender": "female",
"dob": "1995-04-12",
"phone": "08012345678",
"nin": "12345678901",
"trackingId": "NIN-2026-948194",
"residence_address": "24 Specimen Avenue, Off Demo Road",
"residence_state": "Lagos",
"residence_town": "Ikeja",
"residence_lga": "Ikeja",
"photo": "data:image/jpeg;base64,..."
}
},
"billing": {
"amount": 12000,
"currency": "NGN",
"unit": "kobo",
"charged": true,
"note": "Wallet charged 120.00 NGN"
}
}
POST

/api/public/v1/verifications/nin/demographic

Coming Soon

Category: NIN Verification. Retrieve and verify Nigerian National Identity records by demographic details (first name, surname, date of birth, gender). Implementation details and documentation will be published upon release.

POST

/api/public/v1/verifications/bvn

Category: BVN Verification. Performs live Bank Verification Number identity retrieval or returns mock sandbox records.

Headers & Requirements

HeaderTypeRequirement
Authorizationstring (Bearer)Required (BVN_VERIFY scope)
Idempotency-Keystring (8-128 chars)Required
Content-Typeapplication/jsonRequired

Request Body Parameters

FieldTypeRequirementDescription
bvnstring (11 digits)RequiredThe 11-digit Bank Verification Number to verify.

Pricing & Billing Rule

OutcomeCharge AmountKobo Unit
Verified Record Found (200 OK)₦110.0011,000 kobo
Record Not Found (200 OK) / Suspended (422)₦100.0010,000 kobo
Client Error / Auth Error / Idempotent Replay₦0.000 kobo

Sample Request

curlPOST /api/public/v1/verifications/bvn (cURL)
1
2
3
4
5
6
7
curl -X POST "https://idyntic.getapexly.com/api/public/v1/verifications/bvn" \
-H "Authorization: Bearer id_live_your_api_key" \
-H "Idempotency-Key: e8a01103-e69a-4160-84a1-872f3e5be264" \
-H "Content-Type: application/json" \
-d {
"bvn": "22222222222"
}

Response Explorer

jsonHTTP 200 OK (Verified Record)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
"success": true,
"message": "BVN Verification (BVN) Successful",
"data": {
"reference": "clw9x01230003...",
"status": "successful",
"type": "bvn",
"environment": "live",
"result": {
"surname": "NWACHUKWU",
"firstName": "CHIDINMA",
"otherNames": "ADAEZE",
"gender": "Female",
"dob": "05-Dec-1994",
"phone": "08012345678",
"phone2": "08087654321",
"email": "chidinma.nwachukwu@example.com",
"bvn": "22222222222",
"nin": "12345678901",
"stateOfOrigin": "Lagos State",
"lgaOfOrigin": "Ikeja",
"stateOfResidence": "Lagos State",
"lgaOfResidence": "Ikeja",
"residentialAddress": "24 Specimen Avenue, Off Demo Road",
"registrationDate": "05-Dec-2014",
"maritalStatus": "Single",
"enrollmentBank": "Access Bank",
"enrollmentBranch": "Ikeja Main",
"photo": "data:image/jpeg;base64,..."
},
"slip": {
"status": "available",
"type": "bvn-slip",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"previewUrl": "/api/public/v1/verifications/bvn/slip/preview",
"downloadUrl": "/api/public/v1/verifications/bvn/slip/pdf"
}
},
"billing": {
"amount": 11000,
"currency": "NGN",
"unit": "kobo",
"charged": true,
"note": "Wallet charged 110.00 NGN"
}
}
POST

/api/public/v1/verifications/bvn/slip/preview

Category: BVN Verification. Generates and returns a watermarked preview image (JPEG) of the official BVN slip for immediate visual verification in your application.

Headers & Requirements

HeaderTypeRequirement
Authorizationstring (Bearer)Required (BVN_VERIFY scope)
Content-Typeapplication/jsonRequired
Acceptimage/jpeg | application/jsonOptional (defaults to binary image/jpeg)

Request Body Parameters

FieldTypeRequirementDescription
referencestringRequiredThe verification reference identifier returned from POST /api/public/v1/verifications/bvn.
tokenstringRequiredThe signed slip token from data.slip.token in the verification response.
format"image" | "json"OptionalSet to json to receive base64 JPEG payload, or omit for direct binary JPEG stream.

Best Practice for Integrations

25-Minute Window
  • Slip preview and PDF download should be requested immediately following the verification lookup within the 25-minute window.
  • If an integration needs to generate a slip after the 25-minute window has lapsed, it must send a new verification request using a new Idempotency-Key to obtain a fresh slipToken.

Pricing & Billing Rule

OutcomeCharge AmountBilling Object
Slip Preview Generation (Live & Test)₦0.00 (Free)Omitted (No charges)

Sample Request

curlPOST /api/public/v1/verifications/bvn/slip/preview (cURL)
1
2
3
4
5
6
7
8
curl -X POST "https://idyntic.getapexly.com/api/public/v1/verifications/bvn/slip/preview" \
-H "Authorization: Bearer id_live_your_api_key" \
-H "Content-Type: application/json" \
-H "Accept: image/jpeg" \
-d {
"reference": "clw9x01230003...",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
} --output bvn-preview.jpg

Response Explorer

jsonHTTP 200 OK (JSON Format)
1
2
3
4
5
6
7
8
9
{
"success": true,
"message": "BVN Slip Preview generated successfully",
"data": {
"reference": "clw9x01230003...",
"mimeType": "image/jpeg",
"previewBase64": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAYMBQUJCAcHCgwK..."
}
}
POST

/api/public/v1/verifications/bvn/slip/pdf

Category: BVN Verification. Compiles and downloads the official high-resolution A4 Bank Verification Number (BVN) slip in PDF format.

Headers & Requirements

HeaderTypeRequirement
Authorizationstring (Bearer)Required (BVN_VERIFY scope)
Content-Typeapplication/jsonRequired
Acceptapplication/pdf | application/jsonOptional (defaults to binary application/pdf)

Request Body Parameters

FieldTypeRequirementDescription
referencestringRequiredThe verification reference identifier returned from POST /api/public/v1/verifications/bvn.
tokenstringRequiredThe signed slip token from data.slip.token in the verification response.
format"pdf" | "json"OptionalSet to json to receive base64 PDF payload, or omit for direct binary PDF download stream.

Best Practice for Integrations

25-Minute Window
  • Slip preview and PDF download should be requested immediately following the verification lookup within the 25-minute window.
  • If an integration needs to generate a slip after the 25-minute window has lapsed, it must send a new verification request using a new Idempotency-Key to obtain a fresh slipToken.

Pricing & Billing Rule

OutcomeCharge AmountKobo Unit
First PDF Slip Generation (200 OK)₦100.0010,000 kobo
Subsequent Re-download (Same Reference)₦0.00 (Free)0 kobo
Test Mode / Client Error / Auth Error₦0.000 kobo

Sample Request

curlPOST /api/public/v1/verifications/bvn/slip/pdf (cURL)
1
2
3
4
5
6
7
8
curl -X POST "https://idyntic.getapexly.com/api/public/v1/verifications/bvn/slip/pdf" \
-H "Authorization: Bearer id_live_your_api_key" \
-H "Content-Type: application/json" \
-H "Accept: application/pdf" \
-d {
"reference": "clw9x01230003...",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
} --output bvn-slip.pdf

Response Explorer

jsonHTTP 200 OK (JSON Format)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"success": true,
"message": "BVN Slip PDF generated successfully",
"data": {
"reference": "clw9x01230003...",
"filename": "bvn-slip-22222222222.pdf",
"mimeType": "application/pdf",
"pdfBase64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK..."
},
"billing": {
"amount": 10000,
"currency": "NGN",
"unit": "kobo",
"charged": true,
"note": "Wallet charged 100.00 NGN"
}
}
POST

/api/public/v1/verifications/bvn/phone

Coming Soon

Category: BVN Verification. Retrieve and verify Nigerian Bank Verification Number records by registered phone number. Implementation details and documentation will be published upon release.

Sandbox Test Vectors & Deterministic Fixtures

When using test credentials (id_test_...), use the following input numbers to test predictable scenarios without external provider network calls or wallet charges.

Test InputSimulated ResultHTTP Status
12345678901 (NIN)
22222222222 (BVN)
08012345678 (Phone)		Deterministic verified identity record200 OK
33333333333 / 08033333333Simulates identity restricted or suspended by national authorities422 Unprocessable
44444444444 / 08044444444Simulates merchant insufficient wallet balance error402 Payment Required
55555555555 / 08055555555Simulates upstream verification provider service outage503 Service Unavailable
Any other 11 digits / phone numberSimulates record not found in national registry (result: null)200 OK

Standardized Error Response Model

All API errors return a standard JSON envelope with an error code, message, requestId, and billing object.

Error CodeHTTP StatusDescription & Recovery
INVALID_REQUEST400 Bad RequestThe request body failed schema validation (e.g. NIN is not 11 digits).
INVALID_IDEMPOTENCY_KEY400 Bad RequestIdempotency-Key must be 8 to 128 characters matching valid regex format.
UNAUTHORIZED401 UnauthorizedInvalid, expired, revoked, or insufficiently scoped API key.
INSUFFICIENT_BALANCE402 Payment RequiredFund merchant wallet balance before executing live verification.
IDEMPOTENCY_KEY_REUSED409 ConflictThe same Idempotency-Key was previously used with a different request body.
IDEMPOTENCY_IN_PROGRESS409 ConflictA request with this key is still actively processing. Retry after Retry-After seconds.
IDENTITY_RESTRICTED422 UnprocessableThe requested identity record is suspended or restricted by national authorities.
RATE_LIMIT_EXCEEDED429 Too Many RequestsRate quota exceeded. Check Retry-After header before executing retries.
SERVICE_UNAVAILABLE503 UnavailableUpstream provider is temporarily down. Implement exponential backoff.

Key Lifecycle & Zero-Downtime Rotation

Manage API keys securely with configurable expiration dates, permanent revocation, and overlap windows.

When updating production credentials, use the Zero-Downtime Rotation feature directly in your Developer Dashboard under Key Management. Rotation issues a replacement key with identical scopes while keeping the previous key active for a configurable overlap grace window (0 to 168 hours) to prevent service interruptions during deployment.

Rate Limits & SLA

Standard rate limits per API key.

Test Sandbox Environment
60 req/min

Limited to 60 requests per minute per key.

Live Production Environment
120 req/min

Limited to 120 requests per minute per key.