REST API endpoints for creating and managing prospects

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

string

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

string

ISO 8601 date string. Returns prospects created on or after this date. Example: 2024-01-01

string

ISO 8601 date string. Returns prospects created on or before this date. Example: 2024-12-31

string

Comma-separated list of status values. Example: contacted,sold

string

Comma-separated list of user IDs. Admin and owner only. Example: 12,34

string

Comma-separated list of rep full names. Admin and owner only. Example: Jane Smith,Bob Jones

string

Comma-separated list of tag display values (not IDs). Example: solar,roofing

string

Comma-separated list of city names. Example: Grand Rapids,Holland

string

Full-text search across name, phone, email, address, and notes.

number

default:"1"

Page number (1-indexed).

number

default:"50"

Number of records per page.

Response

object[]

Array of prospect objects.

Show prospect object

number

Unique prospect ID.

string | null

Prospect’s full name.

string | null

Primary phone number.

string | null

Secondary phone number.

string | null

Email address.

number | null

Latitude coordinate.

number | null

Longitude coordinate.

string | null

How the prospect was added (e.g. csv-import).

object | null

Key/value store for custom fields.

string

ISO 8601 creation timestamp.

object | null

Show address

number

Address ID.

string

Street line 1.

string | null

Street line 2.

string

City.

string

State.

string

ZIP code.

string | null

Full formatted address string.

object | null

Show status

number

Status ID.

string

Status display label.

string

Hex color code.

object | null

Show assignedTo

number

User ID.

string

First name.

string

Last name.

string

Email address.

object[]

Array of { tag: { id, value, color } } objects.

object[]

Up to one upcoming appointment. See Appointments for the full shape.

number

Total number of matching prospects.

number

Current page number.

number

Records per page.

curl --request GET \
  --url 'https://app.leadscoutapp.com/api/prospects?status=contacted&page=1&pageSize=25' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

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

string

Prospect’s full name.

string

Primary phone number.

string

Secondary phone number.

string

Must be a valid email format if provided.

number

Latitude coordinate.

number

Longitude coordinate.

number

ID of an existing address record to associate.

number

ID of a lead status. If provided, a status history entry is created automatically.

number

ID of the user to assign this prospect to.

string

Origin string (e.g. api, csv-import).

string

External ID from the originating system.

string

ISO 8601 timestamp from the originating system.

object

Arbitrary key/value pairs for custom fields.

Returns 201 with the created prospect object on success.

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
  }'

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

number

required

The prospect ID.

Returns 404 if the prospect does not exist or belongs to a different company.

curl --request GET \
  --url https://app.leadscoutapp.com/api/prospects/42 \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

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

number

required

The prospect ID.

Request body

string

Full name.

string

Primary phone number.

string

Secondary phone number.

string

Valid email address.

number

Latitude coordinate.

number

Longitude coordinate.

number

Address record ID.

number

New lead status ID.

number

User ID to (re-)assign to.

number

User ID of the person performing the assignment.

string

Origin string.

string

External ID.

object

Custom field key/value pairs.

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 }'

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

number

required

The prospect ID.

Returns { "id": <number> } on success.

curl --request DELETE \
  --url https://app.leadscoutapp.com/api/prospects/42 \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

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

curl --request GET \
  --url 'https://app.leadscoutapp.com/api/prospects/export?status=sold' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --output prospects.csv

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

file

required

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

Number of successfully created prospects.

number

Number of rows that were skipped due to errors.

object[]

Array of { row: number, message: string } objects describing each skipped row.

curl --request POST \
  --url https://app.leadscoutapp.com/api/prospects/import \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --form 'file=@/path/to/prospects.csv'

const formData = new FormData();
formData.append('file', csvFile); // File object from an <input type="file">

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

number

Prospect ID.

number

Latitude.

number

Longitude.

string

Hex color from the prospect’s current status, or #9CA3AF if no status is set.

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'

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' }, ...]

Overview

Endpoints

REST API endpoints for creating and managing prospects

List prospects

Query parameters

Response

Create a prospect

Request body

Get a prospect

Path parameters

Update a prospect

Path parameters

Request body

Delete a prospect

Path parameters

Export prospects as CSV

CSV columns

Import prospects from CSV

Form fields

Response

Get map pins

Response

​List prospects

​Query parameters

​Response

​Create a prospect

​Request body

​Get a prospect

​Path parameters

​Update a prospect

​Path parameters

​Request body

​Delete a prospect

​Path parameters

​Export prospects as CSV

​CSV columns

​Import prospects from CSV

​Form fields

​Response

​Get map pins

​Response

List prospects

Query parameters

Response

Create a prospect

Request body

Get a prospect

Path parameters

Update a prospect

Path parameters

Request body

Delete a prospect

Path parameters

Export prospects as CSV

CSV columns

Import prospects from CSV

Form fields

Response

Get map pins

Response