# List reps

`GET` `/api/v1/crm-connections/{crm_connection_id}/bookbuilder/reps`

Returns reps with their active target-book assignment. Each rep's ``id``
is the Salesforce User ID; a user can only be actively assigned to one
target book at a time. Supports filtering by rep name, manager, target
book name or id, and active status, plus cursor-based pagination via
``next_records_url``. Default page size is 50. Pass ``next_records_url``
from one response into the next request to paginate through large
result sets.

## Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| crm_connection_id | string | yes | UUID of the CRM connection |

## Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| query | string | no | Full-text search across rep name and target book name. Requires at least 2 characters; shorter values return an empty result set. |
| book_definition_id | string | no | Filter by target book Salesforce ID (exact match) |
| manager_id | string | no | Filter by manager Salesforce User ID (exact match) |
| is_active | string | no | Filter by User.IsActive. Returns reps of all statuses when omitted. |
| sort_by | string | no | SOQL field on GradientWorks__Book__c (or a dotted relationship path) to sort by, e.g. GradientWorks__User__r.Name. GradientWorks__User__c is always appended as a tiebreaker unless it is already the sort_by value. |
| sort_direction | string | no | ASC or DESC |
| limit | string | no | Maximum number of reps to return (default: 50). |
| next_records_url | string | no | Cursor returned by a previous response to fetch the next page. When provided, filter/sort/search params are ignored (the underlying SOQL query is already shaped by the cursor). Metrics params (metrics, start_date, end_date), if supplied, still apply and fetch metrics for the returned page. |
| metrics | string | no | Comma-separated list of metric names to include per rep (up to 20). Alternatively, pass a single category token — `all_accounts`, `on_book`, or `off_book` — to request every metric in that category. Category tokens cannot be combined with other tokens. Requires start_date and end_date. When omitted, the `metrics` field is null in the response. |
| start_date | string | no | Start of the metrics window (inclusive), formatted as YYYY-MM-DD. Required when metrics is set. |
| end_date | string | no | End of the metrics window (inclusive), formatted as YYYY-MM-DD. Required when metrics is set. |
| hierarchy_rollup_enabled | string | no | When true, expands metrics to include child accounts via the org's configured account hierarchy. Returns 400 if account hierarchy is not configured in the Salesforce org. |

## Response

`200 OK` — `application/json`

| Field | Type | Description |
|-------|------|-------------|
| reps | array[object] | — |
| reps.id | string | Salesforce User ID of the rep |
| reps.name | string | User.Name |
| reps.is_active | boolean | User.IsActive |
| reps.role | object | User.UserRole, if assigned |
| reps.role.id | string | — |
| reps.role.name | string | — |
| reps.profile | object | User.Profile, if any |
| reps.profile.id | string | — |
| reps.profile.name | string | — |
| reps.manager | object | User.Manager, if assigned |
| reps.manager.id | string | — |
| reps.manager.name | string | — |
| reps.target_book | object | — |
| reps.target_book.id | string | — |
| reps.target_book.name | string | — |
| reps.metrics | object | Requested metrics keyed by metric name. Null when the caller did not request metrics. Individual values may be null for threshold-dependent metrics when the target book has no Activity Threshold configured. |
| next_records_url | string | Pass this value as next_records_url on the next request to fetch the following page. Null when all records have been returned. Only present when limit exceeds Salesforce's per-page maximum (2000 records). |

## Errors

| Status | Description |
|--------|-------------|
| 400 | Bad Request |
| 403 | Forbidden |
| 404 | Not Found |
| 422 | Unprocessable Entity |
| 502 | Bad Gateway |