CurbScanner

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.

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

filterall (default), extreme, high, medium, low or kept
cursornext, from the previous page
limit1 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.

filterthe 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."
  }
}
unauthorized401The API key is missing or wrong.
not_found404No such scan or house.
invalid_places400A place id that Find places didn’t give.
invalid_scan400Places and addresses together, an unknown filter, or filters with addresses.
invalid_addresses400No usable addresses.
too_many_addresses400More than 10,000 addresses. Split the list.
insufficient_funds402The balance doesn’t cover the scan. Add funds.
unavailable503Counting the houses failed or took too long. Try again, or pick fewer places.
not_open503Not open yet: starting a scan, adding funds, changing plan and API keys.

openapi.jsonllms.txt