Every endpoint, with its request fields, its responses and a curl example. The sandbox runs the same API; serving and filing real cases are not available yet.
This page is generated from the API’s OpenAPI 3.1 document, which is also public at https://api.evictionsapi.com/v1/openapi.json. The examples use https://api.evictionsapi.com and placeholder keys.
What is available today. Evictions API is a sandbox beta, in test mode only. Available today: sign-up for a free sandbox account, the online case form, the REST API and a sandbox with a fictional test state, where a built-in sandbox reviewer reviews cases automatically, you can step them through to close and receive webhooks. Not available yet: serving notices or filing in court for a real case, in any state, live mode, which would accept real cases and online checkout.
Conventions
Authentication
Send your credential on every request except the public endpoints: Authorization: Bearer <key>. A missing or unknown credential is a 401; a credential of the wrong kind, such as an API key on an attorney endpoint, is a 403. Requests and responses are JSON; send Content-Type: application/json with a body.
Test and live keys
An API key has a mode, which is in its prefix: eak_test_ for test and eak_live_ for live. A case belongs to the mode of the key that created it, and a key sees only the cases of its own organization and mode: the same id with a key of the other mode is a 404.
Test mode uses sandbox adapters and the fictional state ZZ. Nothing is served or filed and nothing reaches a court. A live-mode case needs a state that is open, and no state is open yet, so a live-mode case cannot be served or filed. Use a test key: sign up for a sandbox account and create one under “API keys” in the app, or with POST /v1/api-keys.
Idempotency
Any POST that needs a credential accepts an Idempotency-Key header of 1 to 255 characters. The first request with a key is processed and its response is stored, for a 2xx or a 4xx answer (a 5xx answer is not stored, so retry it with the same key). Send the same request with the same key, from the same credential and in the same mode, and you get the stored response again, with the same status and an Idempotent-Replayed: true header, and nothing is processed twice.
Reuse a key with a different method, path, body or credential, or in the other mode, and the answer is 409 idempotency_conflict. Keys are scoped to your organization. The public endpoints ignore the header, and so do the endpoints that return a one-time secret (POST /v1/api-keys and POST /v1/webhook-endpoints): they run on every request and nothing is stored, so a secret is never kept for replay.
Every error has the same shape, { "error": { "code", "message", "details" } }, and an HTTP status. Branch on code, which is stable; message is for people and can change. details is null unless the code says otherwise.
An invalid request
{
"error": {
"code": "invalid_request",
"message": "The request is invalid.",
"details": {
"issues": [
{ "path": "contentBase64", "code": "invalid_format", "message": "must be valid base64" }
]
}
}
}
The request body, query or Idempotency-Key is invalid (400; details.issues lists each problem), or a draft change is not allowed, such as changing ground or entryPoint (422; details.field names it).
unauthenticated
401
The Authorization header is missing, malformed or names an unknown or revoked credential.
forbidden
403
The credential is valid but not allowed here, for example an attorney endpoint called with an API key.
live_unavailable
403
Live mode is not available yet: a live API key or a signed-in session asking for live mode tried to create an API key, or a session sent X-Evictions-Mode: live.
attorney_not_eligible
403
Attorney endpoints only: the assigned attorney is not verified or not licensed in the property’s state.
not_found
404
The case, document, API key or webhook endpoint does not exist for your organization and mode, or the route does not exist.
invalid_state
409
The case is no longer a draft, so its facts cannot change and evidence cannot be added.
invalid_transition
409
The action is not allowed in the case’s current state, for example submitting a case that is not a draft.
guard_failed
409
A step needs something that is missing, such as a current attorney approval of the exact documents.
stale_approval
409
Attorney endpoints only: the approved document hashes do not match the current documents.
key_limit
409
POST /v1/api-keys only: the organization already has 10 active API keys in this mode. Revoke one first.
cannot_revoke_current_key
409
DELETE /v1/api-keys/{id} only: an API key tried to revoke itself. Use another key, or sign in.
sandbox_only
409
POST /v1/cases/{id}/advance only: the case is not a test-mode case in the sandbox jurisdiction. Live cases are never advanced.
nothing_to_advance
409
POST /v1/cases/{id}/advance only: the test case is a draft, on hold or finished, or is not waiting on anything the sandbox can move on.
idempotency_conflict
409
The Idempotency-Key was already used with a different request or credential.
payload_too_large
413
A document is over 10 MB after decoding, or the request body is too large.
unsupported_media_type
415
The request body is sent with a content type the API does not accept.
gates_failed
422
Submit only: the case did not pass the submission checks. details holds the check results.
prior_notice_missing
422
A prior-notice document was uploaded before the case recorded priorNotice.
documents_unavailable
422
Submit only: the jurisdiction has no documents for this ground and entry point.
rate_limited
429
Too many requests: more than 5 to POST /v1/public/leads from one address in 10 minutes, more than 10 sign-ups and sign-ins from one address in 10 minutes, or more than 60 sandbox advances per organization in a minute. Retry-After gives the seconds to wait.
busy
503
POST /v1/auth/signup and POST /v1/auth/login only: too many password checks are waiting. Nothing was created or changed. Retry-After: 5 gives the seconds to wait.
internal
500
An unexpected error. The response carries no detail.
Pagination
GET /v1/cases returns cases newest first, a page at a time. limit is the page size: 1 to 100, with a default 20; a larger number is treated as 100, and zero or anything that is not a positive whole number is a 400. Pass the nextCursor of one page as cursor to get the next. nextCursor is null on the last page. The cursor is opaque: do not build one. The events list and the attorney queue return everything and take no cursor.
POST /v1/cases/{id}/documents takes JSON, not a multipart form: filename (1 to 255 characters, no path separators or control characters), purpose (one of authority, prior_notice, prior_notice_proof or other) and contentBase64, the file as standard base64 with padding. A file over 10 MB after decoding is a 413 payload_too_large; text that is not valid base64 is a 400.
Evidence can be added only while the case is a draft (otherwise 409 invalid_state), and a prior-notice document only after the case records priorNotice (422 prior_notice_missing). The response includes the document’s contentHash, the SHA-256 of its bytes. Documents of a case are downloaded with GET /v1/cases/{id}/documents/{docId}.
Customer endpoints
Called with an organization API key (or, from the website, a signed-in session). Everything you need to create, check, submit and follow a case.
GET/v1/jurisdictions/resolve
Whether a jurisdiction is served, and its notice rules
Authentication: API key, as Authorization: Bearer eak_test_...
Parameters
Name
In
Type
Required
Description
state
query
string
Yes
Two-letter state code. In test mode, ZZ is the fictional sandbox state.
county
query
string
No
County name, to include county-level rules.
city
query
string
No
City name, to include city-level rules.
Responses
Status
Meaning
Body
200
Served status, jurisdiction ids and, when served in the key's mode, the rules for each ground.
curl -X POST https://api.evictionsapi.com/v1/cases/case_.../withdraw \
-H "Authorization: Bearer eak_test_..."
POST/v1/cases/{id}/advance
Sandbox only: move a test case on by one step. Runs the step the case is waiting for now (the sandbox reviewer's review, a service or filing update, or the end of the notice period on the case's own sandbox clock), or records the next court outcome as the sandbox reviewer. A live case, or a case outside the sandbox jurisdiction, gets 409 `sandbox_only`; a draft, a case on hold or a finished case gets 409 `nothing_to_advance`, as does a step whose last try failed, until its automatic retry (`error.details.retryAt`). While the step is already being taken, the case is returned as it is. At most 60 a minute per organization (429 `rate_limited`)
Authentication: API key, as Authorization: Bearer eak_test_...
curl -X POST https://api.evictionsapi.com/v1/cases/case_.../advance \
-H "Authorization: Bearer eak_test_..."
POST/v1/webhook-endpoints
Register a webhook endpoint
Authentication: API key, as Authorization: Bearer eak_test_...
Request body
JSON. Fields not listed are rejected.
Name
Type
Required
Description
url
string
Yes
1 to 2048 characters.
Responses
Status
Meaning
Body
201
The endpoint. The signing secret appears in this response only. An `Idempotency-Key` header is ignored: every request creates an endpoint, and no response is stored or replayed.
Create a test-mode API key. Live keys cannot be created yet (403 `live_unavailable`); at most 10 active keys per mode (409 `key_limit`)
Authentication: API key, as Authorization: Bearer eak_test_...
Responses
Status
Meaning
Body
201
The new key. The secret appears in this response only. An `Idempotency-Key` header is ignored: every request creates a key, and no response is stored or replayed.
curl -X POST https://api.evictionsapi.com/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "pat@example.com",
"password": "a long passphrase, not this one"
}'
POST/v1/public/leads
Send a website request: access, a partner-attorney application, or a message. No credential; browser calls are allowed from the website origin only
Authentication: none
Request body
JSON. The body is one of these shapes. Fields not listed are rejected.
When kind is "access_request"
Name
Type
Required
Description
kind
string
Yes
Always "access_request".
name
string
Yes
1 to 120 characters.
email
string
Yes
Format: email. Up to 254 characters. Pattern ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$.
company
string
No
1 to 200 characters.
role
string
No
One of: "property_manager", "landlord", "developer", "attorney", "other".
states
array of string
No
1 to 51 items.
message
string
No
1 to 4000 characters.
contact_url
string
No
Honeypot: leave empty. A request with this field filled in is acknowledged and discarded. Up to 0 characters.
When kind is "attorney_application"
Name
Type
Required
Description
kind
string
Yes
Always "attorney_application".
name
string
Yes
1 to 120 characters.
email
string
Yes
Format: email. Up to 254 characters. Pattern ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$.
company
string
No
1 to 200 characters.
states
array of string
Yes
1 to 51 items.
barNumber
string
Yes
1 to 60 characters.
message
string
No
1 to 4000 characters.
contact_url
string
No
Honeypot: leave empty. A request with this field filled in is acknowledged and discarded. Up to 0 characters.
When kind is "contact"
Name
Type
Required
Description
kind
string
Yes
Always "contact".
name
string
Yes
1 to 120 characters.
email
string
Yes
Format: email. Up to 254 characters. Pattern ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$.
message
string
Yes
1 to 4000 characters.
contact_url
string
No
Honeypot: leave empty. A request with this field filled in is acknowledged and discarded. Up to 0 characters.
Responses
Status
Meaning
Body
202
The request was received. A request with the `contact_url` honeypot field filled in gets the same answer and is discarded.
Used by the licensed partner attorneys who review cases, with an attorney token. An API key cannot call them. Customers integrating the API do not need them; they are listed so the reference is complete.
GET/v1/attorney/queue
Cases awaiting the attorney's review, and assigned cases that need attention
Authentication: Partner attorney token, as Authorization: Bearer eut_...
Responses
Status
Meaning
Body
200
Cases in notice or filing review, and open cases on hold or with a failed job, oldest first.