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.
The examples use https://api.evictionsapi.com and placeholder keys. Conventions shared by all endpoints (errors, idempotency, pagination) are in the API reference.
What is available todayYou can start a real eviction case with Evictions API for a rental property in any US state or DC. After you submit a case, we engage a licensed attorney in the property’s state for it and confirm by email. Nothing is served on a tenant or filed in court until that attorney has reviewed the case.The full statement
Endpoints
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, `handling`, jurisdiction ids and the grounds. In live mode every US state and DC is served with `handling: "attorney_direct"`, `action: null` and, for each ground, `notice: null` and the facts intake requires (`requiredFacts`); anything else is `served: false`. In test mode (`handling: "automated"`) the sandbox jurisdiction answers with its notice rules for each ground.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
Upload evidence for a draft case: a PDF, JPEG or PNG, decided by the file's contents (415 `unsupported_media_type` otherwise, for a live case). For a live case, `purpose: "other"` files can also be added after submission, until the case is finished
Authentication: API key, as Authorization: Bearer eak_test_...
Parameters
Name
In
Type
Required
Description
id
path
string
Yes
The case id.
Request body
JSON. Fields not listed are rejected.
Name
Type
Required
Description
filename
string
Yes
1 to 255 characters.
purpose
string
Yes
One of: "authority", "prior_notice", "prior_notice_proof", "other".
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
curl-X POST https://api.evictionsapi.com/v1/cases/case_.../validate \
-H"Authorization: Bearer eak_test_..."
POST/v1/cases/{id}/submit
Submit a draft that passes every gate. A live case moves to `submitted`, its platform fee becomes a due charge, and we engage a licensed attorney in the property's state; nothing is served or filed until that attorney has reviewed it. A test case enters the sandbox review
Authentication: API key, as Authorization: Bearer eak_test_...
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
curl-X POST https://api.evictionsapi.com/v1/cases/case_.../report-cure \
-H"Authorization: Bearer eak_test_..."
POST/v1/cases/{id}/withdraw
Withdraw the case. A live case with an attorney already engaged goes `on_hold` with a `withdrawal_requested` event instead, and is withdrawn once the attorney has confirmed that all work has stopped
Authentication: API key, as Authorization: Bearer eak_test_...
Parameters
Name
In
Type
Required
Description
id
path
string
Yes
The case id.
Responses
Status
Meaning
Body
200
The case: withdrawn, or on hold while the withdrawal is confirmed.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
Open a hosted checkout for one due charge. 409 `payments_unavailable` when online payment is off; 409 `charge_not_due` when the charge is paid, void or refunded
Authentication: API key, as Authorization: Bearer eak_test_...
Parameters
Name
In
Type
Required
Description
id
path
string
Yes
The case id.
chargeId
path
string
Yes
—
Responses
Status
Meaning
Body
200
The checkout URL to send the customer to. They return to the case page on the website.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
curl example for POST /v1/cases/{id}/charges/{chargeId}/checkout
curl-X POST https://api.evictionsapi.com/v1/cases/case_.../charges/chargeId_.../checkout \
-H"Authorization: Bearer eak_test_..."
POST/v1/cases/{id}/charges/{chargeId}/confirm
Check with the payment provider whether the charge's checkout was paid, and record it if so. Safe to repeat. 409 `payments_unavailable` when online payment is off
Authentication: API key, as Authorization: Bearer eak_test_...
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
curl-X POST https://api.evictionsapi.com/v1/cases/case_.../notes \
-H"Authorization: Bearer eak_test_..." \
-H"Content-Type: application/json" \
-d'{
"body": "The tenant paid half of the balance yesterday. Does that change the next step?"
}'
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 (nothing about a real case is ever advanced automatically), 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_...
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
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.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
Create an API key in the credential's mode. A live key can be created only by an owner of the organization, signed in with a session and `X-Evictions-Mode: live` (403 `forbidden` otherwise, also for a live API key); 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.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
curl-X POST https://api.evictionsapi.com/v1/auth/logout \
-H"Authorization: Bearer ess_..."
POST/v1/auth/password-reset/request
Ask for a password reset link by email. No credential. The answer is the same whether or not the address has an account
Authentication: none
Request body
JSON. Fields not listed are rejected.
Name
Type
Required
Description
email
string
Yes
1 to 254 characters.
Responses
Status
Meaning
Body
202
The request was accepted. If the address belongs to an account that signs in to the site, a single-use link valid for one hour was emailed to it. One account is sent at most 3 such emails an hour: a request beyond that gets this same answer and sends nothing. An `Idempotency-Key` header is ignored.
Too many password reset requests from this address: at most 10 every 10 minutes, counting both reset endpoints. `Retry-After` gives the seconds to wait.
Set a new password with the token from a reset link. No credential. The token works once; every session of the user is revoked
Authentication: none
Request body
JSON. Fields not listed are rejected.
Name
Type
Required
Description
token
string
Yes
1 to 200 characters.
password
string
Yes
10 to 200 characters.
Responses
Status
Meaning
Body
200
The password was changed and every session of the user was revoked. Sign in again with the new password. An `Idempotency-Key` header is ignored.
{ ok: boolean }
400
`invalid_reset_token`: the token is unknown, already used or expired. `invalid_request`: the password is not 10 to 200 characters (`details.issues` names `password`).
Too many password reset requests from this address: at most 10 every 10 minutes, counting both reset endpoints. `Retry-After` gives the seconds to wait.
`busy`: too many password checks are waiting. Nothing was changed and the token is still unused. `Retry-After: 5` gives the seconds to wait; try again.
curl example for POST /v1/auth/password-reset/confirm
curl-X POST https://api.evictionsapi.com/v1/auth/password-reset/confirm \
-H"Content-Type: application/json" \
-d'{
"token": "epr_...",
"password": "a new long passphrase, not this one"
}'
GET/v1/me
The signed-in user, their organization and the modes available to it
Authentication: Session token, as Authorization: Bearer ess_...
Responses
Status
Meaning
Body
200
The user with their role, the organization and the modes this server offers.
The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
One of: "customer", "attorney", "platform", "court", "none".
nextAction.description
string
Yes
—
handling
string
No
Who does the legal work. Every live case is `attorney_direct`: a licensed attorney engaged for the case reviews it, serves the notice and files in court, and the platform records each step. Every test case is `automated`: the sandbox pipeline. One of: "automated", "attorney_direct".
attorney
object | null
No
The attorney engaged for an attorney-direct case, once recorded. Null until then, and always null for a test case.
attorney.name
string | null
If attorney is sent
—
attorney.firm
string
If attorney is sent
—
attorney.state
string
If attorney is sent
The property's state.
attorney.barNumber
string | null
If attorney is sent
The attorney's bar number in that state.
erased
boolean
No
Whether the details of the case were erased, which we do case by case on request. An erased case keeps its id, state, dates, deadline names and charges. In `data` the names and the address read `[erased]` (the state and county are kept) and every other fact is gone; `courtCaseNumber` is null; each document keeps its id and `contentHash`, its `filename` reads `[erased]` and downloading it answers 410 `erased`; messages read `[erased]`. Any request that would change the case answers 409 `erased`.
erasedAt
string | null
No
When the details were erased. Null for a case that was not erased. Format: date-time.
createdAt
string
No
Format: date-time.
updatedAt
string
No
Format: date-time.
Document
Name
Type
Required
Description
id
string
Yes
—
kind
string
Yes
One of: "evidence", "notice", "filing", "proof", "other".
specId
string | null
No
—
filename
string
Yes
—
contentType
string
No
Decided from the file's first bytes when it was stored, never from its name. One of: "application/pdf", "image/jpeg", "image/png".
contentHash
string
Yes
SHA-256 of the document bytes. An attorney approval names these.
createdAt
string
No
Format: date-time.
GateResults
Name
Type
Required
Description
passed
boolean
Yes
—
results
array of object
Yes
—
results[].gate
string
Yes
—
results[].status
string
Yes
—
results[].reason
string
No
—
Event
Name
Type
Required
Description
id
string
Yes
—
action
string
Yes
—
actorType
string
Yes
—
fromState
string | null
Yes
—
toState
string | null
Yes
—
detail
any
No
—
createdAt
string
Yes
Format: date-time.
Charge
An amount owed to the platform for a case: the platform fee, or court or service costs passed on at cost. The attorney's legal fee is never a charge here: it is quoted separately and paid to the attorney.
Name
Type
Required
Description
id
string
Yes
—
kind
string
Yes
One of: "platform_fee", "court_costs", "service_costs", "other".
description
string
Yes
—
amountCents
integer
Yes
US cents.
status
string
Yes
One of: "due", "paid", "void", "refunded".
paidAt
string | null
Yes
Format: date-time.
createdAt
string
Yes
Format: date-time.
Note
A message on a case, between the customer and the platform.