Skip to content
For developers
View as Markdown

Escrows API

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

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; GET /escrows overrides this to 20 at the controller level) · Default: 25 · Max: 100 · Min: 1

Responses#

StatusMeaning
200Paginated escrow list with aggregate stats
400Invalid request data
401Authentication required
429Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.
500Internal server error

Example request#

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

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#

StatusMeaning
201Escrow created
400Invalid request data
401Authentication required
429Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.
500Internal server error

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#

StatusMeaning
200The escrow
401Authentication required
404Resource not found
429Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.
500Internal server error

Example request#

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

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#

StatusMeaning
200Escrow updated
400Invalid request data
401Authentication required
404Resource not found
409Version conflict (record changed since you read it) or business-rule violation
429Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.
500Internal server error

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#

StatusMeaning
200Escrow deleted
400Escrow is not archived — archive it before deleting
401Authentication required
404Resource not found
429Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.
500Internal server error

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#

StatusMeaning
200Escrow archived
401Authentication required
404Resource not found
429Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.
500Internal server error

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#

StatusMeaning
200Escrow restored
401Authentication required
404Resource not found
429Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.
500Internal server error

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#

StatusMeaning
200Timeline milestones in display order
401Authentication required
404Resource not found
429Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.
500Internal server error

Example request#

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

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