Add items to a list

Adds sites, jurisdictions, ZIP codes or areas to a list.

A site with the same parcels, or a jurisdiction or ZIP code with no filter, that is already on the list is returned as is and not added again. With an API key, each parcel of a site costs a credit, as a parcel lookup does. Other items cost no credits.

Parameters

path

list_idrequiredstring: The list's id, lst_....

Request body

itemrequiredItemBody[]

Items to add, up to 500.

Show fields

kindrequired"site" | "jurisdiction" | "postal_code" | "area"

What the item is. One of site, jurisdiction, postal_code or area.

parcelstring[] | null

A site's parcels, up to 50. Required when kind is site.

jurisdictionstring | null

The town or county. Required when kind is jurisdiction.

postal_codestring | null

A five-digit ZIP code. Required when kind is postal_code.

geometryGeometry | null

A Polygon or MultiPolygon of up to 10,000 positions, covering up to 1,000 square miles. Required when kind is area.

Show fields

typerequiredstring: Geometry type. One of Polygon or MultiPolygon.
coordinatesrequiredunknown[]: Coordinates, as [longitude, latitude] positions nested by geometry type.

filterobject map | null

GET /v1/parcel parameters that narrow a town, ZIP code or area: owner, min_sale_date, max_sale_date, and the min_ and max_ forms of acres, market_value, year_built and sale_price.

namestring | null

A name for the item, up to 200 characters.

status"new" | "reviewing" | "pursuing" | "passed"

One of new, reviewing, pursuing or passed. Defaults to new.

notesstring | null

Notes, up to 10,000 characters.

Responses

200: Collection_SavedListItem_; A page of list items.
401: ProblemDetail; credential_missing, credential_invalid or credential_expired. The request has no valid credential.
403: ProblemDetail; scope_missing, person_required, api_key_not_accepted or entitlement_missing. The credential or plan does not allow this request. detail names the reason.
404: ProblemDetail; no_such_resource. No object has that id.
422: ProblemDetail; parameter_invalid, id_malformed or a cursor code. A parameter is missing or invalid. errors lists each one.
429: ProblemDetail; rate_limited. Too many requests. Retry after the Retry-After interval. Nothing is charged.

Example request

curl -X POST 'https://api.placestack.com/v1/list/018f4b75-6f79-7c6a-8c80-000000000001/item' \
  -H "Authorization: Bearer $PLACESTACK_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "item": [
    {
      "kind": "site"
    }
  ]
}'

Example response

{
  "object": "list",
  "data": [
    {
      "object": "list_item",
      "id": "lsi_01h455vb4pex5vsknk084sn02q",
      "kind": "site",
      "name": "Hwy 101 site",
      "status": "new",
      "notes": "string",
      "parcel": [
        {
          "id": "prc_01h455vb4pex5vsknk084sn02q",
          "number": "0787517396",
          "address": "4516 PRINTER LN, RALEIGH, NC 27613",
          "acres": 0.26,
          "href": "/v1/parcel/prc_01h455vb4pex5vsknk084sn02q"
        }
      ],
      "address": "4516 PRINTER LN, RALEIGH, NC 27613",
      "acres": 3.09,
      "jurisdiction": {
        "id": "jur_01h455vb4pex5vsknk084sn02q",
        "name": "Wake",
        "type": "county",
        "fips": "37183",
        "href": "/v1/jurisdiction/jur_01h455vb4pex5vsknk084sn02q"
      },
      "postal_code": "27613",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -78.6999,
              35.849
            ],
            [
              -78.6993,
              35.849
            ],
            [
              -78.6993,
              35.8494
            ],
            [
              -78.6999,
              35.8494
            ],
            [
              -78.6999,
              35.849
            ]
          ]
        ]
      },
      "filter": {
        "min_acres": 10
      },
      "centroid": {
        "lat": 35.8492,
        "lon": -78.6996
      },
      "added_by": "ana@example.com",
      "created_at": "2026-09-13T12:00:00Z",
      "updated_at": "2026-09-13T12:00:00Z",
      "href": "/v1/list/lst_01h455vb4pex5vsknk084sn02q/item/lsi_01h455vb4pex5vsknk084sn02q"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJrIjoiMjAyNi0xMC0wMSIsInQiOjQyfQ",
  "suppressed": 0,
  "total": {
    "value": 1,
    "relation": "eq"
  }
}

Parameters

Request body

Responses

Next steps

GET /list/{list_id}/item/{item_id}