Skip to content
For developers

Leads API

REST endpoints for leads — request and response reference with examples.

Last updated

Lead capture and qualification, including converting a lead into a client.

Base URL: https://api.actuallycare.com/v1 · Errors use the standard envelope — see Errors.

List all leads#

GET/v1/leads

Returns paginated list of prospective client leads. Default page size 25 (max 100).

Parameters#

ParameterInTypeRequiredDescription
statusqueryenumNoOne of: new, contacted, qualified, unqualified, converted, lost
interest_levelqueryenumNoOne of: hot, warm, cold
pagequeryintegerNoPage number for pagination · Default: 1 · Min: 1
limitqueryintegerNoNumber of items per page (default 25, max 100) · Default: 25 · Max: 100 · Min: 1

Responses#

StatusMeaningWhat to do
200Paginated list — records under data.leads, pagination under data.meta (the envelope also carries data.stats and data.cursors)
401Authentication requiredCheck the X-API-Key header (or bearer token). See Authentication
429Rate 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
500Internal server errorRetry with exponential backoff. See Errors

Example request#

cURL
curl "https://api.actuallycare.com/v1/leads" \
  -H "X-API-Key: YOUR_API_KEY"

Try it

Sends a real request from your browser to the API, as you. GET requests only read data.

Kept in this browser tab only, and filled into the samples on this page.
GET /v1/leads

Enter your API key to send.

Example response (200)#

{
  "success": true,
  "data": {
    "leads": [
      {
        "id": "f2b8d4a6-3c5e-4f7a-9b1d-8e0c6a4f2d9b",
        "name": "Rachel Kim",
        "email": "[email protected]",
        "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"
}

Create new lead#

POST/v1/leads

Request body#

FieldTypeRequiredDescription
namestringYesLead's full name
emailstringNoLead's email address
phonestringNoLead's phone number
sourcestringNoHow the lead was acquired (e.g. Website Form, Zillow)
lead_typeenumNoWhether the lead is a buyer, seller, or both · One of: buyer, seller, both

Responses#

StatusMeaningWhat to do
201Lead created
400Invalid request dataFix the request; error.message and error.details name the problem. Don't retry unchanged
401Authentication requiredCheck the X-API-Key header (or bearer token). See Authentication
429Rate 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
500Internal server errorRetry with exponential backoff. See Errors

Example request#

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"
  }'

Example response (201)#

{
  "success": true,
  "data": {
    "id": "f2b8d4a6-3c5e-4f7a-9b1d-8e0c6a4f2d9b",
    "name": "Rachel Kim",
    "email": "[email protected]",
    "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"
}

Get lead by ID#

GET/v1/leads/{id}

Parameters#

ParameterInTypeRequiredDescription
idpathstringYesUnique identifier (UUID) · Format: uuid

Responses#

StatusMeaningWhat to do
200Lead found
401Authentication requiredCheck the X-API-Key header (or bearer token). See Authentication
404Resource not foundCheck the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See Errors
429Rate 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
500Internal server errorRetry with exponential backoff. See Errors

Example request#

cURL
curl "https://api.actuallycare.com/v1/leads/:id" \
  -H "X-API-Key: YOUR_API_KEY"

Try it

Sends a real request from your browser to the API, as you. GET requests only read data.

Kept in this browser tab only, and filled into the samples on this page.
GET /v1/leads/

Enter your API key to send.

Example response (200)#

{
  "success": true,
  "data": {
    "id": "f2b8d4a6-3c5e-4f7a-9b1d-8e0c6a4f2d9b",
    "name": "Rachel Kim",
    "email": "[email protected]",
    "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"
}

Update lead#

PUT/v1/leads/{id}

Parameters#

ParameterInTypeRequiredDescription
idpathstringYesUnique identifier (UUID) · Format: uuid

Request body#

FieldTypeRequiredDescription
statusstringNoLead status (new, contacted, qualified, unqualified, converted, lost)
interest_levelstringNoLead's level of interest (hot, warm, cold)
versionintegerNoCurrent record version for optimistic locking

Responses#

StatusMeaningWhat to do
200Lead updated
400Invalid request dataFix the request; error.message and error.details name the problem. Don't retry unchanged
401Authentication requiredCheck the X-API-Key header (or bearer token). See Authentication
404Resource not foundCheck the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See Errors
429Rate 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
500Internal server errorRetry with exponential backoff. See Errors

Example request#

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
  }'

Example response (200)#

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Jane Smith",
    "email": "[email protected]",
    "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"
}

Delete lead#

DELETE/v1/leads/{id}

Parameters#

ParameterInTypeRequiredDescription
idpathstringYesUnique identifier (UUID) · Format: uuid

Responses#

StatusMeaningWhat to do
200Lead deleted
401Authentication requiredCheck the X-API-Key header (or bearer token). See Authentication
404Resource not foundCheck the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See Errors
429Rate 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
500Internal server errorRetry with exponential backoff. See Errors

Example request#

cURL
curl -X DELETE "https://api.actuallycare.com/v1/leads/:id" \
  -H "X-API-Key: YOUR_API_KEY"

Example response (200)#

{
  "success": true,
  "data": {},
  "timestamp": "2026-07-15T14:32:10.000Z"
}

Convert lead to client#

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#

ParameterInTypeRequiredDescription
idpathstringYesUnique identifier (UUID) · Format: uuid

Request body#

FieldTypeRequiredDescription
clientTypeenumNoClient type for the new client record · One of: buyer, seller, both · Default: "buyer"

Responses#

StatusMeaningWhat to do
200Lead converted successfully
401Authentication requiredCheck the X-API-Key header (or bearer token). See Authentication
404Resource not foundCheck the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See Errors
429Rate 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
500Internal server errorRetry with exponential backoff. See Errors

Example request#

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"
  }'

Example response (200)#

{
  "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"
}