Evictions API

API reference

The conventions shared by all endpoints, and an index of every endpoint. Each group of endpoints has its own page. Test keys and live keys use the same API.

This reference 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 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

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 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 under “API keys” in the app, or with POST /v1/api-keys.

Live keys are for real cases, for a property in any of the 50 states or DC. A live case is handled by a licensed attorney in the property’s state, engaged for that case after you submit it, and nothing is served or filed until that attorney has reviewed it. A live key can be created only by an owner of your organization, from a signed-in session in the app. The quickstart lists what is different for a live case.

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.

Create a case that is safe to retry
curl -X POST https://api.evictionsapi.com/v1/cases \
  -H "Authorization: Bearer eak_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-case-pat-landlord-2026-10" \
  -d '{ ... }'

Errors

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" }
      ]
    }
  }
}
A case that does not exist
{ "error": { "code": "not_found", "message": "Case not found", "details": null } }
NameTypeRequiredDescription
errorobjectYes—
error.codestringYes—
error.messagestringYes—
error.detailsanyYes—
CodeStatusWhen
invalid_request400, 422The 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).
invalid_reset_token400POST /v1/auth/password-reset/confirm only: the token is unknown, was already used, or expired (a reset link lasts one hour). Ask for a new link.
invalid_confirmation_token400POST /v1/auth/email-confirm/confirm only: the token is unknown, was already used, or expired (a confirmation link lasts three days). Ask for a new link with POST /v1/auth/email-confirm/request.
unauthenticated401The Authorization header is missing, malformed or names an unknown or revoked credential.
forbidden403The credential is valid but not allowed here, for example an attorney endpoint called with an API key.
permission_denied403Signed-in sessions only: the person’s role in the organization does not include the permission this needs, for example a viewer opening a case. An owner can change their role. Nobody grants what they do not hold: POST /v1/organization/invitations and /resend, and PATCH /v1/organization/members/{userId}, also answer it when someone who is not an owner invites or assigns a role with a permission they lack; only an owner makes, changes or removes an owner. An API key gets it from PATCH /v1/organization.
account_kind403POST /v1/me/organizations, POST /v1/invitations/{token}/accept, and POST /v1/auth/google with an invitationToken: an attorney’s or the operator’s account cannot start or join an organization. POST /v1/me/password and POST /v1/me/email: those accounts cannot change their password or email there.
wrong_password403POST /v1/me/password and POST /v1/me/email: the current password is not correct. Nothing was changed. Five wrong ones for an account in 15 minutes lock it for a while, sign-in included.
no_organization403Signed-in sessions only: the person belongs to no organization yet. Start one with POST /v1/me/organizations, or accept an invitation.
live_unavailable403, 409Live mode is switched off on this server, and the request asked for it: a signed-in session sent X-Evictions-Mode: live, or a live API key was used or requested (403). POST /v1/payment-method/setup and /confirm, and every change to /v1/payment-methods, in live mode while live full-service cases are not switched on (409): the full service works only with test keys for now.
attorney_not_eligible403Attorney endpoints only: the assigned attorney is not verified or not licensed in the property’s state.
invitation_invalid404GET /v1/invitations/{token}, POST /v1/invitations/{token}/accept, and POST /v1/auth/google with an invitationToken: the invitation is unknown, already accepted, revoked or expired (a link lasts seven days). Ask the person who invited you for a new one.
email_change_invalid404POST /v1/me/email/confirm only: the token is unknown, was already used, was replaced by a newer request, or expired (an email change link lasts 24 hours). Ask for a new one with POST /v1/me/email.
not_found404The case, document, API key, webhook endpoint or saved card does not exist for your organization and mode, or the route does not exist.
invalid_state409The case is no longer a draft, so its facts cannot change and evidence cannot be added.
invalid_transition409The action is not allowed in the case’s current state, for example submitting a case that is not a draft.
erased409, 410The details of the case were erased, which we do case by case on request. Any request that would change the case answers 409; downloading one of its documents answers 410. The case can still be read.
guard_failed409A step needs something that is missing, such as a current attorney approval of the exact documents.
stale_approval409Attorney endpoints only: the approved document hashes do not match the current documents.
not_agent_filed409The complaint-signature endpoints, and PATCH /v1/cases/{id} with paymentMethodId: the case is not a full-service case, where we act as your authorized agent, so it has no complaint to sign and is not charged to a saved card. The authorization endpoints answer it for a test case that is not a full-service case: every live case has an authorization to sign.
payment_required402POST /v1/cases/{id}/submit on a live case handled through an attorney whose platform fee is not paid: the case passed its checks and stays a draft. details.chargeId and details.amountCents name the charge, and details.payAt is the case page. Open a checkout for that charge (POST /v1/cases/{id}/charges/{chargeId}/checkout); the case moves to submitted when the payment is recorded.
authorization_required409POST /v1/cases/{id}/charges/{chargeId}/checkout only: nothing of a live case is paid before the owner has signed the authorization for us to act as their agent (GET and POST /v1/cases/{id}/authorization). details.signAt is the case page, where the owner reads and signs it; then the checkout opens.
agent_filing_refused409POST /v1/cases/{id}/submit on a full-service case: we cannot act on the case yet. details.reason says why: for example authorization_missing or authorization_stale (sign the authorization again), card_missing (save a card), complaint_signer_not_permitted (where the client signs the court filing, name for sign_complaint a member the court allows: the plaintiff in person or its own officer or full-time employee, never our staff), disabled, state_closed, state_paused or pack_missing (full service is not open for that state, and nothing was done).
jurisdiction_unavailable409GET and POST /v1/cases/{id}/authorization, and submit: no rules cover the case, so there is no authorization text and nothing to submit.
not_required409The complaint-signature endpoints only: there is nothing for you to sign now. The county has us sign the complaint, or the complaint is not ready yet (the case is not in filing_approved), or it has no documents.
documents_changed409POST /v1/cases/{id}/signatures/complaint where the filing is an affidavit sworn by electronic verification: documentHashes are not the hashes of the affidavit as it would be filed now (it changed since it was read, for example on a new day, or none were sent). Nothing was signed. Read it again (GET the signature, then its sworn.documents), then swear to it.
affiant_name_mismatch422POST /v1/cases/{id}/signatures/complaint where the filing is an affidavit sworn by electronic verification: the typed signerName is not the affiant's name as the affidavit prints it (sworn.affiantName; case and spacing aside). details.field is signerName. Nothing was signed.
already_member409POST /v1/organization/invitations and /resend, and accepting an invitation: the address belongs to a person who is already a member of the organization.
member_limit409POST /v1/organization/invitations and /resend, and accepting an invitation: the organization already has 50 people. Write to hello@evictionsapi.com if you need more.
invitation_email_mismatch409POST /v1/invitations/{token}/accept and POST /v1/auth/google with an invitationToken: the invitation was sent to another address than the signed-in account’s or the Google account’s. Nothing was changed.
email_taken409POST /v1/auth/signup, POST /v1/me/email and POST /v1/me/email/confirm: an account with that email address already exists. Nothing was changed.
organization_changed409Signed-in sessions only, on a change sent with X-Evictions-Organization (our website sends it): the session now acts for another organization, switched in another tab. Nothing was changed. Reload the page and try again. A request without the header, and every API key, is not checked.
no_password409POST /v1/me/password and POST /v1/me/email: the account signs in with Google and has no password, so neither can be changed there.
last_owner409POST /v1/me/organizations/{id}/leave, PATCH /v1/organization/members/{userId} (a demotion) and DELETE /v1/organization/members/{userId}: the person is the organization’s last owner. Make someone else an owner first.
landlord_limit409POST /v1/landlords only: the organization already keeps 1,000 saved landlords, archived ones included. Nothing was saved. Write to hello@evictionsapi.com if you need more.
landlord_file_limit409POST /v1/landlords/{id}/documents only: the landlord already has 20 files, replaced ones included. Nothing was saved. Write to hello@evictionsapi.com if you need more.
key_limit409POST /v1/api-keys only: the organization already has 10 active API keys in this mode. Revoke one first.
cannot_revoke_current_key409DELETE /v1/api-keys/{id} only: an API key tried to revoke itself. Use another key, or sign in.
sandbox_only409POST /v1/cases/{id}/advance: the case is not a test case in the fictional test state. Live cases are never advanced. POST /v1/payment-method/test-setup: the request is in live mode, where there are no test cards.
nothing_to_advance409POST /v1/cases/{id}/advance only: the test case is a draft, on hold or finished, or is not waiting on anything a test step can move on.
payments_unavailable409, 503POST /v1/cases/{id}/charges/{chargeId}/checkout and /confirm (409): online payment is switched off on this server, and the charge stays due. POST /v1/payment-method/setup and /confirm, and POST /v1/payment-methods/setup and /confirm, in live mode (503): a card cannot be saved while online payment is off.
payments_error502The checkout and payment-method endpoints (/v1/payment-method and /v1/payment-methods): the payment service did not answer or refused the request. Nothing was charged and any charge stays due. Try again.
automatic_charge409POST /v1/cases/{id}/charges/{chargeId}/checkout and /confirm: the charge is a cost of a full-service case. It is taken from the saved card, so it is not paid by checkout.
setup_incomplete409POST /v1/payment-method/confirm and POST /v1/payment-methods/confirm only: the card has not been saved on the payment provider's page yet, or that page expired. details.status says which.
idempotency_conflict409The Idempotency-Key was already used with a different request or credential.
payload_too_large413A document is over 10 MB after decoding, or the request body is too large.
unsupported_media_type415The request body is sent with a content type the API does not accept, or an uploaded document is not a PDF, a JPEG or a PNG.
payment_method_unusable422PATCH /v1/payment-methods/{id} with default: true: the card was declined, so it cannot be the default. Nothing was changed. Add another card or choose one that works.
landlord_not_found404, 422GET, PATCH /v1/landlords/{id}, its /archive, /unarchive and /documents routes (404): the landlord does not exist for your organization. POST /v1/cases and PATCH /v1/cases/{id} with landlordId (422): the landlord is not one of your organization’s active landlords (an archived one cannot be chosen for a case), and nothing was changed. The same answer for one that never existed and for another organization’s. Landlords are real owners, so with a test key every landlord read answers 404 (and GET /v1/landlords an empty list), and a test case cannot take one (422).
payment_method_not_found422PATCH /v1/cases/{id} with paymentMethodId: the card is not one of your organization’s saved cards in this mode that can be charged (it may have been removed or declined). Nothing was changed. Choose a card from GET /v1/payment-methods, or null for the default card.
gates_failed422Submit only: the case did not pass the submission checks. details holds the check results.
signer_unnamed422POST /v1/cases and PATCH /v1/cases/{id} with declared facts: the member named to sign the court filing for you has no full name on their account (an email address or a name without a letter is not one). The court filing prints the signer's name, so the person sets their full name on their Account page first. details.field names the actor. Nothing was stored.
signer_not_member422POST /v1/cases and PATCH /v1/cases/{id} with declared facts: the person named to sign the court filing for you (an actor with sign_complaint whose relationship is not platform_employee) is not a member of your organization. Name them by their user id from GET /v1/organization; a typed name is not accepted for this role. details.field names the actor. Nothing was stored.
prior_notice_missing422A prior-notice document was uploaded before the case recorded priorNotice.
documents_unavailable422Submit only: the jurisdiction has no documents for this ground and entry point.
invitation_rate_limited429POST /v1/organization/invitations and /resend: the organization sent 20 invitations in the last 24 hours, or the person sent 20 across all their organizations, resent and replaced ones included. Nothing was sent. Please try again later.
rate_limited429Too 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, a sign-in to an account after 5 wrong passwords for it in 15 minutes (whatever the password), more than 10 password reset requests from one address in 10 minutes, a password or email change after 5 wrong current passwords for the account in 15 minutes, more than 10 email change requests and email change links opened, counted together, from one address in 10 minutes, more than 3 email change links sent for one account in an hour, more than 5 organizations started by one person in 24 hours (POST /v1/me/organizations, the one made at sign-up included), more than 60 test-case advances per organization in a minute, or more than 20 messages on cases per organization in 10 minutes. Retry-After gives the seconds to wait.
busy503POST /v1/auth/signup, POST /v1/auth/login, POST /v1/auth/password-reset/confirm, POST /v1/me/password and POST /v1/me/email only: too many password checks are waiting. Nothing was created or changed. Retry-After: 5 gives the seconds to wait.
internal500An unexpected error. The response carries no detail.

