Skip to content
For developers

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.

Last updated

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 <token>. These endpoints are JWT-only (API keys get 401): the /auth session and profile endpoints, /api-keys, /webhooks, and authenticated /billing.
  • First request:
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.
  • Spec: openapi.json · Errors · 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.
  • Tool index: 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.

Machine-readable docs#

llms.txt · llms-full.txt · append .md to any page URL · .well-known/ai.json