---
title: "Add items to a list"
method: POST
path: "/v1/list/{list_id}/item"
tags: ["list"]
---

# Add items to a list

`POST /v1/list/{list_id}/item`

## Request

- Base URL: `http://localhost:3030`
- URL: `http://localhost:3030/v1/list/{list_id}/item`
- Auth: HTTP bearer

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.

## Path parameters

- `list_id` string, required: The list's id, `lst_...`.

## Request body

- ItemAddition
  - `item` ItemBody[], required: Items to add, up to 500.
    - `kind` 'site' | 'jurisdiction' | 'postal_code' | 'area', required: What the item is. One of `site`, `jurisdiction`, `postal_code` or `area`.
    - `parcel` string[], nullable: A site's parcels, up to 50. Required when `kind` is `site`.
    - `jurisdiction` string, nullable: A jurisdiction id.
    - `postal_code` string, nullable: A five-digit ZIP code. Required when `kind` is `postal_code`.
    - `geometry` Geometry: A GeoJSON geometry in WGS 84, longitude first.
      - `type` string, required: Geometry type. One of `Polygon` or `MultiPolygon`.
      - `coordinates` unknown[], required: Coordinates, as `[longitude, latitude]` positions nested by geometry type.
        - unknown
    - `filter` object, nullable: `GET /v1/parcel` parameters that narrow a town, ZIP code or area: `owner`, `min_sale_date`, `max_sale_date`, `land_use` (a list), and the `min_` and `max_` forms of `acres`, `market_value`, `year_built` and `sale_price`.
    - `name` string, nullable: A name for the item, up to 200 characters.
    - `status` 'new' | 'reviewing' | 'pursuing' | 'passed': One of `new`, `reviewing`, `pursuing` or `passed`. Defaults to `new`.
    - `notes` string, nullable: Notes, up to 10,000 characters.
    - `tags` string[]: Tags, up to 20, each up to 40 characters. A tag that matches one already in use, ignoring case, takes that tag's spelling.

## Response `200`

A page of list items.

- CollectionSavedListItem
  - `object` 'list', required: The object's type. Always `list`.
  - `data` SavedListItem[], required: The results on this page.
    - `object` 'list_item', required: The object's type. Always `list_item`.
    - `id` string, required: Unique identifier for the object.
    - `kind` 'site' | 'jurisdiction' | 'postal_code' | 'area', required: What the item is. One of `site` (one or more parcels), `jurisdiction` (a town or county), `postal_code` or `area` (a drawn polygon).
    - `name` string, nullable, required: The item's name. Null when none was given.
    - `status` 'new' | 'reviewing' | 'pursuing' | 'passed', required: Where the item stands. One of `new`, `reviewing`, `pursuing` or `passed`.
    - `notes` string, nullable, required: Notes on the item. Null when there are none.
    - `tags` string[], required: Tags on the item, in the order they were added.
    - `parcel` SiteParcel[], nullable, required: A site's parcels, as they were when saved. Null unless `kind` is `site`.
      - `id` string, required: The parcel's id.
      - `number` string, nullable: The parcel number, as published. Null when it had none.
      - `address` string, nullable: The parcel's primary site address. Null when it had none.
      - `acres` number, nullable: Lot size, in acres. Null when not known.
      - `href` string, required: The parcel's path in the API.
    - `address` string, nullable, required: A site's first parcel's address. Null unless `kind` is `site`.
    - `acres` number, nullable, required: A site's total lot size, in acres. Null unless `kind` is `site`.
    - `jurisdiction` ParcelJurisdictionRef, required: The jurisdiction that assesses the parcel.
      - `id` string, required: A jurisdiction id.
      - `name` string, required: The jurisdiction's common name.
      - `type` string, required: Kind of jurisdiction, in local terms, such as `county`, `parish`, `city` or `town`.
      - `fips` string, nullable: The Census GEOID. Null outside the US.
      - `href` string, required: The object's path in the API.
    - `postal_code` string, nullable, required: The ZIP code. Null unless `kind` is `postal_code`.
    - `geometry` Geometry, required: A GeoJSON geometry in WGS 84, longitude first.
      - `type` string, required: Geometry type. One of `Polygon` or `MultiPolygon`.
      - `coordinates` unknown[], required: Coordinates, as `[longitude, latitude]` positions nested by geometry type.
        - unknown
    - `filter` object, nullable, required: `GET /v1/parcel` parameters that narrow a town, ZIP code or area. Null when there are none.
    - `centroid` ParcelPoint, required: A point in WGS 84.
      - `lat` number, required: Latitude, in WGS 84.
      - `lon` number, required: Longitude, in WGS 84.
    - `added_by` string, nullable, required: The email address of the member who added the item. Null when that member has left.
    - `created_at` string, date-time, required: Time at which the object was created.
    - `updated_at` string, date-time, required: Time at which the object was last updated.
    - `href` string, required: The object's path in the API.
  - `has_more` boolean, required: Whether there are more results after this page.
  - `next_cursor` string, nullable, required: The cursor for the next page. Send it as `cursor`. Null on the last page.
  - `suppressed` integer, required: The number of matching results withheld because the plan does not include them.
  - `total` Total, required: The number of matching results.
    - `value` integer, required: The number of matching results.
    - `relation` 'eq' | 'gte', required: One of `eq` (exact) or `gte` (at least `value`). Counts above 10,000 are `gte`.

## Other responses

- `401`: `credential_missing`, `credential_invalid` or `credential_expired`. The request has no valid credential.
- `403`: `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`: `no_such_resource`. No object has that id.
- `422`: `parameter_invalid`, `id_malformed` or a cursor code. A parameter is missing or invalid. `errors` lists each one.
- `429`: `rate_limited`. Too many requests. Retry after the `Retry-After` interval. Nothing is charged.

---

[API](https://skmtc.dev/placestack/apis/placestack-api.md) · [All operations](https://skmtc.dev/placestack/apis/placestack-api/llms.txt) · [OpenAPI document](https://skmtc.dev/placestack/apis/placestack-api/revisions/0ccdf0882668?raw)