The sheriff 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 SHERIFFSALEDATA_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 ssd_api_ followed by 46 letters and digits, matching ^ssd_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).
• 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.sheriffsaledata.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 sale list 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.sheriffsaledata.com/api/v1/openapi.json, for Postman, Insomnia or a client generator. It and https://www.sheriffsaledata.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 court case being sold in its county (or the sheriff’s own number for it, where no case is listed), not its id, so a sale whose id changes, or that is adjourned to a new date, is not counted twice. A rare regrouping of the listings behind a sale can count 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 columns, under the same names and in the same order, with its status_history after rescheduled_from, then when we first and last saw it, its record page and its other ids. Every field is always present.

There is no separate endpoint for a sale’s history: every dated status the sheriff posted, each postponement, adjournment, stay and result, is in its own status_history, newest first. In New Jersey the opening_bid is the sheriff’s approximate upset price where the list prints one; many sheriffs announce it only at the sale, so it is often null.

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, adjourned or listed 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=NJ&sort=first_seen.
2. Every day, after the daily refresh (it starts at about 09:20 UTC): 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 adjourned, often more than once, and their dates, bids and statuses change; sales are stayed, cancelled or paid off and leave the list, with no record left to say so; 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 better listing of a sale takes it over, the office’s own sale list joining another listing of it or a resale under the same case, the sale’s id changes. other_ids lists the ids of its other listings, 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. 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 SHERIFFSALEDATA_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 parties the court case names: the plaintiff, the defendant and the plaintiff’s attorney. The API finds sales by place and property, never by person: q matches addresses, towns, ZIP codes, parcel numbers, case numbers and sheriff’s numbers, and never a defendant or a plaintiff, and the plaintiff filter takes only an organization with a page on the site, never a private person. Legal descriptions are not searched either: some print the owner, or a court case’s whole caption.

Each record is a copy of a sale as the office holding it listed it when we last read its sale list, and not an authoritative record of any sale, debt or title: sales are adjourned, stayed or cancelled after they are listed, sometimes on the morning of the sale. Confirm the date, time, place, opening bid and terms with the sheriff’s office or the court 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 with its status history), coverage (states and counties), the account, and the OpenAPI 3.1 description.