Verify an individual's address

POST/api/v1/kyc/address

Submit a person’s name, phone and address for physical verification in Nigeria. The call is asynchronous — it returns a reference_id you poll to collect the result once an agent has visited the address.

Headers

Header	Required	Description
`Authorization`	Yes	Your app’s secret key, sent as-is — not `Bearer`.
`AppId`	Yes	The App ID from your dashboard.
`Content-Type`	Yes	`application/json`

Body parameters

Parameter	Type	Required	Description
`first_name`	string	Yes	First name of the individual.
`last_name`	string	Yes	Last name of the individual.
`middle_name`	string	No	Middle name of the individual.
`dob`	string	No	Date of birth, `yyyy-mm-dd`.
`gender`	string	No	Gender of the individual.
`mobile`	string	Yes	Active mobile number of the individual.
`street`	string	Yes	House number and street name.
`landmark`	string	No	Closest landmark to the street.
`lga`	string	Yes	Local Government Area.
`state`	string	Yes	State.

Response

The submit call returns an entity with status: "pending" and a reference_id. Store the reference_id — it’s how you retrieve the result.

Fetch verification results

Poll GET /api/v1/kyc/address with the reference_id from the submit call. While the visit is outstanding the status stays pending; once complete, data carries the applicant details, captured location and photos, a neighbour reference and any agent comments.

Query	Type	Required	Description
`reference_id`	string	Yes	The `reference_id` returned by the submit call.

GET /api/v1/kyc/address

curl "https://api.dojah.io/api/v1/kyc/address?reference_id=69e10264-4b90-64fe-b4b7-c9dddafd0241" \
  -H "Authorization: {{secret_key}}" \
  -H "AppId: {{app_id}}"

200 — result ready

{
  "entity": {
    "status": "pending",
    "reference_id": "69e10264-4b90-64fe-b4b7-c9dddafd0241",
    "data": {
      "applicant": {
        "first_name": "John",
        "last_name": "Musa",
        "middle_name": "Doe",
        "phone": "08012345678",
        "gender": "Male",
        "dob": "17/01/1988",
        "photo": ""
      },
      "location": "7.081273, 8.232523",
      "photos": [""],
      "neighbor": {
        "name": "Musa Garba",
        "comment": "Very friendly",
        "phone": "080987654321"
      },
      "street": "270 Murtala Muhammed Way, Alagomeji. Yaba",
      "city": "oshodi",
      "lga": "lagos mainland",
      "state": "Lagos",
      "country": "Nigeria",
      "comments": ""
    }
  }
}

Errors

Code	Meaning
`400`	Bad request — a required field is missing or malformed.
`401`	Unauthorized — check your key and `AppId` (no `Bearer` prefix).
`402`	Insufficient wallet balance. Fund your wallet.
`429`	Too many requests — back off and retry.

curl -X POST "https://api.dojah.io/api/v1/kyc/address" \
  -H "Authorization: {{secret_key}}" \
  -H "AppId: {{app_id}}" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Musa",
    "mobile": "08012345678",
    "street": "270 Murtala Muhammed Way, Yaba",
    "lga": "Lagos Mainland",
    "state": "Lagos"
  }'

const res = await fetch("https://api.dojah.io/api/v1/kyc/address", {
  method: "POST",
  headers: {
    Authorization: process.env.DOJAH_SECRET_KEY,
    AppId: process.env.DOJAH_APP_ID,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    first_name: "John",
    last_name: "Musa",
    mobile: "08012345678",
    street: "270 Murtala Muhammed Way, Yaba",
    lga: "Lagos Mainland",
    state: "Lagos"
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://api.dojah.io/api/v1/kyc/address",
    headers={
        "Authorization": os.environ["DOJAH_SECRET_KEY"],
        "AppId": os.environ["DOJAH_APP_ID"],
    },
    json={
        "first_name": "John",
        "last_name": "Musa",
        "mobile": "08012345678",
        "street": "270 Murtala Muhammed Way, Yaba",
        "lga": "Lagos Mainland",
        "state": "Lagos"
    },
)
data = res.json()

{
  "entity": {
    "status": "pending",
    "reference_id": "69e10264-4b90-64fe-b4b7-c9dddafd0241"
  }
}

Get started

Core concepts

API Endpoints

Widget SDKs

API clients

Verify an individual's address

Headers

Body parameters

Response

Fetch verification results

Errors

​Headers

​Body parameters

​Response

​Fetch verification results

​Errors

Headers

Body parameters

Response

Fetch verification results

Errors