Skip to content
For developers

Contacts API

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

Last updated

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 — see Errors.

List contacts#

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#

ParameterInTypeRequiredDescription
searchquerystringNoFuzzy search across full name, first name, last name, and email
typequerystringNoFilter by contact type
archivedquerybooleanNoShow archived contacts instead of active ones · Default: false
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 contact list with stats
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 "https://api.actuallycare.com/v1/contacts" \
  -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/contacts

Enter your API key to send.

Example response (200)#

{
  "success": true,
  "data": {
    "contacts": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "first_name": "Jordan",
        "last_name": "Lee",
        "full_name": "example full name",
        "email": "[email protected]",
        "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
    }
  }
}

Create a contact#

POST/v1/contacts

Adds a contact to the authenticated user's database. First name and contact type are required.

Request body#

FieldTypeRequiredDescription
first_namestringYesContact's first name
last_namestringNoContact's last name
contact_typeenumYesRole 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
emailstringNoContact's email address · Format: email
phonestringNoContact's phone number
companystringNoCompany or organization the contact belongs to
license_numberstringNoProfessional license number (e.g. for agents, lenders, inspectors)
street_addressstringNoStreet address
citystringNoCity name
statestringNoTwo-letter state code
zip_codestringNoZIP code
notesstringNoFree-form notes about the contact
tagsarray of stringsNoFree-form labels for grouping and filtering contacts

Responses#

StatusMeaningWhat to do
201Contact 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/contacts" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jordan",
    "contact_type": "buyer"
  }'

Example response (201)#

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Jordan",
    "last_name": "Lee",
    "full_name": "example full name",
    "email": "[email protected]",
    "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"
  }
}

Search contacts#

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#

ParameterInTypeRequiredDescription
namequerystringNoCase-insensitive substring match on full name
emailquerystringNoCase-insensitive substring match on email
rolequerystringNoFilter by assigned contact role name
limitqueryintegerNoDefault: 50 · Max: 100 · Min: 1

Responses#

StatusMeaningWhat to do
200Matching contacts
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 "https://api.actuallycare.com/v1/contacts/search" \
  -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/contacts/search

Enter your API key to send.

Example response (200)#

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "first_name": "Jordan",
      "last_name": "Lee",
      "full_name": "example full name",
      "email": "[email protected]",
      "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
}

Get a contact#

GET/v1/contacts/{id}

Parameters#

ParameterInTypeRequiredDescription
idpathstringYesUnique identifier (UUID) · Format: uuid

Responses#

StatusMeaningWhat to do
200The contact
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/contacts/: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/contacts/

Enter your API key to send.

Example response (200)#

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Jordan",
    "last_name": "Lee",
    "full_name": "example full name",
    "email": "[email protected]",
    "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"
  }
}

Update a contact#

PUT/v1/contacts/{id}

Updates contact fields. All fields are optional; only the fields you send are changed.

Parameters#

ParameterInTypeRequiredDescription
idpathstringYesUnique identifier (UUID) · Format: uuid

Request body#

FieldTypeRequiredDescription
first_namestringNoContact's first name
last_namestringNoContact's last name
emailstringNoContact's email address · Format: email
phonestringNoContact's phone number
contact_typestringNoRole this contact plays in transactions (e.g. buyer, seller, lender, inspector)
contact_statusstringNoWorkflow status of the contact (free-form, e.g. active, lead, client, past_client)
companystringNoCompany or organization the contact belongs to
street_addressstringNoStreet address
citystringNoCity name
statestringNoTwo-letter state code
zip_codestringNoZIP code
notesstringNoFree-form notes about the contact
tagsarray of stringsNoFree-form labels for grouping and filtering contacts

Responses#

StatusMeaningWhat to do
200Contact 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/contacts/:id" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jordan",
    "last_name": "Lee",
    "email": "[email protected]",
    "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"
    ]
  }'

Example response (200)#

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Jordan",
    "last_name": "Lee",
    "full_name": "example full name",
    "email": "[email protected]",
    "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"
  }
}

Delete a contact#

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#

ParameterInTypeRequiredDescription
idpathstringYesUnique identifier (UUID) · Format: uuid

Responses#

StatusMeaningWhat to do
200Contact deleted (response echoes the deleted contact record)
401Authentication requiredCheck the X-API-Key header (or bearer token). See Authentication
403Caller lacks permission to delete this contactCheck 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
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/contacts/:id" \
  -H "X-API-Key: YOUR_API_KEY"

Example response (200)#

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Jordan",
    "last_name": "Lee",
    "full_name": "example full name",
    "email": "[email protected]",
    "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"
  }
}

Archive a contact#

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#

ParameterInTypeRequiredDescription
idpathstringYesUnique identifier (UUID) · Format: uuid

Responses#

StatusMeaningWhat to do
200Contact archived (response is the updated contact record)
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 PATCH "https://api.actuallycare.com/v1/contacts/:id/archive" \
  -H "X-API-Key: YOUR_API_KEY"

Example response (200)#

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Jordan",
    "last_name": "Lee",
    "full_name": "example full name",
    "email": "[email protected]",
    "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"
  }
}

Restore an archived contact#

PATCH/v1/contacts/{id}/restore

Returns an archived contact to the active list.

Parameters#

ParameterInTypeRequiredDescription
idpathstringYesUnique identifier (UUID) · Format: uuid

Responses#

StatusMeaningWhat to do
200Contact restored (response is the updated contact record)
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 PATCH "https://api.actuallycare.com/v1/contacts/:id/restore" \
  -H "X-API-Key: YOUR_API_KEY"

Example response (200)#

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Jordan",
    "last_name": "Lee",
    "full_name": "example full name",
    "email": "[email protected]",
    "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"
  }
}

Extract contact fields from a business-card photo#

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).

Responses#

StatusMeaningWhat to do
200Fields extracted from the card, for the agent to review
400Upload 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
401Authentication requiredCheck the X-API-Key header (or bearer token). See Authentication
403AI is disabled for this brokerage, or the agent has not accepted the AI disclosureCheck 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
422Invalid request dataFix the value error.message names. Don't retry unchanged
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/contacts/scan-card" \
  -H "X-API-Key: YOUR_API_KEY"

Example response (200)#

{
  "success": true,
  "data": {
    "isBusinessCard": true,
    "firstName": "example firstName",
    "lastName": "example lastName",
    "company": "example company",
    "jobTitle": "example jobTitle",
    "email": "[email protected]",
    "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": {}
  }
}