> ## 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 Records

> Retrieve a paginated list of records

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

Retrieve a paginated list of records filtered by type and optional date range.

## Query Parameters

<ParamField query="recordType" type="string" required>
  Type of records to retrieve. Must be URL-encoded. Common values include `Preliminary Damage Assessment` and `Log`, but the available types vary by account. Consult your customer success manager for your account's set of record types.
</ParamField>

<ParamField query="externalSystemId" type="string">
  Find record via it's `externalSystemId`. Since this value is unique, this will return exactly zero or one entry in the records array. `externalSystemId` can be set via the [Submit SI/SD](/developers/api/sisd/submit) or [Update SI/SD](/developers/api/sisd/update) API or through an integration with an external data source (such as Accela).
</ParamField>

<ParamField query="page" type="integer">
  Used for getting the next page in the sequence. See `pageInfo` for pagination details.
</ParamField>

<ParamField query="createdFrom" type="string">
  Filter records created strictly after this timestamp (exclusive). Provide in ISO 8601 format (e.g., `2024-09-25T21:33:10Z`).
</ParamField>

## Response

<ResponseField name="records" type="array">
  Array of record objects (25 per page)

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

    <ResponseField name="externalSystemId" type="string">
      External system identifier for the record
    </ResponseField>

    <ResponseField name="data" type="object">
      Record fields. The structure depends on the `recordType` and your community's configuration.
    </ResponseField>

    <ResponseField name="property" type="object">
      Associated property. See [Property object](/developers/api/properties/list#response) for the object schema.
    </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 theme={null}
  curl "https://app.withforerunner.com/api/v1/records?recordType=Preliminary%20Damage%20Assessment&page=1" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL - With Date Filter theme={null}
  curl "https://app.withforerunner.com/api/v1/records?recordType=Preliminary%20Damage%20Assessment&createdFrom=2024-09-25T21:33:10Z" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

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

<ResponseExample>
  ```json Success theme={null}
  {
    "records": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "externalSystemId": "PDA-2024-001",
        "data": {
          "damageCategory": "Major",
          "estimatedLoss": 75000,
          "inspectionDate": "2024-09-20"
        },
        "property": {
          "id": "f0e1d2c3-b4a5-6789-0fed-cba987654321",
          "address": "123 Main St, Springfield, IL 62701",
          "coordinates": [39.7817, -89.6501],
          "url": "https://demoville.app.withforerunner.com/map?lat=39.7817&lng=-89.6501",
          "publicURL": "https://demoville.withforerunner.com/properties/f0e1d2c3-b4a5-6789-0fed-cba987654321"
        }
      }
    ],
    "pageInfo": {
      "page": 1,
      "pageSize": 25,
      "totalCount": 187,
      "totalPages": 8
    },
    "errors": []
  }
  ```

  ```json Success - Log theme={null}
  {
    "records": [
      {
        "id": "f8a3b2c1-d4e5-6789-abcd-ef0123456789",
        "externalSystemId": null,
        "data": {
          "date": "2024-03-20T00:00:00.000Z",
          "status": "complete",
          "type": "phone",
          "contactName": "Jane Doe",
          "contactEmail": "jane.doe@example.com",
          "contactPhone": "(555) 987-6543",
          "contactType": "homeowner",
          "address": "456 Oak Ave, Springfield, IL",
          "firmPanel": "17167C0033E",
          "floodZone": "AE",
          "bfe": "12.5",
          "baseFloodDepth": null,
          "insuranceInfoGiven": "verbally",
          "siteVisit": false,
          "propertyProtectionAdvice": false,
          "financialAdvice": false,
          "coastalOrCBRS": false,
          "pastFlood": false,
          "erosion": false,
          "requestedHelpWith": "Flood zone status inquiry",
          "internalNotes": null,
          "sharedViaEmail": false,
          "viaPublicSite": false,
          "createdBy": null
        },
        "property": {
          "id": "f0e1d2c3-b4a5-6789-0fed-cba987654321",
          "address": "456 Oak Ave, Springfield, IL 62704",
          "coordinates": [39.7637, -89.6688],
          "url": "https://demoville.app.withforerunner.com/map?lat=39.7637&lng=-89.6688",
          "publicURL": "https://demoville.withforerunner.com/properties/f0e1d2c3-b4a5-6789-0fed-cba987654321"
        }
      }
    ],
    "pageInfo": {
      "page": 1,
      "pageSize": 25,
      "totalCount": 42,
      "totalPages": 2
    },
    "errors": []
  }
  ```

  ```json Error theme={null}
  {
    "records": [],
    "errors": [
      {
        "message": "Invalid record type",
        "field": "recordType"
      }
    ]
  }
  ```
</ResponseExample>

## Best Practices

<AccordionGroup>
  <Accordion title="Pagination for large datasets">
    Always paginate through results when querying record types with many entries. Don't assume all data will fit in a single response.
  </Accordion>

  <Accordion title="Incremental synchronization">
    Use the `createdFrom` parameter to implement efficient incremental syncs rather than fetching all records every time. Store the last sync timestamp and use it for subsequent requests.
  </Accordion>

  <Accordion title="URL encoding record types">
    Always URL-encode the `recordType` parameter, especially for types with spaces or special characters.
  </Accordion>

  <Accordion title="Handle varying data structures">
    Different record types have different data structures. Build flexible parsers that can handle type-specific fields based on the `recordType` value.
  </Accordion>
</AccordionGroup>