# Quickstart

> Create, validate and submit a test eviction case with curl and a free test key, follow it to closed, then see what changes for a real case with a live key.

Source: https://evictionsapi.com/docs

## Before you start

Sign up at https://evictionsapi.com/signup?next=/app/get-started and create a free test key under "API keys" in the app. The examples show it as `eak_test_...`. The commands use `curl` and `jq` and these two variables:

```sh
export EVICTIONS_API_URL=https://api.evictionsapi.com
export EVICTIONS_API_KEY=eak_test_...
```

Send `Authorization: Bearer <key>` on every request except the public endpoints. A key has a mode, which is in its prefix: `eak_live_...` for live and `eak_test_...` for test. A key sees only the cases of its own organization and mode.

Test keys are free. They are a developer feature for building and testing an integration: a test key works only with the fictional test state `ZZ`, and nothing real is served or filed. Create a test key on the site under "API keys", or with `POST /v1/api-keys`.

## 1. Resolve a jurisdiction

Ask whether a state is served for the key, how a case there is handled, and what facts each ground needs. With a test key, the fictional state `ZZ` is the one that answers `served: true`.

```sh
curl "$EVICTIONS_API_URL/v1/jurisdictions/resolve?state=ZZ" \
  -H "Authorization: Bearer $EVICTIONS_API_KEY"
```

## 2. Create a case

A case starts as a draft. `ground` is `nonpayment`, `lease_violation` or `holdover`; `entryPoint` is `notice`. Dates are `YYYY-MM-DD` and money is whole cents. Until it is submitted, change it with `PATCH /v1/cases/{id}`.

```sh
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
```

## 3. Upload proof of authority

A case cannot be submitted without a document showing authority over the property (a deed, a management agreement). The file goes in the JSON body as base64, up to 10 MB decoded: a PDF, a JPEG or a PNG. Any small PDF will do for a test case.

```sh
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')\"}"
```

## 4. Validate

Runs the same checks as submission and changes nothing. Each failed check has a `reason`.

```sh
curl -X POST "$EVICTIONS_API_URL/v1/cases/$CASE/validate" \
  -H "Authorization: Bearer $EVICTIONS_API_KEY"
```

## 5. Submit

A test case that passes every check gets its notice generated and goes to review by the built-in test reviewer. A case that does not pass is refused with `422 gates_failed`, and the check results are in `error.details`.

```sh
curl -X POST "$EVICTIONS_API_URL/v1/cases/$CASE/submit" \
  -H "Authorization: Bearer $EVICTIONS_API_KEY"
```

## 6. Read status

Every case response has its `state`, deadlines, documents and a `nextAction` that says who the case is waiting on. The events list is its history, oldest first.

```sh
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"
```

## 7. Advance the test case

Test cases only: each call moves the case on by one step and returns it. Some calls find nothing new and leave the state as it was; call again. Repeat until the state is `closed`. A draft, held or finished case answers `409 nothing_to_advance`; at most 60 calls a minute.

```sh
curl -X POST "$EVICTIONS_API_URL/v1/cases/$CASE/advance" \
  -H "Authorization: Bearer $EVICTIONS_API_KEY"
```

## 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 creating the case to receive that case’s events. The signing secret is in this response only: store it.

```sh
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" }'
```

## Real cases with a live key

Live mode is for real cases, for a rental property in any of the 50 states or DC. Submitting a live case serves nothing and files nothing. A live case is submitted when its platform fee is paid: until then `POST /v1/cases/{id}/submit` answers `402 payment_required` with the charge to pay, and the case is not yet submitted; a licensed attorney in the property’s state is engaged for that case after it is submitted, and the case moves when that attorney acts. A live key can be created only by an owner of the organization, signed in on the site, under "API keys".

The charges on a live case are listed by `GET /v1/cases/{id}/charges`, and `POST /v1/cases/{id}/charges/{chargeId}/checkout` returns the `url` of a hosted checkout page where a person pays one. Messages on a case are at `/v1/cases/{id}/notes`. `advance` works on test cases only.

## What next

- Every endpoint, field and response: https://evictionsapi.com/docs/api.md
- Webhooks: https://evictionsapi.com/docs/webhooks.md
- Connecting an AI agent over MCP: https://evictionsapi.com/docs/agents.md
- The platform fee and the other costs of a real case: https://evictionsapi.com/pricing.md