Rate limits

The requests in this table are rate limited, the same way for test and live keys. No other endpoint is rate limited today: creating, reading, listing and changing cases, documents, API keys and webhook endpoints have no limit.

EndpointLimit
POST /v1/public/leads5 requests per address every 10 minutes
POST /v1/auth/signup, POST /v1/auth/login and POST /v1/auth/google10 requests per address every 10 minutes, counted together
POST /v1/auth/login, POST /v1/me/password and POST /v1/me/email, per account5 wrong passwords per account every 15 minutes, counting sign-ins and the current password given to change the password or email. Past that, signing in to the account, or changing its password or email, answers 429 whatever the password, until the oldest failure is 15 minutes old. A successful sign-in, or a right current password, clears the count
POST /v1/auth/password-reset/request and POST /v1/auth/password-reset/confirm10 requests per address every 10 minutes, counted together and apart from sign-up and sign-in
POST /v1/auth/password-reset/request, per account3 reset emails per account every hour. A request past that is still answered 202, not 429, and sends no email
POST /v1/auth/email-confirm/request and POST /v1/auth/email-confirm/confirm10 requests per address every 10 minutes, counted together and apart from sign-up, sign-in and password reset
POST /v1/auth/email-confirm/request, per account3 confirmation emails per account every hour, the one sent at sign-up included. A request past that is still answered 202, not 429, and sends no email
POST /v1/me/email and POST /v1/me/email/confirm10 requests per address every 10 minutes, counted together and apart from the sign-in, password reset and confirmation limits
POST /v1/me/email, per account3 email change links per account every hour. A request past that answers 429 and sends nothing
POST /v1/organization/invitations and POST /v1/organization/invitations/{id}/resend, per organization20 invitations per organization in any 24 hours, resent and replaced ones included. A request past that answers 429 invitation_rate_limited and sends nothing
POST /v1/organization/invitations and POST /v1/organization/invitations/{id}/resend, per person20 invitations per person in any 24 hours, counted across all their organizations. A request past that answers 429 invitation_rate_limited and sends nothing
POST /v1/me/organizations, per person5 new organizations per person in any 24 hours, the one made at sign-up included. A request past that answers 429 and creates nothing
POST /v1/cases/{id}/advance60 requests per organization every minute
POST /v1/cases/{id}/notes20 requests per organization every 10 minutes
POST /v1/geo/county60 requests per organization every hour
POST /v1/intake/files60 requests per organization every hour
POST /v1/intake/email, the email Worker's delivery route, per organization60 accepted messages per organization every hour. The route is internal: our email Worker calls it for mail sent to an intake address, not with an API key; it exists only when email intake is set up, and it is not in the API document. A message past the limit is answered 200, not 429, and nothing is stored or emailed
POST /v1/integrations/{system}/connect and POST /v1/integrations/{system}/leases60 requests per organization every hour, counted together
POST /v1/integrations/{system}/pull10 requests per organization every hour
POST /v1/extract20 requests per organization every hour (one lease, one ledger PDF, or one set of up to 10 messages; a refused request counts too)

