Skip to content
Land Insights Land Insights

Add a region to the user's saved markets

POST
/api/public/v1/markets/
 
curl --request POST \
  --url https://app-api.landinsights.co/api/public/v1/markets/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "region_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "status": "example" }'

Saves a market (county or ZIP region) to the authenticated user’s market list. Look up the region_id from the Market Stats response (its id field).

Cost: free.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type application/json
object
region_id
required

UUID of the region to save. Obtain from the /markets-stats/{fips}/stats/ response (its id field) or another regions response.

string format: uuid
status

Pipeline label, mirroring the in-app market board columns (e.g., ‘Backlog’, ‘Watching’, ‘Active’). Free-form string.

string
>= 1 characters
Example generated
{
  "region_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "status": "example"
}

Responses

Section titled “ Responses ”

201

Section titled “201 ”
Media type application/json
object
id
required

Identifier for the saved market row.

string format: uuid
region
required

Identity of the saved region (county / ZIP). Statistics are not included here — fetch them from the Market Stats endpoint.

object
id
required

Internal region identifier.

string format: uuid
type
required

Region type — ‘county’ for full-county stats, ‘zip’ for a single ZIP.

  • county - Whole county.
  • zip - Single ZIP code.
string
Allowed values: county zip
name
required

County name (when type=‘county’) or ZIP code (when type=‘zip’).

string
state
required

Two-letter US state code (e.g., ‘CA’).

string
county_name
required

Primary county name. For ZIP regions, the county the ZIP falls into.

string
fips
required

5-digit county FIPS code.

string
nullable
status

Pipeline label, mirroring the in-app market board columns (e.g., ‘Backlog’, ‘Watching’, ‘Active’). Free-form string.

string
created_at
required

ISO-8601 timestamp.

string format: date-time
updated_at
required

ISO-8601 timestamp.

string format: date-time
Example 
{
  "region": {
    "type": "county"
  }
}

400

Section titled “400 ”

Validation error.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, payment_required, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}

401

Section titled “401 ”

Missing or invalid credentials.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, payment_required, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}

402

Section titled “402 ”

A Pro subscription or higher API tier is required.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, payment_required, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}

403

Section titled “403 ”

Authenticated but not permitted.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, payment_required, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}

404

Section titled “404 ”

Resource not found.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, payment_required, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}

429

Section titled “429 ”

Rate limit exceeded.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, payment_required, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}

500

Section titled “500 ”

Internal error.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, payment_required, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}