API
Authentication
Send your API key in the Authorization header. Your key is on the Account screen.
Authorization: Bearer cs_live_…Find places
GET/api/places
ZIPs, cities and counties, each with its houses: single-family homes, townhouses, 2-4 units and manufactured homes.
q | a name, or the start of a ZIP: Fairview, Kettle County, 537 |
Response 200
{
"items": [
{
"id": "city:WI:fairview",
"kind": "city",
"name": "Fairview, WI",
"houses": 21480
},
{
"id": "zip:53711",
"kind": "zip",
"name": "53711 · Fairview, WI",
"houses": 2839
}
]
}Start a scan
POST/api/scans
Places from Find places, or up to 10,000 addresses, not both. An address is a line of text or an object with address, city, state and zip. Where places overlap, each house is scanned once. Filters narrow a scan of places (absentee: the owner’s mailing address is somewhere else, or the owner is a company). Without a name, a scan of places is named after its places and filters.
Request
{
"places": [
"zip:53711"
]
} Response 201
{
"id": "k3f9q2",
"name": "53711 · Fairview, WI",
"created": "2026-11-16T15:04:05Z",
"status": "running",
"total": 2839,
"scanned": 0,
"counts": {
"extreme": 0,
"high": 0,
"medium": 0,
"low": 0,
"no_photo": 0,
"not_visible": 0,
"kept": 0
},
"charged": 0,
"filters": []
}Estimate a scan
POST/api/scans/estimate
The houses Start a scan would cover, and the most it can cost on your plan. Houses with no photo are free, so the charge is usually lower.
Request
{
"places": [
"county:55901"
],
"filters": [
"absentee"
]
} Response 200
{
"houses": 10302,
"ceiling": 282.66
}Get a scan
GET/api/scans/{id}
Progress while it runs. Houses and tiers arrive when the status is done.
Response 200
{
"id": "k3f9q2",
"name": "53711 · Fairview, WI",
"created": "2026-11-16T15:04:05Z",
"status": "done",
"total": 2839,
"scanned": 2839,
"counts": {
"extreme": 41,
"high": 212,
"medium": 398,
"low": 1513,
"no_photo": 312,
"not_visible": 363,
"kept": 0
},
"charged": 0,
"filters": []
}List scans
GET/api/scans
Newest first.
Response 200
{
"items": [
{
"id": "k3f9q2",
"name": "53711 · Fairview, WI",
"created": "2026-11-16T15:04:05Z",
"status": "done",
"total": 2839,
"scanned": 2839,
"counts": {
"extreme": 41,
"high": 212,
"medium": 398,
"low": 1513,
"no_photo": 312,
"not_visible": 363,
"kept": 0
},
"charged": 0,
"filters": []
}
]
}List houses
GET/api/scans/{id}/houses
Ordered by tier, Extreme first. Houses that weren’t graded come last.
filter | all (default), extreme, high, medium, low or kept |
cursor | next, from the previous page |
limit | 1 to 500, default 100 |
Response 200
{
"items": [
{
"n": 7,
"address": "2210 Juniper Ave, Fairview, WI 53711",
"result": "graded",
"tier": "extreme",
"condition": "distressed",
"vacancy": "likely",
"evidence": [
{
"text": "Boarded windows",
"severity": "severe"
},
{
"text": "Roof tarp",
"severity": "moderate"
}
],
"vacancy_cues": [
"Mail piled at the door"
],
"signs": [],
"photo_date": "2024-08",
"photo_old": false,
"sold_after_photo": false,
"verdict": null
}
],
"next": "100",
"total": 2839
}Get a house
GET/api/scans/{id}/houses/{n}
One house, with the houses before and after it in the same order.
filter | the order to step through, as in List houses |
Response 200
{
"n": 7,
"address": "2210 Juniper Ave, Fairview, WI 53711",
"result": "graded",
"tier": "extreme",
"condition": "distressed",
"vacancy": "likely",
"evidence": [
{
"text": "Boarded windows",
"severity": "severe"
},
{
"text": "Roof tarp",
"severity": "moderate"
}
],
"vacancy_cues": [
"Mail piled at the door"
],
"signs": [],
"photo_date": "2024-08",
"photo_old": false,
"sold_after_photo": false,
"verdict": null,
"prev": null,
"next": 12
}Keep or reject a house
PUT/api/scans/{id}/houses/{n}/verdict
Send null to clear it.
Request
{
"verdict": "keep"
} Response 200
{
"n": 7,
"address": "2210 Juniper Ave, Fairview, WI 53711",
"result": "graded",
"tier": "extreme",
"condition": "distressed",
"vacancy": "likely",
"evidence": [
{
"text": "Boarded windows",
"severity": "severe"
},
{
"text": "Roof tarp",
"severity": "moderate"
}
],
"vacancy_cues": [
"Mail piled at the door"
],
"signs": [],
"photo_date": "2024-08",
"photo_old": false,
"sold_after_photo": false,
"verdict": "keep"
}Get your account
GET/api/account
Plan, included houses used this month, balance and receipts.
Response 200
{
"email": "you@example.com",
"plan": "scout",
"included_used": 1620,
"balance": 18.4,
"renews": "2026-12-01T00:00:00Z",
"api_key_last4": "4f2a",
"receipts": [
{
"id": "r3",
"date": "2026-11-13T09:00:00Z",
"amount": 49,
"what": "Scout, monthly"
}
]
}Change plan
PUT/api/account/plan
payg, scout or pro.
Request
{
"plan": "pro"
} Response 200
{
"email": "you@example.com",
"plan": "pro",
"included_used": 1620,
"balance": 18.4,
"renews": "2026-12-01T00:00:00Z",
"api_key_last4": "4f2a",
"receipts": [
{
"id": "r3",
"date": "2026-11-13T09:00:00Z",
"amount": 49,
"what": "Scout, monthly"
}
]
}Add funds
POST/api/account/funds
At least $25. The card token comes from the card form on the Account screen.
Request
{
"amount": 50,
"card_token": "tok_…"
} Response 200
{
"email": "you@example.com",
"plan": "scout",
"included_used": 1620,
"balance": 68.4,
"renews": "2026-12-01T00:00:00Z",
"api_key_last4": "4f2a",
"receipts": [
{
"id": "r3",
"date": "2026-11-13T09:00:00Z",
"amount": 49,
"what": "Scout, monthly"
}
]
}New API key
POST/api/account/key
Replaces the current key. The new key is shown once.
Response 200
{
"key": "cs_live_…"
}Errors
{
"error": {
"code": "insufficient_funds",
"message": "The balance doesn’t cover the scan. Add funds."
}
} unauthorized | 401 | The API key is missing or wrong. |
not_found | 404 | No such scan or house. |
invalid_places | 400 | A place id that Find places didn’t give. |
invalid_scan | 400 | Places and addresses together, an unknown filter, or filters with addresses. |
invalid_addresses | 400 | No usable addresses. |
too_many_addresses | 400 | More than 10,000 addresses. Split the list. |
insufficient_funds | 402 | The balance doesn’t cover the scan. Add funds. |
unavailable | 503 | Counting the houses failed or took too long. Try again, or pick fewer places. |
not_open | 503 | Not open yet: starting a scan, adding funds, changing plan and API keys. |