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

# LeadScout REST API — overview and getting started

> A complete reference to the LeadScout REST API. Manage prospects, territories, appointments, knocks, tags, webhooks, and users from any HTTP client.

The LeadScout API is a REST interface that gives you programmatic access to every resource in your account. All requests and responses use JSON, all endpoints require authentication, and all mutations are scoped to your company so you can never accidentally read or write another organization's data. Whether you are building a custom integration, syncing data with a CRM, or powering a mobile canvassing app, the same API routes handle every client.

## Base URL

```
https://app.leadscoutapp.com/api
```

All example URLs in this reference use that base.

## Request format

Send `Content-Type: application/json` with every `POST` and `PATCH` request. `GET` and `DELETE` requests never require a body.

## Response format

Successful responses return JSON. List endpoints return a paginated envelope:

```json theme={null}
{
  "items": [...],
  "total": 142,
  "page": 1,
  "pageSize": 50
}
```

Single-resource endpoints return the object directly. Delete endpoints return `{ "id": <number> }`.

## HTTP status codes

| Code  | Meaning                                                     |
| ----- | ----------------------------------------------------------- |
| `200` | Success                                                     |
| `201` | Resource created                                            |
| `400` | Bad request — malformed body or business-logic error        |
| `401` | Unauthorized — missing or invalid token                     |
| `403` | Forbidden — valid token but insufficient role or permission |
| `404` | Resource not found or not accessible to your account        |
| `422` | Validation failed — response body includes `details` array  |
| `500` | Internal server error                                       |

## Pagination

List endpoints that support pagination accept `page` (default `1`) and `pageSize` (default `50`) query parameters. The response `total` field tells you how many records match your filters in total.

<Tip>
  Keep `pageSize` at or below 100 for best performance. The `/api/prospects/export` endpoint streams all matching records as a CSV file and is not paginated.
</Tip>

## Authentication

Every request must carry a valid credential — either a session cookie (set automatically by the web dashboard) or a `Bearer` JWT token for external integrations. See the [Authentication](/api/authentication) page for full details and code examples.

## Resource groups

<CardGroup cols={2}>
  <Card title="Prospects" icon="user" href="/api/prospects">
    Create, query, update, delete, export, and import prospect records.
  </Card>

  <Card title="Territories" icon="map" href="/api/territories">
    Define polygon-based territories and assign them to reps.
  </Card>

  <Card title="Appointments" icon="calendar" href="/api/appointments">
    List appointments across all prospects, with optional date filtering.
  </Card>

  <Card title="Knocks" icon="door-open" href="/api/knocks">
    Retrieve the full knock history (status-change events) for your team.
  </Card>

  <Card title="Tags" icon="tag" href="/api/tags">
    Create and list the tag labels that can be applied to prospects.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api/webhooks">
    Register outbound webhooks to receive real-time event notifications.
  </Card>

  <Card title="Users" icon="users" href="/api/users">
    List team members, invite new users, and manage roles and permissions.
  </Card>

  <Card title="Authentication" icon="lock" href="/api/authentication">
    Understand the two supported auth mechanisms and how to obtain tokens.
  </Card>
</CardGroup>