Quickstart
Sign up and create a free test key. Then create, validate and submit a test case and follow it by API and webhooks. Test keys work only with a fictional test state. The last section shows what changes for a real case with a live key.
Before you start
The API takes two kinds of key. A live key is for real cases: a case for a rental property in any US state or DC, handled by a licensed attorney in the property’s state who is engaged for that case. A test key is a free developer feature for building and testing an integration: it works only with a fictional test state, and nothing real is served or filed. This walkthrough uses a test key from step 1 to step 8.
- Sign up and get a test key. Sign up and create a test key under “API keys” in the app, where you can also revoke it. A test key starts with
eak_test_; the examples show it aseak_test_.... - What a test key can do. Resolve a jurisdiction, create, validate and submit test cases, upload evidence, read cases and their history, and register webhook endpoints to receive events. Test cases use the fictional state
ZZ, with a built-in stand-in for the process server and the court. Use made-up names and details. - How review works for a test case. A built-in test reviewer stands in for the attorney and approves a submitted test case once it enters review, approving the exact documents by their hashes. You can then step the test case through the rest of its life, one step at a time, with
advance(step 7), instead of waiting out notice periods and court dates. - What is different for a real case. A live case is reviewed by a real attorney, engaged after you submit, and it moves when that attorney acts. The test reviewer and
advancework on test cases only. See Real cases with a live key.
Examples use curl and jq. Set your key and the API address once:
export EVICTIONS_API_URL=https://api.evictionsapi.com
export EVICTIONS_API_KEY=eak_test_...Every request carries the key as Authorization: Bearer. Conventions shared by all endpoints (errors, idempotency, pagination) are in the API reference.
Setting up with an AI agent
Copy this whole walkthrough as one text, with the API address and the rules of the API, and paste it into your AI coding tool or assistant. It has no key in it: put your test key where it shows eak_test_...
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
1. Resolve a jurisdiction
Ask whether a state is served for your key, how a case there is handled, and what facts each ground needs. With a test key, ZZ is the fictional test state, and the answer includes its fixture notice rules.
curl "$EVICTIONS_API_URL/v1/jurisdictions/resolve?state=ZZ" \
-H "Authorization: Bearer $EVICTIONS_API_KEY"{
"served": true,
"handling": "automated",
"jurisdictionIds": ["us-zz"],
"action": { "name": "Unlawful Detainer", "court": "Fixture Justice Court" },
"grounds": {
"nonpayment": {
"notice": { "type": "pay_or_quit", "periodDays": 3, "cureRight": true, "serviceMethods": [ ... ] },
"requiredFacts": ["lease.monthlyRentCents", "ledger", "amountOwedCents"]
},
"lease_violation": { ... },
"holdover": { ... }
}
}With a test key every other state answers served: false with no rules. (With a live key, all 50 states and DC answer served: true; see the last section.)
{ "served": false, "jurisdictionIds": ["us-ca"], "action": null, "grounds": {} }2. Create a case
A case starts as a draft. ground is nonpayment, lease_violation or holdover; entryPoint is notice to start at the notice. Dates are YYYY-MM-DD and money is whole cents. The Idempotency-Key header makes the request safe to retry: send the same request with the same key and you get the first response back instead of a second case.
CASE=$(curl -X POST "$EVICTIONS_API_URL/v1/cases" \
-H "Authorization: Bearer $EVICTIONS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"ground": "nonpayment",
"entryPoint": "notice",
"property": {
"line1": "1 Main St",
"city": "Testville",
"state": "ZZ",
"zip": "00000",
"ownerOfRecord": "Pat Landlord"
},
"parties": [
{ "role": "plaintiff", "name": "Pat Landlord" },
{ "role": "defendant", "name": "Terry Tenant" }
],
"lease": { "startDate": "2025-01-01", "monthlyRentCents": 150000 },
"ledger": [
{ "date": "2026-09-01", "type": "charge", "amountCents": 150000 },
{ "date": "2026-10-01", "type": "charge", "amountCents": 150000 },
{ "date": "2026-10-02", "type": "payment", "amountCents": 50000 }
],
"amountOwedCents": 250000,
"attestations": {
"authority": true,
"notRetaliatory": true,
"notDiscriminatory": true,
"servicemember": "no",
"caresCovered": false
}
}' | jq -r .id)
echo $CASE{
"id": "case_21a1f8ed-79f4-4248-a682-10184ca8a5c1",
"reference": "EV-1001",
"mode": "test",
"state": "draft",
"ground": "nonpayment",
"entryPoint": "notice",
"data": { ... },
"deadlines": [],
"documents": [],
"nextAction": { "by": "customer", "description": "Complete the case details and submit the case." }
}Every field is listed under POST /v1/cases. Until the case is submitted you can change it with PATCH /v1/cases/{id}.
3. Upload proof of authority
A case cannot be submitted without a document showing your authority over the property, such as a deed or a management agreement. The file goes in the JSON body as base64, up to 10 MB once decoded. It must be a PDF, a JPEG or a PNG. For this walkthrough any small PDF will do; the example reads one named deed.pdf.
curl -X POST "$EVICTIONS_API_URL/v1/cases/$CASE/documents" \
-H "Authorization: Bearer $EVICTIONS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"filename\":\"deed.pdf\",\"purpose\":\"authority\",\"contentBase64\":\"$(base64 < deed.pdf | tr -d '\n')\"}"{
"id": "doc_f31d5d4d-c667-4d2b-ba0f-5dee4893aad3",
"kind": "evidence",
"filename": "deed.pdf",
"contentHash": "df75f3ea1d63370ba642bde84f53668817f063ac887beb86b8593d78cf5642b9",
"purpose": "authority",
"createdAt": "2026-10-04T22:15:59.978Z"
}4. Validate
Validation runs the same checks as submission and changes nothing. Run it as often as you like. Each failed check comes with a reason; before step 3, for example, the authority check fails and says which document is missing.
curl -X POST "$EVICTIONS_API_URL/v1/cases/$CASE/validate" \
-H "Authorization: Bearer $EVICTIONS_API_KEY"{
"results": [
{ "gate": "jurisdiction", "status": "pass" },
{ "gate": "authority", "status": "pass" },
{ "gate": "ground_allowed", "status": "pass" },
{ "gate": "required_facts", "status": "pass" },
{ "gate": "ledger_reconciles", "status": "pass" },
{ "gate": "cares_act", "status": "pass" },
{ "gate": "servicemember", "status": "pass" },
{ "gate": "prohibited_basis", "status": "pass" }
],
"passed": true
}5. Submit
Submitting a test case that passes every check generates its notice and sends the case to review. A case that does not pass is refused with 422 gates_failed, and the check results are in error.details.
curl -X POST "$EVICTIONS_API_URL/v1/cases/$CASE/submit" \
-H "Authorization: Bearer $EVICTIONS_API_KEY"{
"case": {
"id": "case_21a1f8ed-79f4-4248-a682-10184ca8a5c1",
"mode": "test",
"state": "notice_review",
"documents": [
{ "kind": "evidence", "filename": "deed.pdf", ... },
{ "kind": "notice", "filename": "case_21a1f8ed-...-notice-nonpayment.pdf", ... }
],
"nextAction": {
"by": "attorney",
"description": "..."
}
},
"gates": [ ... ]
}For a test case the built-in test reviewer approves the notice, and the built-in stand-in for the process server then receives it. No real person is involved. A real case does not work this way: it waits for the attorney engaged for it.
6. Read status
Every case response carries its state, its deadlines and documents, and a nextAction that says who the case is waiting on. The events list is the history visible to you, oldest first.
curl "$EVICTIONS_API_URL/v1/cases/$CASE" \
-H "Authorization: Bearer $EVICTIONS_API_KEY"
curl "$EVICTIONS_API_URL/v1/cases/$CASE/events" \
-H "Authorization: Bearer $EVICTIONS_API_KEY"{
"items": [
{ "action": "submit", "fromState": "draft", "toState": "submitted", ... },
{ "action": "assign_attorney", "fromState": "submitted", "toState": "attorney_assigned", ... },
{ "action": "begin_review", "fromState": "attorney_assigned", "toState": "notice_review", ... },
{ "action": "approve_notice", "fromState": "notice_review", "toState": "notice_approved", ... },
{ "action": "send_notice", "fromState": "notice_approved", "toState": "notice_out_for_service", ... }
]
}7. Advance the test case
A real case waits days for service, the notice period and the court. A test case does not have to: each call to advance moves it on by one step and returns the case. The step is whatever the case is waiting for: the test reviewer’s review, the next update from the stand-in process server or court, the end of the notice period (on the case’s own test clock, so other cases are not affected), or the next court outcome, which the test reviewer records. Some steps are a check that finds nothing new yet, so the state stays the same; call again. Repeat until the case is closed.
curl -X POST "$EVICTIONS_API_URL/v1/cases/$CASE/advance" \
-H "Authorization: Bearer $EVICTIONS_API_KEY"{
"id": "case_21a1f8ed-79f4-4248-a682-10184ca8a5c1",
"mode": "test",
"state": "notice_out_for_service",
...
"nextAction": { "by": "platform", "description": "The notice is being served on the tenant." }
}Every step of a test case still needs an approval of the exact documents before it moves. A case that is a draft, on hold or finished answers 409 nothing_to_advance, a live case answers 409 sandbox_only, and you can advance at most 60 times a minute.
8. Receive webhooks
Register an https endpoint and the API posts a signed event to it each time a case changes state. Register it before you create or submit a case to receive that case’s events. The signing secret appears in this response only, so store it now.
curl -X POST "$EVICTIONS_API_URL/v1/webhook-endpoints" \
-H "Authorization: Bearer $EVICTIONS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/webhooks/evictions" }'{ "id": "whe_...", "secret": "whsec_..." }An endpoint registered with a test key receives events for test cases only. The webhooks guide has the payload, the signature check and the retry schedule.
Real cases with a live key
A live key starts with eak_live_. It can be created only by an owner of your organization, from a signed-in session: open “API keys” in the app. The calls are the same as above, with these differences.
- Every state and DC is served.
GET /v1/jurisdictions/resolveanswersserved: truefor the 50 states and DC, with thehandlinga case created there gets. There are no notice rules in the answer (noticeisnull): the attorney decides what the state’s law requires. - Submitting does not serve or file anything.
POST /v1/cases/{id}/submitruns the submission checks. A live case is submitted when its platform fee is paid: until then the answer is402 payment_required, the case stays adraft, anderror.detailsnames the charge (chargeId,amountCents) and the case page (payAt). When the payment is recorded, the case moves tosubmitted. We then engage a licensed attorney in the property’s state and confirm by email. Until then the case’sattorneyisnull. Nothing is served on a tenant or filed in court until that attorney has reviewed the case. - Charges.
GET /v1/cases/{id}/chargeslists the charges on a case with their status (due,paid,voidorrefunded).POST /v1/cases/{id}/charges/{chargeId}/checkoutreturns theurlof a Stripe Checkout page where a person pays it, andPOST /v1/cases/{id}/charges/{chargeId}/confirmreturns the charge after checking the payment with Stripe. Paying the platform fee of a draft submits the case. - Messages.
GET /v1/cases/{id}/noteslists the messages on a case, andPOST /v1/cases/{id}/noteswith abodysends us one, for example to say the tenant has paid. - More documents. On a live case you can upload a document with
purpose: "other"at any time before the case closes, not only while it is a draft. - The case moves when the attorney acts. Its
statechanges as each step is recorded, and your webhook endpoint registered with a live key receives an event each time.advanceanswers409 sandbox_only. We do not promise how long any step takes.
{
"served": true,
"handling": "attorney_direct",
"jurisdictionIds": ["us-ca"],
"action": null,
"grounds": {
"nonpayment": { "notice": null, "requiredFacts": [ ... ] },
"lease_violation": { "notice": null, "requiredFacts": [ ... ] },
"holdover": { "notice": null, "requiredFacts": [ ... ] }
}
}{
"error": {
"code": "payment_required",
"message": "...",
"details": {
"chargeId": "chg_...",
"amountCents": 2900,
"payAt": "https://evictionsapi.com/app/cases/case_..."
}
}
}{
"items": [
{ "id": "...", "kind": "platform_fee", "description": "...", "amountCents": 2900, "status": "due", "paidAt": null, "createdAt": "..." }
],
"paymentsEnabled": true
}The platform fee and the other costs of a real case are on the pricing page. The API itself and test keys are free.
What next
- Withdraw a test case with
POST /v1/cases/{id}/withdraw, or report that the tenant has paid or cured withPOST /v1/cases/{id}/report-cure. - List your cases with
GET /v1/cases, a page at a time. - Read the API reference for every endpoint, field and response.