The trustee sale data API

1. Subscribe to Pro or Business. The API opens with the first payment; during the free trial, the Start <your plan> now button under Subscription on your account page ends the trial and opens it today.
2. Create a key under Data API on your account page, and copy it when it is shown: it is shown once.
3. Keep it in an environment variable on the machine that calls the API, here TRUSTEESALEDATA_API_KEY, and send it in the Authorization header:

• Every request carries Authorization: Bearer <key>, and nothing else is accepted: not your website sign-in (the API ignores cookies), not an X-API-Key header, not a query parameter.
• A key is tsd_api_ followed by 46 letters and digits, matching ^tsd_api_[0-9A-Za-z]{46}$: give that pattern to your secret scanner. Its last six characters are a checksum, so a mistyped or cut-short key is refused at once with 401 invalid_key.
• Never put a key in a web address. Addresses are written to access logs on their way in, so a key found in one, in any parameter or in the path, encoded or not, is answered with 400 key_in_url and revoked, and we email you to say so.
• Keys belong on servers. The data endpoints send no CORS headers, so a web page cannot call them; a key in front-end code, a mobile app or the cells of a shared spreadsheet is a published key (the Google Sheets example below keeps it in the script’s properties instead).
• A connected app is not a key. ChatGPT and other apps you connect under Connected apps on your account page use tokens of their own; one sent to the data API is refused with 401 invalid_key, saying what it is. Create a key for your own code.
• Pro holds 2 live keys at once and Business 5; up to 10 can be created in a day. A key unused for 180 days stops working.
• Every answer from a data endpoint, errors included, carries an X-Request-Id, which is an error’s request_id too. It is all we need to look into a request: never send us a key.

Every endpoint is under https://www.trusteesaledata.com/api/v1: the www address, over HTTPS, with no trailing slash (an address ending in a slash is answered with a redirect to the one without).

• JSON only, UTF-8. Dates are YYYY-MM-DD, times ISO 8601 in UTC, money a number of US dollars, and a value the record does not state is null, never left out.
• No CSV. The API has no CSV format and no format parameter. CSV export is part of the website, from a search, signed in; it shares the same monthly allowance and does not take API keys (a request to it carrying an Authorization header is refused).
• Version 1 changes only by addition: new fields, endpoints and optional parameters may appear at any time, so ignore what you do not know. A change that would break a client comes as /api/v2, announced by email at least 30 days ahead.
• The OpenAPI 3.1 description is at https://www.trusteesaledata.com/api/v1/openapi.json, for Postman, Insomnia or a client generator. It and https://www.trusteesaledata.com/api/v1 need no key.

• Records a month are one allowance, shared with CSV export: Pro 3,000, Business 10,000. A CSV row is a record, and through the API a sale is a record the first time any of your keys fetches it in the calendar month (UTC). After that it is free for the rest of the month, even once the allowance is spent: pulling the same markets every day costs each sale once.
• New records in any 24 hours, through the API: Pro 1,000, Business 2,500. A ceiling that keeps a leaked key from taking a month in a morning; sales you fetched already do not count.
• Free: /me, /states, /states/{state}/counties, /sales/count, /api/v1 and openapi.json, every error, and any sale already fetched this month. Requests are never charged, only rate-limited.
• A page that would go past the allowance is cut short, not refused. The sales that fit are served, in order, with truncated: true and a next_cursor that resumes at the first one held back. Only when not one sale on a page can be served is the answer 429 quota_exceeded, whose details.limit says which allowance (month or day) and whose Retry-After says when it comes back: 00:00 UTC on the 1st, or when the oldest new record leaves the 24 hours.
• “The same sale” is the sale itself, the property and the loan being foreclosed, not its id: a newer notice of the sale moves its id but does not count it again. Now and then a re-notice for a new date, or a regrouping of the records behind a sale, counts it twice in one month.
• Records through the API do not touch the site’s own daily limit on viewing full records, so a nightly sync never locks you out of the site.

• Requests are counted per account, every key together: a minute (sliding), a day (UTC) and at once, as the table above sets out. Over any of them, the answer is 429 rate_limited with details.window (minute, day or in_flight). Wait Retry-After seconds and repeat the request.
• The API answers at most 4 requests at once across every account; past that, and when the database is slow, the answer is 503 busy, with a Retry-After.
• Once 20 requests from one address have sent keys that do not work within 10 minutes, further bad keys from it get 429 (failed_auth) instead of 401. A working key from the same address is never refused for its neighbours’ mistakes: offices and automation platforms share addresses.
• A key whose plan does not open the API gets 10 requests a minute, 500 a day and 1 at once: enough to read /me and the reason.

