Scribeless
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

ParameterTypeDescription
lookupIdstringLookup 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

FieldTypeDescription
idstringLookup ID.
external_idstring or nullYour reference from the request.
statusstringqueued, running, completed or failed.
resultobject or nullnull until the lookup is complete.
result.recommendationstringWhat to do with the address. See below.
result.confidencenumberConfidence in the address, from 0 to 100.
result.addressobject or nullThe address found, or null when there is none.
result.address_typestringhq_or_office, registered_office, retail_location, warehouse_or_fulfilment, po_box_or_mailbox, virtual_office, residential or unclear.
result.reason_codesstringShort codes that explain the result.
result.summarystringA plain-language explanation of the result.
created_atstringWhen the lookup started (ISO 8601).
updated_atstringWhen the lookup last changed (ISO 8601).

Recommendations

ValueMeaning
send_readyReady to send.
usable_with_caveatsProbably usable. Read summary before you send.
manual_reviewCheck the address before you send.
do_not_sendNo address that is safe to send to was found.

Usage

  • Poll every 5 to 10 seconds. Stop when status is completed or failed.
  • Most lookups complete in 30 to 90 seconds.
  • Copy result.address into a recipient with POST /api/recipients to send a letter.

Status codes

StatusMeaning
200Lookup found.
401Missing, malformed, invalid, or unauthorized API key.
403Address Finder is not enabled for your team.
404No lookup with this ID for your team.
502Address Finder is temporarily unavailable. Retry later.
Copyright © 2026