POST /v1/cases/{id}/advance moves a test case on by one step; a live case does not use it.

A request over a limit is answered 429 rate_limited in the usual error shape, with a Retry-After header that gives the seconds to wait before trying again. The API sends no other rate limit headers.

Three limits answer without a 429: past their limits, password-reset and confirmation emails are simply not sent (the request is still answered 202, so the answer never shows whether an address has an account), and the email Worker's deliveries are answered 200 with nothing stored. A reset link that was already sent keeps working until it is used or expires.

A rate-limited request
HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json

{ "error": { "code": "rate_limited", "message": "Too many requests. Please try again later.", "details": null } }

Sign-up and sign-in can also answer 503 busy with Retry-After: 5 when too many password checks are waiting. Nothing was created or changed; wait and send the request again.

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.

A page of cases
{
  "items": [ { "id": "case_...", "state": "notice_review", ... } ],
  "nextCursor": "eyJ..."
}

Document upload

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, lease, ledger, correspondence or other) and contentBase64, the file as standard base64 with padding. The case's documents list each upload with its purpose; only the first three are linked into the case facts. The file must be a PDF, a JPEG or a PNG, judged by its content, not its name. 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), except that a live case accepts other documents until it closes. 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}.

Full-service cases

For now, full service works only with test keys. With it we act as your authorized agent, no attorney reviews the case, and we are not a law firm and do not give legal advice. A live request for full service where it is not open answers 409 service_unavailable and creates no case; details.reason says why (for example disabled, state_closed or pack_missing). To start the case with an attorney instead, send the request again without service.

