Skip to content
For developers

Listings API

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

Last updated

Property inventory — create, list, update, and remove listings.

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

List all property listings#

GET/v1/listings

Returns paginated list of property listings with optional filtering. Default page size 25 (max 100).

Parameters#

ParameterInTypeRequiredDescription
statusqueryenumNoOne of: active, pending, sold, withdrawn, expired
minPricequerynumberNo
maxPricequerynumberNo
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.listings, pagination under data.meta (the envelope also carries data.stats aggregates)
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/listings" \
  -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/listings

Enter your API key to send.

Example response (200)#

{
  "success": true,
  "data": {
    "listings": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "mls_number": "ML81992437",
        "address": "456 Oak Ave, Tehachapi, CA 93561",
        "city": "Tehachapi",
        "state": "CA",
        "zip_code": "93561",
        "list_price": 425000,
        "status": "active",
        "property_type": "single_family",
        "bedrooms": 4,
        "bathrooms": 3,
        "square_feet": 2800
      }
    ],
    "meta": {
      "page": 1,
      "limit": 25,
      "total": 87,
      "totalPages": 4,
      "hasMore": true
    }
  },
  "timestamp": "2026-07-01T22:45:03.120Z"
}

Create new listing#

POST/v1/listings

Request body#

FieldTypeRequiredDescription
addressstringYesStreet address of the property
list_pricenumberYesListing price in USD
property_typestringNoProperty type (e.g. single_family, condo, townhouse, multi_family, land, commercial)
bedroomsintegerNoNumber of bedrooms
bathroomsnumberNoNumber of bathrooms

Responses#

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

Example response (201)#

{
  "success": true,
  "data": {
    "id": "8c5e2a9f-4d7b-4e3a-b1c8-6f0d9e2a5c74",
    "address": "1847 Cerro Vista Dr, Bakersfield, CA 93306",
    "list_price": 389000,
    "status": "active",
    "property_type": "single_family",
    "bedrooms": 3,
    "bathrooms": 2,
    "version": 1,
    "created_at": "2026-07-01T22:46:18.402Z",
    "updated_at": "2026-07-01T22:46:18.402Z"
  },
  "timestamp": "2026-07-01T22:46:18.410Z"
}

Get listing by ID#

GET/v1/listings/{id}

Parameters#

ParameterInTypeRequiredDescription
idpathstringYesUnique identifier (UUID) · Format: uuid

Responses#

StatusMeaningWhat to do
200Listing 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/listings/: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/listings/

Enter your API key to send.

Example response (200)#

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "mls_number": "ML81992437",
    "address": "456 Oak Ave, Tehachapi, CA 93561",
    "city": "Tehachapi",
    "state": "CA",
    "zip_code": "93561",
    "list_price": 425000,
    "status": "active",
    "property_type": "single_family",
    "bedrooms": 4,
    "bathrooms": 3,
    "square_feet": 2800,
    "year_built": 2010,
    "version": 3
  },
  "timestamp": "2026-07-01T22:47:00.115Z"
}

Update listing#

PUT/v1/listings/{id}

Parameters#

ParameterInTypeRequiredDescription
idpathstringYesUnique identifier (UUID) · Format: uuid

Request body#

FieldTypeRequiredDescription
list_pricenumberNoListing price in USD
statusstringNoListing status (active, pending, sold, withdrawn, expired)
versionintegerNoCurrent record version for optimistic locking

Responses#

StatusMeaningWhat to do
200Listing 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/listings/:id" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "list_price": 450000,
    "status": "your-status",
    "version": 3
  }'

Example response (200)#

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "mls_number": "ML123456",
    "address": "456 Oak Ave, Tehachapi, CA 93561",
    "city": "Tehachapi",
    "state": "CA",
    "zip_code": "93561",
    "list_price": 425000,
    "status": "active",
    "property_type": "single_family",
    "bedrooms": 4,
    "bathrooms": 3,
    "square_feet": 2800,
    "lot_size": 0.5,
    "year_built": 2010,
    "description": "example description",
    "listing_date": "2026-07-15",
    "expiration_date": "2026-07-15",
    "photos": [
      "example photos"
    ],
    "virtual_tour_url": "example virtual tour url",
    "showing_instructions": "example showing instructions",
    "days_on_market": 1,
    "price_per_sqft": 1800,
    "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 listing#

DELETE/v1/listings/{id}

Permanently deletes a listing (hard delete — only allowed after the listing has been archived)

Parameters#

ParameterInTypeRequiredDescription
idpathstringYesUnique identifier (UUID) · Format: uuid

Responses#

StatusMeaningWhat to do
200Listing 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/listings/:id" \
  -H "X-API-Key: YOUR_API_KEY"

Example response (200)#

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