Check address

Send one address and your reference. Run returns the full verification.

POST /business/ava/verify

cURL

curl -X POST "$RUN_BASE_URL/business/ava/verify" \
  -H "Authorization: Bearer $RUN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1842-12-adeola" \
  -d '{
    "address": "12 Adeola Odeku, Victoria Island, Lagos",
    "external_ref": "ORDER-1842"
  }'

Address matched

{
  "id": "avr_01hxyzaddresscheck",
  "external_ref": "ORDER-1842",
  "status": "confirmed",
  "created_at": "2026-10-25T15:20:00.000Z",
  "checked_at": "2026-10-25T15:20:01.000Z",
  "address": {
    "input": "12 Adeola Odeku, Victoria Island, Lagos",
    "normalized": "12 Adeola Odeku Street, Victoria Island, Lagos",
    "lat": 6.4281,
    "lng": 3.4219
  },
  "evidence": {
    "type": "delivered_record",
    "checked_at": "2026-10-25T15:20:01.000Z",
    "delivered_at": "2026-10-20T14:00:00.000Z",
    "confirmed_at": null,
    "method": null,
    "outcome": "confirmed",
    "address_recorded": "12 Adeola Odeku Street, Victoria Island, Lagos",
    "area": "Victoria Island",
    "lat": 6.4281,
    "lng": 3.4219,
    "reachable": true,
    "notes": null,
    "reference": null,
    "proof_image_urls": []
  },
  "field_visit_offer": {
    "available": false,
    "amount_ngn": null,
    "currency": "NGN"
  },
  "notes": null,
  "charge": {
    "amount_ngn": 2000,
    "currency": "NGN",
    "check_type": "historical",
    "transaction_id": "txn_01hxyz"
  }
}

Send one address and your reference. Run returns the full verification object.

Requires scope: ava:write

The same key is not charged twice. If you omit Idempotency-Key, Run uses your reference plus the address. A later search of the same address, with a new key, is a new check and is charged again.

Headers

Authorization · string · required

Bearer API key (Bearer <api_key>).

Idempotency-Key · string

Your own key for this check. When you omit it, Run uses external_ref plus the trimmed address.

Content-Type · string · required

application/json

Body

address · string · required

The address to check.

external_ref · string · required

Your reference for this check.

Response

The body is one verification. Every field is listed here.

address.normalized, address.lat, and address.lng are present only when status is confirmed. Otherwise they are null. evidence is one object, or null when Run has not recorded evidence yet.

id · string

Run’s id for this check. It starts with avr_.

external_ref · string

Your reference for this check.

status · string

confirmed, not_found, declined, processing, not_confirmed, or unreachable. See Verification statuses.

created_at · string

When you created the check, in ISO 8601. Null only if the time is missing.

checked_at · string

When the check finished, in ISO 8601. null until then.

address.input · string

The address you sent.

address.normalized · string

The address Run confirmed. null unless status is confirmed.

address.lat · number

Latitude of the confirmed address. null unless status is confirmed.

address.lng · number

Longitude of the confirmed address. null unless status is confirmed.

evidence · object

One evidence object, or null. type is delivered_record for a past delivery, or location_verification for a check Run recorded.

evidence.type · string

delivered_record or location_verification. null when evidence is null.

evidence.checked_at · string

When this evidence was recorded, in ISO 8601, or null.

evidence.delivered_at · string

When a past delivery arrived, in ISO 8601, or null.

evidence.confirmed_at · string

When the evidence was confirmed, in ISO 8601, or null.

evidence.method · string

How it was checked: field_visit, rider, agent, local_contact, or desk_review. null when this evidence has no method.

evidence.outcome · string

confirmed, not_confirmed, or unreachable. null when this evidence has no outcome.

evidence.address_recorded · string

The address that was found, or null.

evidence.area · string

The area that was recorded, or null.

evidence.lat · number

Latitude recorded with the evidence, or null.

evidence.lng · number

Longitude recorded with the evidence, or null.

evidence.reachable · boolean

Whether the address could be reached. null when that was not recorded.

evidence.notes · string

The note stored with the evidence, or null.

evidence.reference · string

A reference stored with the evidence, or null.

