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

# REST API endpoint for knock history and lead statuses

> Retrieve the full knock history — every status-change event recorded by your team — alongside your company's configured lead status list.

Every time a rep updates a prospect's status in the field, LeadScout records a "knock" — a status-change event that captures which rep made the change, which status they set, and when. The knocks endpoint returns this complete event log alongside your company's configured lead statuses so you can build activity reports, performance dashboards, and funnel analytics without additional lookups.

<Note>
  Sales reps without the `canViewAllProspects` permission see only knocks for prospects assigned to them. Admins and owners see all knocks across the company.
</Note>

## List knocks and statuses

```
GET /api/knocks
```

Returns all knock events and the full lead status configuration in a single response.

### Response

<ResponseField name="knocks" type="object[]">
  Array of knock (status-change) events, ordered by `createdAt` ascending.

  <Expandable title="knock object">
    <ResponseField name="id" type="number">Knock event ID.</ResponseField>
    <ResponseField name="prospectId" type="number">ID of the prospect this knock belongs to.</ResponseField>
    <ResponseField name="addedByUserId" type="number">ID of the user who recorded the knock.</ResponseField>
    <ResponseField name="leadStatusId" type="number">ID of the status that was set.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601 timestamp when the knock was recorded.</ResponseField>

    <ResponseField name="addedBy" type="object">
      <Expandable title="addedBy">
        <ResponseField name="id" type="number">User ID.</ResponseField>
        <ResponseField name="firstName" type="string">First name.</ResponseField>
        <ResponseField name="lastName" type="string">Last name.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="leadStatus" type="object">
      <Expandable title="leadStatus">
        <ResponseField name="id" type="number">Status ID.</ResponseField>
        <ResponseField name="value" type="string">Status display label (e.g. `"Contacted"`, `"Not Home"`).</ResponseField>
        <ResponseField name="color" type="string">Hex color code used for map pins and UI badges.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="statuses" type="object[]">
  Your company's full lead status configuration, ordered by `order` ascending.

  <Expandable title="status object">
    <ResponseField name="id" type="number">Status ID.</ResponseField>
    <ResponseField name="value" type="string">Display label.</ResponseField>
    <ResponseField name="color" type="string">Hex color code.</ResponseField>
    <ResponseField name="order" type="number">Sort position in the status list.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://app.leadscoutapp.com/api/knocks \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.leadscoutapp.com/api/knocks', {
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  const { knocks, statuses } = await response.json();
  ```
</CodeGroup>

<Tip>
  To count total knocks per rep, group the `knocks` array by `addedByUserId`. To build a status funnel, group by `leadStatusId` and join against the `statuses` array using the matching `id`.
</Tip>