Skip to content
For developers

Escrows API

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

Last updated

Transactions from contract to close — create, list, update, and manage escrows.

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

List escrows#

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#

ParameterInTypeRequiredDescription
statusqueryenumNoFilter by escrow status (case-insensitive) · One of: active, pending, closed, cancelled
searchquerystringNoFree-text search across property address and display ID
minPricequerynumberNoMinimum purchase price · Min: 0
maxPricequerynumberNoMaximum purchase price · Min: 0
closingDateStartquerystringNoEarliest closing date (ISO 8601) · Format: date
closingDateEndquerystringNoLatest closing date (ISO 8601) · Format: date
archivedquerybooleanNoInclude archived escrows instead of active ones · Default: false
sortquerystringNoSort column · Default: "created_at"
orderqueryenumNoSort direction · One of: asc, desc · Default: "desc"
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 escrow list with aggregate 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/escrows" \
  -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/escrows

Enter your API key to send.

Example response (200)#

{
  "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": "[email protected]",
            "phone": "(555) 123-4567"
          }
        ],
        "sellers": [
          {
            "name": "John Doe",
            "email": "[email protected]",
            "phone": "(555) 123-4567"
          }
        ],
        "listing_agent": {
          "name": "Alex Rivera",
          "email": "[email protected]",
          "phone": "+1 661 555 0123",
          "license": "DRE #02209852",
          "brokerage": "Associated Real Estate"
        },
        "selling_agent": {
          "name": "Alex Rivera",
          "email": "[email protected]",
          "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
    }
  }
}

Create an escrow#

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#

FieldTypeRequiredDescription
property_addressstringYesStreet address of the property in escrow
purchase_pricenumberNoPurchase price in USD
escrow_statusenumNoInitial escrow status (defaults to active) · One of: active, pending, closed, cancelled · Default: "active"
acceptance_datestringNoOffer acceptance date (ISO 8601) · Format: date
closing_datestringNoExpected closing date (ISO 8601) · Format: date
citystringNoCity name
statestringNoState abbreviation (e.g. CA)
zip_codestringNoZIP code
earnest_money_depositnumberNoEarnest money deposit amount in USD
commission_percentagenumberNoTotal commission rate as a percentage of purchase price
my_commissionnumberNoThe authenticated agent's commission amount in USD
representation_typestringNoWhich side the agent represents (e.g. buyer, seller, dual)
escrow_companystringNoEscrow company handling the transaction
title_companystringNoTitle company name
buyersarray of objectsNoBuyer parties to attach at creation
buyers[].namestringNoBuyer's full name
buyers[].emailstringNoBuyer's email address
sellersarray of objectsNoSeller parties to attach at creation
sellers[].namestringNoSeller's full name
sellers[].emailstringNoSeller's email address

Responses#

StatusMeaningWhat to do
201Escrow 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/escrows" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "property_address": "123 Main St, Bakersfield, CA 93301"
  }'

Example response (201)#

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "displayId": "ESC-2026-0001"
  }
}

Get an escrow#

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#

ParameterInTypeRequiredDescription
idpathstringYesEscrow UUID, display ID, or numeric sequence

Responses#

StatusMeaningWhat to do
200The escrow
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/escrows/: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/escrows/

Enter your API key to send.

Example response (200)#

{
  "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": "[email protected]",
        "phone": "(555) 123-4567"
      }
    ],
    "sellers": [
      {
        "name": "John Doe",
        "email": "[email protected]",
        "phone": "(555) 123-4567"
      }
    ],
    "listing_agent": {
      "name": "Alex Rivera",
      "email": "[email protected]",
      "phone": "+1 661 555 0123",
      "license": "DRE #02209852",
      "brokerage": "Associated Real Estate"
    },
    "selling_agent": {
      "name": "Alex Rivera",
      "email": "[email protected]",
      "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"
  }
}

Update an escrow#

PUT/v1/escrows/{id}

Updates escrow fields. Pass the current version to enable optimistic-locking; a stale version returns 409.

Parameters#

ParameterInTypeRequiredDescription
idpathstringYes

Request body#

FieldTypeRequiredDescription
purchase_pricenumberNoPurchase price in USD
closing_datestringNoExpected closing date (ISO 8601) · Format: date
escrow_statusenumNoUpdated escrow status · One of: active, pending, closed, cancelled
versionintegerNoCurrent record version for optimistic locking

Responses#

StatusMeaningWhat to do
200Escrow 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
409Version conflict (record changed since you read it) or business-rule violationRe-fetch the current state, then decide deliberately; don't blind-retry
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/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
  }'

Example response (200)#

{
  "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": "[email protected]",
        "phone": "(555) 123-4567"
      }
    ],
    "sellers": [
      {
        "name": "John Doe",
        "email": "[email protected]",
        "phone": "(555) 123-4567"
      }
    ],
    "listing_agent": {
      "name": "Alex Rivera",
      "email": "[email protected]",
      "phone": "+1 661 555 0123",
      "license": "DRE #02209852",
      "brokerage": "Associated Real Estate"
    },
    "selling_agent": {
      "name": "Alex Rivera",
      "email": "[email protected]",
      "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"
}

Delete an escrow#

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#

ParameterInTypeRequiredDescription
idpathstringYes

Responses#

StatusMeaningWhat to do
200Escrow deleted
400Escrow is not archived — archive it before deletingFix 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 DELETE "https://api.actuallycare.com/v1/escrows/:id" \
  -H "X-API-Key: YOUR_API_KEY"

Example response (200)#

{
  "success": true,
  "message": "Escrow permanently deleted",
  "data": {
    "displayId": "ESC-2026-0847"
  }
}

Archive an escrow#

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#

ParameterInTypeRequiredDescription
idpathstringYes

Responses#

StatusMeaningWhat to do
200Escrow archived
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/escrows/:id/archive" \
  -H "X-API-Key: YOUR_API_KEY"

Example response (200)#

{
  "success": true,
  "message": "Escrow archived successfully",
  "data": {
    "displayId": "ESC-2026-0847"
  }
}

Restore an archived escrow#

PATCH/v1/escrows/{id}/restore

Returns an archived escrow to the active list.

Parameters#

ParameterInTypeRequiredDescription
idpathstringYes

Responses#

StatusMeaningWhat to do
200Escrow restored
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/escrows/:id/restore" \
  -H "X-API-Key: YOUR_API_KEY"

Example response (200)#

{
  "success": true,
  "message": "Escrow restored successfully",
  "data": {
    "displayId": "ESC-2026-0847"
  }
}

Get an escrow's timeline#

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#

ParameterInTypeRequiredDescription
idpathstringYes

Responses#

StatusMeaningWhat to do
200Timeline milestones in display order
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/escrows/:id/timeline" \
  -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/escrows//timeline

Enter your API key to send.

Example response (200)#

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