> ## 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 prospect tags

> Create and list the tag labels that categorize prospects. Requires canManageTags permission to create. Reference tag values when filtering prospect lists.

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.

## List tags

```
GET /api/tags
```

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

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

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

### Response

Returns an array of tag objects directly.

<ResponseField name="id" type="number">Tag ID.</ResponseField>
<ResponseField name="value" type="string">Display label for the tag (e.g. `"solar-interest"`).</ResponseField>
<ResponseField name="color" type="string | null">Hex color code used when rendering the tag badge, or `null` if no color is set.</ResponseField>
<ResponseField name="companyId" type="number">Your company ID.</ResponseField>
<ResponseField name="createdAt" type="string">ISO 8601 creation timestamp.</ResponseField>
<ResponseField name="hiddenAt" type="string | null">ISO 8601 timestamp if the tag has been hidden, otherwise `null`.</ResponseField>

***

## Create a tag

```
POST /api/tags
```

<Warning>
  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`.
</Warning>

### Request body

<ParamField body="value" type="string" required>
  Display label for the tag. Must be at least 1 character. Must be unique within your company.
</ParamField>

<ParamField body="color" type="string">
  Hex color code (e.g. `#22C55E`). Displayed in the tag badge across the dashboard and mobile app.
</ParamField>

Returns `201` with the created tag object on success.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  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();
  ```
</CodeGroup>

<Tip>
  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`
</Tip>