Evictions API

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 as eak_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 advance work on test cases only. See Real cases with a live key.

Examples use curl and jq. Set your key and the API address once:

Set the API address and your key
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.

Resolve the fictional test state
curl "$EVICTIONS_API_URL/v1/jurisdictions/resolve?state=ZZ" \
  -H "Authorization: Bearer $EVICTIONS_API_KEY"
Response (abbreviated)
{
  "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.)

A real state, asked with a test key
{ "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.

Create a draft 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
Response, without jq (abbreviated)
{
  "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.

Upload evidence
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')\"}"
Response
{
  "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.

Validate the case
curl -X POST "$EVICTIONS_API_URL/v1/cases/$CASE/validate" \
  -H "Authorization: Bearer $EVICTIONS_API_KEY"
Response
{
  "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.

Submit the case
curl -X POST "$EVICTIONS_API_URL/v1/cases/$CASE/submit" \
  -H "Authorization: Bearer $EVICTIONS_API_KEY"
Response (abbreviated)
{
  "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.

Read the case and its events
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"
Events response (abbreviated)
{
  "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.

Move the case on by one step
curl -X POST "$EVICTIONS_API_URL/v1/cases/$CASE/advance" \
  -H "Authorization: Bearer $EVICTIONS_API_KEY"
Response (abbreviated)
{
  "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.

Register a webhook endpoint
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" }'
Response
{ "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/resolve answers served: true for the 50 states and DC, with the handling a case created there gets. There are no notice rules in the answer (notice is null): the attorney decides what the state’s law requires.
  • Submitting does not serve or file anything. POST /v1/cases/{id}/submit runs the submission checks. A live case is submitted when its platform fee is paid: until then the answer is 402 payment_required, the case stays a draft, and error.details names the charge (chargeId, amountCents) and the case page (payAt). When the payment is recorded, the case moves to submitted. We then engage a licensed attorney in the property’s state and confirm by email. Until then the case’s attorney is null. Nothing is served on a tenant or filed in court until that attorney has reviewed the case.
  • Charges. GET /v1/cases/{id}/charges lists the charges on a case with their status (due, paid, void or refunded). POST /v1/cases/{id}/charges/{chargeId}/checkout returns the url of a Stripe Checkout page where a person pays it, and POST /v1/cases/{id}/charges/{chargeId}/confirm returns the charge after checking the payment with Stripe. Paying the platform fee of a draft submits the case.
  • Messages. GET /v1/cases/{id}/notes lists the messages on a case, and POST /v1/cases/{id}/notes with a body sends 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 state changes as each step is recorded, and your webhook endpoint registered with a live key receives an event each time. advance answers 409 sandbox_only. We do not promise how long any step takes.
Resolve a real state with a live key (abbreviated)
{
  "served": true,
  "handling": "attorney_direct",
  "jurisdictionIds": ["us-ca"],
  "action": null,
  "grounds": {
    "nonpayment": { "notice": null, "requiredFacts": [ ... ] },
    "lease_violation": { "notice": null, "requiredFacts": [ ... ] },
    "holdover": { "notice": null, "requiredFacts": [ ... ] }
  }
}
Submit a live case before its fee is paid (402)
{
  "error": {
    "code": "payment_required",
    "message": "...",
    "details": {
      "chargeId": "chg_...",
      "amountCents": 2900,
      "payAt": "https://evictionsapi.com/app/cases/case_..."
    }
  }
}
Charges on a live 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 with POST /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.