> ## 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 endpoints for creating and managing prospects
> Create, list, update, delete, export, and import prospect records. Filter by bounding box, status, tags, assigned rep, date range, or free-text search.
Prospects are the core resource in LeadScout — they represent individual homes or businesses your team is canvassing. The prospects API gives you full CRUD access plus bulk CSV export and import. Sales reps automatically see only their own assigned prospects; admins and owners see all prospects across the company. Every response includes the prospect's current status, address, assigned rep, and tags.
## List prospects
Sales reps without `canViewAllProspects` permission see only prospects assigned to them. Admins and owners see all company prospects.
```
GET /api/prospects
```
### Query parameters
Bounding box filter as `minLng,minLat,maxLng,maxLat`. Returns only prospects whose coordinates fall within the box. Example: `-85.7,42.9,-85.5,43.1`
ISO 8601 date string. Returns prospects created on or after this date. Example: `2024-01-01`
ISO 8601 date string. Returns prospects created on or before this date. Example: `2024-12-31`
Comma-separated list of status values. Example: `contacted,sold`
Comma-separated list of user IDs. Admin and owner only. Example: `12,34`
Comma-separated list of rep full names. Admin and owner only. Example: `Jane Smith,Bob Jones`
Comma-separated list of tag display values (not IDs). Example: `solar,roofing`
Comma-separated list of city names. Example: `Grand Rapids,Holland`
Full-text search across name, phone, email, address, and notes.
Page number (1-indexed).
Number of records per page.
### Response
Array of prospect objects.
Unique prospect ID.Prospect's full name.Primary phone number.Secondary phone number.Email address.Latitude coordinate.Longitude coordinate.How the prospect was added (e.g. `csv-import`).Key/value store for custom fields.ISO 8601 creation timestamp.Address ID.Street line 1.Street line 2.City.State.ZIP code.Full formatted address string.Status ID.Status display label.Hex color code.User ID.First name.Last name.Email address.
Array of `{ tag: { id, value, color } }` objects.
Up to one upcoming appointment. See [Appointments](/api/appointments) for the full shape.
Total number of matching prospects.Current page number.Records per page.
```bash cURL theme={null}
curl --request GET \
--url 'https://app.leadscoutapp.com/api/prospects?status=contacted&page=1&pageSize=25' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```
```javascript JavaScript theme={null}
const response = await fetch(
'https://app.leadscoutapp.com/api/prospects?status=contacted&page=1&pageSize=25',
{ headers: { Authorization: `Bearer ${accessToken}` } }
);
const { items, total } = await response.json();
```
***
## Create a prospect
```
POST /api/prospects
```
### Request body
Prospect's full name.
Primary phone number.
Secondary phone number.
Must be a valid email format if provided.
Latitude coordinate.
Longitude coordinate.
ID of an existing address record to associate.
ID of a lead status. If provided, a status history entry is created automatically.
ID of the user to assign this prospect to.
Origin string (e.g. `api`, `csv-import`).
External ID from the originating system.
ISO 8601 timestamp from the originating system.
Arbitrary key/value pairs for custom fields.
Returns `201` with the created prospect object on success.
```bash cURL theme={null}
curl --request POST \
--url https://app.leadscoutapp.com/api/prospects \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"name": "Jane Smith",
"phoneNumber": "616-555-0100",
"emailAddress": "jane@example.com",
"lat": 42.9634,
"lng": -85.6681,
"currentStatusId": 3,
"assignedToUserId": 7
}'
```
```javascript JavaScript theme={null}
const response = await fetch('https://app.leadscoutapp.com/api/prospects', {
method: 'POST',
headers: {
Authorization: `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Jane Smith',
phoneNumber: '616-555-0100',
emailAddress: 'jane@example.com',
lat: 42.9634,
lng: -85.6681,
currentStatusId: 3,
assignedToUserId: 7,
}),
});
const prospect = await response.json();
```
***
## Get a prospect
```
GET /api/prospects/:id
```
Returns a single prospect with its full history, including up to 5 recent notes, all appointments, and the complete status history.
### Path parameters
The prospect ID.
Returns `404` if the prospect does not exist or belongs to a different company.
```bash cURL theme={null}
curl --request GET \
--url https://app.leadscoutapp.com/api/prospects/42 \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```
```javascript JavaScript theme={null}
const response = await fetch('https://app.leadscoutapp.com/api/prospects/42', {
headers: { Authorization: `Bearer ${accessToken}` },
});
const prospect = await response.json();
```
***
## Update a prospect
```
PATCH /api/prospects/:id
```
All body fields are optional. Only the fields you send are changed. If you change `currentStatusId`, a new status history entry is created.
### Path parameters
The prospect ID.
### Request body
Full name.Primary phone number.Secondary phone number.Valid email address.Latitude coordinate.Longitude coordinate.Address record ID.New lead status ID.User ID to (re-)assign to.User ID of the person performing the assignment.Origin string.External ID.Custom field key/value pairs.
```bash cURL theme={null}
curl --request PATCH \
--url https://app.leadscoutapp.com/api/prospects/42 \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{ "currentStatusId": 5, "assignedToUserId": 12 }'
```
```javascript JavaScript theme={null}
const response = await fetch('https://app.leadscoutapp.com/api/prospects/42', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ currentStatusId: 5, assignedToUserId: 12 }),
});
const updated = await response.json();
```
***
## Delete a prospect
```
DELETE /api/prospects/:id
```
Deletes the prospect. The record is excluded from all list and single-get responses immediately, but is not permanently destroyed so your data history is preserved.
### Path parameters
The prospect ID.
Returns `{ "id": }` on success.
```bash cURL theme={null}
curl --request DELETE \
--url https://app.leadscoutapp.com/api/prospects/42 \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```
```javascript JavaScript theme={null}
await fetch('https://app.leadscoutapp.com/api/prospects/42', {
method: 'DELETE',
headers: { Authorization: `Bearer ${accessToken}` },
});
```
***
## Export prospects as CSV
```
GET /api/prospects/export
```
Returns a downloadable `prospects.csv` file. Supports the same filter parameters as the list endpoint (`bbox`, `dateFrom`, `dateTo`, `status`, `assignedToUserId`, `tagId`). The file is streamed in batches of 500 records — there is no page limit.
### CSV columns
`id`, `name`, `phone`, `email`, `lat`, `lng`, `address1`, `address2`, `city`, `state`, `zip`, `status`, `assignedTo`, `assignedToEmail`, `tags` (semicolon-separated), `notes` (most recent), `createdBy`, `source`, `createdAt`
```bash cURL theme={null}
curl --request GET \
--url 'https://app.leadscoutapp.com/api/prospects/export?status=sold' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--output prospects.csv
```
```javascript JavaScript theme={null}
const response = await fetch(
'https://app.leadscoutapp.com/api/prospects/export?status=sold',
{ headers: { Authorization: `Bearer ${accessToken}` } }
);
const blob = await response.blob();
// In a browser: trigger download
const url = URL.createObjectURL(blob);
```
***
## Import prospects from CSV
```
POST /api/prospects/import
```
This endpoint requires the `canManageProspects` permission. Sales reps without that permission receive a `403`.
Upload a CSV file as `multipart/form-data`. Each row creates one prospect. Rows missing both an address (`address1` + `city` + `state` + `zip`) and coordinates (`lat` + `lng`) are skipped.
### Form fields
A CSV file. The first row must be a header row. Supported columns: `name`, `phone`, `email`, `lat`, `lng`, `address1`, `address2`, `city`, `state`, `zip`, `status` (matched by display value), `assignedTo` (matched by email address), `tags` (semicolon-separated tag values), `notes`.
### Response
Number of successfully created prospects.Number of rows that were skipped due to errors.
Array of `{ row: number, message: string }` objects describing each skipped row.
```bash cURL theme={null}
curl --request POST \
--url https://app.leadscoutapp.com/api/prospects/import \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--form 'file=@/path/to/prospects.csv'
```
```javascript JavaScript theme={null}
const formData = new FormData();
formData.append('file', csvFile); // File object from an
const response = await fetch('https://app.leadscoutapp.com/api/prospects/import', {
method: 'POST',
headers: { Authorization: `Bearer ${accessToken}` },
body: formData,
});
const { imported, skipped, errors } = await response.json();
```
***
## Get map pins
```
GET /api/prospects/pins
```
Returns a lightweight array of coordinate and color data for rendering map pins. Supports the same filter parameters as the list endpoint. Use this endpoint instead of the full list when you only need to render markers on a map — it returns far less data.
### Response
Returns an array of pin objects directly (not paginated).
Prospect ID.Latitude.Longitude.Hex color from the prospect's current status, or `#9CA3AF` if no status is set.
```bash cURL theme={null}
curl --request GET \
--url 'https://app.leadscoutapp.com/api/prospects/pins?bbox=-85.7,42.9,-85.5,43.1' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```
```javascript JavaScript theme={null}
const response = await fetch(
'https://app.leadscoutapp.com/api/prospects/pins?bbox=-85.7,42.9,-85.5,43.1',
{ headers: { Authorization: `Bearer ${accessToken}` } }
);
const pins = await response.json();
// [{ id: 1, lat: 42.96, lng: -85.66, statusColor: '#22C55E' }, ...]
```