Every response to a key that works carries the RateLimit headers, errors included; sales and /me add the allowance’s. The same numbers are in the body’s usage, for tools that hide headers. Answers given before the key is read carry only X-Request-Id: a 401, a key sent in the address, an unknown path or method, too many failed keys from one address, and a 503 when the API is paused or full.

Every endpoint answers GET and nothing else (405, HEAD included, so nothing is spent on a body nobody reads), and an address under /api/v1 that is not one of these is a JSON 404. Parameters are strict: one the endpoint does not take is 400 unknown_parameter rather than ignored, because a misspelt filter that is quietly dropped returns a different list from the one asked for.

A sale carries the CSV export’s fields, under the same names and in the same order, then when we first and last saw it, its record page, its other ids, the kind of property, its other noticed dates and whether its sale date needs checking. Every field is always present. The text of the notice is not one of them, as it is not part of CSV export: it stays on the sale’s record page (url), for plans that include it.

Lists are paged by cursor. Ask for up to 200 sales with limit, then pass each page’s next_cursor back as cursor, with the same filters and sort, until it is null. A cursor resumes exactly after the last sale it was given, so sales added or dropped by a refresh while you walk never make it skip or repeat one (a sale whose date or id changes mid-walk, postponed or noticed again, can move past the cursor; the weekly re-pull below catches it). A cursor sent with other filters is 400 invalid_cursor. You may change limit between pages.

Keeping a copy in step

1. Once: walk your markets’ upcoming sales (the default status) in the order we first saw them, to the end, keeping each sale by its id: /sales?state=AZ&sort=first_seen.
2. Every day, or as often as every hour (new sales are added through the day): ask for what is new since, first_seen_after set a few minutes before the newest first_seen_at you hold. A sale you already have comes back free.
3. Every week: pull your markets’ upcoming sales again and replace your copy of them. Sales are postponed, often more than once, and their dates, balances and statuses change; sales are withdrawn or cancelled and leave the list; and now and then a sale joins with an older first_seen_at. Sales fetched this month cost nothing to fetch again.

Ids can change. When a newer notice or sale record of the same sale takes it over, the sale’s id moves to it. other_ids lists the ids of its other notices and sale records, so an id you hold that appears there is this sale, and /sales/{id} still finds a sale by an id it used to have. An id whose sale has left the list is 410 gone: remove it from your copy. Sales, counts and coverage carry data_as_of, the date of the newest data behind them.

Every error has the same shape, so a client needs one branch: a code to act on, a message for people, the param at fault when there is one, details where they help, a doc_url to its row below and the request_id. On a 429 or a 503, wait Retry-After seconds and repeat the request, except on quota_exceeded, which means stop until the allowance comes back.

Each walks every page of a search, waits out a 429 or a 503 for as long as Retry-After says, and stops when the allowance is spent. Each reads the key from TRUSTEESALEDATA_API_KEY.

Apps Script fetches from Google’s servers, so the key never reaches the sheet’s viewers; but anyone who can edit the script can read its properties, so share editing only with people you would give the key to.

• Keep keys where your code keeps secrets: an environment variable, a secret manager. Never in source control, a web page, an app others download, a shared document or a web address.
• Rotate by creating a second key, deploying it, then revoking the first: Pro holds two, so a rotation never needs downtime.
• Revoke a key the moment you think someone else has it, on your account page; it stops working on its next request. We email you whenever a key is created: if it was not you, revoke it and tell us.
• Each key shows when it was last used and how many sales it counted against the allowance this month (a sale counts to the key that fetched it first), so a key you thought idle is easy to spot.

A sale carries what CSV export carries, including the borrower the notice names. The API finds sales by place and property, never by person: q matches addresses, cities, counties, parcel numbers (APN) and trustee sale numbers, and never a borrower.

Each record reflects a published notice of trustee’s sale or a trustee’s sale record as we last saw it, and is not an authoritative record of any sale, debt or title: sales are often postponed, reinstated or cancelled after publication. Confirm the date, time, place and terms with the trustee named in the record before you act. The data is not a consumer report, and the terms forbid using it to decide anyone’s credit, insurance, employment or housing, or to harass or defraud anyone named in it.

Your keys are yours alone: use them from systems you control, within your plan’s limits, and keep them out of web pages and addresses. You may use the data in your own business; you may not resell or redistribute it in bulk, or use it to build a database or a service for others. The full text is in the terms, and what we store about keys and their use is in the privacy policy.

• Version 1, October 12, 2026: the first release. Sales (search, count, one sale), coverage (states and counties), the account, and the OpenAPI 3.1 description.