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
Last updated
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:
curl "https://api.actuallycare.com/v1/listings" \
-H "X-API-Key: YOUR_API_KEY"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`);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"){
"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#
- Sign in at app.actuallycare.com and open Settings → API Keys (direct link: 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_ACTIVEon every endpoint (including key creation) until approved. - 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.
- 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 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. When something goes wrong, success flips to false and an error object explains why — see 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 for how to choose.
Import the API into Postman or Insomnia#
The whole API is described in one OpenAPI file. Download 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 for trying endpoints in the browser.
Where next#
| You want to | Go to |
|---|---|
| Understand API keys, JWTs, and 401 vs 403 | Authentication |
| Page through large result sets | Pagination |
| Handle errors and retries properly | Errors |
| Stay under the request limits | Rate limits |
| Browse every endpoint, parameter, and field | API reference |
| React to changes instead of polling | Webhooks |