evidence.proof_image_urls · string[]

Photo links. An empty list when there are no photos. Omitted from the object only when evidence itself is null.

field_visit_offer.available · boolean

true when you can still accept or decline a field visit.

field_visit_offer.amount_ngn · number

The visit price in naira when available is true. null when no visit is offered. This is the rate on your account.

field_visit_offer.currency · string

Always NGN.

notes · string

The note for this check, or null.

charge.amount_ngn · number

The amount taken from the wallet, in naira, or null when this check has not been charged.

charge.currency · string

Always NGN.

charge.check_type · string

historical for a normal check, or field_visit for a visit. null when this check has not been charged.

charge.transaction_id · string

The wallet transaction id, or null when this check has not been charged.

A successful call returns HTTP 200. Read status to see what happened.

Address matched. status is confirmed. The pin is filled in, and charge.amount_ngn is the rate on your account. Run does not send ava.verification.completed for this result.

Still checking. The address did not match a past record, so Run is checking it. status is processing. The pin is null. Run holds the normal check price. notes is “We are checking this address. You will get an update when the check is finished.” There is no field-visit offer. Run sends the webhook when this check finishes.

Field visit offered. The address did not match a past record, and a field visit is available on your account. status is not_found. field_visit_offer.available is true, and field_visit_offer.amount_ngn is your visit rate. Nothing is charged and nothing is held. You accept or decline that offer with Field visit.

See Verification statuses for the bodies after a check is closed.

cURL

curl -X POST "$RUN_BASE_URL/business/ava/verify" \
  -H "Authorization: Bearer $RUN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1842-12-adeola" \
  -d '{
    "address": "12 Adeola Odeku, Victoria Island, Lagos",
    "external_ref": "ORDER-1842"
  }'

Address matched

{
  "id": "avr_01hxyzaddresscheck",
  "external_ref": "ORDER-1842",
  "status": "confirmed",
  "created_at": "2026-10-25T15:20:00.000Z",
  "checked_at": "2026-10-25T15:20:01.000Z",
  "address": {
    "input": "12 Adeola Odeku, Victoria Island, Lagos",
    "normalized": "12 Adeola Odeku Street, Victoria Island, Lagos",
    "lat": 6.4281,
    "lng": 3.4219
  },
  "evidence": {
    "type": "delivered_record",
    "checked_at": "2026-10-25T15:20:01.000Z",
    "delivered_at": "2026-10-20T14:00:00.000Z",
    "confirmed_at": null,
    "method": null,
    "outcome": "confirmed",
    "address_recorded": "12 Adeola Odeku Street, Victoria Island, Lagos",
    "area": "Victoria Island",
    "lat": 6.4281,
    "lng": 3.4219,
    "reachable": true,
    "notes": null,
    "reference": null,
    "proof_image_urls": []
  },
  "field_visit_offer": {
    "available": false,
    "amount_ngn": null,
    "currency": "NGN"
  },
  "notes": null,
  "charge": {
    "amount_ngn": 2000,
    "currency": "NGN",
    "check_type": "historical",
    "transaction_id": "txn_01hxyz"
  }
}

Staging samples

On the staging API, these five addresses always return the same result. Send each address as written. Letter case and extra spaces do not change the result. A live key on production treats the same text as a normal address.

The price is the rate on your account. A repeat of the same idempotency key is not charged again.

12 Bourdillon Road, Ikoyi, Lagos

Status is confirmed. The pin is filled in. The normal check price is charged. No webhook.

5 Thompson Avenue, Ikoyi, Lagos

Status is processing. The normal check price is held. The note says the check is still running. No webhook yet. Poll this check to see it stay open.

22 Fola Osibo Street, Lekki Phase 1, Lagos

Status is not_found, with a field visit offered. Nothing is charged and nothing is held. Accept or decline the visit.

54 Admiralty Way, Lekki Phase 1, Lagos

Opens as processing, then closes as not_confirmed. The hold is released. ava.verification.completed is sent.

9 Oduduwa Street, GRA Ikeja, Lagos

Opens as processing with the visit price held, then closes as unreachable. The visit rate is charged. The note is “The address was not there.” ava.verification.completed is sent.