# ActuallyCare Docs — REST API # For AI agents > Machine-readable docs: llms.txt, raw Markdown mirrors, tools.json, and the OpenAPI spec. This site is built to be read by machines as well as people. If you're an LLM, an agent, or a scraper — or the human configuring one — this page tells you where the machine-readable versions of everything live, and how to connect to ActuallyCare programmatically. ## Machine-readable formats | Resource | URL | What it is | |---|---|---| | Docs index | `/llms.txt` | One-page index of every docs page, per the [llmstxt.org](https://llmstxt.org) convention | | Full docs | `/llms-full.txt` | The entire docs site concatenated into a single Markdown file | | Sectioned docs | `/llms-mcp.txt`, `/llms-api.txt`, `/llms-tools.txt` | Smaller slices of the full file: connecting Claude and MCP clients, the REST API, and the tool reference | | Surface pointer | `/.well-known/ai.json` | A small JSON file pointing to every machine-readable surface on this site | | Any page as Markdown | append `.md` to the page URL, or send `Accept: text/markdown` | Raw Markdown source of that page | | MCP tool catalog | `/tools.json` | Every MCP tool: names, descriptions, JSON Schemas, safety annotations, aliases | | Sitemap | `/sitemap.xml` | Standard XML sitemap of all pages | | REST API spec | `https://docs.actuallycare.com/openapi.json` | OpenAPI spec the API reference is built from (live copy: `https://api.actuallycare.com/v1/openapi.json`) | | Docs MCP server | `https://docs.actuallycare.com/docs-mcp` | Read-only MCP server with `search_docs` and `get_page` over these docs — see [Search these docs from an MCP client](#search-these-docs-from-an-mcp-client) | | MCP discovery metadata | `https://mcp.actuallycare.com/.well-known/mcp` | Live server metadata — tool count, categories, capabilities, limits (derived from the running registry) | ### Raw Markdown for every page Every docs page (everything except the home page) is available as raw Markdown by appending `.md` to its URL. Example pair: ```text HTML: https://docs.actuallycare.com/mcp/quickstart Markdown: https://docs.actuallycare.com/mcp/quickstart.md ``` If you're feeding a single page into a model's context, fetch the `.md` version — it's smaller and has no navigation chrome. You can also request the normal URL with an `Accept: text/markdown` header and get the same Markdown back. ### llms.txt and llms-full.txt [/llms.txt](/llms.txt) follows the [llmstxt.org](https://llmstxt.org) convention: a short description of the site plus a linked index of every page with one-line summaries. Use it to decide which pages to fetch. [/llms-full.txt](/llms-full.txt) is the whole site in one file. Use it when you want all of the documentation in context at once and don't want to crawl. It's large, so if you only need one area, use a sectioned file instead: [/llms-mcp.txt](/llms-mcp.txt), [/llms-api.txt](/llms-api.txt), or [/llms-tools.txt](/llms-tools.txt). ### tools.json [/tools.json](/tools.json) is the canonical machine-readable answer to "what can this MCP server do." For every tool it includes: - the tool name (mostly entity first, like `escrows_list` and `leads_convert`; workflow tools are verb first, like `draft_email`) - a description - the full JSON Schema for its input - safety annotations (whether the tool reads, writes, or destroys data) - an `aliasOf` field recording the tool's previous published name (for example, `escrows_list` was once published as `search_escrows`). This is historical metadata only — legacy names are **not** callable; `tools/call` matches canonical names, and the old name's only afterlife is that its old docs URL redirects here The human-browsable version of the same catalog is at [/tools](/tools). ### OpenAPI spec The REST API is described by an OpenAPI spec. `https://docs.actuallycare.com/openapi.json` is the snapshot these docs are generated from, so it always matches the reference pages; the live copy is at `https://api.actuallycare.com/v1/openapi.json`. Note that the REST surface is intentionally smaller than the MCP surface — see [API vs MCP](/concepts/api-vs-mcp) for which to use when. The human-readable endpoint reference is at [/api/reference](/api/reference). ## Stable structure for parsers Pages on this site keep a predictable shape so anchors and extraction stay reliable: - Exactly one `h1` per page (the title), followed by `h2` and `h3` sections in order, never skipping levels. - Heading anchors are stable and lowercase-hyphenated (for example, `#stable-structure-for-parsers` on this page). We avoid renaming headings on published pages. - `/sitemap.xml` lists every page and is regenerated on each deploy. ## Connecting as an agent The MCP server is at: ```text https://mcp.actuallycare.com/mcp ``` Transport is Streamable HTTP (POST for JSON-RPC, GET for the SSE stream), MCP protocol version 2025-03-26. A legacy HTTP+SSE transport is available at `/sse` for older clients. Three auth options for programmatic clients: 1. **OAuth 2.1** — the standard path. Dynamic client registration is supported: `POST /register` on `mcp.actuallycare.com`, then the usual authorization-code flow with PKCE. Access tokens last 24 hours and refresh tokens rotate automatically. 2. **API key** — send an `X-API-Key` header. Simplest option for headless agents. Keys are created in the ActuallyCare app or via the REST API; see [Authentication](/api/authentication). 3. **JWT Bearer token** — the same token a normal REST login (`POST /v1/auth/login`) returns also works against the MCP server. Useful for custom apps that already sign users in; see [Authentication](/api/authentication). Full setup details, including a working TypeScript client, are on the [custom apps page](/mcp/custom-apps). ### Don't assume tools/list is exhaustive The server uses progressive disclosure: a standard `tools/list` call advertises only a set of everyday tools plus discovery meta-tools. A custom MCP client can still call any tool in the catalog by name with `tools/call`. Claude's own apps can only call advertised tools, so in a Claude chat the advertised set is the whole surface. If you need the complete catalog, consult [/tools.json](/tools.json) rather than treating the advertised list as the full surface. ## Search these docs from an MCP client These docs have their own small MCP server, separate from the CRM server above. It's read-only, needs no sign-in, and has two tools: `search_docs` (ranked pages with a snippet) and `get_page` (one page as Markdown). Add it to Claude Code with: ```bash claude mcp add --transport http actuallycare-docs https://docs.actuallycare.com/docs-mcp ``` Any MCP client that speaks Streamable HTTP can use it: POST JSON-RPC to `https://docs.actuallycare.com/docs-mcp`, and the server replies with JSON (there's no server-to-client stream). It only reads public docs; for your CRM data, connect to `https://mcp.actuallycare.com/mcp`. ## Citing these docs If you're an AI assistant answering a question from this site's content, please cite the page URL you used (for example, `https://docs.actuallycare.com/mcp/quickstart`) so the person you're helping can verify the answer and find updates. Every page here has a stable URL and a raw `.md` mirror. --- # Integration cheat sheet > Everything an agent needs to start calling ActuallyCare, in one page: base URL, auth, one working request, and the MCP connect URL. The minimum viable context for integrating with ActuallyCare. Everything here is expanded elsewhere — this page is sized for an agent's context window. ## REST API - **Base URL:** `https://api.actuallycare.com/v1` - **Auth:** send your API key in the `X-API-Key` header. Create one under **Settings → API Keys** in the web app (or `POST /v1/api-keys` with a JWT) and **pick its scopes** — `read`, `write` and `delete` are separate grants, and a request outside them gets `403`. JWT bearer auth also works: `POST /v1/auth/login` → `Authorization: Bearer `. These endpoints are JWT-only (API keys get `401`): the `/auth` session and profile endpoints, `/api-keys`, `/webhooks`, and authenticated `/billing`. - **First request:** ```bash curl -s https://api.actuallycare.com/v1/escrows \ -H "X-API-Key: $ACTUALLYCARE_API_KEY" ``` - **Envelope:** every response is `{ "success": true|false, "data": ..., "error": { "code", "message" } }`. Branch on `error.code`, never the message. - **Pagination:** `?page=1&limit=50` on most list endpoints; the response `meta` carries totals. `/v1/contacts` ignores `page` — use `offset` there. Details: [Pagination](/api/pagination). - **Spec:** [openapi.json](https://api.actuallycare.com/v1/openapi.json) · [Errors](/api/errors) · [Rate limits](/api/rate-limits) ## MCP server - **Endpoint:** `https://mcp.actuallycare.com/mcp` (Streamable HTTP) - **Auth:** OAuth 2.1 with PKCE and dynamic client registration — clients discover everything from the 401 `WWW-Authenticate` header. An ActuallyCare login is required at the consent screen. Custom clients can also send an API key in `X-API-Key` or a JWT as a bearer token. - **Tool surface:** `tools/list` advertises a set of everyday tools. Claude's apps can call only those; a custom client can call any catalog tool by name. - **Connect from Claude:** Customize → Connectors → + Add → Add custom connector → paste the endpoint URL → Continue → Add. Walkthrough: [Connect Claude in 5 minutes](/mcp/quickstart). - **Tool index:** [tools.json](https://docs.actuallycare.com/tools.json) — names, descriptions, input schemas, safety annotations for every tool. ## Webhooks Register via `POST /v1/webhooks` (JWT bearer auth, broker or system-admin role); deliveries are HMAC-signed. Setup and verification: [Set up webhooks](/guides/webhook-setup). ## Machine-readable docs [llms.txt](https://docs.actuallycare.com/llms.txt) · [llms-full.txt](https://docs.actuallycare.com/llms-full.txt) · append `.md` to any page URL · [.well-known/ai.json](https://docs.actuallycare.com/.well-known/ai.json) --- # REST API quickstart > Get an ActuallyCare API key and make your first authenticated request in about two minutes. > > **Takes:** 2 min · **Skill:** Developer · **Needs:** An active ActuallyCare account The ActuallyCare REST API lives at `https://api.actuallycare.com/v1`. You authenticate with an API key in the `X-API-Key` header, and every response comes back in the same JSON envelope. Here's the whole loop: ```bash title="cURL" curl "https://api.actuallycare.com/v1/listings" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/listings", { headers: { "X-API-Key": process.env.ACTUALLYCARE_API_KEY }, }); const body = await res.json(); console.log(`Fetched ${body.data.listings.length} of ${body.data.meta.total} listings`); ``` ```python title="Python" import os import requests resp = requests.get( "https://api.actuallycare.com/v1/listings", headers={"X-API-Key": os.environ["ACTUALLYCARE_API_KEY"]}, ) body = resp.json() print(f"Fetched {len(body['data']['listings'])} of {body['data']['meta']['total']} listings") ``` ```json { "success": true, "data": { "listings": [ { "id": "0d4f8a9c-3b2e-4f6a-9d1c-7e5b2a8f4c10", "property_address": "456 Oak Ave, Tehachapi, CA 93561", "listing_status": "Active", "list_price": 425000 } ], "meta": { "page": 1, "limit": 25, "total": 1, "totalPages": 1, "hasMore": false } }, "timestamp": "2026-06-11T18:24:09.123Z" } ``` Keep your key in an environment variable — never in source code or anything that ships to a browser. The rest of this page gets you from zero to that response. ## Get an API key 1. Sign in at [app.actuallycare.com](https://app.actuallycare.com) and open **Settings → API Keys** (direct link: [app.actuallycare.com/settings?tab=api](https://app.actuallycare.com/settings?tab=api)). Every user can create their own keys — each key acts as you, with your role's visibility. You need an **active** account: self-registration currently lands on a waitlist, and waitlisted accounts get `403 ACCOUNT_NOT_ACTIVE` on every endpoint (including key creation) until approved. 2. Click to create a key, give it a name that says what it's for ("Reporting script", "Zapier bridge"), choose an expiration, and choose its access level. **Read-only** is the default, so pick **Read & write** or **Full access** if your integration changes data. 3. Copy the key immediately. It's a 64-character hex string, shown exactly once — ActuallyCare stores only a hash, and the UI shows just the first 8 and last 4 characters afterward. Keys can also be created, listed, and revoked over the API itself — see [Authentication](/api/authentication) for the details, including how scopes grant each key its access. ## The response envelope Every successful response has `success: true` and the result in `data`; most also include a `timestamp` (server time), but don't rely on it. On paginated list endpoints `data` is an object keyed by the resource (`data.listings`, `data.clients`, …) with pagination metadata at `data.meta` — see [Pagination](/api/pagination). When something goes wrong, `success` flips to `false` and an `error` object explains why — see [Errors](/api/errors). ## What the API covers The documented REST surface today covers Authentication, API Keys, Contacts, Clients, Leads, Escrows, Listings, Appointments, Webhooks, and Billing. If you need data the REST API doesn't expose, the MCP server covers far more of the platform — see [API vs MCP](/concepts/api-vs-mcp) for how to choose. ## Import the API into Postman or Insomnia The whole API is described in one OpenAPI file. Download [`openapi.json`](/openapi.json) — the spec these docs are built from — or point your tool at the live copy, `https://api.actuallycare.com/v1/openapi.json`. In Postman or Insomnia, choose **Import** and give it the file or the URL; every endpoint arrives as a ready-made request. Add your key as an `X-API-Key` header (or set it once at the collection level) and you can call any endpoint. The same file works for generating a typed client in your language. There's also an interactive Swagger UI at [api.actuallycare.com/v1/api-docs](https://api.actuallycare.com/v1/api-docs) for trying endpoints in the browser. ## Where next | You want to | Go to | | --- | --- | | Understand API keys, JWTs, and 401 vs 403 | [Authentication](/api/authentication) | | Page through large result sets | [Pagination](/api/pagination) | | Handle errors and retries properly | [Errors](/api/errors) | | Stay under the request limits | [Rate limits](/api/rate-limits) | | Browse every endpoint, parameter, and field | [API reference](/api/reference) | | React to changes instead of polling | [Webhooks](/concepts/webhooks) | --- # Authentication > API keys and JWT bearer tokens for the ActuallyCare REST API, plus how 401 differs from 403. Most integrations authenticate with an API key in the `X-API-Key` header: ```bash curl "https://api.actuallycare.com/v1/clients" \ -H "X-API-Key: YOUR_API_KEY" ``` ```json { "success": true, "data": { "clients": [], "meta": { "page": 1, "limit": 25, "total": 0, "totalPages": 0, "hasMore": false } } } ``` A `200` with the standard envelope means your key works **and has the scope this endpoint needs** — a key can do only what its scopes allow, so scopes are part of "working" (see [Scopes](#scopes) below). The rest of this page covers API keys in depth, then JWT auth for apps where users sign in directly. A few endpoint groups take **only** a JWT bearer token — an `X-API-Key` header gets `401 No authentication token provided` there: the `/v1/auth` session and profile endpoints, key management (`/v1/api-keys`), webhooks (`/v1/webhooks`), and authenticated billing (`/v1/billing`). Each page in the [API reference](/api/reference) shows the auth its endpoints actually accept. ## API keys ### The header Send the key on every request in the `X-API-Key` header. The header name `API-Key` also works, but `X-API-Key` is the documented form — use it in new code. ### Key format Keys are 64-character hex strings with no prefix: ```text 9f2c4e8a1b3d5f7092c4e6a8b0d2f4169e8c0a2b4d6f8e1a3c5b7d9f0e2a4c6b ``` The full key is shown exactly once, at creation. ActuallyCare stores only a hash, so it can never be retrieved again — if you lose it, create a new key. After creation the UI shows just the first 8 and last 4 characters so you can tell keys apart. ### Create a key in the app 1. Sign in at [app.actuallycare.com](https://app.actuallycare.com) and open **Settings → API Keys** ([app.actuallycare.com/settings?tab=api](https://app.actuallycare.com/settings?tab=api)). Every user can create their own keys — each key acts as you, with your role's visibility. 2. Name the key after the integration it serves, choose its access level, pick an expiration (the UI also allows 0, meaning no expiration), and create it. The access levels are **Read-only** (the default: view only), **Read & write** (view, create and update, but not delete) and **Full access** (also delete). 3. Copy the key before closing the dialog. Pick the narrowest level that works. A read-only key gets `403` on any create, update or delete call (see [Scopes](#scopes)). ### Create a key over the API `POST /v1/api-keys` creates a key programmatically. Key management authenticates with a **JWT bearer token** (sign in first — see [JWT bearer tokens](#jwt-bearer-tokens) below), not with an API key: ```bash curl -X POST "https://api.actuallycare.com/v1/api-keys" \ -H "Authorization: Bearer YOUR_JWT" \ -H "Content-Type: application/json" \ -d '{ "name": "Reporting integration", "expiresInDays": 90, "scopes": { "all": ["read", "write"] } }' ``` ```json { "success": true, "data": { "id": "5c2e7f1a-8b4d-4e6f-9a0c-1d3e5f7a9b2c", "key": "9f2c4e8a1b3d5f7092c4e6a8b0d2f4169e8c0a2b4d6f8e1a3c5b7d9f0e2a4c6b", "name": "Reporting integration", "expires_at": "2026-09-09T18:24:09.123Z" }, "timestamp": "2026-06-11T18:24:09.123Z" } ``` `name` is required. `expiresInDays` is optional — 1 to 365 days. **If you omit it, the key never expires** — there's no implicit default, so set an expiry explicitly. `scopes` is required: a request without it, or with an empty object, is rejected with `400` ("Pick at least one permission for this API key"). The `data.key` field in the response is the only time you'll see the full key. The full set of key-management endpoints (list, revoke, delete) is in the [API Keys reference](/api/reference/api-keys). ### Scopes Scopes **grant** access — a key has no permissions except the ones its scopes spell out. Each grant pairs a resource with actions: `read` (GET), `write` (POST, PUT, PATCH) and `delete` (DELETE). A request the scopes don't cover gets `403` with a message naming the missing grant, such as `API key missing required scope: leads:write`. Endpoints outside the API-key surface return `403` ("This endpoint does not accept API keys"). - `{"all":["read"]}` — read access everywhere the key's user can see (**Read-only** in Settings) - `{"all":["read","write"]}` — read, create and update, but no deletes (**Read & write**) - `{"all":["read","write","delete"]}` — full access, including deletes (**Full access**) - `{"clients":["read","write"]}` — per-resource grants; this key can only touch clients Grants combine, so `{"all":["read"],"clients":["read","write"]}` means read everywhere plus write on clients. You can also grant or change scopes after creation with `PATCH /v1/api-keys/:id/scopes`: ```bash curl -X PATCH "https://api.actuallycare.com/v1/api-keys/KEY_ID/scopes" \ -H "Authorization: Bearer YOUR_JWT" \ -H "Content-Type: application/json" \ -d '{ "scopes": { "all": ["read"], "clients": ["read", "write"] } }' ``` Give each key the narrowest grant that still works. Scopes are an API-key concept — JWT-authenticated users aren't scope-checked; they act with their normal role and permissions. ### Rotate keys Rotation is a three-step swap, with no downtime: 1. Create a new key. 2. Update the integration to use it and confirm it works. 3. Revoke the old key (in the UI, or via the [API Keys endpoints](/api/reference/api-keys)). Use one key per integration so you can rotate or revoke each one independently, and revoke immediately if a key ever leaks. A revoked key fails with `401` on the next request. ### Store keys safely - Keep keys in environment variables or a secrets manager — never in source code, and never committed to git. - Never ship a key in client-side code (browser bundles, mobile apps). Anything a user can download can be read. - Don't log keys, and don't paste them into chat tools or tickets. ```bash export ACTUALLYCARE_API_KEY="9f2c4e8a1b3d5f7092c4e6a8b0d2f4169e8c0a2b4d6f8e1a3c5b7d9f0e2a4c6b" ``` ```javascript const res = await fetch("https://api.actuallycare.com/v1/clients", { headers: { "X-API-Key": process.env.ACTUALLYCARE_API_KEY }, }); ``` ## JWT bearer tokens If you're building an app where ActuallyCare users sign in with their own email and password, use JWT auth instead of a shared API key — each user acts with their own permissions. ### Log in ```bash curl -X POST "https://api.actuallycare.com/v1/auth/login" \ -H "Content-Type: application/json" \ -d '{ "email": "agent@example.com", "password": "their-password" }' ``` The `email` field also accepts a username — `{ "username": "agent1", "password": "..." }` works the same way (that's why a failed login says "Invalid username or password"). ```json { "success": true, "data": { "user": { "id": "ab12cd34-..." }, "accessToken": "eyJhbGciOiJIUzI1NiIs...", "refreshToken": "f3a1c9e7...", "expiresIn": "15m", "tokenType": "Bearer" }, "message": "Login successful" } ``` Send the access token on requests as a bearer token: ```bash curl "https://api.actuallycare.com/v1/clients" \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." ``` ### Other login outcomes A `200` from `/auth/login` isn't always a ready-to-use session — branch on the response shape: - **Two-factor enabled:** the response carries `data.requiresTOTP: true` (or `data.requiresSMS: true`) plus `data.userId`, and no token. Complete the challenge on the corresponding verification endpoint before you get a JWT. - **Waitlisted account:** newly registered accounts start on a waitlist. Login succeeds with `data.status: "waitlisted"` and a token, but that token works only on `/v1/auth/*` and `/v1/waitlist/*` — every other endpoint returns `403 ACCOUNT_NOT_ACTIVE` until the account is approved. The response's `data.redirect` points at the waitlist page. - **Account locked:** five consecutive failed logins lock the account for **30 minutes** and send an alert email to the account owner. While locked, login returns HTTP `423` with the code `ACCOUNT_LOCKED` and `error.details.locked_until`. Stop retrying and wait it out — more attempts extend nothing but the frustration. ### Token lifetimes and refresh Access-token lifetime is **role-based** — anywhere from 15 minutes to 8 hours depending on the user's role. Don't hardcode an expiry, and note that `expiresIn` is a **duration string** like `"15m"`, `"4h"`, or `"8h"` — not a number of seconds. Parse the string, or decode the JWT's `exp` claim, and refresh before the token runs out. To refresh, call `POST /v1/auth/refresh` with `{ "refreshToken": "..." }` in the body (or the `refreshToken` cookie). The response body carries a new `accessToken`. Each refresh **rotates** the refresh token: the old one stops working, and the new one comes back **only** in the `Set-Cookie: refreshToken=...` response header, not in the JSON body. Read it from that header and store it. Sessions stay alive on a 30-day sliding window, with a 90-day absolute cap; after that the user signs in again. Refresh from the same client that logged in. A refresh from a different user agent or network revokes the whole session (`401 FINGERPRINT_MISMATCH`), and logging in again from the same client invalidates that client's earlier refresh token. Refresh errors are all `401`: `NO_REFRESH_TOKEN`, `INVALID_REFRESH_TOKEN`, and `FINGERPRINT_MISMATCH`. ### One token, both servers The same JWT also authenticates against the MCP server at `https://mcp.actuallycare.com/mcp`, so an app that manages user sessions can call REST endpoints and MCP tools with a single credential. See [Build a custom MCP app](/mcp/custom-apps). ## 401 vs 403 | Status | What it means | Typical causes | | --- | --- | --- | | `401` | The request wasn't authenticated | Missing `X-API-Key` or `Authorization` header, a typo'd or revoked key, an expired key, an expired JWT | | `403` | Authenticated, but not allowed | The endpoint is role-gated, the record belongs to another team, or the key is missing the required scope (the message names it, for example `leads:write`) | The practical rule: a `401` means fix your credential; a `403` means fix your permissions — retrying won't help either one. Both come back in the standard error envelope described in [Errors](/api/errors). --- # Errors > The ActuallyCare error envelope, HTTP status codes, and when (and when not) to retry. Every error from the API comes back in the same envelope — `success` flips to `false` and an `error` object explains what happened. An illustrative example: ```json { "success": false, "error": { "code": "NOT_FOUND", "message": "Contact not found." }, "timestamp": "2026-06-11T18:24:09.123Z" } ``` | Field | What it is | | --- | --- | | `success` | Always `false` on errors | | `error.code` | Machine-readable code in SCREAMING_SNAKE_CASE (like `NOT_FOUND` or `VALIDATION_ERROR`) — stable, safe to branch on | | `error.message` | Human-readable explanation — wording can change, so never string-match it in code | | `error.details` | Optional extra context: an array of per-field problems on validation errors, or an object (for example `locked_until` on an account lockout) | | `error.errorId`, `error.correlationId` | Trace identifiers (rate-limit `429`s carry only `errorId`) — include them when contacting support so the failure can be traced | | `timestamp` | Server time of the failure | Login failures return stable snake-case codes: `INVALID_CREDENTIALS` (401 — unknown user or wrong password), `ACCOUNT_DISABLED` (401), `ACCOUNT_SUSPENDED` (403), and `ACCOUNT_LOCKED` (423, with `error.details.locked_until`). Token-layer failures — a missing, expired, or invalid bearer token, or an invalid, revoked, or expired API key — return `401` with code `UNAUTHORIZED`; a role or scope denial returns `403` with `FORBIDDEN`. Unexpected server errors can still carry a non-standard code, so branch on the HTTP status first. ## HTTP status codes | Status | Meaning | What to do | | --- | --- | --- | | `200` | Success | Read `data` from the envelope | | `201` | Created | Read `data` for the new record | | `400` | Bad request — malformed JSON or invalid parameters (`VALIDATION_ERROR`) | Fix the request; check `error.message` | | `401` | Not authenticated | Check the `X-API-Key` header or token — see [Authentication](/api/authentication) | | `403` | Authenticated but not allowed | First check the ID: looking up a client, lead, escrow, listing or appointment that doesn't exist, or isn't yours, returns `403 FORBIDDEN`, not `404`. Otherwise it's a permissions problem (role, team, or key scope) and retrying won't help. Also returned as `ACCOUNT_NOT_ACTIVE` when a waitlisted account isn't approved yet, and `ACCOUNT_SUSPENDED` for suspended accounts | | `404` | Not found | Check the ID. Contacts answer `404` for an unknown ID; most other record lookups answer `403` instead (see above) | | `409` | Conflict | The request clashes with current state (a duplicate, or a stale update) — re-fetch and decide deliberately | | `422` | Valid request, but a rule rejected a value (`VALIDATION_ERROR` or `COMPLIANCE_VIOLATION`) | Fix the value; `error.message` names the problem | | `423` | Account locked | Returned as `ACCOUNT_LOCKED`. Five consecutive failed logins lock the account for 30 minutes; `error.details.locked_until` says when it reopens. Stop retrying — see [Authentication](/api/authentication) | | `429` | Rate limited | Back off and retry — see [Rate limits](/api/rate-limits) | | `5xx` | Server error | Retry with backoff; check [status.actuallycare.com](https://status.actuallycare.com) if it persists | ## Retry on 429 and 5xx — and nothing else A `429` or `5xx` is transient: waiting and retrying usually succeeds. Every other `4xx` is deterministic — the same request will fail the same way, so retrying just burns rate limit. Fix the request instead. Use exponential backoff with a little jitter: ```javascript async function withRetry(makeRequest, maxRetries = 3) { for (let attempt = 0; ; attempt++) { const res = await makeRequest(); if (res.ok) return res.json(); const retryable = res.status === 429 || res.status >= 500; if (!retryable || attempt === maxRetries) { const body = await res.json().catch(() => null); throw new Error(body?.error?.message ?? `HTTP ${res.status}`); } // 1s, 2s, 4s... plus jitter so parallel clients don't retry in lockstep const delay = 2 ** attempt * 1000 + Math.random() * 250; await new Promise((resolve) => setTimeout(resolve, delay)); } } const listings = await withRetry(() => fetch("https://api.actuallycare.com/v1/listings", { headers: { "X-API-Key": process.env.ACTUALLYCARE_API_KEY }, }) ); ``` ## A 429 in practice Rate-limited responses use the standard envelope with the code `RATE_LIMIT_EXCEEDED` (the message varies by limit), plus `RateLimit-*` and `Retry-After` headers that tell you exactly when to come back: ```json { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests from this IP, please try again later.", "errorId": "3f6c1e2a-9b4d-4c1e-8a7f-2d5b6c9e0a14" } } ``` Branch on the status (or `error.code`), wait out `Retry-After` (seconds) or `RateLimit-Reset`, and retry. The `errorId` is a server-side trace id — include it if you contact support about a stuck limit. Guarding `res.json()` on non-2xx responses is still good hygiene (proxies and load balancers can produce non-JSON bodies), but the API itself answers `429` in JSON. The current limits, and a retry snippet that reads `RateLimit-Reset` instead of guessing, are on the [Rate limits](/api/rate-limits) page. ## Debugging tips - **Start with the HTTP status, then `error.code`.** The code is the stable, machine-readable answer to "what went wrong" — branch on it, not on the message. - **Read `error.message` as a human.** It usually names the exact field or rule that failed. - **Most 401s are credential problems.** A missing header, a typo, or a revoked or expired key — walk through [Authentication](/api/authentication) before suspecting anything else. - **On 429s, check the `RateLimit-*` headers.** They tell you your limit, what's left, and how many seconds until the window resets. - **Use the `timestamp` field.** It's the server's clock at the moment of failure — handy for lining errors up with your own logs, and worth including when you contact support. - **On 400s, check the request body against the reference.** Required fields and types for every endpoint are in the [API reference](/api/reference). --- # Pagination > Page through list endpoints with the page and limit query parameters. The paginated list endpoints — contacts, clients, leads, escrows, listings, and appointments — take a `limit` query parameter and return the records under `data`, keyed by the resource name, with pagination metadata at `data.meta`. All of them except contacts choose the page with `page`: ```bash curl "https://api.actuallycare.com/v1/clients?page=2&limit=50" \ -H "X-API-Key: YOUR_API_KEY" ``` ```json { "success": true, "data": { "clients": [ { "id": "7b1e9c44-2f6a-4d83-9c0e-5a1f2b3c4d5e" } ], "meta": { "page": 2, "limit": 50, "total": 137, "totalPages": 3, "hasMore": true } } } ``` The entity key matches the resource — `data.clients` here, `data.leads` on `/v1/leads`, `data.listings` on `/v1/listings`, `data.appointments` on `/v1/appointments`. (Records trimmed for brevity — each entry is a full object; the per-endpoint field lists are in the [API reference](/api/reference).) ## Parameters | Parameter | Type | Default | Notes | | --- | --- | --- | --- | | `page` | integer | `1` | Which page to fetch, starting at 1. Ignored by `/v1/contacts` | | `offset` | integer | `0` | Records to skip. Use this on `/v1/contacts`: `offset = (page - 1) * limit` | | `limit` | integer | `25` | Records per page, maximum 100. `/v1/escrows` defaults to 20 and `/v1/contacts` to 50 | Out-of-range values aren't clamped: a `limit` above 100 or below 1, or a `page` below 1, returns `400 VALIDATION_ERROR`. `/v1/webhooks` and `/v1/api-keys` aren't paginated — they return a plain array in `data`, with no `meta`. Stick to the parameters documented for each endpoint in the [API reference](/api/reference) — don't invent sort or filter parameters that aren't listed there. ## The meta object | Field | Meaning | | --- | --- | | `page` | The page you got back | | `limit` | Records per page for this response | | `total` | Total matching records across all pages | | `totalPages` | Total number of pages at this `limit` | | `hasMore` | `true` while there are more pages to fetch | You're done when `hasMore` is `false` — or, defensively, when a page comes back empty. ## Fetch every page Both loops below request 100 records at a time (the maximum) and stop when `data.meta.hasMore` goes `false`. JavaScript: ```javascript async function fetchAll(path, entity) { const all = []; let page = 1; let hasMore = true; while (hasMore) { const res = await fetch( `https://api.actuallycare.com/v1${path}?page=${page}&limit=100`, { headers: { "X-API-Key": process.env.ACTUALLYCARE_API_KEY } } ); if (!res.ok) throw new Error(`HTTP ${res.status}`); const body = await res.json(); all.push(...body.data[entity]); hasMore = body.data.meta.hasMore; page += 1; } return all; } const clients = await fetchAll("/clients", "clients"); // Not for /contacts — it ignores page. Page contacts with offset instead. ``` Python: ```python import os import requests def fetch_all(path, entity): records = [] page = 1 has_more = True while has_more: res = requests.get( f"https://api.actuallycare.com/v1{path}", headers={"X-API-Key": os.environ["ACTUALLYCARE_API_KEY"]}, params={"page": page, "limit": 100}, ) res.raise_for_status() body = res.json() records.extend(body["data"][entity]) has_more = body["data"]["meta"]["hasMore"] page += 1 return records clients = fetch_all("/clients", "clients") # Not for /contacts — it ignores page. Page contacts with offset instead. ``` ## Paginate less The fastest page is the one you don't fetch: - **Filter server-side where filters exist.** For example, `GET /v1/listings` accepts `status`, `minPrice`, and `maxPrice` — filtering there beats downloading everything and filtering in your code. Each endpoint's filters are in [the listings reference](/api/reference/listings). - **Mind the rate limit.** Every page is one request against your [rate limit](/api/rate-limits), so a full export at `limit=100` costs a request per hundred records. Cache results you'll reuse. - **Don't poll for changes.** If you're re-fetching everything on a schedule just to spot what changed, subscribe to [webhooks](/concepts/webhooks) instead and let ActuallyCare push the changes to you. --- # Rate limits > Request limits for the REST API and MCP server, and how to handle a 429 cleanly. Every response from the API tells you where you stand. Make any request with `-i` and read the headers: ```bash curl -i "https://api.actuallycare.com/v1/listings" \ -H "X-API-Key: YOUR_API_KEY" ``` ```text HTTP/2 200 RateLimit-Limit: 500 RateLimit-Remaining: 499 RateLimit-Reset: 893 ``` `RateLimit-Limit` is your budget for the window, `RateLimit-Remaining` is what's left, and `RateLimit-Reset` is the number of seconds until the window resets. These are the standard `RateLimit-*` headers — not the older `X-RateLimit-*` convention, so check the exact names if your HTTP library helpfully "normalizes" headers. ## The limits | Scope | Limit | Window | | --- | --- | --- | | All `/v1` endpoints | 500 requests per IP | 15 minutes | | Auth endpoints (`/v1/auth`, excluding `/refresh`) | 30 **failed** attempts per IP — successful requests don't count | 15 minutes | | `POST /v1/auth/login` (additional cap) | 50 **total** attempts per IP — successes included | 15 minutes | | `/v1/auth/refresh` | 30 requests per IP, shared with other sensitive endpoints (sign-up, Google and Microsoft sign-in) | 1 minute | | `POST /v1/auth/forgot-password`, `POST /v1/auth/reset-password` | 3 requests per IP | 1 hour | Limits apply per IP address. Two limits stack on login: the 30-failed-attempts budget is the one a broken integration hits first, and a second 50-total-attempts cap protects the endpoint even from successful-login loops. The `RateLimit-*` headers on a login response report the **50-total** cap (`RateLimit-Limit: 50`) because it's the last limiter in the chain — the 30-failed budget is enforced but not surfaced in headers. If you're hitting either one, something is failing repeatedly, or you're logging in per request instead of reusing tokens. Authenticate once and refresh; see [Authentication](/api/authentication). ## When you hit 429 A rate-limited request returns the standard error envelope with `error.code` set to `RATE_LIMIT_EXCEEDED` (see [Errors](/api/errors)), along with the `RateLimit-*` headers above and a `Retry-After` header in seconds. The polite retry honors `Retry-After` (falling back to `RateLimit-Reset`) instead of guessing: ```javascript async function getJSON(url, attempt = 0) { const res = await fetch(url, { headers: { "X-API-Key": process.env.ACTUALLYCARE_API_KEY }, }); if (res.status === 429 && attempt < 3) { const wait = Number(res.headers.get("Retry-After")) || Number(res.headers.get("RateLimit-Reset")) || 2 ** attempt * 5; await new Promise((resolve) => setTimeout(resolve, wait * 1000)); return getJSON(url, attempt + 1); } if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`); return res.json(); } ``` Retry only on `429` and `5xx` — other errors won't get better with repetition. The full backoff pattern is on the [Errors](/api/errors) page. ## Stay under the limits - **Cache reads.** If a script asks for the same listings three times in one run, that's two wasted requests. Fetch once, reuse. - **Use webhooks instead of polling.** Re-fetching everything on a timer to spot changes is the fastest way to burn 500 requests. Subscribe to [webhooks](/concepts/webhooks) and let ActuallyCare push changes to you. - **Fetch big lists at `limit=100`.** One page of 100 costs a fifth of five pages of 20 — see [Pagination](/api/pagination). - **Spread out scheduled jobs.** A cron job that fans out dozens of parallel requests at the top of the hour competes with itself. Stagger the work. ## MCP server limits If you're building a custom MCP client, the MCP server has its own per-user limits, separate from the REST limits above: | Scope | Limit | | --- | --- | | All MCP requests | 120 per minute, per user | | Tool calls | 30 per minute, per user | Tool executions can also run for up to 300 seconds before timing out, so set your client timeouts accordingly. See [Build a custom MCP app](/mcp/custom-apps) for the rest of the operational details. --- # Endpoint reference > Every REST endpoint on api.actuallycare.com — 65 operations across 10 resource groups. The REST API exposes **65 operations** across **10 resource groups**. All requests use the base URL `https://api.actuallycare.com/v1` and authenticate with an [API key or JWT](/api/authentication). This reference is generated from a snapshot of the live OpenAPI spec. Download that snapshot as [`openapi.json`](/openapi.json) to import into Postman or Insomnia; the live copy is at `https://api.actuallycare.com/v1/openapi.json`. ## [API Keys](/api/reference/api-keys) | Endpoint | Summary | | --- | --- | | `GET /v1/api-keys` | [List API keys](/api/reference/api-keys#list-api-keys) | | `POST /v1/api-keys` | [Create new API key](/api/reference/api-keys#create-new-api-key) | | `PATCH /v1/api-keys/{id}/scopes` | [Update API key scopes](/api/reference/api-keys#update-api-key-scopes) | | `PUT /v1/api-keys/{id}/revoke` | [Revoke API key](/api/reference/api-keys#revoke-api-key) | | `DELETE /v1/api-keys/{id}` | [Delete API key](/api/reference/api-keys#delete-api-key) | ## [Appointments](/api/reference/appointments) | Endpoint | Summary | | --- | --- | | `GET /v1/appointments` | [List all appointments](/api/reference/appointments#list-all-appointments) | | `POST /v1/appointments` | [Create new appointment](/api/reference/appointments#create-new-appointment) | | `GET /v1/appointments/{id}` | [Get appointment by ID](/api/reference/appointments#get-appointment-by-id) | | `PUT /v1/appointments/{id}` | [Update appointment](/api/reference/appointments#update-appointment) | | `DELETE /v1/appointments/{id}` | [Delete appointment](/api/reference/appointments#delete-appointment) | ## [Authentication](/api/reference/authentication) | Endpoint | Summary | | --- | --- | | `POST /v1/auth/register` | [Register new user](/api/reference/authentication#register-new-user) | | `POST /v1/auth/login` | [Login user](/api/reference/authentication#login-user) | | `POST /v1/auth/refresh` | [Refresh access token](/api/reference/authentication#refresh-access-token) | | `POST /v1/auth/logout` | [Logout user](/api/reference/authentication#logout-user) | | `GET /v1/auth/verify` | [Verify token validity](/api/reference/authentication#verify-token-validity) | | `GET /v1/auth/profile` | [Get user profile](/api/reference/authentication#get-user-profile) | | `PUT /v1/auth/profile` | [Update user profile](/api/reference/authentication#update-user-profile) | | `POST /v1/auth/logout-all` | [Logout from all devices](/api/reference/authentication#logout-from-all-devices) | | `GET /v1/auth/sessions` | [List active sessions](/api/reference/authentication#list-active-sessions) | ## [Billing](/api/reference/billing) | Endpoint | Summary | | --- | --- | | `GET /v1/billing/public-plans` | [Get public plan pricing](/api/reference/billing#get-public-plan-pricing) | | `POST /v1/billing/public-checkout` | [Start checkout without an account](/api/reference/billing#start-checkout-without-an-account) | | `GET /v1/billing/plans` | [Get plans with checkout identifiers](/api/reference/billing#get-plans-with-checkout-identifiers) | | `GET /v1/billing/subscription` | [Get current subscription status](/api/reference/billing#get-current-subscription-status) | | `POST /v1/billing/checkout` | [Start checkout for a subscription](/api/reference/billing#start-checkout-for-a-subscription) | | `POST /v1/billing/portal` | [Open the billing portal](/api/reference/billing#open-the-billing-portal) | ## [Clients](/api/reference/clients) | Endpoint | Summary | | --- | --- | | `GET /v1/clients` | [List all clients](/api/reference/clients#list-all-clients) | | `POST /v1/clients` | [Create new client](/api/reference/clients#create-new-client) | | `GET /v1/clients/{id}` | [Get client by ID](/api/reference/clients#get-client-by-id) | | `PUT /v1/clients/{id}` | [Update client](/api/reference/clients#update-client) | | `DELETE /v1/clients/{id}` | [Delete client](/api/reference/clients#delete-client) | ## [Contacts](/api/reference/contacts) | Endpoint | Summary | | --- | --- | | `GET /v1/contacts` | [List contacts](/api/reference/contacts#list-contacts) | | `POST /v1/contacts` | [Create a contact](/api/reference/contacts#create-a-contact) | | `GET /v1/contacts/search` | [Search contacts](/api/reference/contacts#search-contacts) | | `GET /v1/contacts/{id}` | [Get a contact](/api/reference/contacts#get-a-contact) | | `PUT /v1/contacts/{id}` | [Update a contact](/api/reference/contacts#update-a-contact) | | `DELETE /v1/contacts/{id}` | [Delete a contact](/api/reference/contacts#delete-a-contact) | | `PATCH /v1/contacts/{id}/archive` | [Archive a contact](/api/reference/contacts#archive-a-contact) | | `PATCH /v1/contacts/{id}/restore` | [Restore an archived contact](/api/reference/contacts#restore-an-archived-contact) | | `POST /v1/contacts/scan-card` | [Extract contact fields from a business-card photo](/api/reference/contacts#extract-contact-fields-from-a-business-card-photo) | ## [Escrows](/api/reference/escrows) | Endpoint | Summary | | --- | --- | | `GET /v1/escrows` | [List escrows](/api/reference/escrows#list-escrows) | | `POST /v1/escrows` | [Create an escrow](/api/reference/escrows#create-an-escrow) | | `GET /v1/escrows/{id}` | [Get an escrow](/api/reference/escrows#get-an-escrow) | | `PUT /v1/escrows/{id}` | [Update an escrow](/api/reference/escrows#update-an-escrow) | | `DELETE /v1/escrows/{id}` | [Delete an escrow](/api/reference/escrows#delete-an-escrow) | | `PATCH /v1/escrows/{id}/archive` | [Archive an escrow](/api/reference/escrows#archive-an-escrow) | | `PATCH /v1/escrows/{id}/restore` | [Restore an archived escrow](/api/reference/escrows#restore-an-archived-escrow) | | `GET /v1/escrows/{id}/timeline` | [Get an escrow's timeline](/api/reference/escrows#get-an-escrows-timeline) | ## [Leads](/api/reference/leads) | Endpoint | Summary | | --- | --- | | `GET /v1/leads` | [List all leads](/api/reference/leads#list-all-leads) | | `POST /v1/leads` | [Create new lead](/api/reference/leads#create-new-lead) | | `GET /v1/leads/{id}` | [Get lead by ID](/api/reference/leads#get-lead-by-id) | | `PUT /v1/leads/{id}` | [Update lead](/api/reference/leads#update-lead) | | `DELETE /v1/leads/{id}` | [Delete lead](/api/reference/leads#delete-lead) | | `POST /v1/leads/{id}/convert` | [Convert lead to client](/api/reference/leads#convert-lead-to-client) | ## [Listings](/api/reference/listings) | Endpoint | Summary | | --- | --- | | `GET /v1/listings` | [List all property listings](/api/reference/listings#list-all-property-listings) | | `POST /v1/listings` | [Create new listing](/api/reference/listings#create-new-listing) | | `GET /v1/listings/{id}` | [Get listing by ID](/api/reference/listings#get-listing-by-id) | | `PUT /v1/listings/{id}` | [Update listing](/api/reference/listings#update-listing) | | `DELETE /v1/listings/{id}` | [Delete listing](/api/reference/listings#delete-listing) | ## [Webhooks](/api/reference/webhooks) | Endpoint | Summary | | --- | --- | | `GET /v1/webhooks` | [List webhook subscriptions](/api/reference/webhooks#list-webhook-subscriptions) | | `POST /v1/webhooks` | [Create a webhook subscription](/api/reference/webhooks#create-a-webhook-subscription) | | `GET /v1/webhooks/events` | [List available webhook events](/api/reference/webhooks#list-available-webhook-events) | | `GET /v1/webhooks/events/categories` | [List webhook event categories](/api/reference/webhooks#list-webhook-event-categories) | | `PUT /v1/webhooks/{id}` | [Update a webhook subscription](/api/reference/webhooks#update-a-webhook-subscription) | | `DELETE /v1/webhooks/{id}` | [Deactivate a webhook subscription](/api/reference/webhooks#deactivate-a-webhook-subscription) | | `GET /v1/webhooks/{id}/logs` | [Get webhook delivery logs](/api/reference/webhooks#get-webhook-delivery-logs) | ## Error responses Every endpoint returns errors in the same envelope — `success` is `false` and an `error` object carries a stable machine-readable `code` and a human `message`. Branch on `error.code`, never the message. See [Errors](/api/errors) for the full status-code and error-code reference and retry guidance. ```json { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Invalid request data", "errorId": "ERR_1782972632_ab12cd", "correlationId": "b7e4c2a8-3f6d-4e29-9c41-8d5a2f7e1b93", "details": null }, "timestamp": "2026-07-15T14:32:10.000Z" } ``` --- # API Keys API > REST endpoints for api keys — request and response reference with examples. Create and revoke API keys programmatically, or self-serve in the app: Settings → API Keys → Create API Key. Base URL: `https://api.actuallycare.com/v1` · Errors use the [standard envelope](/api/reference#error-responses) — see [Errors](/api/errors). ## List API keys ```http GET /v1/api-keys ``` Returns list of API keys for authenticated user (keys are masked) ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/api-keys" \ -H "Authorization: Bearer YOUR_JWT" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/api-keys", { headers: { "Authorization": "Bearer YOUR_JWT", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/api-keys", headers={"Authorization": "Bearer YOUR_JWT"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Jordan Lee", "key_preview": "example key preview", "is_active": true, "created_at": "2026-07-15T14:32:10.000Z", "last_used_at": "2026-07-15T14:32:10.000Z", "expires_at": "2026-07-15T14:32:10.000Z" } ] } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | API keys retrieved successfully | | | `401` | Unauthorized | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Create new API key ```http POST /v1/api-keys ``` Generates a new API key for authenticated user. Key is only shown once. ⚠️ **CONSEQUENTIAL ACTION**: Creates new authentication credentials. Store the key securely - it cannot be retrieved again. ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | Yes | Descriptive name for the API key | | `expiresInDays` | integer | No | Number of days until expiration (1-365). If omitted, the key does not expire. | | `scopes` | object | Yes | Map of resource → allowed actions (an OBJECT, not a string array), e.g. {"escrows": ["read", "write"], "clients": ["read"]}. Use resource "all" as a wildcard (e.g. {"all": ["read"]}). Valid resources: all, appointments, artifacts, clients, contacts, daily-insights, deals, details, disclosures, documents, emails, engagements, entity-links, escrows, groups, habits, integrations, inventory, leads, listings, mls-agents, notifications, onboarding, open-houses, organizations, partners, pipelines, prospects, referral-pipeline, referrals, saved-searches, search, security, service-types, showings, tasks, tracks, users, verified-sales (source of truth: KNOWN_RESOURCES in middleware/auth/apiKeyScope.js). **Required (SPEC-5781).** A request with no scopes, `{}`, an unknown resource or an unknown action is rejected with 400. An endpoint that is not mapped to a resource denies every API key (403). | ### Example request ```bash title="cURL" curl -X POST "https://api.actuallycare.com/v1/api-keys" \ -H "Authorization: Bearer YOUR_JWT" \ -H "Content-Type: application/json" \ -d '{ "name": "Jordan Lee", "scopes": { "all": [ "read" ], "escrows": [ "read", "write" ] } }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/api-keys", { method: "POST", headers: { "Authorization": "Bearer YOUR_JWT", "Content-Type": "application/json", }, body: JSON.stringify({ "name": "Jordan Lee", "scopes": { "all": [ "read" ], "escrows": [ "read", "write" ] } }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.post( "https://api.actuallycare.com/v1/api-keys", headers={"Authorization": "Bearer YOUR_JWT"}, json={ "name": "Jordan Lee", "scopes": { "all": [ "read" ], "escrows": [ "read", "write" ] } }, ) data = resp.json() ``` ### Example response (201) ```json { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "key": "example key", "name": "Jordan Lee", "key_prefix": "example key prefix", "scopes": {}, "expires_at": "2026-07-15T14:32:10.000Z", "created_at": "2026-07-15T14:32:10.000Z" }, "message": "example message", "timestamp": "2026-07-15T14:32:10.000Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `201` | API key created successfully | | | `400` | Validation error | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Unauthorized | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Update API key scopes ```http PATCH /v1/api-keys/{id}/scopes ``` Replaces the scopes object on an existing API key. Requires JWT authentication (API keys cannot manage API keys). Scopes are a map of resource → allowed actions; see POST /api-keys for the valid resource list. ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Format: uuid | ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `scopes` | object | Yes | Full replacement scopes map (resource → actions) | ### Example request ```bash title="cURL" curl -X PATCH "https://api.actuallycare.com/v1/api-keys/:id/scopes" \ -H "Authorization: Bearer YOUR_JWT" \ -H "Content-Type: application/json" \ -d '{ "scopes": { "escrows": [ "read", "write" ], "all": [ "read" ] } }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/api-keys/:id/scopes", { method: "PATCH", headers: { "Authorization": "Bearer YOUR_JWT", "Content-Type": "application/json", }, body: JSON.stringify({ "scopes": { "escrows": [ "read", "write" ], "all": [ "read" ] } }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.patch( "https://api.actuallycare.com/v1/api-keys/:id/scopes", headers={"Authorization": "Bearer YOUR_JWT"}, json={ "scopes": { "escrows": [ "read", "write" ], "all": [ "read" ] } }, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "id": "7d3f9b2e-5a8c-4e1d-b6f0-9c2a4e8d1b57", "scopes": { "escrows": [ "read", "write" ], "all": [ "read" ] } }, "timestamp": "2026-07-01T22:48:31.554Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Scopes updated | | | `400` | Validation error (scopes must be an object) | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Unauthorized | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `404` | API key not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Revoke API key ```http PUT /v1/api-keys/{id}/revoke ``` Deactivates an API key without deleting it ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Format: uuid | ### Example request ```bash title="cURL" curl -X PUT "https://api.actuallycare.com/v1/api-keys/:id/revoke" \ -H "Authorization: Bearer YOUR_JWT" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/api-keys/:id/revoke", { method: "PUT", headers: { "Authorization": "Bearer YOUR_JWT", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.put( "https://api.actuallycare.com/v1/api-keys/:id/revoke", headers={"Authorization": "Bearer YOUR_JWT"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "id": "7d3f9b2e-5a8c-4e1d-b6f0-9c2a4e8d1b57" }, "timestamp": "2026-07-01T22:53:07.114Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | API key revoked successfully | | | `401` | Unauthorized | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `404` | API key not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Delete API key ```http DELETE /v1/api-keys/{id} ``` Permanently deletes an API key ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Format: uuid | ### Example request ```bash title="cURL" curl -X DELETE "https://api.actuallycare.com/v1/api-keys/:id" \ -H "Authorization: Bearer YOUR_JWT" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/api-keys/:id", { method: "DELETE", headers: { "Authorization": "Bearer YOUR_JWT", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.delete( "https://api.actuallycare.com/v1/api-keys/:id", headers={"Authorization": "Bearer YOUR_JWT"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": {}, "timestamp": "2026-07-15T14:32:10.000Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | API key deleted successfully | | | `401` | Unauthorized | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `404` | API key not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | --- # Appointments API > REST endpoints for appointments — request and response reference with examples. Calendar events — create, list, update, and cancel appointments. Base URL: `https://api.actuallycare.com/v1` · Errors use the [standard envelope](/api/reference#error-responses) — see [Errors](/api/errors). ## List all appointments ```http GET /v1/appointments ``` Returns paginated list of appointments/showings. Default page size 25 (max 100). ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `appointment_type` | query | enum | No | One of: `showing`, `inspection`, `signing`, `meeting`, `call`, `other` | | `status` | query | enum | No | One of: `scheduled`, `completed`, `cancelled`, `no_show` | | `start_date` | query | string | No | Format: date | | `page` | query | integer | No | Page number for pagination · Default: `1` · Min: 1 | | `limit` | query | integer | No | Number of items per page (default 25, max 100) · Default: `25` · Max: 100 · Min: 1 | ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/appointments" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/appointments", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/appointments", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "appointments": [ { "id": "d4b7a9e2-8c1f-4d6a-b3e5-7f9c2a0d8b46", "title": "Buyer consultation — Torres family", "appointment_type": "meeting", "start_time": "2026-07-10T17:00:00Z", "end_time": "2026-07-10T18:00:00Z", "location": "9900 Stockdale Hwy, Bakersfield, CA 93311", "client_id": "a3f8c1d2-6b4e-4a9f-8d27-95c0e3b1f684", "status": "scheduled" } ], "meta": { "page": 1, "limit": 25, "total": 12, "totalPages": 1, "hasMore": false } }, "timestamp": "2026-07-01T22:50:41.207Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Paginated list — records under data.appointments, pagination under data.meta | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Create new appointment ```http POST /v1/appointments ``` ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `title` | string | Yes | Appointment title | | `start_time` | string | Yes | Appointment start time (ISO 8601) · Format: date-time | | `end_time` | string | Yes | Appointment end time (ISO 8601) · Format: date-time | | `appointment_type` | string | No | Type of appointment (showing, inspection, signing, meeting, call, other) | | `location` | string | No | Appointment location | ### Example request ```bash title="cURL" curl -X POST "https://api.actuallycare.com/v1/appointments" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "your-title", "start_time": "your-start-time", "end_time": "your-end-time" }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/appointments", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ "title": "your-title", "start_time": "your-start-time", "end_time": "your-end-time" }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.post( "https://api.actuallycare.com/v1/appointments", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "title": "your-title", "start_time": "your-start-time", "end_time": "your-end-time" }, ) data = resp.json() ``` ### Example response (201) ```json { "success": true, "data": { "id": "d4b7a9e2-8c1f-4d6a-b3e5-7f9c2a0d8b46", "title": "Showing — 456 Oak Ave", "appointment_type": "showing", "start_time": "2026-07-12T21:30:00Z", "end_time": "2026-07-12T22:00:00Z", "location": "456 Oak Ave, Tehachapi, CA 93561", "status": "scheduled", "version": 1 }, "message": "Appointment created successfully", "timestamp": "2026-07-01T22:51:12.940Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `201` | Appointment created | | | `400` | Invalid request data | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Get appointment by ID ```http GET /v1/appointments/{id} ``` ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Unique identifier (UUID) · Format: uuid | ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/appointments/:id" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/appointments/:id", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/appointments/:id", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "id": "d4b7a9e2-8c1f-4d6a-b3e5-7f9c2a0d8b46", "title": "Buyer consultation — Torres family", "appointment_type": "meeting", "start_time": "2026-07-10T17:00:00Z", "end_time": "2026-07-10T18:00:00Z", "location": "9900 Stockdale Hwy, Bakersfield, CA 93311", "client_id": "a3f8c1d2-6b4e-4a9f-8d27-95c0e3b1f684", "status": "scheduled", "version": 1 }, "timestamp": "2026-07-01T22:51:44.518Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Appointment found | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Update appointment ```http PUT /v1/appointments/{id} ``` ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Unique identifier (UUID) · Format: uuid | ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `start_time` | string | No | Appointment start time (ISO 8601) · Format: date-time | | `end_time` | string | No | Appointment end time (ISO 8601) · Format: date-time | | `status` | string | No | Appointment status (scheduled, completed, cancelled, no_show) | | `version` | integer | No | Current record version for optimistic locking | ### Example request ```bash title="cURL" curl -X PUT "https://api.actuallycare.com/v1/appointments/:id" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "start_time": "your-start-time", "end_time": "your-end-time", "status": "your-status", "version": 3 }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/appointments/:id", { method: "PUT", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ "start_time": "your-start-time", "end_time": "your-end-time", "status": "your-status", "version": 3 }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.put( "https://api.actuallycare.com/v1/appointments/:id", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "start_time": "your-start-time", "end_time": "your-end-time", "status": "your-status", "version": 3 }, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "user_id": "550e8400-e29b-41d4-a716-446655440000", "title": "Property Showing - 123 Main St", "description": "example description", "appointment_type": "showing", "start_time": "2025-02-01T14:00:00Z", "end_time": "2025-02-01T15:00:00Z", "location": "123 Main St, Tehachapi, CA 93561", "client_id": "550e8400-e29b-41d4-a716-446655440000", "listing_id": "550e8400-e29b-41d4-a716-446655440000", "escrow_id": "550e8400-e29b-41d4-a716-446655440000", "status": "scheduled", "attendees": [ { "name": "Jordan Lee", "email": "agent@example.com", "phone": "+1 661 555 0123" } ], "reminder_sent": true, "notes": "example notes", "version": 1, "created_at": "2026-07-15T14:32:10.000Z", "updated_at": "2026-07-15T14:32:10.000Z" }, "timestamp": "2026-07-15T14:32:10.000Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Appointment updated | | | `400` | Invalid request data | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Delete appointment ```http DELETE /v1/appointments/{id} ``` ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Unique identifier (UUID) · Format: uuid | ### Example request ```bash title="cURL" curl -X DELETE "https://api.actuallycare.com/v1/appointments/:id" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/appointments/:id", { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.delete( "https://api.actuallycare.com/v1/appointments/:id", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": {}, "timestamp": "2026-07-15T14:32:10.000Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Appointment deleted | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | --- # Authentication API > REST endpoints for authentication — request and response reference with examples. Session management for user-facing apps: register, log in, refresh tokens, and manage sessions. If you are building a server-side integration, you usually want an [API key](/api/authentication) instead. Base URL: `https://api.actuallycare.com/v1` · Errors use the [standard envelope](/api/reference#error-responses) — see [Errors](/api/errors). ## Register new user ```http POST /v1/auth/register ``` Creates a new user account and always returns a signed JWT. **Waitlist gate:** when the platform is accepting signups (open registration, or the registration arrives via a brokerage invite) the account is created with status `active` and onboarding starts immediately. Otherwise the account is created with status `waitlisted` — the returned JWT can only reach `/auth/*` and `/waitlist/*` endpoints; every other endpoint returns 403 with error.code `ACCOUNT_NOT_ACTIVE` until an admin approves the account. Both outcomes return 201 with the same shape; check `data.status` and follow `data.redirect`. ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `email` | string | Yes | User's email address (login identifier, stored lowercase) · Format: email | | `username` | string | Yes | Unique username — letters, numbers, and underscores only (stored lowercase) | | `password` | string | Yes | Account password — min 8 chars, at least one uppercase letter and one number | | `firstName` | string | Yes | User's first name | | `lastName` | string | Yes | User's last name | | `role` | enum | No | Optional starting role for the account · One of: `agent`, `broker`, `lender`, `vendor` · Default: `"agent"` | | `emailKind` | enum | No | Optional classification of the provided email address · One of: `personal`, `work`, `offers` | | `phone` | string | No | Optional phone number (required for SMS consent to be recorded) | | `smsConsent` | boolean | No | Optional explicit consent to receive SMS (recorded only when phone is provided) | ### Example request ```bash title="cURL" curl -X POST "https://api.actuallycare.com/v1/auth/register" \ -H "Content-Type: application/json" \ -d '{ "email": "sarah.chen@example.com", "username": "sarahchen", "password": "your-password", "firstName": "Sarah", "lastName": "Chen", "phone": "(661) 555-0142" }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/auth/register", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ "email": "sarah.chen@example.com", "username": "sarahchen", "password": "your-password", "firstName": "Sarah", "lastName": "Chen", "phone": "(661) 555-0142" }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.post( "https://api.actuallycare.com/v1/auth/register", json={ "email": "sarah.chen@example.com", "username": "sarahchen", "password": "your-password", "firstName": "Sarah", "lastName": "Chen", "phone": "(661) 555-0142" }, ) data = resp.json() ``` ### Example response (201) ```json { "success": true, "data": { "user": { "id": "b7e9d2c4-5f1a-4e8b-9c3d-2a6f8e0b4d17", "email": "sarah.chen@example.com", "firstName": "Sarah", "lastName": "Chen", "role": [ "agent" ], "isActive": true, "status": "active" }, "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImI3ZTlkMmM0LTVmMWEtNGU4Yi05YzNkLTJhNmY4ZTBiNGQxNyJ9.Qm4x8pT2cVhLk9wYzR0aXNlY3VyZQ", "status": "active", "redirect": "/get-started", "onboarding": { "sampleDataGenerated": true, "tutorialAvailable": true, "nextStep": "/onboarding/welcome" } }, "message": "User registered successfully" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `201` | User registered — `data.status` is `active` or `waitlisted` depending on whether the platform is accepting signups | | | `400` | Invalid request data | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `409` | A user with this email or username already exists (case-insensitive check) | Re-fetch the current state, then decide deliberately; don't blind-retry | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Login user ```http POST /v1/auth/login ``` Authenticate with email OR username plus password. On full success, returns a JWT access token whose lifetime is role-based (`expiresIn` duration string: `15m` for system_admin and default, `4h` for broker/team_lead, `8h` for agent) and sets a `refreshToken` httpOnly cookie (default 30 days). The 200 body has four possible `data` shapes: full login, TOTP challenge (`requiresTOTP`), SMS challenge (`requiresSMS`), or waitlisted account. ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `email` | string | No | User's email address (provide email OR username; case-insensitive) | | `username` | string | No | Username (provide email OR username; case-insensitive) | | `password` | string | Yes | Account password | ### Example request ```bash title="cURL" curl -X POST "https://api.actuallycare.com/v1/auth/login" \ -H "Content-Type: application/json" \ -d '{ "email": "sarah.chen@example.com", "password": "YourPassword123!" }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/auth/login", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ "email": "sarah.chen@example.com", "password": "YourPassword123!" }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.post( "https://api.actuallycare.com/v1/auth/login", json={ "email": "sarah.chen@example.com", "password": "YourPassword123!" }, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "user": { "id": "b7e9d2c4-5f1a-4e8b-9c3d-2a6f8e0b4d17", "email": "sarah.chen@example.com", "username": "sarahchen", "firstName": "Sarah", "lastName": "Chen", "role": [ "agent" ], "isActive": true, "teamId": "3c1e8f5a-7d2b-4a9c-b6e4-0f8d2c5a7e91", "teamName": "Chen Home Team", "brokerageId": "9e4b2d7f-1a6c-4e8b-a3d5-6c0f9b2e4d78", "corporationName": "Golden Empire Realty", "scopeLevel": "team", "verticals": [ "realtor" ], "managedTeams": [] }, "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImI3ZTlkMmM0LTVmMWEtNGU4Yi05YzNkLTJhNmY4ZTBiNGQxNyJ9.Qm4x8pT2cVhLk9wYzR0aXNlY3VyZQ", "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImI3ZTlkMmM0LTVmMWEtNGU4Yi05YzNkLTJhNmY4ZTBiNGQxNyJ9.Qm4x8pT2cVhLk9wYzR0aXNlY3VyZQ", "refreshToken": "9c2f8e4a1d6b3c5e7f0a2b4d6e8f1a3c5b7d9e0f2a4c6e8b1d3f5a7c9e0b2d4f", "expiresIn": "8h", "tokenType": "Bearer", "requiresTOTPSetup": false }, "message": "Login successful" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Password verified — data is one of four shapes (full login, TOTP required, SMS required, waitlisted) | | | `401` | Invalid credentials (INVALID_CREDENTIALS) or disabled account (ACCOUNT_DISABLED) | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `403` | Account suspended (ACCOUNT_SUSPENDED) | Check the ID first: an ID that doesn't exist or isn't yours also returns 403. Otherwise a role or key-scope problem; retrying won't help. See [Errors](/api/errors#http-status-codes) | | `423` | Account locked (ACCOUNT_LOCKED). The 5th consecutive failed attempt locks the account for 30 minutes; attempts made WHILE locked return this 423 with details.locked_until (the failure that triggers the lock itself returns 401). | Account locked; `error.details.locked_until` says when it reopens. Stop retrying | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Refresh access token ```http POST /v1/auth/refresh ``` Exchanges the refresh token (httpOnly `refreshToken` cookie, or `refreshToken` in the request body for cookie-less clients) for a new access token. The refresh token is rotated on every call — the previous one is invalidated and the new one is set on the same httpOnly cookie. A device-fingerprint mismatch (different IP + user agent than the token was issued to) revokes the whole token family and returns 401 FINGERPRINT_MISMATCH. ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `refreshToken` | string | No | Refresh token — only needed when the httpOnly cookie is unavailable (e.g. native clients) | ### Example request ```bash title="cURL" curl -X POST "https://api.actuallycare.com/v1/auth/refresh" \ -H "Content-Type: application/json" \ -d '{ "refreshToken": "your-refreshToken" }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/auth/refresh", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ "refreshToken": "your-refreshToken" }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.post( "https://api.actuallycare.com/v1/auth/refresh", json={ "refreshToken": "your-refreshToken" }, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "accessToken": "example accessToken", "expiresIn": "8h", "refreshTokenExpiresIn": "30d" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Token refreshed (a rotated refreshToken cookie is also set) | | | `401` | Missing, invalid, expired, or revoked refresh token (NO_REFRESH_TOKEN, INVALID_REFRESH_TOKEN, or FINGERPRINT_MISMATCH) | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Logout user ```http POST /v1/auth/logout ``` Revokes the current refresh token (if present) and clears the refreshToken cookie. Succeeds even without a token — the endpoint requires no authentication and always returns 200 for a well-formed request. ### Example request ```bash title="cURL" curl -X POST "https://api.actuallycare.com/v1/auth/logout" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/auth/logout", { method: "POST", }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.post( "https://api.actuallycare.com/v1/auth/logout", ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "message": "Logged out successfully" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Logged out successfully (refreshToken cookie cleared) | | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Verify token validity ```http GET /v1/auth/verify ``` Checks if the JWT access token is valid. Returns the same full profile payload as GET /auth/profile (both are served by the same handler). ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/auth/verify" \ -H "Authorization: Bearer YOUR_JWT" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/auth/verify", { headers: { "Authorization": "Bearer YOUR_JWT", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/auth/verify", headers={"Authorization": "Bearer YOUR_JWT"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "user": { "id": "b7e9d2c4-5f1a-4e8b-9c3d-2a6f8e0b4d17", "email": "sarah.chen@example.com", "role": [ "agent" ] } } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Token is valid — body matches GET /auth/profile | | | `401` | Token missing, invalid, or expired | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Get user profile ```http GET /v1/auth/profile ``` Returns authenticated user's profile information ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/auth/profile" \ -H "Authorization: Bearer YOUR_JWT" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/auth/profile", { headers: { "Authorization": "Bearer YOUR_JWT", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/auth/profile", headers={"Authorization": "Bearer YOUR_JWT"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "user": { "id": "b7e9d2c4-5f1a-4e8b-9c3d-2a6f8e0b4d17", "email": "sarah.chen@example.com", "username": "sarahchen", "firstName": "Sarah", "lastName": "Chen", "role": [ "agent" ], "isActive": true, "status": "active", "emailVerified": true, "licenseVerified": false, "lastLogin": "2026-07-15T14:32:10.000Z", "createdAt": "2026-07-15T14:32:10.000Z", "updatedAt": "2026-07-15T14:32:10.000Z", "timezone": "America/Los_Angeles", "teamId": "550e8400-e29b-41d4-a716-446655440000", "teamName": "example teamName", "brokerageId": "550e8400-e29b-41d4-a716-446655440000", "aiPlanTier": "free", "subscriptionTier": "free", "subscriptionStatus": "none", "hasStripeCustomer": false, "scopeLevel": "personal", "managedTeams": [ {} ] } } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Profile retrieved successfully (payload is nested under data.user) | | | `401` | Unauthorized | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Update user profile ```http PUT /v1/auth/profile ``` Updates authenticated user's profile information ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `firstName` | string | No | Updated first name | | `lastName` | string | No | Updated last name | | `currentPassword` | string | No | Required when changing the password · Format: password | | `newPassword` | string | No | New password — changing it revokes ALL refresh tokens (every session is logged out) · Format: password | | `homeCity` | string | No | Home-base city used to center map and search defaults | | `homeState` | string | No | Home-base state (two-letter code) | | `homeZip` | string | No | Home-base ZIP code | | `homeLat` | number | No | Home-base latitude | | `homeLng` | number | No | Home-base longitude | | `licensedStates` | array of strings | No | States where the agent holds an active license (two-letter codes) | | `searchRadiusMiles` | integer | No | Default listing-search radius in miles | | `timezone` | string | No | IANA timezone identifier for the user | ### Example request ```bash title="cURL" curl -X PUT "https://api.actuallycare.com/v1/auth/profile" \ -H "Authorization: Bearer YOUR_JWT" \ -H "Content-Type: application/json" \ -d '{ "firstName": "Sarah", "lastName": "Chen", "currentPassword": "your-currentPassword", "newPassword": "your-newPassword", "homeCity": "Bakersfield", "homeState": "CA", "homeZip": "93309", "homeLat": 35.3433, "homeLng": -119.0587, "licensedStates": [ "CA" ], "searchRadiusMiles": 25, "timezone": "America/Los_Angeles" }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/auth/profile", { method: "PUT", headers: { "Authorization": "Bearer YOUR_JWT", "Content-Type": "application/json", }, body: JSON.stringify({ "firstName": "Sarah", "lastName": "Chen", "currentPassword": "your-currentPassword", "newPassword": "your-newPassword", "homeCity": "Bakersfield", "homeState": "CA", "homeZip": "93309", "homeLat": 35.3433, "homeLng": -119.0587, "licensedStates": [ "CA" ], "searchRadiusMiles": 25, "timezone": "America/Los_Angeles" }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.put( "https://api.actuallycare.com/v1/auth/profile", headers={"Authorization": "Bearer YOUR_JWT"}, json={ "firstName": "Sarah", "lastName": "Chen", "currentPassword": "your-currentPassword", "newPassword": "your-newPassword", "homeCity": "Bakersfield", "homeState": "CA", "homeZip": "93309", "homeLat": 35.3433, "homeLng": -119.0587, "licensedStates": [ "CA" ], "searchRadiusMiles": 25, "timezone": "America/Los_Angeles" }, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "id": "b7e9d2c4-5f1a-4e8b-9c3d-2a6f8e0b4d17", "email": "sarah.chen@example.com", "firstName": "Sarah", "lastName": "Chen", "role": [ "agent" ], "isActive": true, "home_city": "Bakersfield", "home_state": "CA", "home_zip": "93309", "home_lat": 35.3433, "home_lng": -119.0587, "licensed_states": [ "CA" ], "search_radius_miles": 25 }, "message": "Profile updated successfully" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Profile updated successfully | | | `400` | Validation error (no fields to update, missing currentPassword, or incorrect current password) | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Unauthorized | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Logout from all devices ```http POST /v1/auth/logout-all ``` Invalidates all refresh tokens for the authenticated user, logging them out from all sessions ### Example request ```bash title="cURL" curl -X POST "https://api.actuallycare.com/v1/auth/logout-all" \ -H "Authorization: Bearer YOUR_JWT" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/auth/logout-all", { method: "POST", headers: { "Authorization": "Bearer YOUR_JWT", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.post( "https://api.actuallycare.com/v1/auth/logout-all", headers={"Authorization": "Bearer YOUR_JWT"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "message": "Logged out from all devices successfully" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Logged out from all devices successfully | | | `401` | Unauthorized | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## List active sessions ```http GET /v1/auth/sessions ``` Returns list of active refresh tokens/sessions for authenticated user ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/auth/sessions" \ -H "Authorization: Bearer YOUR_JWT" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/auth/sessions", { headers: { "Authorization": "Bearer YOUR_JWT", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/auth/sessions", headers={"Authorization": "Bearer YOUR_JWT"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "sessions": [ { "id": "3f8c1d7a-9e2b-4c6f-a1d8-7b4e2c9f5a30", "createdAt": "2026-06-28T17:03:22.481Z", "expiresAt": "2026-07-28T17:03:22.481Z", "ipAddress": "203.0.113.42", "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36", "deviceInfo": {}, "isCurrent": true } ] } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Sessions retrieved successfully (array is nested under data.sessions) | | | `401` | Unauthorized | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | --- # Billing API > REST endpoints for billing — request and response reference with examples. Subscription plans and checkout. The public-plans and public-checkout endpoints require no authentication; the rest operate on the authenticated account. Pricing on [www.actuallycare.com/pricing](https://www.actuallycare.com/pricing) comes from these endpoints. Base URL: `https://api.actuallycare.com/v1` · Errors use the [standard envelope](/api/reference#error-responses) — see [Errors](/api/errors). ## Get public plan pricing ```http GET /v1/billing/public-plans ``` Returns the current subscription plans with pricing in cents. This endpoint requires no authentication and is the source of truth for pricing shown on the marketing site. Responses are cacheable (5 minutes in browsers, 1 hour at the CDN edge). ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/billing/public-plans" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/billing/public-plans"); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/billing/public-plans", ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "plans": [ { "key": "agent", "name": "ActuallyCare+ Agent", "priceMonthly": 10000, "priceYearly": 120000, "trialDays": 30, "seats": 1, "recommended": false, "features": [ "example features" ] } ], "currency": "usd", "version": "example version" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Available plans | | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Start checkout without an account ```http POST /v1/billing/public-checkout ``` Creates a Stripe Checkout session for a new customer who doesn't have an account yet. Only the agent plan is available through this endpoint; team and brokerage subscriptions require an account and the authenticated checkout endpoint. Returns the Stripe-hosted checkout URL to redirect the visitor to. ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `email` | string | Yes | Email address for the new customer and Stripe Checkout session · Format: email | | `planKey` | enum | No | Subscription plan tier (only agent is available without an account) · One of: `agent` · Default: `"agent"` | | `interval` | enum | No | Billing interval (defaults to monthly) · One of: `monthly`, `yearly` · Default: `"monthly"` | ### Example request ```bash title="cURL" curl -X POST "https://api.actuallycare.com/v1/billing/public-checkout" \ -H "Content-Type: application/json" \ -d '{ "email": "agent@example.com" }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/billing/public-checkout", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ "email": "agent@example.com" }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.post( "https://api.actuallycare.com/v1/billing/public-checkout", json={ "email": "agent@example.com" }, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "url": "example url", "sessionId": "example sessionId" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Checkout session created | | | `400` | Invalid request data | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Get plans with checkout identifiers ```http GET /v1/billing/plans ``` Returns the subscription plans for the in-app billing page. Same plans as the public endpoint, plus the identifiers needed to start an authenticated checkout. Prices here are in dollars. ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/billing/plans" \ -H "Authorization: Bearer YOUR_JWT" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/billing/plans", { headers: { "Authorization": "Bearer YOUR_JWT", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/billing/plans", headers={"Authorization": "Bearer YOUR_JWT"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": [ { "key": "agent", "name": "ActuallyCare+ Agent", "priceId": "price_XXXXXXXXXXXXXXXXXXXXXXXX", "priceIds": { "monthly": "price_XXXXXXXXXXXXXXXXXXXXXXXX", "yearly": "price_YYYYYYYYYYYYYYYYYYYYYYYY" }, "price": 100, "priceMonthly": 100, "priceYearly": 1000, "seats": 1, "escrowsPerMonth": -1, "includes": "base", "features": [ "1 agent seat", "Unlimited data", "Base AI included (~20 requests/session)" ] } ] } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Available plans | | | `401` | Authentication required | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Get current subscription status ```http GET /v1/billing/subscription ``` Returns the authenticated user's subscription state at each scope (personal, team, brokerage) plus which scope currently provides coverage. ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/billing/subscription" \ -H "Authorization: Bearer YOUR_JWT" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/billing/subscription", { headers: { "Authorization": "Bearer YOUR_JWT", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/billing/subscription", headers={"Authorization": "Bearer YOUR_JWT"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "personal": { "status": "active", "tier": "agent", "currentPeriodEnd": "2026-07-15T14:32:10.000Z", "canceledAt": "2026-07-15T14:32:10.000Z" }, "team": {}, "brokerage": {}, "effective_coverage": "brokerage" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Subscription status per scope | | | `401` | Authentication required | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Start checkout for a subscription ```http POST /v1/billing/checkout ``` Creates a Stripe Checkout session for the authenticated user at the requested scope. Valid scope and plan combinations are personal+agent, team+team, brokerage+team, and brokerage+broker. Eligibility depends on your role and how your brokerage pays for seats; ineligible requests return 400 with a specific reason. ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `scope` | enum | Yes | Subscription scope the seat applies to (personal, team, or brokerage) · One of: `personal`, `team`, `brokerage` | | `planKey` | enum | Yes | Subscription plan tier to subscribe to · One of: `agent`, `team`, `broker` | | `interval` | enum | No | Billing interval (defaults to monthly) · One of: `monthly`, `yearly` · Default: `"monthly"` | ### Example request ```bash title="cURL" curl -X POST "https://api.actuallycare.com/v1/billing/checkout" \ -H "Authorization: Bearer YOUR_JWT" \ -H "Content-Type: application/json" \ -d '{ "scope": "personal", "planKey": "agent" }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/billing/checkout", { method: "POST", headers: { "Authorization": "Bearer YOUR_JWT", "Content-Type": "application/json", }, body: JSON.stringify({ "scope": "personal", "planKey": "agent" }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.post( "https://api.actuallycare.com/v1/billing/checkout", headers={"Authorization": "Bearer YOUR_JWT"}, json={ "scope": "personal", "planKey": "agent" }, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "url": "example url", "sessionId": "example sessionId" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Checkout session created | | | `400` | Invalid scope/plan combination or eligibility check failed (the message explains why) | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `404` | Team or brokerage not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Open the billing portal ```http POST /v1/billing/portal ``` Creates a Stripe customer portal session where the user can manage payment methods, view invoices, and change or cancel their subscription. Requires an existing billing account (returns 400 if the user has never subscribed). ### Example request ```bash title="cURL" curl -X POST "https://api.actuallycare.com/v1/billing/portal" \ -H "Authorization: Bearer YOUR_JWT" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/billing/portal", { method: "POST", headers: { "Authorization": "Bearer YOUR_JWT", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.post( "https://api.actuallycare.com/v1/billing/portal", headers={"Authorization": "Bearer YOUR_JWT"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "url": "example url" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Portal session created | | | `400` | No billing account found — subscribe to a plan first | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | --- # Clients API > REST endpoints for clients — request and response reference with examples. The people you represent — create, list, update, and remove client records. Base URL: `https://api.actuallycare.com/v1` · Errors use the [standard envelope](/api/reference#error-responses) — see [Errors](/api/errors). ## List all clients ```http GET /v1/clients ``` Returns paginated list of client contacts. Default page size 25 (max 100). ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `client_type` | query | enum | No | One of: `buyer`, `seller`, `both` | | `status` | query | enum | No | One of: `active`, `inactive`, `closed` | | `page` | query | integer | No | Page number for pagination · Default: `1` · Min: 1 | | `limit` | query | integer | No | Number of items per page (default 25, max 100) · Default: `25` · Max: 100 · Min: 1 | ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/clients" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/clients", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/clients", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "clients": [ { "id": "a3f8c1d2-6b4e-4a9f-8d27-95c0e3b1f684", "first_name": "Michael", "last_name": "Torres", "email": "michael.torres@example.com", "phone": "(661) 555-0142", "client_type": "buyer", "status": "active", "source": "Zillow", "budget_min": 350000, "budget_max": 475000 } ], "meta": { "page": 1, "limit": 25, "total": 42, "totalPages": 2, "hasMore": true } } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Paginated list — records under data.clients, pagination under data.meta | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Create new client ```http POST /v1/clients ``` ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `first_name` | string | Yes | Client's first name | | `last_name` | string | Yes | Client's last name | | `email` | string | No | Client's email address | | `phone` | string | No | Client's phone number | | `client_type` | enum | Yes | Whether the client is a buyer, seller, or both · One of: `buyer`, `seller`, `both` | ### Example request ```bash title="cURL" curl -X POST "https://api.actuallycare.com/v1/clients" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "first_name": "Jordan", "last_name": "Lee", "client_type": "buyer" }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/clients", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ "first_name": "Jordan", "last_name": "Lee", "client_type": "buyer" }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.post( "https://api.actuallycare.com/v1/clients", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "first_name": "Jordan", "last_name": "Lee", "client_type": "buyer" }, ) data = resp.json() ``` ### Example response (201) ```json { "success": true, "data": { "id": "a3f8c1d2-6b4e-4a9f-8d27-95c0e3b1f684", "first_name": "Michael", "last_name": "Torres", "email": "michael.torres@example.com", "phone": "(661) 555-0142", "client_type": "buyer", "status": "active", "version": 1, "created_at": "2026-07-01T22:49:27.331Z", "updated_at": "2026-07-01T22:49:27.331Z" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `201` | Client created | | | `400` | Invalid request data | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Get client by ID ```http GET /v1/clients/{id} ``` ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Unique identifier (UUID) · Format: uuid | ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/clients/:id" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/clients/:id", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/clients/:id", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "id": "a3f8c1d2-6b4e-4a9f-8d27-95c0e3b1f684", "first_name": "Michael", "last_name": "Torres", "email": "michael.torres@example.com", "phone": "(661) 555-0142", "client_type": "buyer", "status": "active", "source": "Zillow", "budget_min": 350000, "budget_max": 475000, "pre_approved": true, "pre_approval_amount": 460000, "version": 2 } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Client found | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Update client ```http PUT /v1/clients/{id} ``` ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Unique identifier (UUID) · Format: uuid | ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `email` | string | No | Client's email address | | `phone` | string | No | Client's phone number | | `status` | string | No | Client status (active, inactive, closed) | | `version` | integer | No | Current record version for optimistic locking | ### Example request ```bash title="cURL" curl -X PUT "https://api.actuallycare.com/v1/clients/:id" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "email": "agent@example.com", "phone": "+1 661 555 0123", "status": "your-status", "version": 3 }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/clients/:id", { method: "PUT", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ "email": "agent@example.com", "phone": "+1 661 555 0123", "status": "your-status", "version": 3 }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.put( "https://api.actuallycare.com/v1/clients/:id", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "email": "agent@example.com", "phone": "+1 661 555 0123", "status": "your-status", "version": 3 }, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "user_id": "550e8400-e29b-41d4-a716-446655440000", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "(555) 123-4567", "client_type": "buyer", "status": "active", "source": "Zillow", "budget_min": 400000, "budget_max": 650000, "preferred_locations": [ "example preferred locations" ], "property_preferences": { "bedrooms_min": 3, "bathrooms_min": 3, "square_feet_min": 1800, "property_types": [ "example property types" ] }, "pre_approved": true, "pre_approval_amount": 450000, "notes": "example notes", "tags": [ "example tags" ], "version": 1, "created_at": "2026-07-15T14:32:10.000Z", "updated_at": "2026-07-15T14:32:10.000Z" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Client updated | | | `400` | Invalid request data | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Delete client ```http DELETE /v1/clients/{id} ``` ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Unique identifier (UUID) · Format: uuid | ### Example request ```bash title="cURL" curl -X DELETE "https://api.actuallycare.com/v1/clients/:id" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/clients/:id", { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.delete( "https://api.actuallycare.com/v1/clients/:id", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": {}, "timestamp": "2026-07-15T14:32:10.000Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Client deleted | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | --- # Contacts API > REST endpoints for contacts — request and response reference with examples. Your wider address book — vendors, lenders, other agents, and everyone else in your sphere. Base URL: `https://api.actuallycare.com/v1` · Errors use the [standard envelope](/api/reference#error-responses) — see [Errors](/api/errors). ## List contacts ```http GET /v1/contacts ``` Returns a paginated list of contacts visible to the authenticated user, with aggregate stats by status. Supports fuzzy search across name and email. ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `search` | query | string | No | Fuzzy search across full name, first name, last name, and email | | `type` | query | string | No | Filter by contact type | | `archived` | query | boolean | No | Show archived contacts instead of active ones · Default: `false` | | `page` | query | integer | No | Page number for pagination · Default: `1` · Min: 1 | | `limit` | query | integer | No | Number of items per page (default 25, max 100) · Default: `25` · Max: 100 · Min: 1 | ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/contacts" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/contacts", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/contacts", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "contacts": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "first_name": "Jordan", "last_name": "Lee", "full_name": "example full name", "email": "agent@example.com", "phone": "+1 661 555 0123", "contact_type": "buyer", "contact_status": "example contact status", "company": "example company", "license_number": "example license number", "street_address": "example street address", "city": "Bakersfield", "state": "CA", "zip_code": "93301", "notes": "example notes", "tags": [ "example tags" ], "is_archived": false, "archived_at": "2026-07-15T14:32:10.000Z", "created_at": "2026-07-15T14:32:10.000Z", "updated_at": "2026-07-15T14:32:10.000Z" } ], "stats": {}, "meta": { "total": 150, "page": 1, "limit": 20, "totalPages": 8, "hasMore": true } } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Paginated contact list with stats | | | `400` | Invalid request data | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Create a contact ```http POST /v1/contacts ``` Adds a contact to the authenticated user's database. First name and contact type are required. ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `first_name` | string | Yes | Contact's first name | | `last_name` | string | No | Contact's last name | | `contact_type` | enum | Yes | Role this contact plays in transactions (e.g. buyer, seller, lender, inspector) · One of: `buyer`, `seller`, `agent`, `lender`, `title_officer`, `inspector`, `appraiser`, `contractor`, `client`, `vendor`, `other` | | `email` | string | No | Contact's email address · Format: email | | `phone` | string | No | Contact's phone number | | `company` | string | No | Company or organization the contact belongs to | | `license_number` | string | No | Professional license number (e.g. for agents, lenders, inspectors) | | `street_address` | string | No | Street address | | `city` | string | No | City name | | `state` | string | No | Two-letter state code | | `zip_code` | string | No | ZIP code | | `notes` | string | No | Free-form notes about the contact | | `tags` | array of strings | No | Free-form labels for grouping and filtering contacts | ### Example request ```bash title="cURL" curl -X POST "https://api.actuallycare.com/v1/contacts" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "first_name": "Jordan", "contact_type": "buyer" }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/contacts", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ "first_name": "Jordan", "contact_type": "buyer" }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.post( "https://api.actuallycare.com/v1/contacts", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "first_name": "Jordan", "contact_type": "buyer" }, ) data = resp.json() ``` ### Example response (201) ```json { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "first_name": "Jordan", "last_name": "Lee", "full_name": "example full name", "email": "agent@example.com", "phone": "+1 661 555 0123", "contact_type": "buyer", "contact_status": "example contact status", "company": "example company", "license_number": "example license number", "street_address": "example street address", "city": "Bakersfield", "state": "CA", "zip_code": "93301", "notes": "example notes", "tags": [ "example tags" ], "is_archived": false, "archived_at": "2026-07-15T14:32:10.000Z", "created_at": "2026-07-15T14:32:10.000Z", "updated_at": "2026-07-15T14:32:10.000Z" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `201` | Contact created | | | `400` | Invalid request data | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Search contacts ```http GET /v1/contacts/search ``` Searches the authenticated user's contacts by name, email, or role. Returns a flat array (not paginated) capped at the requested limit. ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `name` | query | string | No | Case-insensitive substring match on full name | | `email` | query | string | No | Case-insensitive substring match on email | | `role` | query | string | No | Filter by assigned contact role name | | `limit` | query | integer | No | Default: `50` · Max: 100 · Min: 1 | ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/contacts/search" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/contacts/search", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/contacts/search", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "first_name": "Jordan", "last_name": "Lee", "full_name": "example full name", "email": "agent@example.com", "phone": "+1 661 555 0123", "contact_type": "buyer", "contact_status": "example contact status", "company": "example company", "license_number": "example license number", "street_address": "example street address", "city": "Bakersfield", "state": "CA", "zip_code": "93301", "notes": "example notes", "tags": [ "example tags" ], "is_archived": false, "archived_at": "2026-07-15T14:32:10.000Z", "created_at": "2026-07-15T14:32:10.000Z", "updated_at": "2026-07-15T14:32:10.000Z" } ], "count": 3 } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Matching contacts | | | `400` | Invalid request data | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Get a contact ```http GET /v1/contacts/{id} ``` ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Unique identifier (UUID) · Format: uuid | ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/contacts/:id" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/contacts/:id", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/contacts/:id", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "first_name": "Jordan", "last_name": "Lee", "full_name": "example full name", "email": "agent@example.com", "phone": "+1 661 555 0123", "contact_type": "buyer", "contact_status": "example contact status", "company": "example company", "license_number": "example license number", "street_address": "example street address", "city": "Bakersfield", "state": "CA", "zip_code": "93301", "notes": "example notes", "tags": [ "example tags" ], "is_archived": false, "archived_at": "2026-07-15T14:32:10.000Z", "created_at": "2026-07-15T14:32:10.000Z", "updated_at": "2026-07-15T14:32:10.000Z" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | The contact | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Update a contact ```http PUT /v1/contacts/{id} ``` Updates contact fields. All fields are optional; only the fields you send are changed. ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Unique identifier (UUID) · Format: uuid | ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `first_name` | string | No | Contact's first name | | `last_name` | string | No | Contact's last name | | `email` | string | No | Contact's email address · Format: email | | `phone` | string | No | Contact's phone number | | `contact_type` | string | No | Role this contact plays in transactions (e.g. buyer, seller, lender, inspector) | | `contact_status` | string | No | Workflow status of the contact (free-form, e.g. active, lead, client, past_client) | | `company` | string | No | Company or organization the contact belongs to | | `street_address` | string | No | Street address | | `city` | string | No | City name | | `state` | string | No | Two-letter state code | | `zip_code` | string | No | ZIP code | | `notes` | string | No | Free-form notes about the contact | | `tags` | array of strings | No | Free-form labels for grouping and filtering contacts | ### Example request ```bash title="cURL" curl -X PUT "https://api.actuallycare.com/v1/contacts/:id" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "first_name": "Jordan", "last_name": "Lee", "email": "agent@example.com", "phone": "+1 661 555 0123", "contact_type": "your-contact-type", "contact_status": "your-contact-status", "company": "your-company", "street_address": "your-street-address", "city": "Bakersfield", "state": "CA", "zip_code": "93301", "notes": "your-notes", "tags": [ "your-tags" ] }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/contacts/:id", { method: "PUT", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ "first_name": "Jordan", "last_name": "Lee", "email": "agent@example.com", "phone": "+1 661 555 0123", "contact_type": "your-contact-type", "contact_status": "your-contact-status", "company": "your-company", "street_address": "your-street-address", "city": "Bakersfield", "state": "CA", "zip_code": "93301", "notes": "your-notes", "tags": [ "your-tags" ] }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.put( "https://api.actuallycare.com/v1/contacts/:id", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "first_name": "Jordan", "last_name": "Lee", "email": "agent@example.com", "phone": "+1 661 555 0123", "contact_type": "your-contact-type", "contact_status": "your-contact-status", "company": "your-company", "street_address": "your-street-address", "city": "Bakersfield", "state": "CA", "zip_code": "93301", "notes": "your-notes", "tags": [ "your-tags" ] }, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "first_name": "Jordan", "last_name": "Lee", "full_name": "example full name", "email": "agent@example.com", "phone": "+1 661 555 0123", "contact_type": "buyer", "contact_status": "example contact status", "company": "example company", "license_number": "example license number", "street_address": "example street address", "city": "Bakersfield", "state": "CA", "zip_code": "93301", "notes": "example notes", "tags": [ "example tags" ], "is_archived": false, "archived_at": "2026-07-15T14:32:10.000Z", "created_at": "2026-07-15T14:32:10.000Z", "updated_at": "2026-07-15T14:32:10.000Z" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Contact updated | | | `400` | Invalid request data | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Delete a contact ```http DELETE /v1/contacts/{id} ``` Soft-deletes a contact. Deleted contacts disappear from all lists and searches and cannot be restored; to hide a contact reversibly, use archive instead. ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Unique identifier (UUID) · Format: uuid | ### Example request ```bash title="cURL" curl -X DELETE "https://api.actuallycare.com/v1/contacts/:id" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/contacts/:id", { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.delete( "https://api.actuallycare.com/v1/contacts/:id", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "first_name": "Jordan", "last_name": "Lee", "full_name": "example full name", "email": "agent@example.com", "phone": "+1 661 555 0123", "contact_type": "buyer", "contact_status": "example contact status", "company": "example company", "license_number": "example license number", "street_address": "example street address", "city": "Bakersfield", "state": "CA", "zip_code": "93301", "notes": "example notes", "tags": [ "example tags" ], "is_archived": false, "archived_at": "2026-07-15T14:32:10.000Z", "created_at": "2026-07-15T14:32:10.000Z", "updated_at": "2026-07-15T14:32:10.000Z" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Contact deleted (response echoes the deleted contact record) | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `403` | Caller lacks permission to delete this contact | Check the ID first: an ID that doesn't exist or isn't yours also returns 403. Otherwise a role or key-scope problem; retrying won't help. See [Errors](/api/errors#http-status-codes) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Archive a contact ```http PATCH /v1/contacts/{id}/archive ``` Hides a contact from default lists. Archived contacts can be listed with `archived=true` and restored at any time. ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Unique identifier (UUID) · Format: uuid | ### Example request ```bash title="cURL" curl -X PATCH "https://api.actuallycare.com/v1/contacts/:id/archive" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/contacts/:id/archive", { method: "PATCH", headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.patch( "https://api.actuallycare.com/v1/contacts/:id/archive", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "first_name": "Jordan", "last_name": "Lee", "full_name": "example full name", "email": "agent@example.com", "phone": "+1 661 555 0123", "contact_type": "buyer", "contact_status": "example contact status", "company": "example company", "license_number": "example license number", "street_address": "example street address", "city": "Bakersfield", "state": "CA", "zip_code": "93301", "notes": "example notes", "tags": [ "example tags" ], "is_archived": false, "archived_at": "2026-07-15T14:32:10.000Z", "created_at": "2026-07-15T14:32:10.000Z", "updated_at": "2026-07-15T14:32:10.000Z" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Contact archived (response is the updated contact record) | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Restore an archived contact ```http PATCH /v1/contacts/{id}/restore ``` Returns an archived contact to the active list. ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Unique identifier (UUID) · Format: uuid | ### Example request ```bash title="cURL" curl -X PATCH "https://api.actuallycare.com/v1/contacts/:id/restore" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/contacts/:id/restore", { method: "PATCH", headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.patch( "https://api.actuallycare.com/v1/contacts/:id/restore", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "first_name": "Jordan", "last_name": "Lee", "full_name": "example full name", "email": "agent@example.com", "phone": "+1 661 555 0123", "contact_type": "buyer", "contact_status": "example contact status", "company": "example company", "license_number": "example license number", "street_address": "example street address", "city": "Bakersfield", "state": "CA", "zip_code": "93301", "notes": "example notes", "tags": [ "example tags" ], "is_archived": false, "archived_at": "2026-07-15T14:32:10.000Z", "created_at": "2026-07-15T14:32:10.000Z", "updated_at": "2026-07-15T14:32:10.000Z" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Contact restored (response is the updated contact record) | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Extract contact fields from a business-card photo ```http POST /v1/contacts/scan-card ``` Sends the image to Claude and returns structured fields for the agent to review. Does NOT create a contact — the caller decides what to save, so an OCR misread never lands in the CRM unreviewed. Gated by the brokerage AI toggle + agent disclosure acceptance (requireAiEnabled). ### Example request ```bash title="cURL" curl -X POST "https://api.actuallycare.com/v1/contacts/scan-card" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/contacts/scan-card", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.post( "https://api.actuallycare.com/v1/contacts/scan-card", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "isBusinessCard": true, "firstName": "example firstName", "lastName": "example lastName", "company": "example company", "jobTitle": "example jobTitle", "email": "agent@example.com", "phone": "+1 661 555 0123", "mobile": "example mobile", "website": "example website", "addressLine": "example addressLine", "city": "Bakersfield", "state": "CA", "postalCode": "example postalCode", "licenseNumber": "example licenseNumber", "confidence": "high", "model": "example model", "usage": {} } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Fields extracted from the card, for the agent to review | | | `400` | Upload rejected before the image was read — over the 5MB limit, or a MIME type outside the allowlist. Returned directly by the route's multer error handler, which is why this is a 400 and the content-level failures below are 422. | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `403` | AI is disabled for this brokerage, or the agent has not accepted the AI disclosure | Check the ID first: an ID that doesn't exist or isn't yours also returns 403. Otherwise a role or key-scope problem; retrying won't help. See [Errors](/api/errors#http-status-codes) | | `422` | Invalid request data | Fix the value `error.message` names. Don't retry unchanged | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | --- # Escrows API > REST endpoints for escrows — request and response reference with examples. Transactions from contract to close — create, list, update, and manage escrows. Base URL: `https://api.actuallycare.com/v1` · Errors use the [standard envelope](/api/reference#error-responses) — see [Errors](/api/errors). ## List escrows ```http GET /v1/escrows ``` Returns a paginated list of escrows visible to the authenticated user, with aggregate stats. Supports filtering by status, price range, closing-date range, and free-text search across property address and display ID. Note the effective default page size for this endpoint is 20 (a controller-level override of the platform-wide default of 25). ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `status` | query | enum | No | Filter by escrow status (case-insensitive) · One of: `active`, `pending`, `closed`, `cancelled` | | `search` | query | string | No | Free-text search across property address and display ID | | `minPrice` | query | number | No | Minimum purchase price · Min: 0 | | `maxPrice` | query | number | No | Maximum purchase price · Min: 0 | | `closingDateStart` | query | string | No | Earliest closing date (ISO 8601) · Format: date | | `closingDateEnd` | query | string | No | Latest closing date (ISO 8601) · Format: date | | `archived` | query | boolean | No | Include archived escrows instead of active ones · Default: `false` | | `sort` | query | string | No | Sort column · Default: `"created_at"` | | `order` | query | enum | No | Sort direction · One of: `asc`, `desc` · Default: `"desc"` | | `page` | query | integer | No | Page number for pagination · Default: `1` · Min: 1 | | `limit` | query | integer | No | Number of items per page (default 25, max 100) · Default: `25` · Max: 100 · Min: 1 | ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/escrows" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/escrows", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/escrows", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "escrows": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "user_id": "550e8400-e29b-41d4-a716-446655440000", "property_address": "123 Main St, Tehachapi, CA 93561", "city": "Tehachapi", "state": "CA", "zip_code": "93561", "purchase_price": 500000, "escrow_status": "active", "acceptance_date": "2025-01-15", "closing_date": "2025-03-01", "buyers": [ { "name": "John Doe", "email": "john@example.com", "phone": "(555) 123-4567" } ], "sellers": [ { "name": "John Doe", "email": "john@example.com", "phone": "(555) 123-4567" } ], "listing_agent": { "name": "Alex Rivera", "email": "agent@example.com", "phone": "+1 661 555 0123", "license": "DRE #02209852", "brokerage": "Associated Real Estate" }, "selling_agent": { "name": "Alex Rivera", "email": "agent@example.com", "phone": "+1 661 555 0123", "license": "DRE #02209852", "brokerage": "Associated Real Estate" }, "escrow_company": "First American Title", "escrow_officer": "Jane Smith", "property_type": "single_family", "bedrooms": 3, "bathrooms": 2.5, "square_feet": 2400, "lot_size": 0.25, "year_built": 2015, "contingencies": [ { "type": "inspection", "due_date": "2026-07-15", "status": "pending" } ], "earnest_money": 10000, "commission_rate": 3, "notes": "example notes", "version": 1, "created_at": "2026-07-15T14:32:10.000Z", "updated_at": "2026-07-15T14:32:10.000Z", "last_modified_by": "550e8400-e29b-41d4-a716-446655440000" } ], "stats": {}, "meta": { "page": 1, "limit": 20, "total": 150, "totalPages": 8, "hasMore": true } } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Paginated escrow list with aggregate stats | | | `400` | Invalid request data | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Create an escrow ```http POST /v1/escrows ``` Opens a new escrow (transaction). Only the property address is required; financial, party, and vendor details can be added later. ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `property_address` | string | Yes | Street address of the property in escrow | | `purchase_price` | number | No | Purchase price in USD | | `escrow_status` | enum | No | Initial escrow status (defaults to active) · One of: `active`, `pending`, `closed`, `cancelled` · Default: `"active"` | | `acceptance_date` | string | No | Offer acceptance date (ISO 8601) · Format: date | | `closing_date` | string | No | Expected closing date (ISO 8601) · Format: date | | `city` | string | No | City name | | `state` | string | No | State abbreviation (e.g. CA) | | `zip_code` | string | No | ZIP code | | `earnest_money_deposit` | number | No | Earnest money deposit amount in USD | | `commission_percentage` | number | No | Total commission rate as a percentage of purchase price | | `my_commission` | number | No | The authenticated agent's commission amount in USD | | `representation_type` | string | No | Which side the agent represents (e.g. buyer, seller, dual) | | `escrow_company` | string | No | Escrow company handling the transaction | | `title_company` | string | No | Title company name | | `buyers` | array of objects | No | Buyer parties to attach at creation | | `buyers[].name` | string | No | Buyer's full name | | `buyers[].email` | string | No | Buyer's email address | | `sellers` | array of objects | No | Seller parties to attach at creation | | `sellers[].name` | string | No | Seller's full name | | `sellers[].email` | string | No | Seller's email address | ### Example request ```bash title="cURL" curl -X POST "https://api.actuallycare.com/v1/escrows" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "property_address": "123 Main St, Bakersfield, CA 93301" }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/escrows", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ "property_address": "123 Main St, Bakersfield, CA 93301" }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.post( "https://api.actuallycare.com/v1/escrows", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "property_address": "123 Main St, Bakersfield, CA 93301" }, ) data = resp.json() ``` ### Example response (201) ```json { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "displayId": "ESC-2026-0001" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `201` | Escrow created | | | `400` | Invalid request data | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Get an escrow ```http GET /v1/escrows/{id} ``` Returns a single escrow. The ID may be a UUID, a display ID (ESC-2026-0001), or the user-scoped numeric sequence. ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Escrow UUID, display ID, or numeric sequence | ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/escrows/:id" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/escrows/:id", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/escrows/:id", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "user_id": "550e8400-e29b-41d4-a716-446655440000", "property_address": "123 Main St, Tehachapi, CA 93561", "city": "Tehachapi", "state": "CA", "zip_code": "93561", "purchase_price": 500000, "escrow_status": "active", "acceptance_date": "2025-01-15", "closing_date": "2025-03-01", "buyers": [ { "name": "John Doe", "email": "john@example.com", "phone": "(555) 123-4567" } ], "sellers": [ { "name": "John Doe", "email": "john@example.com", "phone": "(555) 123-4567" } ], "listing_agent": { "name": "Alex Rivera", "email": "agent@example.com", "phone": "+1 661 555 0123", "license": "DRE #02209852", "brokerage": "Associated Real Estate" }, "selling_agent": { "name": "Alex Rivera", "email": "agent@example.com", "phone": "+1 661 555 0123", "license": "DRE #02209852", "brokerage": "Associated Real Estate" }, "escrow_company": "First American Title", "escrow_officer": "Jane Smith", "property_type": "single_family", "bedrooms": 3, "bathrooms": 2.5, "square_feet": 2400, "lot_size": 0.25, "year_built": 2015, "contingencies": [ { "type": "inspection", "due_date": "2026-07-15", "status": "pending" } ], "earnest_money": 10000, "commission_rate": 3, "notes": "example notes", "version": 1, "created_at": "2026-07-15T14:32:10.000Z", "updated_at": "2026-07-15T14:32:10.000Z", "last_modified_by": "550e8400-e29b-41d4-a716-446655440000" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | The escrow | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Update an escrow ```http PUT /v1/escrows/{id} ``` Updates escrow fields. Pass the current `version` to enable optimistic-locking; a stale version returns 409. ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | | ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `purchase_price` | number | No | Purchase price in USD | | `closing_date` | string | No | Expected closing date (ISO 8601) · Format: date | | `escrow_status` | enum | No | Updated escrow status · One of: `active`, `pending`, `closed`, `cancelled` | | `version` | integer | No | Current record version for optimistic locking | ### Example request ```bash title="cURL" curl -X PUT "https://api.actuallycare.com/v1/escrows/:id" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "purchase_price": 450000, "closing_date": "2026-07-15", "escrow_status": "active", "version": 3 }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/escrows/:id", { method: "PUT", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ "purchase_price": 450000, "closing_date": "2026-07-15", "escrow_status": "active", "version": 3 }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.put( "https://api.actuallycare.com/v1/escrows/:id", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "purchase_price": 450000, "closing_date": "2026-07-15", "escrow_status": "active", "version": 3 }, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "user_id": "550e8400-e29b-41d4-a716-446655440000", "property_address": "123 Main St, Tehachapi, CA 93561", "city": "Tehachapi", "state": "CA", "zip_code": "93561", "purchase_price": 500000, "escrow_status": "active", "acceptance_date": "2025-01-15", "closing_date": "2025-03-01", "buyers": [ { "name": "John Doe", "email": "john@example.com", "phone": "(555) 123-4567" } ], "sellers": [ { "name": "John Doe", "email": "john@example.com", "phone": "(555) 123-4567" } ], "listing_agent": { "name": "Alex Rivera", "email": "agent@example.com", "phone": "+1 661 555 0123", "license": "DRE #02209852", "brokerage": "Associated Real Estate" }, "selling_agent": { "name": "Alex Rivera", "email": "agent@example.com", "phone": "+1 661 555 0123", "license": "DRE #02209852", "brokerage": "Associated Real Estate" }, "escrow_company": "First American Title", "escrow_officer": "Jane Smith", "property_type": "single_family", "bedrooms": 3, "bathrooms": 2.5, "square_feet": 2400, "lot_size": 0.25, "year_built": 2015, "contingencies": [ { "type": "inspection", "due_date": "2026-07-15", "status": "pending" } ], "earnest_money": 10000, "commission_rate": 3, "notes": "example notes", "version": 1, "created_at": "2026-07-15T14:32:10.000Z", "updated_at": "2026-07-15T14:32:10.000Z", "last_modified_by": "550e8400-e29b-41d4-a716-446655440000" }, "message": "Escrow updated successfully" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Escrow updated | | | `400` | Invalid request data | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `409` | Version conflict (record changed since you read it) or business-rule violation | Re-fetch the current state, then decide deliberately; don't blind-retry | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Delete an escrow ```http DELETE /v1/escrows/{id} ``` Permanently deletes an escrow. The escrow must be archived first (PATCH /escrows/{id}/archive); deleting a non-archived escrow returns 400. ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | | ### Example request ```bash title="cURL" curl -X DELETE "https://api.actuallycare.com/v1/escrows/:id" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/escrows/:id", { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.delete( "https://api.actuallycare.com/v1/escrows/:id", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "message": "Escrow permanently deleted", "data": { "displayId": "ESC-2026-0847" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Escrow deleted | | | `400` | Escrow is not archived — archive it before deleting | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Archive an escrow ```http PATCH /v1/escrows/{id}/archive ``` Moves an escrow to the archive. Archived escrows are hidden from default lists, can be restored at any time, and are the only escrows eligible for permanent deletion. ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | | ### Example request ```bash title="cURL" curl -X PATCH "https://api.actuallycare.com/v1/escrows/:id/archive" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/escrows/:id/archive", { method: "PATCH", headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.patch( "https://api.actuallycare.com/v1/escrows/:id/archive", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "message": "Escrow archived successfully", "data": { "displayId": "ESC-2026-0847" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Escrow archived | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Restore an archived escrow ```http PATCH /v1/escrows/{id}/restore ``` Returns an archived escrow to the active list. ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | | ### Example request ```bash title="cURL" curl -X PATCH "https://api.actuallycare.com/v1/escrows/:id/restore" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/escrows/:id/restore", { method: "PATCH", headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.patch( "https://api.actuallycare.com/v1/escrows/:id/restore", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "message": "Escrow restored successfully", "data": { "displayId": "ESC-2026-0847" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Escrow restored | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Get an escrow's timeline ```http GET /v1/escrows/{id}/timeline ``` Returns the escrow's milestone timeline (deposits, contingencies, closing) with target dates, completion state, and a computed status for each milestone. ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | | ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/escrows/:id/timeline" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/escrows/:id/timeline", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/escrows/:id/timeline", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": [ { "key": "example key", "label": "example label", "date": "2026-07-15T14:32:10.000Z", "completed": true, "completedDate": "2026-07-15T14:32:10.000Z", "status": "active", "sortOrder": 1 } ] } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Timeline milestones in display order | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | --- # Leads API > REST endpoints for leads — request and response reference with examples. Lead capture and qualification, including converting a lead into a client. Base URL: `https://api.actuallycare.com/v1` · Errors use the [standard envelope](/api/reference#error-responses) — see [Errors](/api/errors). ## List all leads ```http GET /v1/leads ``` Returns paginated list of prospective client leads. Default page size 25 (max 100). ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `status` | query | enum | No | One of: `new`, `contacted`, `qualified`, `unqualified`, `converted`, `lost` | | `interest_level` | query | enum | No | One of: `hot`, `warm`, `cold` | | `page` | query | integer | No | Page number for pagination · Default: `1` · Min: 1 | | `limit` | query | integer | No | Number of items per page (default 25, max 100) · Default: `25` · Max: 100 · Min: 1 | ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/leads" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/leads", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/leads", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "leads": [ { "id": "f2b8d4a6-3c5e-4f7a-9b1d-8e0c6a4f2d9b", "name": "Rachel Kim", "email": "rachel.kim@outlook.com", "phone": "(661) 555-0198", "source": "Website Form", "status": "new", "lead_type": "buyer", "interest_level": "warm", "budget": 380000, "timeline": "3-6 months" } ], "meta": { "page": 1, "limit": 25, "total": 34, "totalPages": 2, "hasMore": true } }, "timestamp": "2026-07-01T22:52:30.664Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Paginated list — records under data.leads, pagination under data.meta (the envelope also carries data.stats and data.cursors) | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Create new lead ```http POST /v1/leads ``` ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | Yes | Lead's full name | | `email` | string | No | Lead's email address | | `phone` | string | No | Lead's phone number | | `source` | string | No | How the lead was acquired (e.g. Website Form, Zillow) | | `lead_type` | enum | No | Whether the lead is a buyer, seller, or both · One of: `buyer`, `seller`, `both` | ### Example request ```bash title="cURL" curl -X POST "https://api.actuallycare.com/v1/leads" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Jordan Lee" }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/leads", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ "name": "Jordan Lee" }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.post( "https://api.actuallycare.com/v1/leads", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "name": "Jordan Lee" }, ) data = resp.json() ``` ### Example response (201) ```json { "success": true, "data": { "id": "f2b8d4a6-3c5e-4f7a-9b1d-8e0c6a4f2d9b", "name": "Rachel Kim", "email": "rachel.kim@outlook.com", "phone": "(661) 555-0198", "source": "Website Form", "status": "new", "lead_type": "buyer", "interest_level": "warm", "version": 1, "created_at": "2026-07-01T22:53:05.882Z" }, "message": "Lead created successfully", "timestamp": "2026-07-01T22:53:05.890Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `201` | Lead created | | | `400` | Invalid request data | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Get lead by ID ```http GET /v1/leads/{id} ``` ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Unique identifier (UUID) · Format: uuid | ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/leads/:id" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/leads/:id", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/leads/:id", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "id": "f2b8d4a6-3c5e-4f7a-9b1d-8e0c6a4f2d9b", "name": "Rachel Kim", "email": "rachel.kim@outlook.com", "phone": "(661) 555-0198", "source": "Website Form", "status": "contacted", "lead_type": "buyer", "interest_level": "warm", "budget": 380000, "timeline": "3-6 months", "version": 2 }, "timestamp": "2026-07-01T22:53:41.126Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Lead found | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Update lead ```http PUT /v1/leads/{id} ``` ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Unique identifier (UUID) · Format: uuid | ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `status` | string | No | Lead status (new, contacted, qualified, unqualified, converted, lost) | | `interest_level` | string | No | Lead's level of interest (hot, warm, cold) | | `version` | integer | No | Current record version for optimistic locking | ### Example request ```bash title="cURL" curl -X PUT "https://api.actuallycare.com/v1/leads/:id" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "status": "your-status", "interest_level": "your-interest-level", "version": 3 }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/leads/:id", { method: "PUT", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ "status": "your-status", "interest_level": "your-interest-level", "version": 3 }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.put( "https://api.actuallycare.com/v1/leads/:id", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "status": "your-status", "interest_level": "your-interest-level", "version": 3 }, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "user_id": "550e8400-e29b-41d4-a716-446655440000", "name": "Jane Smith", "email": "jane.smith@example.com", "phone": "(555) 987-6543", "source": "Website Form", "status": "new", "lead_type": "buyer", "interest_level": "warm", "budget": 450000, "timeline": "3-6 months", "message": "example message", "notes": "example notes", "last_contact_date": "2026-07-15T14:32:10.000Z", "next_follow_up": "2026-07-15T14:32:10.000Z", "converted_to_client_id": "550e8400-e29b-41d4-a716-446655440000", "version": 1, "created_at": "2026-07-15T14:32:10.000Z", "updated_at": "2026-07-15T14:32:10.000Z" }, "timestamp": "2026-07-15T14:32:10.000Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Lead updated | | | `400` | Invalid request data | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Delete lead ```http DELETE /v1/leads/{id} ``` ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Unique identifier (UUID) · Format: uuid | ### Example request ```bash title="cURL" curl -X DELETE "https://api.actuallycare.com/v1/leads/:id" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/leads/:id", { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.delete( "https://api.actuallycare.com/v1/leads/:id", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": {}, "timestamp": "2026-07-15T14:32:10.000Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Lead deleted | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Convert lead to client ```http POST /v1/leads/{id}/convert ``` Converts a qualified lead into a full client record (transactional). Creates or reuses a contact, creates the client, and marks the lead converted. ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Unique identifier (UUID) · Format: uuid | ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `clientType` | enum | No | Client type for the new client record · One of: `buyer`, `seller`, `both` · Default: `"buyer"` | ### Example request ```bash title="cURL" curl -X POST "https://api.actuallycare.com/v1/leads/:id/convert" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "clientType": "buyer" }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/leads/:id/convert", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ "clientType": "buyer" }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.post( "https://api.actuallycare.com/v1/leads/:id/convert", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "clientType": "buyer" }, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "client": { "id": "c9d2e4f6-1a3b-4c5d-8e7f-0b2d4f6a8c1e", "contact_id": "7e5a3c1b-9d8f-4e2a-b6c4-1f0e8d7a5b3c", "client_type": "buyer", "status": "active", "price_range_min": 342000, "price_range_max": 418000 }, "lead": { "id": "f2b8d4a6-3c5e-4f7a-9b1d-8e0c6a4f2d9b", "lead_status": "converted", "client_id": "c9d2e4f6-1a3b-4c5d-8e7f-0b2d4f6a8c1e" }, "primaryContactId": "7e5a3c1b-9d8f-4e2a-b6c4-1f0e8d7a5b3c", "additionalContactsCount": 0 }, "message": "Lead successfully converted to client", "timestamp": "2026-07-01T22:54:29.773Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Lead converted successfully | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | --- # Listings API > REST endpoints for listings — request and response reference with examples. Property inventory — create, list, update, and remove listings. Base URL: `https://api.actuallycare.com/v1` · Errors use the [standard envelope](/api/reference#error-responses) — see [Errors](/api/errors). ## List all property listings ```http GET /v1/listings ``` Returns paginated list of property listings with optional filtering. Default page size 25 (max 100). ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `status` | query | enum | No | One of: `active`, `pending`, `sold`, `withdrawn`, `expired` | | `minPrice` | query | number | No | | | `maxPrice` | query | number | No | | | `page` | query | integer | No | Page number for pagination · Default: `1` · Min: 1 | | `limit` | query | integer | No | Number of items per page (default 25, max 100) · Default: `25` · Max: 100 · Min: 1 | ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/listings" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/listings", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/listings", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "listings": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "mls_number": "ML81992437", "address": "456 Oak Ave, Tehachapi, CA 93561", "city": "Tehachapi", "state": "CA", "zip_code": "93561", "list_price": 425000, "status": "active", "property_type": "single_family", "bedrooms": 4, "bathrooms": 3, "square_feet": 2800 } ], "meta": { "page": 1, "limit": 25, "total": 87, "totalPages": 4, "hasMore": true } }, "timestamp": "2026-07-01T22:45:03.120Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Paginated list — records under data.listings, pagination under data.meta (the envelope also carries data.stats aggregates) | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Create new listing ```http POST /v1/listings ``` ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `address` | string | Yes | Street address of the property | | `list_price` | number | Yes | Listing price in USD | | `property_type` | string | No | Property type (e.g. single_family, condo, townhouse, multi_family, land, commercial) | | `bedrooms` | integer | No | Number of bedrooms | | `bathrooms` | number | No | Number of bathrooms | ### Example request ```bash title="cURL" curl -X POST "https://api.actuallycare.com/v1/listings" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "address": "123 Main St, Bakersfield, CA 93301", "list_price": 450000 }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/listings", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ "address": "123 Main St, Bakersfield, CA 93301", "list_price": 450000 }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.post( "https://api.actuallycare.com/v1/listings", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "address": "123 Main St, Bakersfield, CA 93301", "list_price": 450000 }, ) data = resp.json() ``` ### Example response (201) ```json { "success": true, "data": { "id": "8c5e2a9f-4d7b-4e3a-b1c8-6f0d9e2a5c74", "address": "1847 Cerro Vista Dr, Bakersfield, CA 93306", "list_price": 389000, "status": "active", "property_type": "single_family", "bedrooms": 3, "bathrooms": 2, "version": 1, "created_at": "2026-07-01T22:46:18.402Z", "updated_at": "2026-07-01T22:46:18.402Z" }, "timestamp": "2026-07-01T22:46:18.410Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `201` | Listing created | | | `400` | Invalid request data | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Get listing by ID ```http GET /v1/listings/{id} ``` ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Unique identifier (UUID) · Format: uuid | ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/listings/:id" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/listings/:id", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/listings/:id", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "mls_number": "ML81992437", "address": "456 Oak Ave, Tehachapi, CA 93561", "city": "Tehachapi", "state": "CA", "zip_code": "93561", "list_price": 425000, "status": "active", "property_type": "single_family", "bedrooms": 4, "bathrooms": 3, "square_feet": 2800, "year_built": 2010, "version": 3 }, "timestamp": "2026-07-01T22:47:00.115Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Listing found | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Update listing ```http PUT /v1/listings/{id} ``` ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Unique identifier (UUID) · Format: uuid | ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `list_price` | number | No | Listing price in USD | | `status` | string | No | Listing status (active, pending, sold, withdrawn, expired) | | `version` | integer | No | Current record version for optimistic locking | ### Example request ```bash title="cURL" curl -X PUT "https://api.actuallycare.com/v1/listings/:id" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "list_price": 450000, "status": "your-status", "version": 3 }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/listings/:id", { method: "PUT", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ "list_price": 450000, "status": "your-status", "version": 3 }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.put( "https://api.actuallycare.com/v1/listings/:id", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "list_price": 450000, "status": "your-status", "version": 3 }, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "user_id": "550e8400-e29b-41d4-a716-446655440000", "mls_number": "ML123456", "address": "456 Oak Ave, Tehachapi, CA 93561", "city": "Tehachapi", "state": "CA", "zip_code": "93561", "list_price": 425000, "status": "active", "property_type": "single_family", "bedrooms": 4, "bathrooms": 3, "square_feet": 2800, "lot_size": 0.5, "year_built": 2010, "description": "example description", "listing_date": "2026-07-15", "expiration_date": "2026-07-15", "photos": [ "example photos" ], "virtual_tour_url": "example virtual tour url", "showing_instructions": "example showing instructions", "days_on_market": 1, "price_per_sqft": 1800, "version": 1, "created_at": "2026-07-15T14:32:10.000Z", "updated_at": "2026-07-15T14:32:10.000Z" }, "timestamp": "2026-07-15T14:32:10.000Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Listing updated | | | `400` | Invalid request data | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Delete listing ```http DELETE /v1/listings/{id} ``` Permanently deletes a listing (hard delete — only allowed after the listing has been archived) ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Unique identifier (UUID) · Format: uuid | ### Example request ```bash title="cURL" curl -X DELETE "https://api.actuallycare.com/v1/listings/:id" \ -H "X-API-Key: YOUR_API_KEY" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/listings/:id", { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.delete( "https://api.actuallycare.com/v1/listings/:id", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": {}, "timestamp": "2026-07-15T14:32:10.000Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Listing deleted | | | `401` | Authentication required | Check the `X-API-Key` header (or bearer token). See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | --- # Webhooks API > REST endpoints for webhooks — request and response reference with examples. Manage webhook subscriptions and browse the self-documenting event catalog. Concepts and signature verification live in [Webhooks](/concepts/webhooks); the hands-on walkthrough is [Set up webhooks](/guides/webhook-setup). Base URL: `https://api.actuallycare.com/v1` · Errors use the [standard envelope](/api/reference#error-responses) — see [Errors](/api/errors). ## List webhook subscriptions ```http GET /v1/webhooks ``` Returns the webhook subscriptions in your brokerage. Requires the broker or system admin role. Secrets are never returned. ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `page` | query | integer | No | Page number for pagination · Default: `1` · Min: 1 | | `limit` | query | integer | No | Number of items per page (default 25, max 100) · Default: `25` · Max: 100 · Min: 1 | ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/webhooks" \ -H "Authorization: Bearer YOUR_JWT" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/webhooks", { headers: { "Authorization": "Bearer YOUR_JWT", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/webhooks", headers={"Authorization": "Bearer YOUR_JWT"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": [ { "id": "wh_abc123def456", "url": "example url", "events": [ "escrow.created" ], "has_secret": true, "active": true, "brokerage_id": "550e8400-e29b-41d4-a716-446655440000", "team_id": "550e8400-e29b-41d4-a716-446655440000", "last_triggered": "2026-07-15T14:32:10.000Z", "created_at": "2026-07-15T14:32:10.000Z" } ] } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Webhook subscriptions | | | `401` | Authentication required | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `403` | Requires broker or system admin role | Check the ID first: an ID that doesn't exist or isn't yours also returns 403. Otherwise a role or key-scope problem; retrying won't help. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Create a webhook subscription ```http POST /v1/webhooks ``` Registers an endpoint to receive event notifications. Each delivery is an HTTPS POST with the JSON payload, an `X-Webhook-Event` header naming the event, an `X-Webhook-Timestamp` header, and an `X-Webhook-Signature` header containing `sha256=` followed by the hex-encoded HMAC-SHA256 of the payload computed with your secret. Each event gets 4 delivery attempts total: the initial delivery plus retries after 1, 5, and 15 minutes. Only HTTP 5xx, 408, and 429 responses (and network failures) are retried — any other 4xx response is logged and NOT retried. ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `url` | string | Yes | Endpoint to deliver events to · Format: uri | | `events` | array of strings | Yes | Event names to subscribe to (see GET /webhooks/events for the catalog) | | `secret` | string | Yes | Shared secret used to sign every delivery | ### Example request ```bash title="cURL" curl -X POST "https://api.actuallycare.com/v1/webhooks" \ -H "Authorization: Bearer YOUR_JWT" \ -H "Content-Type: application/json" \ -d '{ "url": "your-url", "events": [ "escrow.created" ], "secret": "your-secret" }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/webhooks", { method: "POST", headers: { "Authorization": "Bearer YOUR_JWT", "Content-Type": "application/json", }, body: JSON.stringify({ "url": "your-url", "events": [ "escrow.created" ], "secret": "your-secret" }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.post( "https://api.actuallycare.com/v1/webhooks", headers={"Authorization": "Bearer YOUR_JWT"}, json={ "url": "your-url", "events": [ "escrow.created" ], "secret": "your-secret" }, ) data = resp.json() ``` ### Example response (201) ```json { "success": true, "data": { "id": "wh_abc123def456", "url": "example url", "events": [ "escrow.created" ], "has_secret": true, "active": true, "brokerage_id": "550e8400-e29b-41d4-a716-446655440000", "team_id": "550e8400-e29b-41d4-a716-446655440000", "last_triggered": "2026-07-15T14:32:10.000Z", "created_at": "2026-07-15T14:32:10.000Z" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `201` | Webhook created | | | `400` | Invalid request data | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `403` | Requires broker or system admin role | Check the ID first: an ID that doesn't exist or isn't yours also returns 403. Otherwise a role or key-scope problem; retrying won't help. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## List available webhook events ```http GET /v1/webhooks/events ``` Returns the catalog of events you can subscribe to, including each event's category, description, and the field names included in its payload. ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `category` | query | string | No | Filter to a single category (e.g. escrow, lead, email) | ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/webhooks/events" \ -H "Authorization: Bearer YOUR_JWT" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/webhooks/events", { headers: { "Authorization": "Bearer YOUR_JWT", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/webhooks/events", headers={"Authorization": "Bearer YOUR_JWT"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": [ { "event": "escrow.created", "category": "escrow", "description": "example description", "payload": [ "example payload" ] } ], "meta": { "total": 150, "categories": [ "escrow" ] } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Event catalog | | | `401` | Authentication required | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `403` | Requires broker or system admin role | Check the ID first: an ID that doesn't exist or isn't yours also returns 403. Otherwise a role or key-scope problem; retrying won't help. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## List webhook event categories ```http GET /v1/webhooks/events/categories ``` Returns every event category with the number of events it contains. ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/webhooks/events/categories" \ -H "Authorization: Bearer YOUR_JWT" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/webhooks/events/categories", { headers: { "Authorization": "Bearer YOUR_JWT", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/webhooks/events/categories", headers={"Authorization": "Bearer YOUR_JWT"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": [ { "category": "escrow", "event_count": 3 } ] } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Categories with event counts | | | `401` | Authentication required | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `403` | Requires broker or system admin role | Check the ID first: an ID that doesn't exist or isn't yours also returns 403. Otherwise a role or key-scope problem; retrying won't help. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Update a webhook subscription ```http PUT /v1/webhooks/{id} ``` Updates a subscription's URL, events, secret, or active flag. Only the fields you send are changed. ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Webhook ID | ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `url` | string | No | Endpoint that receives event deliveries · Format: uri | | `events` | array of strings | No | Subscribed event names (entity.action format) | | `active` | boolean | No | Whether the subscription is enabled to receive deliveries | | `secret` | string | No | Shared secret used to sign deliveries (minimum 10 characters) | ### Example request ```bash title="cURL" curl -X PUT "https://api.actuallycare.com/v1/webhooks/:id" \ -H "Authorization: Bearer YOUR_JWT" \ -H "Content-Type: application/json" \ -d '{ "url": "your-url", "events": [ "your-events" ], "active": true, "secret": "your-secret" }' ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/webhooks/:id", { method: "PUT", headers: { "Authorization": "Bearer YOUR_JWT", "Content-Type": "application/json", }, body: JSON.stringify({ "url": "your-url", "events": [ "your-events" ], "active": true, "secret": "your-secret" }), }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.put( "https://api.actuallycare.com/v1/webhooks/:id", headers={"Authorization": "Bearer YOUR_JWT"}, json={ "url": "your-url", "events": [ "your-events" ], "active": true, "secret": "your-secret" }, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "id": "wh_abc123def456", "url": "example url", "events": [ "escrow.created" ], "has_secret": true, "active": true, "brokerage_id": "550e8400-e29b-41d4-a716-446655440000", "team_id": "550e8400-e29b-41d4-a716-446655440000", "last_triggered": "2026-07-15T14:32:10.000Z", "created_at": "2026-07-15T14:32:10.000Z" } } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Webhook updated | | | `400` | Invalid request data | Fix the request; `error.message` and `error.details` name the problem. Don't retry unchanged | | `401` | Authentication required | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Deactivate a webhook subscription ```http DELETE /v1/webhooks/{id} ``` Deactivates a subscription so it stops receiving deliveries. The subscription record is kept and can be re-enabled by setting `active` back to true. ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Webhook ID | ### Example request ```bash title="cURL" curl -X DELETE "https://api.actuallycare.com/v1/webhooks/:id" \ -H "Authorization: Bearer YOUR_JWT" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/webhooks/:id", { method: "DELETE", headers: { "Authorization": "Bearer YOUR_JWT", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.delete( "https://api.actuallycare.com/v1/webhooks/:id", headers={"Authorization": "Bearer YOUR_JWT"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": { "id": "wh_abc123def456", "url": "example url", "events": [ "escrow.created" ], "has_secret": true, "active": true, "brokerage_id": "550e8400-e29b-41d4-a716-446655440000", "team_id": "550e8400-e29b-41d4-a716-446655440000", "last_triggered": "2026-07-15T14:32:10.000Z", "created_at": "2026-07-15T14:32:10.000Z" }, "timestamp": "2026-07-01T22:51:14.902Z" } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Webhook deactivated (response is the updated subscription with active=false) | | | `401` | Authentication required | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | ## Get webhook delivery logs ```http GET /v1/webhooks/{id}/logs ``` Returns recent delivery attempts for a subscription, including the payload sent, the HTTP status your endpoint returned, and whether delivery succeeded. ### Parameters | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Webhook ID | | `page` | query | integer | No | Page number for pagination · Default: `1` · Min: 1 | | `limit` | query | integer | No | Number of items per page (default 25, max 100) · Default: `25` · Max: 100 · Min: 1 | ### Example request ```bash title="cURL" curl "https://api.actuallycare.com/v1/webhooks/:id/logs" \ -H "Authorization: Bearer YOUR_JWT" ``` ```javascript title="JavaScript" const res = await fetch("https://api.actuallycare.com/v1/webhooks/:id/logs", { headers: { "Authorization": "Bearer YOUR_JWT", }, }); const data = await res.json(); ``` ```python title="Python" import requests resp = requests.get( "https://api.actuallycare.com/v1/webhooks/:id/logs", headers={"Authorization": "Bearer YOUR_JWT"}, ) data = resp.json() ``` ### Example response (200) ```json { "success": true, "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "webhook_id": "550e8400-e29b-41d4-a716-446655440000", "event": "escrow.created", "payload": {}, "response_status": 200, "delivered_at": "2026-07-15T14:32:10.000Z", "created_at": "2026-07-15T14:32:10.000Z" } ] } ``` ### Responses | Status | Meaning | What to do | | --- | --- | --- | | `200` | Delivery log entries, most recent first | | | `401` | Authentication required | Send a JWT as `Authorization: Bearer …` — this endpoint rejects API keys. See [Authentication](/api/authentication) | | `404` | Resource not found | Check the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See [Errors](/api/errors#http-status-codes) | | `429` | Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying. | Back off and retry after `Retry-After`. See [Rate limits](/api/rate-limits) | | `500` | Internal server error | Retry with exponential backoff. See [Errors](/api/errors#retry-on-429-and-5xx--and-nothing-else) | --- # Versioning & deprecation > How the ActuallyCare REST API is versioned, what counts as a breaking change, and how deprecations are communicated. The API is path-versioned. There is currently **one version: `/v1`** — every endpoint lives under `https://api.actuallycare.com/v1`. ## What we change without notice (non-breaking) These can happen at any time and your integration must tolerate them: - New endpoints, and new **optional** request parameters - New fields in response objects (parse what you need; ignore unknown fields) - New enum values in fields that are documented as open-ended (e.g. new `status` values on new features) - New webhook event types (subscribe explicitly; ignore types you don't handle) - Documentation-only changes to the OpenAPI spec (descriptions, examples) ## What counts as breaking Anything that would make a working integration stop working: - Removing or renaming an endpoint, request parameter, or response field - Changing a field's type or meaning - Tightening validation so previously-valid requests fail - Removing an enum value or changing error `code` strings **Breaking changes ship under a new version path** (`/v2`), not in place. `/v1` keeps working while any published version is supported. ## How deprecations are communicated No `/v1` endpoint is deprecated today. When a deprecation is scheduled it will be announced in the [changelog](https://www.actuallycare.com/changelog), marked `deprecated: true` in the [OpenAPI spec](https://api.actuallycare.com/v1/openapi.json), and given an explicit sunset date in both places — with a migration path documented before the clock starts. ## MCP tools MCP tools follow the same philosophy at the tool level: tool inputs only gain optional parameters in place. When a tool is renamed, only the new name is callable — the `aliasOf` field in [tools.json](https://docs.actuallycare.com/tools.json) records the old name so you can update your code, and the old docs URL redirects. New tools appear without notice — read [tools.json](https://docs.actuallycare.com/tools.json) or use the discovery tools rather than hardcoding the tool set. `tools/list` returns only the everyday tools, not the whole catalog. --- # Concepts > How ActuallyCare's integration surface fits together: API vs MCP, authentication, the data model, and webhooks. The thinking-clearly pages. Read these when you want to understand how the pieces fit together, before (or instead of) memorizing endpoints. ## [API vs MCP](/concepts/api-vs-mcp) Two ways to integrate — when to use the REST API, when to use the MCP server, and how to combine them. ## [Authentication model](/concepts/authentication) The three credential types — OAuth for Claude users, API keys for servers, JWTs for user sessions — and when each applies. ## [Data model](/concepts/data-model) The entities behind your CRM — contacts vs clients vs leads, transactions, the vendor pipeline, property management, ID formats, and how visibility follows the team/brokerage hierarchy. ## [Webhooks](/concepts/webhooks) Event-driven integration: the self-documenting event catalog, which events fire today, payload signatures, and delivery semantics. --- # API vs MCP > Two ways to integrate - when to use which, and how to combine them. ActuallyCare gives you two ways to integrate: a REST API and an MCP (Model Context Protocol) server. They sit in front of the same database — the difference is who's doing the talking. The REST API is for code you write. MCP is for an AI assistant like Claude. ## Which one do you need? | If you're building... | Reach for | |---|---| | A custom UI, dashboard, or internal tool | REST API | | A data sync with another system (MLS feed, accounting, email marketing) | REST API | | An event-driven integration that reacts to changes | REST API plus [webhooks](/concepts/webhooks) | | An AI assistant that can actually work your CRM | MCP | | A daily "ask Claude about my pipeline" workflow | MCP | | All of the above | Both — this is common | ## At a glance | Aspect | REST API | MCP | |---|---|---| | Interface | HTTP requests you write | Natural language via Claude | | Best for | Apps, scripts, syncs | Conversational work and AI analysis | | Authentication | API key (`X-API-Key`) or JWT | OAuth 2.1 (handled by Claude), or an API key or JWT for custom clients | | Response format | JSON envelope | Claude reads tool results and answers in plain English | | Surface | Small and focused | Much larger | Both authentication models are covered in depth in [the authentication model](/concepts/authentication). ## When to use the REST API Choose REST when a program — not a person — is the consumer. You control the exact request, you parse the exact response, and you can schedule, retry, and log however you like. ```bash curl "https://api.actuallycare.com/v1/clients?page=1&limit=20" \ -H "X-API-Key: YOUR_API_KEY" ``` Every successful response has `success: true` and the result in `data`: ```json { "success": true, "data": { "clients": [], "meta": { "page": 1, "limit": 25, "total": 0, "totalPages": 0, "hasMore": false } } } ``` Here `data` is an object keyed by the resource — the page of clients lives at `data.clients`, with pagination metadata at `data.meta`. See [pagination](/api/pagination) and [errors](/api/errors) for the details, and the [endpoint reference](/api/reference) for every documented operation. Good REST use cases: - **Custom applications** — internal dashboards, reporting tools, mobile front ends - **Automation** — scheduled scripts, Zapier-style workflows, bulk imports (see [the bulk import guide](/guides/bulk-import)) - **Syncing with other systems** — push leads in from your website, push closings out to accounting - **Reacting to events** — pair the API with [webhooks](/concepts/webhooks) instead of polling ## When to use MCP Choose MCP when you want to talk to your CRM instead of program against it. Once your CRM is connected to Claude (see the [MCP quickstart](/mcp/quickstart)), you ask in plain English: > "Show me all escrows closing this month with their current status." Claude picks the right tool — in this case [`escrows_list`](/tools/escrows/escrows_list) — runs it against your data, narrows the results to this month's closing dates, and presents them conversationally. Most tool names are entity first (`escrows_list`, `clients_create`, `leads_convert`); workflow tools are verb first (`get_dashboard_stats`, `draft_email`). Good MCP use cases: - **Quick lookups** — "What's the status of 123 Main St?" - **Natural updates** — "Mark John Smith as contacted" - **Analysis** — "Which of my deals look at risk of falling through?" - **Multi-step questions** — "Find clients who bought in 2024 and haven't heard from me in 90 days" To keep conversations fast, Claude gets a set of everyday tools — you don't have to do anything to enable them. Claude can only call those tools; the rest of the catalog is available to custom apps, which can call any tool by name. ## Two surfaces, one database The two surfaces are deliberately different sizes. The documented REST surface is focused: resource groups covering the core CRM entities (contacts, clients, leads, escrows, listings, appointments) plus auth, API keys, webhooks, and billing. The full list lives in the [endpoint reference](/api/reference). The MCP surface is much larger. It covers escrows, showings, open houses, financial calculators, the vendor pipeline, property management, reporting, and more — browse the full catalog at [the tool reference](/tools), where the live tool counts are rendered from the same registry the server uses. That means some things you can ask Claude to do don't have a documented REST equivalent yet. If you need an operation that only exists as an MCP tool, call it from your own code via a [custom MCP client](/mcp/custom-apps). Claude's apps can only use the everyday tools, so not every catalog tool is available in a Claude chat. ## Using both together Many teams run both, and that's the recommended setup for power users: - **MCP for daily work** — quick queries, updates, and analysis while chatting with Claude - **REST for automation** — webhook handlers, scheduled jobs, and integrations that run without a human in the loop A typical pattern: a webhook fires when a lead is created, your server enriches it via the REST API, and the agent reviews and works the lead through Claude the next morning. ## Data consistency Both interfaces read and write the same underlying records. A client Claude creates is immediately visible to your REST integration, and vice versa. There's no sync delay and no separate data store to reconcile. ## Rate limits The two surfaces are limited independently: - **REST API** — 500 requests per 15 minutes per IP across `/v1` (auth endpoints are tighter: 30 **failed** attempts per 15 minutes, plus a 50-total-attempts cap on `POST /v1/auth/login` — that second cap is what the `RateLimit-Limit` header on login responses reports — with `/v1/auth/refresh` on its own 30-per-minute limit) - **MCP** — 120 requests per minute and 30 tool calls per minute per user When you hit a limit you'll get a 429 — back off and retry. Full details, including the response headers to watch, are on the [rate limits page](/api/rate-limits). --- # Authentication model > How OAuth, API keys, and JWTs fit together across the platform. ActuallyCare has one backend and three credential types. Which one you need depends entirely on who — or what — is making the call. This page explains the model; for copy-paste REST details see [API authentication](/api/authentication), and for the plain-English version written for agents see [permissions and safety](/agents/permissions-and-safety). ## Who uses what | You are... | You use... | Why | |---|---|---| | An agent connecting Claude to your CRM | OAuth 2.1 | Claude handles the whole flow — you just log in and approve once | | A developer writing a server-side integration or script | API key | One long-lived secret, no login flow, no token refresh logic | | A developer building an app where your users sign in | JWT | Short-lived tokens tied to a real user session, with refresh rotation | ## OAuth 2.1 — for Claude users When you add ActuallyCare as a connector in Claude, Claude starts an OAuth 2.1 flow with PKCE (Proof Key for Code Exchange — a standard protection against intercepted authorization codes). You never see a token. What you do see is the consent page at `app.actuallycare.com/mcp/authorize`, titled "Connect with ActuallyCare". It names the app asking for access, warns if ActuallyCare does not recognize that app, and lists exactly what you're approving: 1. Read your CRM data — escrows, listings, clients, leads, and calendar 2. Create and update records when you ask 3. Draft emails and texts for your approval — nothing sends without your okay 4. Archive or delete records, with confirmation If you're not already logged in to ActuallyCare, you go through the normal login first. After approval: - **Access tokens last 24 hours.** - **Refresh tokens rotate automatically**, so you stay connected without re-approving. To disconnect, remove the connector in Claude's own settings (Settings, then Connectors). That's the revocation path — there is no separate ActuallyCare page for revoking Claude's access. Custom MCP clients can also use OAuth 2.1 via dynamic client registration — see [building custom apps](/mcp/custom-apps). ## API keys — for servers and scripts API keys are the simplest credential for code that runs unattended. Send the key in the `X-API-Key` header (the header `API-Key` also works): ```bash curl "https://api.actuallycare.com/v1/listings" \ -H "X-API-Key: YOUR_API_KEY" ``` Key facts: - Keys are **64-character hex strings** — there's no prefix to look for. - The full key is shown **once**, at creation. It's stored hashed; afterwards the UI only shows the first 8 and last 4 characters. If you lose a key, create a new one. - A key acts as the user who created it, so requests inherit that user's role and visibility. - Scopes **grant** a key its access — they don't narrow it. Every key must be created with at least one grant. The actions are `read`, `write` and `delete`: grant `{"all":["read","write","delete"]}` for full access, or per-resource grants like `{"clients":["read","write"]}`, and adjust later with `PATCH /v1/api-keys/:id/scopes`. (Scopes are an API-key concept — JWT users aren't scope-checked.) Create keys in the app under Settings, in the API Keys tab (`app.actuallycare.com/settings?tab=api`). Every user can create their own keys — each key acts as you, with your role's visibility. You can also create keys via the API itself: `POST /v1/api-keys` with a `name`, a `scopes` object, and an optional `expiresInDays` between 1 and 365. If you omit `expiresInDays`, the key never expires — there's no implicit default, so set an expiry explicitly. Standard hygiene applies: keep keys in environment variables, never commit them to source control, never ship them in client-side code, and rotate them periodically. ## JWTs — for user-session apps If you're building an app where each user logs in with their own ActuallyCare account, use JWT auth. Log in: ```bash curl -X POST "https://api.actuallycare.com/v1/auth/login" \ -H "Content-Type: application/json" \ -d '{"email": "you@example.com", "password": "YOUR_PASSWORD"}' ``` The response follows the standard envelope: ```json { "success": true, "data": { "user": {}, "accessToken": "...", "refreshToken": "...", "expiresIn": "15m", "tokenType": "Bearer" }, "message": "Login successful" } ``` If the user has two-factor sign-in turned on, or the account is still on the waitlist, login returns `200` without these tokens. See [API authentication](/api/authentication#other-login-outcomes) for those cases. Then send the access token on every request: ```text Authorization: Bearer YOUR_ACCESS_TOKEN ``` What to know: - **Access-token lifetime is role-based**, ranging from 15 minutes to 8 hours. The `expiresIn` field is a **duration string** like `"15m"` or `"8h"` — not seconds — so parse the string or decode the JWT's `exp` claim rather than assuming a number. - **Refresh with `POST /v1/auth/refresh`.** The refresh token rotates on every use, and the new one comes back only in the `Set-Cookie` header. Sessions have a 30-day sliding window and a 90-day absolute cap; after that, the user logs in again. Details are in [API authentication](/api/authentication#token-lifetimes-and-refresh). - **The same JWT also works against the MCP server**, so a user-session app can call MCP tools on the user's behalf. ## One backend, three front doors The credentials map onto the two surfaces like this: | Surface | Accepts | |---|---| | REST API (`api.actuallycare.com/v1`) | API key, JWT | | MCP server (`mcp.actuallycare.com/mcp`) | OAuth 2.1, API key, JWT | Whichever door you come through, you're acting as a specific user with a specific role — authentication decides who you are, and the role decides what you can see and change. How roles shape data visibility is covered in [the data model](/concepts/data-model). --- # Data model > The entities behind your CRM and how they relate. ActuallyCare's data model follows the shape of a real estate business: people you know, deals in flight, properties you market, and the calendar that ties it together — plus newer verticals for vendor relationships and property management. This page is the conceptual map. For the exact fields and parameters of any operation, see the [tool reference](/tools) and the [endpoint reference](/api/reference). ## The core six The six entities you'll touch every day: | Entity | What it is | |---|---| | Contacts | Every person in your database | | Clients | People you represent | | Leads | Potential business in your pipeline | | Escrows | Active transactions, open to close | | Listings | Properties you're marketing | | Appointments | Your calendar | ### Contacts vs clients vs leads This distinction confuses almost everyone at first, so here it is plainly: - A **contact** is a *person*. Everyone in your database — past clients, leads, other agents, your lender, your mom — is a contact. It's the universal address book. - A **lead** is *potential business*. A lead represents someone moving through your pipeline who might transact with you. Leads get qualified, nurtured, and eventually [converted](/tools/leads/leads_convert) — or archived. - A **client** is an *active representation relationship*. When someone actually works with you — buying, selling, or both — they're a client. The key insight: lead and client aren't different people, they're different *relationships with the same person*. A client is always backed by a contact record. A lead holds its own name and contact details, and you can link it to existing contacts. Converting a lead creates the client and, if needed, its contact. ### Escrows, listings, and appointments - **Escrows** are transactions. An escrow opens when a deal goes under contract and tracks everything through closing. - **Listings** are inventory — properties you're marketing. A listing and an escrow often describe the same property at different stages: you list it, then it goes into escrow. - **Appointments** are calendar entries — showings you're driving to, listing presentations, closings, anything with a time attached. ## Around the transaction An escrow at the center of a deal accumulates satellite records: - **Documents** — files attached to the transaction (documents can attach to other records too). Documents can be run through AI risk analysis to surface red flags (see [`documents_get_risks`](/tools/documents/documents_get_risks)). - **Deadlines and checklists** — contingency deadlines, the escrow checklist, and deadline alerts so nothing slips during the contract period. Listings have their own satellites: - **Showings** — individual property showings, including buyer feedback. - **Open houses** — events with their own schedule and visitor logging. ## The vendor pipeline "Vendor" here means the service businesses around a transaction — lenders, escrow officers, inspectors, contractors, insurance agents, and other professionals you exchange business with. The vendor pipeline tracks those relationships the way the core pipeline tracks buyers and sellers: - **Prospects** — vendors you're evaluating but don't work with yet - **Partners** — vendors you actively work with - **Referrals** — business passed between you and a partner, in either direction - **Deals** — revenue opportunities that come out of those relationships - **Engagements** — logged interactions with partners, so the relationship history is on the record ## Property management For agents and brokerages doing property management, a dedicated set of entities covers the rental side: - **Rental applications** — applicants for a rental; an approved application can convert directly into a lease - **Leases** — the agreements themselves, with expiration tracking - **Tenancies** — the ongoing tenant relationship: rent collection, inspections, delinquency - **PM consultations** — intake conversations with property owners considering your management services; a consultation can convert into a tenancy ## Care status Care status is ActuallyCare's measure of follow-up health: is this relationship being actively cared for, or is it going cold? It changes as you log activity, and it gives "who needs attention?" a concrete answer instead of a gut feeling. Care status changes also fire `care_status.*` [webhook events](/concepts/webhooks), so you can build follow-up automation on top of it. ## Custom pipelines Beyond the built-in pipelines, ActuallyCare supports config-driven pipelines: pipeline types and stages are configuration, not code. Records move through stages, activity gets logged along the way, and you get pipeline-level reporting — which lets a team model a workflow the built-ins don't cover. See the [pipeline tools](/tools/pipelines). ## Entity links Sometimes two records are related in a way no built-in relationship captures — a lead who's interested in a specific listing, or a deal that depends on an escrow. **Entity links** are lightweight cross-references between escrows, deals, leads, clients, contacts, appointments, and listings. See the [entity link tools](/tools/entity-links). ## How your org shapes what you see Most users belong to a team inside a brokerage. Solo agents may have no team, and then they just see their own records: ```text Brokerage └─ Team └─ Agent (user) ├─ Contacts ── the person record ├─ Leads ──(convert)──► Clients (backed by a contact) ├─ Appointments ├─ Listings ◄─┐ │ ├─ Showings │ └─ Open houses ├─ Escrows ───┘ often the same property, two stages │ ├─ Documents (with AI risk analysis) │ └─ Deadlines and checklists ├─ Vendor pipeline: Prospects ► Partners ► Referrals · Deals · Engagements └─ Property mgmt: Applications ► Leases ► Tenancies · PM consultations ``` Data visibility follows four **visibility scopes** that map onto the hierarchy: **standard** (your own records), **team** (across your team), **brokerage** (across the brokerage), and **admin** (platform administration). Roles are how users land in a scope — the classic real estate roles map directly (agent → standard, team_lead → team, broker → brokerage, system_admin → admin), and other verticals add their own roles (lender, property_manager, escrow_officer, and more) that slot into the same four scopes. Whatever credential you connect with (Claude, an API key, a JWT), you act as a specific user, so this hierarchy applies everywhere — see [the authentication model](/concepts/authentication). ## IDs and lifecycle Treat IDs as opaque strings. Most are UUIDs, but not all: document IDs look like `doc_1a2b3c4d5e6f`, and webhook IDs like `wh_1a2b3c4d5e6f`. Escrows also have a human-readable display ID like `ESC-2026-0042`. Core entities share a soft-delete lifecycle: 1. **Archive** — the record leaves normal lists but nothing is lost. Reversible. 2. **Restore** — bring an archived record back. A restored lead's status goes back to `new`. 3. **Delete** — removes the record from the app. Deletes are role-gated, and a lead must be archived before it can be deleted (otherwise `422`). Deleting a client also removes its linked contact. Bulk versions of archive, restore, and delete exist for the core entities — see the [bulk operations tools](/tools/bulk-operations). When in doubt, archive: it's the safe default, and you can always restore. --- # Webhooks > Event-driven integration: catalog, signatures, retries. Webhooks turn your integration from pull to push. Instead of polling the API on a schedule and diffing results, you register a URL once and ActuallyCare sends an HTTP POST to it the moment something happens. This page covers the concepts — event catalog, payload, signatures, delivery. For a step-by-step walkthrough, see the [webhook setup guide](/guides/webhook-setup). ## Webhooks or polling? | Situation | Better fit | |---|---| | React to changes as they happen (new lead, escrow update) | Webhooks | | Periodic full sync or reporting snapshot | Polling the REST API | | You can't host a public HTTPS endpoint | Polling | | Low latency matters (lead routing, notifications) | Webhooks | The usual pattern is both: webhooks for the real-time signal, with an occasional polled reconciliation pass as a safety net. ## The event catalog The catalog is self-documenting. Ask the API what events exist (all `/v1/webhooks` endpoints take a JWT bearer token — not an API key — and need a broker or system-admin role, see [Managing webhooks](#managing-webhooks)): ```bash curl "https://api.actuallycare.com/v1/webhooks/events" \ -H "Authorization: Bearer YOUR_JWT" ``` The response uses the standard envelope: `data` lists every event type with its category, description, and a list of key fields, and `meta` totals it up. The delivered record usually has more fields than that list, and some events use different field names, so read fields defensively. Add `?category=` to get one category. Trimmed to two entries: ```json { "success": true, "data": [ { "event": "escrow.created", "category": "escrow", "description": "An escrow/transaction was created", "payload": ["id", "status", "property_address", "escrow_number"] }, { "event": "lead.created", "category": "lead", "description": "A new lead was created", "payload": ["id", "name", "email", "phone", "source", "status"] } ], "meta": { "total": 150, "categories": ["appointment", "care_status", "client", "..."] } } ``` The catalog covers every event name you can subscribe to — `escrow.*`, `lead.*`, `client.*`, `listing.*`, `appointment.*`, `care_status.*`, and more. Today, deliveries are sent for escrow, lead, client, listing, appointment, showing feedback, inventory, and care status events; other catalog events don't fire yet. A few representative examples: | Event | Fires when | |---|---| | `escrow.created` | A new escrow is opened | | `escrow.updated` | An escrow's details change | | `lead.created` | A new lead enters the pipeline | | `lead.status_changed` | A lead's status changes | | `client.created` | A new client relationship is created | | `listing.updated` | A listing's details change | | `appointment.status_changed` | An appointment's status changes (including cancellations) | | `care_status.changed` | A relationship's follow-up health changes | This table is illustrative — **the catalog endpoint is the source of truth.** `GET /v1/webhooks/events/categories` returns the category list if you want to browse by group. When you create a webhook you subscribe it to specific events, or to all of them. Event names aren't checked when you register, so a misspelled name is accepted and simply never fires — copy names from the catalog. ## The payload envelope Every delivery is a POST with a JSON body in the same envelope: ```json { "event": "escrow.created", "team_id": "3f8a1c2e-9d4b-4f6a-8e2d-1b7c5a9e0f3d", "timestamp": "2026-06-11T17:32:08.123Z", "data": { "id": "9c4e7b1a-2f8d-4e3c-a6b5-0d1f2e3a4b5c" } } ``` | Field | Meaning | |---|---| | `event` | The event type that fired | | `team_id` | The team the event belongs to, or `null` when the record has no team | | `timestamp` | When the event occurred | | `data` | The affected record — its shape depends on the event type | ## Verifying signatures Every delivery is signed so you can confirm it really came from ActuallyCare. Three headers arrive with each request: | Header | Contents | |---|---| | `X-Webhook-Signature` | `sha256=` followed by the HMAC-SHA256 hex digest of the JSON body, computed with your webhook secret (e.g. `sha256=3f5a…`). | | `X-Webhook-Event` | The event type, same as `event` in the body | | `X-Webhook-Timestamp` | The same value as `timestamp` in the body. It's set when the event is first sent and stays the same on retries | Compute the same HMAC over the raw request body and compare with a timing-safe comparison — never a plain string equality: ```javascript const crypto = require('crypto'); const express = require('express'); const app = express(); function verifySignature(rawBody, signatureHeader, secret) { const expectedHex = crypto .createHmac('sha256', secret) .update(rawBody) .digest('hex'); // Header format: "sha256=" const receivedHex = (signatureHeader || '').replace(/^sha256=/, ''); const expected = Buffer.from(expectedHex, 'hex'); const received = Buffer.from(receivedHex, 'hex'); return ( expected.length === received.length && crypto.timingSafeEqual(expected, received) ); } app.post( '/webhooks/actuallycare', express.raw({ type: 'application/json' }), (req, res) => { const signature = req.get('X-Webhook-Signature'); if (!verifySignature(req.body, signature, process.env.WEBHOOK_SECRET)) { return res.status(401).send('invalid signature'); } // Acknowledge fast, process async res.status(200).send('ok'); const payload = JSON.parse(req.body.toString('utf8')); // handle payload.event, payload.data ... } ); ``` Two details that bite people: verify against the **raw** body (a re-serialized JSON object may not match byte-for-byte), and remember to strip the `sha256=` prefix from the header before comparing digests. Your webhook secret is set when you create the webhook (minimum 10 characters). The API never returns it afterward — webhook responses show `"has_secret": true` instead — so store it when you create it. To change it, send a new `secret` with `PUT /v1/webhooks/:id`. ## Delivery and retries - ActuallyCare waits up to **30 seconds** for your endpoint to respond. Return a 2xx quickly and do real work asynchronously. - **Failed deliveries are retried** at 1 minute, 5 minutes, and 15 minutes after the initial attempt (up to 4 attempts total), then given up. A delivery counts as failed on a network error or on a `5xx`, `408`, or `429` response; other `4xx` responses are treated as your endpoint rejecting the event and are **not** retried. - Retries survive server restarts, and deactivating a webhook cancels its pending retries. - Retries currently apply to webhooks created by someone on a team. A brokerage-wide webhook (created by a broker with no team) gets each delivery once, without retries, so check its delivery logs if you rely on it. - Delivery is **at-least-once**: your endpoint can see the same event more than once, so process idempotently. The delivery logs — visible in the app, and available via `GET /v1/webhooks/:id/logs` — show every attempt. Deduplicate on the signature header value — a retried delivery carries the same signature as the original, and unlike `event` + `timestamp` it can't collide when two records fire the same event in the same instant. ## Managing webhooks A webhook belongs to the brokerage of the person who created it. If that person is on a team, it receives that team's events; if not, it receives every event in the brokerage. Webhooks are managed by **broker** and **system-admin** roles, and you see only your own brokerage's webhooks: any other webhook ID returns `404`. Two ways to manage them: - **In the app** — Settings, Webhooks tab (`app.actuallycare.com/settings?tab=webhooks`): create endpoints, choose events, and review delivery logs. - **Via REST** — `GET`/`POST /v1/webhooks` to list and create, `PUT`/`DELETE /v1/webhooks/:id` to update and deactivate, `GET /v1/webhooks/:id/logs` for delivery history. A deactivated webhook stops receiving deliveries; `PUT` with `"active": true` turns it back on. Your endpoint must be reachable on the public internet. Deliveries to private, loopback, and link-local addresses (like `localhost`) are blocked, so use a tunnel when testing locally. Ready to wire one up end to end? Follow the [webhook setup guide](/guides/webhook-setup). --- # Guides > Hands-on tutorials: build an integration, set up webhooks, and import your data. Step-by-step tutorials for building on ActuallyCare. Each one is complete and copy-pasteable — start at the top and you'll end with something working. ## Build a custom integration Go from an API key to a working two-way sync — an API client, paginated reads, creating and updating records, and a verified webhook receiver. [Build a custom integration →](/guides/build-custom-integration) ## Set up webhooks Discover the event catalog, register a webhook, verify signatures, and process deliveries reliably. [Set up webhooks →](/guides/webhook-setup) ## Bulk import your data Bring clients and leads over from your old CRM with a rate-limit-aware import script, a field-mapping checklist, and safe re-runs. [Bulk import your data →](/guides/bulk-import) ## Connecting Claude? That guide lives on the agent path: [Connect Claude in 5 minutes](/mcp/quickstart). Building your own MCP app instead? See [Build a custom MCP app](/mcp/custom-apps). --- # Build a custom integration > An end-to-end tutorial: API key, client module, paginated lead sync, and a verified webhook receiver. > > **Takes:** 30 min · **Skill:** Developer · **Needs:** Node.js 18+ or Python 3.9+ This tutorial builds a complete, production-shaped integration with a concrete goal: **a nightly sync that pulls new leads out of ActuallyCare into your own system, and pushes status updates back**. Along the way you'll add a webhook receiver so urgent events arrive in real time instead of waiting for the next sync run. Everything here is copy-pasteable. You'll need: - An ActuallyCare account with API access - Node.js 18 or newer (which has `fetch` built in), or Python 3.9+ if you prefer the Python examples - About 30 minutes ## Step 1: Get an API key All requests in this tutorial authenticate with an API key sent in the `X-API-Key` header. 1. Open [app.actuallycare.com](https://app.actuallycare.com) and go to **Settings → API Keys** (direct link: `https://app.actuallycare.com/settings?tab=api`). 2. Create a new key. Give it a name like `nightly-lead-sync`, an expiration, and the scopes it needs — scopes are what grant a key access. For this tutorial, `{"leads":["read","write"]}` covers reading and updating leads (or `{"all":["read","write","delete"]}` for full access). 3. **Copy the key immediately.** It's a 64-character hex string, shown once at creation. After that, ActuallyCare stores only a hash and the UI shows just the first 8 and last 4 characters. Every user can create their own keys — each key acts as you, with your role's visibility. Store the key in an environment variable, never in code: ```bash export ACTUALLYCARE_API_KEY="your-64-character-key" ``` Sanity-check it with curl: ```bash curl "https://api.actuallycare.com/v1/leads?limit=1" \ -H "X-API-Key: $ACTUALLYCARE_API_KEY" ``` Every response uses the same envelope. On list endpoints `data` is an object keyed by the resource, with pagination metadata at `data.meta`. Success looks like this (record fields trimmed): ```json { "success": true, "data": { "leads": [ { "id": "a1b2c3d4-..." } ], "meta": { "page": 1, "limit": 1, "total": 132, "totalPages": 132, "hasMore": true } }, "timestamp": "2026-06-11T17:42:11.000Z" } ``` And errors look like this (an illustrative example): ```json { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Invalid email" } } ``` Rate-limited `429`s use the same envelope (`error.code` of `RATE_LIMIT_EXCEEDED`) and add a `Retry-After` header — branch on the HTTP status or the code, and honor the header. For more on keys, JWTs, and scopes, see [Authentication](/api/authentication). ## Step 2: Write a small API client Wrap the envelope handling, error handling, and retry logic once, in one module, so the rest of your integration never thinks about it. ### Node.js ```javascript // actuallycare.js const BASE_URL = 'https://api.actuallycare.com/v1'; const API_KEY = process.env.ACTUALLYCARE_API_KEY; class ApiError extends Error { constructor(status, code, message) { super(`${code}: ${message}`); this.status = status; this.code = code; } } const sleep = (ms) => new Promise((r) => setTimeout(r, ms)); async function request(method, path, { params, body } = {}) { const url = new URL(BASE_URL + path); for (const [key, value] of Object.entries(params || {})) { url.searchParams.set(key, value); } // Retry on 429 and 5xx with exponential backoff: 1s, 2s, 4s. for (let attempt = 0; ; attempt++) { const res = await fetch(url, { method, headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json', }, body: body ? JSON.stringify(body) : undefined, }); if ((res.status === 429 || res.status >= 500) && attempt < 3) { await sleep(1000 * 2 ** attempt); continue; } if (!res.ok) { // Parse error bodies defensively — proxies can return non-JSON. let err = {}; try { err = (await res.json()).error || {}; } catch { /* non-JSON body */ } throw new ApiError(res.status, err.code || `HTTP_${res.status}`, err.message || 'Request failed'); } const payload = await res.json(); return payload.data; // the envelope's data object, e.g. { leads: [...], meta: {...} } } } module.exports = { ApiError, get: (path, params) => request('GET', path, { params }), post: (path, body) => request('POST', path, { body }), put: (path, body) => request('PUT', path, { body }), }; ``` ### Python ```python # actuallycare.py import os import time import requests BASE_URL = "https://api.actuallycare.com/v1" API_KEY = os.environ["ACTUALLYCARE_API_KEY"] class ApiError(Exception): def __init__(self, status, code, message): super().__init__(f"{code}: {message}") self.status = status self.code = code def request(method, path, params=None, body=None): headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"} # Retry on 429 and 5xx with exponential backoff: 1s, 2s, 4s. for attempt in range(4): res = requests.request( method, BASE_URL + path, headers=headers, params=params, json=body, timeout=30, ) if (res.status_code == 429 or res.status_code >= 500) and attempt < 3: time.sleep(2 ** attempt) continue if not res.ok: # Parse error bodies defensively — proxies can return non-JSON. try: err = res.json().get("error", {}) except ValueError: err = {} raise ApiError(res.status_code, err.get("code", f"HTTP_{res.status_code}"), err.get("message", res.text.strip() or "Request failed")) # The envelope's data object, e.g. {"leads": [...], "meta": {...}} return res.json()["data"] def get(path, **params): return request("GET", path, params=params) def post(path, body): return request("POST", path, body=body) def put(path, body): return request("PUT", path, body=body) ``` Two things worth noting: - The wrapper retries on 429 (rate limited) and 5xx automatically. The limit is 500 requests per 15 minutes per IP — see [Rate limits](/api/rate-limits) for the response headers that tell you where you stand. - Errors surface as a typed exception carrying the HTTP status and, when the body is the JSON envelope, its `error.code` (a `429` carries `RATE_LIMIT_EXCEEDED`). Branch on `err.status` or `err.code`, never on messages; the defensive parse falls back to `HTTP_` if a proxy returns a non-JSON body. ## Step 3: Fetch leads with pagination List endpoints take `page` and `limit` query parameters (`limit` defaults to 25, max 100). The records come back under `data`, keyed by the resource — `data.leads` here — with pagination metadata at `data.meta`. Loop pages until `meta.hasMore` goes `false`: ```javascript // fetch-leads.js const api = require('./actuallycare'); async function getAllLeads() { const leads = []; const limit = 100; for (let page = 1; ; page++) { const data = await api.get('/leads', { page, limit }); leads.push(...data.leads); console.log(`Page ${page}: ${data.leads.length} leads (${leads.length} of ${data.meta.total})`); if (!data.meta.hasMore) break; } return leads; } module.exports = { getAllLeads }; ``` The `meta` object also carries `total` and `totalPages` — see [Pagination](/api/pagination) for the exact shape, and [the leads reference](/api/reference/leads) for everything the endpoint accepts and returns. ## Step 4: Create and update records, with real error handling The nightly sync has two write paths: creating a lead that originated in your system, and pushing a status change back to ActuallyCare. The key habit: **check before you create**. The API doesn't know your external system's IDs, so dedupe on something stable like email before inserting — otherwise a re-run of a failed sync creates duplicates. ```javascript // sync.js const fs = require('fs'); const api = require('./actuallycare'); const { getAllLeads } = require('./fetch-leads'); const STATE_FILE = './synced-lead-ids.json'; function loadState() { try { return new Set(JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'))); } catch { return new Set(); } } async function nightlySync() { const synced = loadState(); const leads = await getAllLeads(); // 1. Pull: hand any lead we haven't seen before to your own system. for (const lead of leads) { if (synced.has(lead.id)) continue; await sendToYourSystem(lead); // your code here synced.add(lead.id); } fs.writeFileSync(STATE_FILE, JSON.stringify([...synced])); // 2. Push: send status changes from your system back to ActuallyCare. for (const change of await getPendingStatusChanges()) { // your code here try { await api.put(`/leads/${change.leadId}`, { lead_status: change.newStatus }); console.log(`Updated lead ${change.leadId} -> ${change.newStatus}`); } catch (err) { if (err.status === 429) { // The client already retried; if it still failed, stop and resume next run. console.error('Rate limited after retries, resuming next run.'); break; } // Validation and not-found errors: log the code and keep going. console.error(`Lead ${change.leadId} failed: ${err.code} - ${err.message}`); } } } nightlySync().catch((err) => { console.error('Sync failed:', err); process.exit(1); }); ``` A lead's status field is `lead_status`; an update with no recognized field fails with `422 VALIDATION_ERROR` ("No valid fields to update"). The generated [endpoint reference](/api/reference) is the source of truth for each resource's exact request and response shapes. Same goes for creating records: a `POST /v1/leads` with the fields from [the leads reference](/api/reference/leads) returns the created record (including its UUID `id`) inside `data`. Run the script from cron, a scheduled CI job, or whatever scheduler you already have. Once a night is plenty — the webhook receiver in the next step covers the in-between. ## Step 5: Receive webhooks in real time Polling nightly means a hot lead could sit for hours. Webhooks fix that: ActuallyCare POSTs to your endpoint when events happen, signed so you can prove they're genuine. Register a webhook first — the [webhook setup guide](/guides/webhook-setup) covers discovery, registration, and the event catalog. Registration needs more than the API key from Step 1: it takes a JWT from a user with the broker or system-admin role. Here's the receiving end in Express: ```javascript // webhook-server.js const express = require('express'); const crypto = require('crypto'); const app = express(); const SECRET = process.env.ACTUALLYCARE_WEBHOOK_SECRET; // Capture the raw body — the signature is computed over the exact bytes sent, // so verify against those, not a re-serialized object. app.use(express.json({ verify: (req, res, buf) => { req.rawBody = buf; }, })); function verifySignature(req) { // The header looks like "sha256=" const received = (req.get('X-Webhook-Signature') || '').replace(/^sha256=/, ''); const expected = crypto .createHmac('sha256', SECRET) .update(req.rawBody) .digest('hex'); const a = Buffer.from(received, 'hex'); const b = Buffer.from(expected, 'hex'); return a.length === b.length && crypto.timingSafeEqual(a, b); } app.post('/webhooks/actuallycare', (req, res) => { if (!verifySignature(req)) { return res.status(401).send('invalid signature'); } // Respond immediately — deliveries time out after 30 seconds, // and a timeout counts as a failure that triggers retries. res.status(200).send('ok'); // Process asynchronously, after the response is sent. setImmediate(() => handleEvent(req.body)); }); function handleEvent(payload) { // Payload envelope: { "event": "...", "team_id": "...", "timestamp": "...", "data": {...} } // Use exact event names from GET /v1/webhooks/events. if (payload.event.startsWith('lead.')) { console.log(`Lead event ${payload.event} at ${payload.timestamp}`); // e.g. push payload.data into your system right away } } app.listen(3000, () => console.log('Listening on :3000')); ``` Three rules keep webhook handling boring (in the good way): 1. **Verify every delivery.** HMAC-SHA256 hex of the raw JSON body using your webhook secret, compared timing-safe against `X-Webhook-Signature` (after stripping its `sha256=` prefix). 2. **Return 200 fast, work later.** Deliveries time out after 30 seconds. Failures (network errors, or `5xx`/`408`/`429` responses) are retried at 1, 5, and 15 minutes, then given up — other `4xx` responses are not retried, so don't reject events you just haven't handled yet. 3. **Be idempotent.** Delivery is at-least-once — the same event can arrive more than once. Dedupe on the `event` plus `timestamp` pair before acting. More background on the event catalog and delivery semantics lives in [Webhooks](/concepts/webhooks). ## Step 6: Production checklist Before you point this at real data: - **Keys in environment variables.** Never commit `ACTUALLYCARE_API_KEY` or `ACTUALLYCARE_WEBHOOK_SECRET`. Use your platform's secret store in production. - **Backoff on 429 and 5xx.** The client module above retries with exponential backoff; keep that behavior if you replace it. Budget your request rate against the 500-per-15-minutes limit — see [Rate limits](/api/rate-limits). - **Idempotency everywhere.** Check before you create (Step 4), dedupe webhook deliveries (Step 5), and persist sync state so a crashed run resumes instead of re-importing. - **Log requests and error codes.** When something fails at 2 a.m., the envelope's `error.code` plus the request you sent is usually all you need to diagnose it. The [errors page](/api/errors) explains the envelope. - **Set key expirations and rotate.** Expiration is optional at creation, and a key without one never expires — so set one explicitly. Treat a leaked key like a leaked password: delete it in Settings → API Keys and issue a new one. - **Watch your webhook logs.** Delivery logs are visible in the app under Settings → Webhooks. From here, the [endpoint reference](/api/reference) documents every resource this tutorial touched, and the [API vs MCP](/concepts/api-vs-mcp) page explains when a Claude-driven MCP integration is a better fit than REST. --- # Bulk import your data > Bring clients and leads in from your old CRM with a rate-limit-aware import script. > > **Skill:** Terminal script · **Needs:** CSV export from your old CRM Moving from another CRM? This guide walks you through exporting your data as CSV, mapping it onto ActuallyCare's entities, and importing it through the REST API with a script that respects rate limits and never creates duplicates. **Honest scope note:** this is an API-based import — you'll run a small script from your terminal. If you'd rather have help migrating, or you want a hands-off import, reach out to support through [www.actuallycare.com](https://www.actuallycare.com) instead. ## Step 1: Export from your old CRM Every mainstream CRM can export contacts as CSV. Look for **Export**, **Download**, or **Backup** in its settings, and export everything to one or more CSV files with a header row. While you're in there, clean the data — it's far easier before import than after: - Remove blank rows and obvious junk records - Standardize phone formats - Fix or remove invalid email addresses - Merge duplicate rows (same person, two entries) ## Step 2: Decide what each record is ActuallyCare distinguishes between three people-shaped entities — the [data model](/concepts/data-model) page covers them in depth: | Entity | Who belongs there | Import via | |---|---|---| | **Leads** | People in your pipeline you don't represent yet — inquiries, open-house sign-ins, referrals to follow up | `POST /v1/leads` | | **Clients** | People you represent or have represented — active buyers and sellers, and your past-client base | `POST /v1/clients` | | **Contacts** | Everyone else in your sphere (vendors, other agents, lenders) | `POST /v1/contacts` — requires `first_name` and `contact_type` | Most old-CRM exports mix all three together. The simplest approach: add a column to your CSV (or split it into two files) marking each row as a lead or a client. Past clients are clients — they're the relationships your follow-up automations care about. Vendors, escrow officers, and other agents belong in **Contacts** (`POST /v1/contacts` with `first_name` and a `contact_type`). The documented surface also covers Escrows, Listings, and Appointments if you're bringing those over — the [endpoint reference](/api/reference) is the current list of everything importable. ## Step 3: Map your fields CRMs name the same fields differently. Common mappings: | Your old CRM's column | Maps to | |---|---| | First Name, FirstName, Given Name | first name | | Last Name, LastName, Surname | last name | | Email, Email Address, Primary Email | email | | Phone, Mobile, Cell, Primary Phone | phone | | Lead Source, Source, Origin | lead source | | Type, Client Type | client type (`buyer`, `seller`, `both`, `investor`, `landlord`, or `tenant`) | | Notes, Comments, Description | notes | The authoritative field names and which are required come from the generated reference — check [clients](/api/reference/clients) and [leads](/api/reference/leads) before you write your mapping, and adjust the `mapRow` function in Step 4 to match. Don't guess — check the reference for the exact spelling of every field you map. Clients and leads both take `first_name` and `last_name`. Clients need both. A lead saves with less, but it stays a draft until it has a first name plus a phone or email. Clients also take a `client_type`; if you leave it out, every client is saved as a buyer, so map it if your export has one. If your data has a source or tag-like field, stamp every imported row with a marker such as `import-2026-06`. Months later, being able to find exactly what this import created (or archive it, if something went wrong) is worth a lot. ## Step 4: The import script The script below: 1. Reads your CSV 2. Fetches your **existing** records first and indexes them by email, so re-running the script skips rows it already imported 3. Creates one record every 2 seconds — about 450 requests per 15 minutes, safely under the [500-per-15-minutes rate limit](/api/rate-limits) 4. Logs failures to a file so you can fix and re-run just those rows It reuses the `actuallycare.js` API client module from the [custom integration tutorial](/guides/build-custom-integration) — copy that file into the same folder first. Then: ```bash mkdir crm-import && cd crm-import npm init -y npm install csv-parse # copy actuallycare.js (from the custom integration tutorial) into this folder export ACTUALLYCARE_API_KEY="your-64-character-key" ``` ```javascript // import.js // Usage: node import.js [--limit N] const fs = require('fs'); const { parse } = require('csv-parse/sync'); const api = require('./actuallycare'); const sleep = (ms) => new Promise((r) => setTimeout(r, ms)); const PACE_MS = 2000; // 1 request per 2s ≈ 450 per 15 min, under the 500 limit // Adjust to your CSV's column names and the fields documented at // /api/reference/clients and /api/reference/leads. // Clients and leads both take first_name/last_name. // Clients also take client_type (defaults to buyer if omitted). function mapRow(row, resource) { const record = { first_name: row.first_name?.trim(), last_name: row.last_name?.trim(), email: row.email?.toLowerCase().trim() || undefined, phone: row.phone?.trim() || undefined, }; if (resource === 'clients') { record.client_type = row.client_type?.trim().toLowerCase() || 'buyer'; } return record; } // Page through existing records once and index by email, // so we can dedupe before creating anything. // List responses put records at data. with pagination at data.meta. async function fetchExistingEmails(resource) { const emails = new Set(); const limit = 100; for (let page = 1; ; page++) { const data = await api.get(`/${resource}`, { page, limit }); for (const record of data[resource]) { if (record.email) emails.add(record.email.toLowerCase().trim()); } if (!data.meta.hasMore) break; } return emails; } async function run() { const args = process.argv.slice(2); const [csvPath, resource] = args; const limitIdx = args.indexOf('--limit'); const maxRows = limitIdx === -1 ? Infinity : Number(args[limitIdx + 1]); if (!csvPath || !['clients', 'leads'].includes(resource)) { console.error('Usage: node import.js [--limit N]'); process.exit(1); } const rows = parse(fs.readFileSync(csvPath), { columns: true, skip_empty_lines: true, }).slice(0, maxRows); console.log(`Checking existing ${resource} for duplicates...`); const existing = await fetchExistingEmails(resource); console.log(`${existing.size} existing emails indexed. Importing ${rows.length} rows...`); const results = { created: 0, skipped: 0, failed: [] }; for (const [i, row] of rows.entries()) { const record = mapRow(row, resource); if (record.email && existing.has(record.email)) { results.skipped++; console.log(`[${i + 1}/${rows.length}] skip (exists): ${record.email}`); continue; } try { await api.post(`/${resource}`, record); results.created++; if (record.email) existing.add(record.email); console.log(`[${i + 1}/${rows.length}] created: ${record.email || record.last_name || record.first_name}`); } catch (err) { results.failed.push({ row, code: err.code, message: err.message }); console.error(`[${i + 1}/${rows.length}] FAILED: ${err.code} - ${err.message}`); } await sleep(PACE_MS); // stay under the rate limit } console.log(`\nDone. Created ${results.created}, skipped ${results.skipped}, failed ${results.failed.length}.`); if (results.failed.length > 0) { fs.writeFileSync('failed-rows.json', JSON.stringify(results.failed, null, 2)); console.log('Failed rows written to failed-rows.json — fix and re-run.'); } } run().catch((err) => { console.error('Import aborted:', err); process.exit(1); }); ``` A few design notes: - **Dedupe before create.** The API doesn't know your old CRM's record IDs, so email is the stable key. Skipping existing emails makes the script safe to re-run after a crash or a partial import. - **The list doesn't show everything.** For clients, the API also refuses an email that already belongs to any contact in your brokerage, even one you can't see in your list. Those rows fail with `409 CONFLICT` — that's a duplicate, not a data problem. Leads have no server-side duplicate check, and archived leads don't appear in the list, so re-running can re-create a lead you archived. - **Pacing matters.** At one create per 2 seconds, a 1,000-row import takes about 35 minutes. That's intentional — bursting through the rate limit gets you `429` responses ([rate limits](/api/rate-limits)) and a forced wait anyway. Let it run in the background. - **Failures are data.** A failed row usually means a missing required field or a malformed value. The `error.code` in `failed-rows.json` tells you which. ## Step 5: Dry run with 5 rows Never run the whole file first. Import five rows: ```bash node import.js my-export.csv clients --limit 5 ``` Then open [app.actuallycare.com](https://app.actuallycare.com) and check those five records in the Clients section. Verify: - Names landed in the right fields (not reversed, no stray whitespace) - Emails and phones look right - Your source/tag marker is present, if you mapped one If something's off, fix `mapRow`, archive the test records in the app, and dry-run again. Iterating on 5 rows costs seconds; discovering a mapping bug after 2,000 rows costs an afternoon. ## Step 6: Run the full import Once the dry run looks right: ```bash node import.js my-export.csv clients node import.js my-leads.csv leads ``` The script prints progress per row and a summary at the end. If any rows fail, fix the data in `failed-rows.json` (or in your CSV), then re-run — the dedupe check means rows this script already imported are skipped. Rows that fail with `409 CONFLICT` are already in your brokerage as contacts, so there's nothing to fix for those. ## Step 7: Verify in the app When the script finishes, confirm the migration in the app, not just in the terminal: 1. **Counts match.** The Clients and Leads sections should show roughly your old CRM's totals (minus skipped duplicates and held-aside rows). The script's `created` plus `skipped` numbers should account for every row. 2. **Spot-check 10 random records.** Open a few clients and leads you know well — right name, right email, right phone. 3. **Search works.** Search for a couple of names and emails; if search finds them, the fields landed where the app expects them. ## Import checklist **Before** - Export and clean your CSV (blanks, duplicates, bad emails) - Decide lead vs client for every row - Check field names against [the reference](/api/reference) - Create an API key with the scopes the import needs — for example `{"clients":["read","write"],"leads":["read","write"]}`; `write` covers creating and updating, and the import never needs `delete` — and set `ACTUALLYCARE_API_KEY` **During** - Dry-run 5 rows and verify in the app before the full run - Watch the log for repeated failures — stop and fix rather than letting hundreds of rows fail the same way - Keep the pacing — don't "speed it up" past the rate limit **After** - Verify counts, spot-check records, test search - Re-run failed rows from `failed-rows.json` - Keep your original CSV export until you're confident — it's your backup --- # Set up webhooks > Register a webhook, verify signatures, and process events reliably. > > **Skill:** Developer · **Needs:** Broker or system-admin role Webhooks push events to your application the moment they happen — a lead comes in, an escrow status changes, an appointment is booked — instead of you polling the API. This guide takes you from zero to a verified, retry-safe webhook receiver. For the conceptual background (what the catalog covers, payload envelope, delivery semantics), see [Webhooks](/concepts/webhooks). > **Who can do this:** webhook management (creating webhooks, listing the event catalog, reading delivery logs) requires a **broker** or **system-admin** role. Agents on a team will get `403` on every `/v1/webhooks` endpoint — ask your broker to set the webhook up, or to run these steps with you. > > **Auth:** the `/v1/webhooks` endpoints accept a **JWT bearer token only** (from [`POST /v1/auth/login`](/api/authentication)) — an `X-API-Key` header gets `401` here. The examples below assume the token is in `$ACTUALLYCARE_JWT`. ## Step 1: Discover the events you can subscribe to The event catalog is self-documenting. Ask the API what's available: ```bash curl "https://api.actuallycare.com/v1/webhooks/events" \ -H "Authorization: Bearer $ACTUALLYCARE_JWT" ``` The response uses the standard envelope, with `data` containing the full catalog of event names you can subscribe to, following an `entity.action` naming pattern (`escrow.*`, `lead.*`, `client.*`, `listing.*`, `appointment.*`, `care_status.*`, and more). There's also a grouped view: ```bash curl "https://api.actuallycare.com/v1/webhooks/events/categories" \ -H "Authorization: Bearer $ACTUALLYCARE_JWT" ``` Pick the specific events you care about, or subscribe to `all` if you want everything. ## Step 2: Register your webhook You can register in the app or via the API. Either way you'll provide three things: the URL to deliver to, the events to subscribe to, and a secret (minimum 10 characters) used to sign every delivery. ### In the app 1. Open **Settings → Webhooks** (direct link: `https://app.actuallycare.com/settings?tab=webhooks`). 2. Add a webhook with your endpoint URL, the events you chose in Step 1, and a secret. The Webhooks tab is available to broker and system-admin roles. A webhook belongs to the brokerage of the person who created it. If that person is on a team, it receives that team's events; if not, it receives every event in the brokerage. ### Via the API ```bash curl -X POST "https://api.actuallycare.com/v1/webhooks" \ -H "Authorization: Bearer $ACTUALLYCARE_JWT" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-app.com/webhooks/actuallycare", "events": ["lead.created", "escrow.updated"], "secret": "a-long-random-secret-string" }' ``` Use exact event names from the Step 1 catalog — names aren't checked when you register, so a misspelled name is accepted and simply never fires. The response envelope's `data` contains your new webhook, including its `id` — keep that for managing it later (`PUT /v1/webhooks/:id`, `DELETE /v1/webhooks/:id`, and the logs endpoint in Step 7). The response never includes the secret (`"has_secret": true` confirms one is set), and neither does any later response. Generate the secret randomly (for example `openssl rand -hex 32`) and store it in an environment variable on your server. You'll need it to verify signatures next. ## Step 3: Receive and verify deliveries Every delivery is an HTTP POST with this payload envelope: ```json { "event": "lead.created", "team_id": "...", "timestamp": "2026-06-11T17:42:11.000Z", "data": {} } ``` And these headers: | Header | Contents | |---|---| | `X-Webhook-Signature` | `sha256=` followed by the HMAC-SHA256 hex digest of the JSON body, keyed with your secret (e.g. `sha256=3f5a…`). | | `X-Webhook-Event` | The event name, so you can route before parsing the body. | | `X-Webhook-Timestamp` | The same value as `timestamp` in the body — set when the event is first sent, unchanged on retries. | **Always verify the signature** with a timing-safe comparison, computed over the raw request body exactly as received — re-serializing the parsed JSON can change byte order or whitespace and break the match. ### Express ```javascript const express = require('express'); const crypto = require('crypto'); const app = express(); const SECRET = process.env.ACTUALLYCARE_WEBHOOK_SECRET; // Keep the raw bytes for signature verification. app.use(express.json({ verify: (req, res, buf) => { req.rawBody = buf; }, })); function verifySignature(req) { // Header format: "sha256=" const received = (req.get('X-Webhook-Signature') || '').replace(/^sha256=/, ''); const expected = crypto .createHmac('sha256', SECRET) .update(req.rawBody) .digest('hex'); const a = Buffer.from(received, 'hex'); const b = Buffer.from(expected, 'hex'); return a.length === b.length && crypto.timingSafeEqual(a, b); } app.post('/webhooks/actuallycare', (req, res) => { if (!verifySignature(req)) { return res.status(401).send('invalid signature'); } res.status(200).send('ok'); // acknowledge first setImmediate(() => processEvent(req.body)); // work after responding }); function processEvent(payload) { console.log(`${payload.event} for team ${payload.team_id} at ${payload.timestamp}`); } app.listen(3000); ``` ### Flask ```python import hashlib import hmac import os from flask import Flask, request app = Flask(__name__) SECRET = os.environ["ACTUALLYCARE_WEBHOOK_SECRET"].encode() def verify_signature(req): # Header format: "sha256=" received = req.headers.get("X-Webhook-Signature", "").removeprefix("sha256=") expected = hmac.new(SECRET, req.get_data(), hashlib.sha256).hexdigest() return hmac.compare_digest(received, expected) @app.route("/webhooks/actuallycare", methods=["POST"]) def webhook(): if not verify_signature(request): return "invalid signature", 401 payload = request.get_json() # Hand off to a queue or worker — don't do slow work in the request. enqueue_for_processing(payload) return "ok", 200 ``` ## Step 4: Respond fast Deliveries time out after **30 seconds**, and a timeout counts as a failed delivery. Don't make ActuallyCare wait while you update your database, call another API, or send an email. The pattern: validate the signature, return `200`, then do the real work asynchronously — `setImmediate` in Node, a task queue or background worker in Python. Both examples above follow it. ## Step 5: Handle retries idempotently Delivery is **at-least-once**. A failed delivery — a network error, or a `5xx`, `408`, or `429` response from your endpoint — is retried at 1, 5, and 15 minutes after the initial attempt (up to 4 attempts total), then given up. Other `4xx` responses are treated as a rejection and are **not** retried, so don't return `400` for events you simply haven't handled yet. Retries survive server restarts; deactivating the webhook cancels any pending retries. The delivery logs (Step 7) show every attempt. At-least-once means your endpoint **will** occasionally see the same event twice — for example if your handler responded slowly and the delivery timed out after you'd already started processing. A retried delivery carries the same `X-Webhook-Timestamp` header and signature as the original, so deduplicate on the **signature header value** — unlike `event` + `timestamp`, it can't collide when two different records fire the same event in the same instant: ```javascript const seen = new Set(); // use a database or cache with a TTL in production function handleDelivery(req) { const key = req.get('X-Webhook-Signature'); // stable across retries, can't collide if (seen.has(key)) return; // already handled — a retry, skip it seen.add(key); processEvent(req.body); // ...actual processing } ``` An in-memory set works for a single process; use your database or a shared cache once you run more than one instance. ## Step 6: Test locally Webhook URLs must be reachable from the internet, but you can develop against your laptop with any tunneling tool (ngrok, Cloudflare Tunnel, or similar): 1. Start your receiver locally (port 3000 in the Express example). 2. Start a tunnel to that port — the tool gives you a public HTTPS URL. 3. Register that URL as a webhook (Step 2). You can register a second, temporary webhook just for development and deactivate it when you're done. 4. Trigger a real event — create a test lead in the app — and watch the delivery arrive in your terminal. When you change tunnels (most tools issue a new URL per session), update the webhook with `PUT /v1/webhooks/:id` or in Settings → Webhooks. ## Step 7: Monitor deliveries Two places to look when you think a delivery went missing: - **In the app:** Settings → Webhooks shows delivery logs per webhook — what was sent, when, and whether your endpoint accepted it. - **Via the API:** ```bash curl "https://api.actuallycare.com/v1/webhooks/WEBHOOK_ID/logs" \ -H "Authorization: Bearer $ACTUALLYCARE_JWT" ``` If deliveries are failing, the usual suspects in order: your endpoint isn't returning 200 within 30 seconds, the URL isn't publicly reachable (firewall, expired tunnel), or your signature check is rejecting valid payloads because it verified a re-serialized body instead of the raw bytes. For a full integration that combines webhooks with the REST API, continue to [Build a custom integration](/guides/build-custom-integration).