Nothing is chosen for a live case: POST /v1/cases gives it the full service wherever it is open for the property, with or without service. Sending service: "full" asks for it by name, and where it is not open the request is refused as above; with a test key it is how a test case gets it. A case with it has handling agent_filed. GET /v1/jurisdictions/resolve answers fullService for a place before you create anything. The steps, in order:

  1. Create the draft and add its documents, as for any case.
  2. Sign the authorization: GET /v1/cases/{id}/authorization returns the text, and POST /v1/cases/{id}/authorization signs it for the facts as they are now. A change to the facts makes the signature stale (stale: true), and the case does not go on until it is signed again.
  3. Save a card: POST /v1/payment-method/setup returns the page where the card is typed, and POST /v1/payment-method/confirm saves it after the customer returns. With a test key no card is typed: POST /v1/payment-method/test-setup finishes the setup with a test card. Nothing is charged when a card is saved.
  4. Submit with POST /v1/cases/{id}/submit. Without a current authorization and a usable card the answer is 409 agent_filing_refused, and details.reason says which is missing.

After that the case runs by itself. GET /v1/cases/{id}/tasks lists each outward step with its status and dates. Each cost is a charge with collection: "automatic", taken from the saved card before the step it pays for; it is not paid by checkout. A declined card puts the case on hold until a new card is saved. Where the county requires the owner to sign the complaint, the case waits in filing_approved and the owner signs with GET and POST /v1/cases/{id}/signatures/complaint. The attorney endpoints refuse a full-service case.

New to the API? Start with the quickstart, and see the webhooks guide for events.