Address Verification (Physical Address)

Validate residential or business addresses in Nigeria through an on-site verification workflow.

Submit verification jobs, track status, list your institution’s jobs, and download PDF reports when complete.

Base URLs

Replace {{URL}} with your environment host (production: https://api.dikript.com).

Environment	Prefix
LIVE	`{{URL}}/dikript`
TEST	`{{URL}}/dikript/test`

All endpoints below append: /api/v1/physical-address/...

Example (live, submit):

POST {{URL}}/dikript/api/v1/physical-address/verifications

Example (test, submit):

POST {{URL}}/dikript/test/api/v1/physical-address/verifications

Authentication (Header)

Header	Required	Description
`x-api-key`	Yes	Your institution secret API key (onboarding credentials)
`Content-Type`	Yes (POST)	`application/json`
`Accept`	No	`application/json` recommended

Response envelope

All responses use the standard Dikript shape:

{
  "status": true,
  "message": "Successful",
  "code": "200",
  "apiVersion": "v1",
  "transactionRef": "N202608121100001234",
  "data": { },
  "error": null
}

On failure, status is false, top-level message is often "Unsuccessful", and details are in error.message. Validation errors may include data.errors as a string array.

Main features

Submit single or batch physical / business address verification requests for Nigeria.
Idempotent-style correlation: supply requestId per job; if omitted, Dikript generates one (prefer sending your own loan/case id).
Poll or fetch a job by id, Dikript reference, requestId, or clientReference.
List verifications (filtered to jobs your institution submitted).
PDF report URL when the field visit is complete and a report is available.
Typical lifecycle statuses include: in_progress, verified, unverified, and failure outcomes such as failed_wrong_address, failed_invalid_address, cancelled, no_access

1. Submit single verification

Description: Create one physical or business address verification. The subject is contacted and an agent may visit the address. Wallet is debited according to your institution pricing for PHYSICALADDRESS.

Endpoint


POST (LIVE)	`{{URL}}/dikript/api/v1/physical-address/verifications`
POST (TEST)	`{{URL}}/dikript/test/api/v1/physical-address/verifications`

Request body (JSON)

Key	Type	Required	Description
`requestId`	string	No	Your unique id for this job (recommended). Auto-generated if omitted.
`clientReference`	string	Yes	Your customer or case reference.
`subjectName`	string	Yes	Full name of person at address.
`subjectPhone`	string	Yes	Contact phone (E.164 recommended, e.g. `+2348012345678`).
`addressRaw`	string	Yes	Full address as one line.
`state`	string	Yes	Nigerian state.
`lga`	string	Yes	Local government area.
`priority`	string	No	Default `standard`.
`verificationType`	string	No	Default `address`. Use `business_address` for business visits when enabled.
`firstName`	string	No	Subject first name.
`lastName`	string	No	Subject last name.
`houseNumber`	string	No	Structured address part.
`street`	string	No	Street name.
`landmark`	string	No	Nearby landmark.
`city`	string	No	City / area.
`latitude`	number	No*	GPS latitude (*must be sent with `longitude`).
`longitude`	number	No*	GPS longitude (*must be sent with `latitude`).
`locationAccuracyMeters`	number	No	GPS accuracy.
`locationSource`	string	No	e.g. `gps`, `google_maps`, `customer_app`, `branch_system`.
`businessName`	string	No	For business address verification.
`rcNumber`	string	No	Company registration number.
`companyType`	string	No	Company type.
`tin`	string	No	Tax identification number.
`contactName`	string	No	Business contact name.
`contactPhone`	string	No	Business contact phone.
`introductionLetter`	string	No	Reference or URL to introduction letter if required.

Example request

{
  "requestId": "LOAN-2026-0841",
  "clientReference": "CUST-12345",
  "subjectName": "Emeka Okafor",
  "subjectPhone": "+2348012345678",
  "addressRaw": "14 Adeola Crescent, Surulere",
  "state": "Lagos",
  "lga": "Surulere",
  "city": "Lagos",
  "houseNumber": "14",
  "street": "Adeola Crescent",
  "landmark": "Near National Stadium",
  "priority": "standard",
  "verificationType": "address"
}

Example success `data`

{
  "id": "ver_xxx",
  "reference": "VTL-XXXX",
  "requestId": "LOAN-2026-0841",
  "clientReference": "CUST-12345",
  "status": "in_progress",
  "outcome": null,
  "priority": "standard",
  "verificationType": "address",
  "submissionChannel": "api",
  "subjectName": "Emeka Okafor",
  "subjectPhone": "+2348012345678",
  "addressRaw": "14 Adeola Crescent, Surulere",
  "city": "Lagos",
  "state": "Lagos",
  "lga": "Surulere",
  "confidenceScore": null,
  "slaDeadline": "2026-01-16T12:00:00Z",
  "dispatchedAt": null,
  "completedAt": null,
  "createdAt": "2026-01-15T12:00:00Z",
  "updatedAt": "2026-01-15T12:00:00Z",
  "report": null,
  "agent": null
}

2. Submit batch verification

Description: Submit many verifications in one call. Billed under PHYSICALADDRESS_BATCH. Response confirms acceptance; poll each job with Get verification or use List.

Endpoint


POST (LIVE)	`{{URL}}/dikript/api/v1/physical-address/verifications/batch`
POST (TEST)	`{{URL}}/dikript/test/api/v1/physical-address/verifications/batch`

Request body

Key	Type	Required	Description
`requestId`	string	No	Batch correlation id. Auto-generated if omitted.
`requests`	array	Yes	One or more objects with the same fields as Submit single.

Each item in requests must satisfy the same required fields as a single submit (clientReference, subjectName, subjectPhone, addressRaw, state, lga).

Example request

{
  "requestId": "BATCH-2026-001",
  "requests": [
    {
      "requestId": "LOAN-001",
      "clientReference": "CUST-001",
      "subjectName": "Ada Bello",
      "subjectPhone": "+2348098765432",
      "addressRaw": "10 Broad Street, Lagos Island",
      "state": "Lagos",
      "lga": "Lagos Island"
    },
    {
      "requestId": "LOAN-002",
      "clientReference": "CUST-002",
      "subjectName": "John Doe",
      "subjectPhone": "+2348011111111",
      "addressRaw": "2 Ring Road, Ibadan",
      "state": "Oyo",
      "lga": "Ibadan North"
    }
  ]
}

Example success `data`

{
  "batchRequestId": "BATCH-2026-001",
  "acceptedCount": 2
}

3. Get verification

Description: Retrieve the latest status and report for one job. Not billed as a new submit.

Path parameter: idOrReference verification id, platform reference, your requestId, or clientReference (must belong to your institution).

Endpoint


GET (LIVE)	`{{URL}}/dikript/api/v1/physical-address/verifications/{idOrReference}`
GET (TEST)	`{{URL}}/dikript/test/api/v1/physical-address/verifications/{idOrReference}`

Parameters

Key	In	Required	Description
`idOrReference`	path	Yes	Job identifier (see above).

Example completed `data` (report present)

{
  "id": "ver_xxx",
  "reference": "VTL-XXXX",
  "requestId": "LOAN-2026-0841",
  "clientReference": "CUST-12345",
  "status": "verified",
  "outcome": "verified",
  "completedAt": "2026-01-18T09:30:00Z",
  "report": {
    "outcome": "verified",
    "failureReason": null,
    "note": "Subject confirmed at address.",
    "photos": ["https://..."],
    "submittedAt": "2026-01-18T09:28:00Z"
  },
  "agent": {
    "fullName": "Agent Name",
    "agentCode": "AGT-001"
  }
}

4. List verifications

Description: Search verifications from the provider, scoped to jobs your institution submitted (matched by stored requestId).

Endpoint


GET (LIVE)	`{{URL}}/dikript/api/v1/physical-address/verifications`
GET (TEST)	`{{URL}}/dikript/test/api/v1/physical-address/verifications`

Query parameters

Key	Required	Default	Description
`status`	No	—	Filter by status.
`requestId`	No	—	Your request id.
`clientReference`	No	—	Your client reference.
`reference`	No	—	Provider reference.
`from`	No	—	Start of date range (ISO date/time as supported by provider).
`to`	No	—	End of date range.
`page`	No	`1`	Page number.
`perPage`	No	`25`	Page size (max 100).

Example success `data`

{
  "items": [
    {
      "id": "ver_xxx",
      "reference": "VTL-XXXX",
      "requestId": "LOAN-2026-0841",
      "clientReference": "CUST-12345",
      "status": "in_progress"
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 25,
    "total": 1,
    "lastPage": 1
  }
}

5. Get verification report (PDF)

Description: Returns a time-limited URL to download the PDF report when available.

Path parameter: same as Get verification (idOrReference).

Endpoint


GET (LIVE)	`{{URL}}/dikript/api/v1/physical-address/verifications/{idOrReference}/report/pdf`
GET (TEST)	`{{URL}}/dikript/test/api/v1/physical-address/verifications/{idOrReference}/report/pdf`

Example success `data`

{
  "verificationId": "ver_xxx",
  "requestId": "LOAN-2026-0841",
  "clientReference": "CUST-12345",
  "reference": "VTL-XXXX",
  "contentType": "application/pdf",
  "reportVersion": "1",
  "url": "https://...",
  "expiresAt": "2026-01-20T12:00:00Z"
}

Download the file from url before expiresAt.

Recommended integration flow

1. POST /verifications          → store requestId, reference, id from response
2. GET  /verifications/{id}     → poll until status is terminal (verified / failed_* / cancelled / no_access)
3. GET  /verifications/{id}/report/pdf   → when status allows, fetch PDF URL

For bulk onboarding:

1. POST /verifications/batch
2. For each requestId in the batch → GET /verifications/{requestId}

Example cURL (live submit)

curl -X POST "{{URL}}/dikript/api/v1/physical-address/verifications" \
  -H "X-Dikript-Api-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "LOAN-2026-0841",
    "clientReference": "CUST-12345",
    "subjectName": "Emeka Okafor",
    "subjectPhone": "+2348012345678",
    "addressRaw": "14 Adeola Crescent, Surulere",
    "state": "Lagos",
    "lga": "Surulere"
  }'

Errors & troubleshooting

Symptom	Likely cause
Invalid or inactive API key	Wrong secret key or inactive institution
Validation failed	Missing required body fields; latitude without longitude
Verification not found	`idOrReference` not owned by your institution
Report PDF not available	Job not complete or report not generated yet
Insufficient wallet balance	Fund institution wallet before submit

Include transactionRef from the response when contacting Dikript support.

Address Verification (Physical Address)

Base URLs

Authentication (Header)

Response envelope

Main features

1. Submit single verification

Endpoint

Request body (JSON)

Example request

Example success data

2. Submit batch verification

Endpoint

Request body

Example request

Example success data

3. Get verification

Endpoint

Parameters

Example completed data (report present)

4. List verifications

Endpoint

Query parameters

Example success data

5. Get verification report (PDF)

Endpoint

Example success data

Recommended integration flow

Example cURL (live submit)

Errors & troubleshooting

Example success `data`

Example success `data`

Example completed `data` (report present)

Example success `data`

Example success `data`