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

> Create, list, update, and delete polygon-based territories. Assign territories to sales reps and track total property counts within each boundary.

Territories let you divide your canvassing area into named geographic zones and assign them to individual reps. Each territory stores a polygon as an array of coordinate pairs, a total property count, and an optional assignee. You can use the territories API to automate territory creation from your own mapping tools, sync assignments from a dispatch system, or simply read back the shapes your team has drawn in the web dashboard.

## List territories

```
GET /api/territories
```

Returns all active territories for your company, ordered newest first.

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

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

### Response

Returns an array of territory objects directly (not paginated).

<ResponseField name="id" type="number">Territory ID.</ResponseField>
<ResponseField name="name" type="string">Display name of the territory.</ResponseField>
<ResponseField name="polygon" type="number[][]">Array of `[lng, lat]` coordinate pairs forming a closed ring. Minimum 3 points.</ResponseField>
<ResponseField name="totalProperties" type="number">Estimated number of properties within this territory.</ResponseField>
<ResponseField name="assignedToUserId" type="number | null">ID of the user assigned to this territory, or `null` if unassigned.</ResponseField>
<ResponseField name="companyId" type="number">Your company ID.</ResponseField>
<ResponseField name="createdAt" type="string">ISO 8601 creation timestamp.</ResponseField>
<ResponseField name="updatedAt" type="string">ISO 8601 last-updated timestamp.</ResponseField>

***

## Create a territory

```
POST /api/territories
```

All fields are optional. `name` defaults to `"Untitled Territory"`, `polygon` defaults to `[]`, and `totalProperties` defaults to `0` if omitted.

### Request body

<ParamField body="name" type="string">
  Display name. Defaults to `"Untitled Territory"` if not provided.
</ParamField>

<ParamField body="polygon" type="number[][]">
  Array of `[lng, lat]` coordinate pairs. Must have at least 3 points to define a valid polygon.
</ParamField>

<ParamField body="totalProperties" type="number">
  Integer count of properties inside the territory boundary.
</ParamField>

<ParamField body="assignedToUserId" type="number">
  ID of the user to assign this territory to. Pass `null` to leave unassigned.
</ParamField>

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

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://app.leadscoutapp.com/api/territories \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{
      "name": "Northwest Quadrant",
      "polygon": [
        [-85.70, 43.02],
        [-85.65, 43.02],
        [-85.65, 42.98],
        [-85.70, 42.98],
        [-85.70, 43.02]
      ],
      "totalProperties": 320,
      "assignedToUserId": 7
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.leadscoutapp.com/api/territories', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Northwest Quadrant',
      polygon: [
        [-85.70, 43.02],
        [-85.65, 43.02],
        [-85.65, 42.98],
        [-85.70, 42.98],
        [-85.70, 43.02],
      ],
      totalProperties: 320,
      assignedToUserId: 7,
    }),
  });
  const territory = await response.json();
  ```
</CodeGroup>

***

## Get a territory

```
GET /api/territories/:id
```

Returns a single territory. Returns `404` if it does not exist or belongs to a different company.

### Path parameters

<ParamField path="id" type="number" required>
  The territory ID.
</ParamField>

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

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

***

## Update a territory

```
PATCH /api/territories/:id
```

All body fields are optional. Only the fields you send are updated.

### Path parameters

<ParamField path="id" type="number" required>
  The territory ID.
</ParamField>

### Request body

<ParamField body="name" type="string">New display name.</ParamField>
<ParamField body="polygon" type="number[][]">Replacement polygon. Must have at least 3 `[lng, lat]` pairs.</ParamField>
<ParamField body="totalProperties" type="number">Updated property count.</ParamField>
<ParamField body="assignedToUserId" type="number">New assignee user ID. Pass `null` to unassign.</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url https://app.leadscoutapp.com/api/territories/15 \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{ "name": "Northwest Zone A", "assignedToUserId": 9 }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.leadscoutapp.com/api/territories/15', {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ name: 'Northwest Zone A', assignedToUserId: 9 }),
  });
  const updated = await response.json();
  ```
</CodeGroup>

***

## Delete a territory

```
DELETE /api/territories/:id
```

Deletes the territory. The record is excluded from list responses immediately but is not permanently destroyed.

### Path parameters

<ParamField path="id" type="number" required>
  The territory ID.
</ParamField>

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

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

  ```javascript JavaScript theme={null}
  await fetch('https://app.leadscoutapp.com/api/territories/15', {
    method: 'DELETE',
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  ```
</CodeGroup>