REST API endpoints for creating and managing prospect tags

Tags are color-coded labels you apply to prospects to categorize them — for example, solar-interest, roofing-lead, or do-not-knock. The tags API lets you list all tags defined for your company and create new ones. To apply a tag to a specific prospect, update that prospect record. Tags are referenced by their display value in prospect filter parameters.

GET /api/tags

Returns all active (non-hidden) tags for your company, ordered alphabetically by value.

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

const response = await fetch('https://app.leadscoutapp.com/api/tags', {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const tags = await response.json();

Response

Returns an array of tag objects directly.

number

Tag ID.

string

Display label for the tag (e.g. "solar-interest").

string | null

Hex color code used when rendering the tag badge, or null if no color is set.

number

Your company ID.

string

ISO 8601 creation timestamp.

string | null

ISO 8601 timestamp if the tag has been hidden, otherwise null.

Create a tag

POST /api/tags

Creating tags requires the canManageTags permission. This is granted to owners by default and can be granted to individual sales users by an admin or owner. Without it you receive a 403.

Request body

string

required

Display label for the tag. Must be at least 1 character. Must be unique within your company.

string

Hex color code (e.g. #22C55E). Displayed in the tag badge across the dashboard and mobile app.

Returns 201 with the created tag object on success.

curl --request POST \
  --url https://app.leadscoutapp.com/api/tags \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "value": "solar-interest",
    "color": "#FACC15"
  }'

const response = await fetch('https://app.leadscoutapp.com/api/tags', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    value: 'solar-interest',
    color: '#FACC15',
  }),
});
const tag = await response.json();

When filtering prospects by tag, pass the tag’s value string (not its id) to the tagId query parameter. For example: GET /api/prospects?tagId=solar-interest,roofing-lead

Overview

Endpoints

REST API endpoints for creating and managing prospect tags

Response

Create a tag

Request body

​List tags

​Response

​Create a tag

​Request body

List tags

Response

Create a tag

Request body