> ## Documentation Index
> Fetch the complete documentation index at: https://run-deliverys.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Check address

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

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](https://run-deliverys.mintlify.site/address-verification/statuses.md).

**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](https://run-deliverys.mintlify.site/address-verification/field-visit.md).

See [Verification statuses](https://run-deliverys.mintlify.site/address-verification/statuses.md) for the bodies after a check is closed.

```bash cURL theme={null}
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"
  }'
```

```javascript Node.js theme={null}
const res = await fetch(`${process.env.RUN_BASE_URL}/business/ava/verify`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RUN_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-1842-12-adeola',
  },
  body: JSON.stringify({
    address: '12 Adeola Odeku, Victoria Island, Lagos',
    external_ref: 'ORDER-1842',
  }),
});
const verification = await res.json();
```

```python Python theme={null}
import os
import requests

res = requests.post(
    f"{os.environ['RUN_BASE_URL']}/business/ava/verify",
    headers={
        "Authorization": f"Bearer {os.environ['RUN_API_KEY']}",
        "Idempotency-Key": "order-1842-12-adeola",
    },
    json={
        "address": "12 Adeola Odeku, Victoria Island, Lagos",
        "external_ref": "ORDER-1842",
    },
)
verification = res.json()
```

```php PHP theme={null}
<?php
$ch = curl_init(getenv('RUN_BASE_URL') . '/business/ava/verify');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('RUN_API_KEY'),
    'Content-Type: application/json',
    'Idempotency-Key: order-1842-12-adeola',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'address' => '12 Adeola Odeku, Victoria Island, Lagos',
    'external_ref' => 'ORDER-1842',
  ]),
]);
$verification = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```go Go theme={null}
package main

import (
  "bytes"
  "net/http"
  "os"
)

func main() {
  body := bytes.NewBufferString(`{"address":"12 Adeola Odeku, Victoria Island, Lagos","external_ref":"ORDER-1842"}`)
  req, _ := http.NewRequest("POST", os.Getenv("RUN_BASE_URL")+"/business/ava/verify", body)
  req.Header.Set("Authorization", "Bearer "+os.Getenv("RUN_API_KEY"))
  req.Header.Set("Content-Type", "application/json")
  req.Header.Set("Idempotency-Key", "order-1842-12-adeola")
  http.DefaultClient.Do(req)
}
```

```json Address matched theme={null}
{
  "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"
  }
}
```

```json Still checking theme={null}
{
  "id": "avr_01hxyzaddresscheck",
  "external_ref": "ORDER-1842",
  "status": "processing",
  "created_at": "2026-10-25T15:20:00.000Z",
  "checked_at": null,
  "address": {
    "input": "5 Thompson Avenue, Ikoyi, Lagos",
    "normalized": null,
    "lat": null,
    "lng": null
  },
  "evidence": null,
  "field_visit_offer": {
    "available": false,
    "amount_ngn": null,
    "currency": "NGN"
  },
  "notes": "We are checking this address. You will get an update when the check is finished.",
  "charge": {
    "amount_ngn": null,
    "currency": "NGN",
    "check_type": null,
    "transaction_id": null
  }
}
```

```json Field visit offered theme={null}
{
  "id": "avr_01hxyzaddresscheck",
  "external_ref": "ORDER-1842",
  "status": "not_found",
  "created_at": "2026-10-25T15:20:00.000Z",
  "checked_at": null,
  "address": {
    "input": "22 Fola Osibo Street, Lekki Phase 1, Lagos",
    "normalized": null,
    "lat": null,
    "lng": null
  },
  "evidence": null,
  "field_visit_offer": {
    "available": true,
    "amount_ngn": 8000,
    "currency": "NGN"
  },
  "notes": null,
  "charge": {
    "amount_ngn": null,
    "currency": "NGN",
    "check_type": null,
    "transaction_id": null
  }
}
```

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.