Address Finder
Fetch lookup
Get the status and result of an Address Finder lookup.
Fetch a lookup to check its status and, when it is complete, its address.
GET https://platform.scribeless.co/api/address-finder/lookups/{lookupId}
Headers
X-API-Key: YOUR_API_KEY
Path parameters
| Parameter | Type | Description |
|---|---|---|
lookupId | string | Lookup ID from POST /api/address-finder/lookups. |
Example request
curl --request GET 'https://platform.scribeless.co/api/address-finder/lookups/LOOKUP_ID' \
--header 'X-API-Key: YOUR_API_KEY'
Response
{
"id": "LOOKUP_ID",
"external_id": "crm-contact-123",
"status": "completed",
"result": {
"recommendation": "send_ready",
"confidence": 88,
"address": {
"address1": "20 Wenlock Road",
"address2": "",
"address3": "",
"city": "London",
"state": "",
"postal_code": "N1 7GU",
"country": "GB"
},
"address_type": "hq_or_office",
"reason_codes": ["company_address_and_person_company_validated"],
"summary": "High confidence business address and person/company match."
},
"created_at": "2026-11-05T10:00:00.000Z",
"updated_at": "2026-11-05T10:01:12.000Z"
}
Fields
| Field | Type | Description |
|---|---|---|
id | string | Lookup ID. |
external_id | string or null | Your reference from the request. |
status | string | queued, running, completed or failed. |
result | object or null | null until the lookup is complete. |
result.recommendation | string | What to do with the address. See below. |
result.confidence | number | Confidence in the address, from 0 to 100. |
result.address | object or null | The address found, or null when there is none. |
result.address_type | string | hq_or_office, registered_office, retail_location, warehouse_or_fulfilment, po_box_or_mailbox, virtual_office, residential or unclear. |
result.reason_codes | string | Short codes that explain the result. |
result.summary | string | A plain-language explanation of the result. |
created_at | string | When the lookup started (ISO 8601). |
updated_at | string | When the lookup last changed (ISO 8601). |
Recommendations
| Value | Meaning |
|---|---|
send_ready | Ready to send. |
usable_with_caveats | Probably usable. Read summary before you send. |
manual_review | Check the address before you send. |
do_not_send | No address that is safe to send to was found. |
Usage
- Poll every 5 to 10 seconds. Stop when
statusiscompletedorfailed. - Most lookups complete in 30 to 90 seconds.
- Copy
result.addressinto a recipient withPOST /api/recipientsto send a letter.
Status codes
| Status | Meaning |
|---|---|
200 | Lookup found. |
401 | Missing, malformed, invalid, or unauthorized API key. |
403 | Address Finder is not enabled for your team. |
404 | No lookup with this ID for your team. |
502 | Address Finder is temporarily unavailable. Retry later. |