> ## Documentation Index
> Fetch the complete documentation index at: https://withforerunner.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List Properties

> Retrieve a paginated list of properties

<ParamField path="GET" type="endpoint">
  /api/v1/properties
</ParamField>

Retrieve a paginated list of properties with optional filtering.

## Query Parameters

<ParamField query="parcelId" type="string">
  Restricts the resulting properties to those associated with the parcel with the given `parcelId`. Cannot be used together with `geometry`.
</ParamField>

<ParamField query="hiddenFromPublic" type="enum">
  Accepts `true` or `false`. Controls visibility filtering. Omitting returns both public and private properties.
</ParamField>

<ParamField query="page" type="number">
  Positive, non-zero integer for pagination. See [Pagination](/developers/api/overview#pagination).
</ParamField>

<ParamField query="geometry" type="string">
  URI-encoded GeoJSON Polygon geometry to filter properties by spatial intersection. Only properties whose coordinates fall within the polygon will be returned. Cannot be used together with `parcelId`.

  ```json Example GeoJSON Polygon theme={null}
  {
    "type": "Polygon",
    "coordinates": [
      [
        [-73.98836883114409, 40.67402149000125],
        [-73.98836883114409, 40.66928110727923],
        [-73.98070752927185, 40.66928110727923],
        [-73.98070752927185, 40.67402149000125],
        [-73.98836883114409, 40.67402149000125]
      ]
    ]
  }
  ```
</ParamField>

## Response

<ResponseField name="properties" type="array">
  Array of property objects (up to 25 per page)

  <Expandable title="Property object properties">
    <ResponseField name="id" type="string">
      UUID uniquely identifying the property
    </ResponseField>

    <ResponseField name="address" type="string | null">
      The property's fully qualified address. Some properties may not have addresses.
    </ResponseField>

    <ResponseField name="publicURL" type="string | null">
      The URL for the property's public profile page. Null if the property is hidden from the public.
    </ResponseField>

    <ResponseField name="url" type="string">
      Internal profile page URL requiring Forerunner platform account access
    </ResponseField>

    <ResponseField name="coordinates" type="[number, number]">
      Two-element array `[latitude, longitude]` in `EPSG:4326` format
    </ResponseField>

    <ResponseField name="parcel" type="object | null">
      Associated parcel object; some properties lack parcels

      <Expandable title="Parcel object properties">
        <ResponseField name="id" type="string">
          UUID uniquely identifying the parcel
        </ResponseField>

        <ResponseField name="parcelId" type="string | null">
          The parcel's id - often used to uniquely identify parcels within external, non-Forerunner systems.
        </ResponseField>

        <ResponseField name="address" type="string | null">
          The parcel's fully qualified address. Some parcels may not have addresses.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pageInfo" type="object">
  Pagination information. See [Pagination](/developers/api/overview#pagination).
</ResponseField>

<ResponseField name="errors" type="array">
  Array of error objects. See [Errors](/developers/api/overview#errors).
</ResponseField>

<RequestExample>
  ```bash cURL - Basic List theme={null}
  curl "https://app.withforerunner.com/api/v1/properties?page=1" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL - Filter by Parcel theme={null}
  curl "https://app.withforerunner.com/api/v1/properties?parcelId=12-34-567-890" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL - Geospatial Query theme={null}
  curl "https://app.withforerunner.com/api/v1/properties?geometry=%7B%22type%22%3A%20%22Polygon%22%2C%20%22coordinates%22%3A%20%5B%5B%5B-73.98836883114409%2C%2040.67402149000125%5D%2C%20%5B-73.98836883114409%2C%2040.66928110727923%5D%2C%20%5B-73.98070752927185%2C%2040.66928110727923%5D%2C%20%5B-73.98070752927185%2C%2040.67402149000125%5D%2C%20%5B-73.98836883114409%2C%2040.67402149000125%5D%5D%5D%7D" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "properties": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "address": "123 Main St, Springfield, IL 62701",
        "publicURL": "https://app.withforerunner.com/public/properties/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "url": "https://app.withforerunner.com/properties/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "coordinates": [39.7817, -89.6501],
        "parcel": {
          "id": "f1e2d3c4-b5a6-7890-dcba-098765432109",
          "parcelId": "12-34-567-890",
          "address": "123 Main St, Springfield, IL 62701"
        }
      }
    ],
    "pageInfo": {
      "page": 1,
      "pageSize": 25,
      "totalCount": 1043,
      "totalPages": 42
    },
    "errors": []
  }
  ```
</ResponseExample>