# Public endpoints: API reference

> No credential. Health, the OpenAPI document, the endpoint behind the website’s forms, and account sign-up and sign-in.

Source: https://evictionsapi.com/docs/api/public

No credential. Health, the OpenAPI document, the endpoint behind the website’s forms, and account sign-up and sign-in.

The examples use https://api.evictionsapi.com and placeholder keys. The conventions shared by all endpoints, the error codes and the rate limits are in https://evictionsapi.com/docs/api.md

## Endpoints

### GET /v1/health

Liveness check

No credential.

```sh
curl https://api.evictionsapi.com/v1/health
```

Responses:

- `200` The service is up. Body: { ok: boolean }.

### GET /v1/openapi.json

This OpenAPI document

No credential.

```sh
curl https://api.evictionsapi.com/v1/openapi.json
```

Responses:

- `200` The OpenAPI 3.1 document. Body: object.

### POST /v1/auth/signup

Create an account: an unverified customer organization, its owner and a session. No credential; the website calls this from its servers

No credential.

```sh
curl -X POST https://api.evictionsapi.com/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Pat Landlord",
  "organizationName": "Acme Property",
  "email": "pat@example.com",
  "password": "a long passphrase, not this one"
}'
```

Responses:

- `201` The new session, user and organization. An `Idempotency-Key` header is ignored. Body: { token: string, user: object, organization: object, modes: object }.
- `400` The request is invalid. Body: Error.
- `401` Sign-in only: the email or password is incorrect (one fixed answer for both). Body: Error.
- `409` Sign-up only: an account with that email already exists (`email_taken`). Body: Error.
- `413` The request body is too large. Body: Error.
- `429` Too many sign-up and sign-in attempts from this address: at most 10 every 10 minutes. Sign-in only: also after 5 wrong passwords for one account within 15 minutes, until the oldest of them is 15 minutes old, whatever password is sent; a successful sign-in clears the count. `Retry-After` gives the seconds to wait. Body: Error.
- `503` `busy`: too many password checks are waiting. Nothing was created or changed. `Retry-After: 5` gives the seconds to wait; try again. Body: Error.

### POST /v1/auth/login

Sign in with email and password. A wrong email and a wrong password get the identical `invalid_credentials` answer

No credential.

```sh
curl -X POST https://api.evictionsapi.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
  "email": "pat@example.com",
  "password": "a long passphrase, not this one"
}'
```

Responses:

- `200` A new session, with the user and organization. An `Idempotency-Key` header is ignored. Body: { token: string, user: object, organization: object, modes: object }.
- `400` The request is invalid. Body: Error.
- `401` Sign-in only: the email or password is incorrect (one fixed answer for both). Body: Error.
- `409` Sign-up only: an account with that email already exists (`email_taken`). Body: Error.
- `413` The request body is too large. Body: Error.
- `429` Too many sign-up and sign-in attempts from this address: at most 10 every 10 minutes. Sign-in only: also after 5 wrong passwords for one account within 15 minutes, until the oldest of them is 15 minutes old, whatever password is sent; a successful sign-in clears the count. `Retry-After` gives the seconds to wait. Body: Error.
- `503` `busy`: too many password checks are waiting. Nothing was created or changed. `Retry-After: 5` gives the seconds to wait; try again. Body: Error.

### POST /v1/public/leads

Send a website request: access, a partner-attorney application, or a message. No credential; browser calls are allowed from the website origin only

No credential.

```sh
curl -X POST https://api.evictionsapi.com/v1/public/leads \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "access_request",
  "name": "Pat Landlord",
  "email": "pat@example.com",
  "role": "landlord",
  "states": ["FL"]
}'
```

Responses:

- `202` The request was received. A request with the `contact_url` honeypot field filled in gets the same answer and is discarded. Body: { received: boolean }.
- `400` The request is invalid. Body: Error.
- `413` The request body is too large. Body: Error.
- `429` Too many requests from this address: at most 5 every 10 minutes. `Retry-After` gives the seconds to wait. Body: Error.