# List assignments

`GET` `/api/v1/crm-connections/{crm_connection_id}/assignments`

Return assignment records for the given Salesforce CRM connection.
Supports filtering by date range, assignment type, assigned rep, record, distribution run,
retrieval run, and queue. Supports sorting and cursor-based pagination.
Default page size is 50.

## 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 record name, queue name, flow name, and detail. Minimum 2 characters. |
| start_date | string | no | Filter records with assigned_time on or after this date (YYYY-MM-DD) |
| end_date | string | no | Filter records with assigned_time on or before this date (YYYY-MM-DD) |
| assignment_type | string | no | Filter by assignment type: Queue, Direct, or Other |
| assigned_to | string | no | Filter by Salesforce User ID of the assigned rep |
| record_id | string | no | Filter by Salesforce ID of the assigned record |
| record_name | string | no | Filter by exact name of the assigned record |
| distribution_run_id | string | no | Filter by Salesforce ID of the distribution run. Mutually exclusive with retrieval_run_id. |
| retrieval_run_id | string | no | Filter by Salesforce ID of the retrieval run. Mutually exclusive with distribution_run_id. |
| queue_id | string | no | Filter by Salesforce ID of the Gradient Works queue |
| sort_by | string | no | Field to sort by: assigned_at (default), assignment_type, record_name, new_owner_name, previous_owner_name, created_at, or updated_at |
| sort_direction | string | no | Sort direction: DESC (default) or ASC |
| limit | string | no | Maximum number of records to return (default: 50) |
| include_book_matches | boolean | no | When true, each assignment includes a book_definition_matches array listing the target books and segments that matched. Only populated for distribution assignments; null for retrievals and manual or queue assignments. |
| next_records_url | string | no | Cursor returned by a previous response to fetch the next page. When provided, all other query params are ignored. |

## Response

`200 OK` — `application/json`

| Field | Type | Description |
|-------|------|-------------|
| assignments | array[object] | Assignment records |
| assignments.id | string | Salesforce ID of the assignment record |
| assignments.name | string | Record name |
| assignments.created_at | string | ISO-8601 creation timestamp |
| assignments.updated_at | string | ISO-8601 last-modified timestamp |
| assignments.assignment_type | string | Assignment type: Queue, Direct, or Other |
| assignments.assigned_time | string | ISO-8601 timestamp when the assignment was made |
| assignments.assigned_by | object | User who triggered the assignment |
| assignments.assigned_by.id | string | Salesforce User ID |
| assignments.assigned_by.name | string | User display name |
| assignments.record | object | The CRM record that was assigned |
| assignments.record.id | string | Salesforce ID of the assigned record |
| assignments.record.type | string | Salesforce object type (Account, Contact, Lead, Opportunity) |
| assignments.record.field | string | Salesforce field updated by the assignment |
| assignments.record.name | string | Name of the assigned record |
| assignments.new_owner | object | User the record was assigned to |
| assignments.new_owner.id | string | Salesforce User ID |
| assignments.new_owner.name | string | User display name |
| assignments.previous_owner | object | Previous owner (null if record had no prior owner) |
| assignments.previous_owner.id | string | Salesforce User ID |
| assignments.previous_owner.name | string | User display name |
| assignments.queue | object | Queue context (null for non-Queue assignments) |
| assignments.queue.id | string | Salesforce Queue ID |
| assignments.queue.name | string | Queue name |
| assignments.queue.item_id | string | Salesforce ID of the associated Gradient Works queue item |
| assignments.request_id | string | Request ID associated with this assignment |
| assignments.flow | object | Flow context (null when the assignment was not triggered by a Salesforce Flow) |
| assignments.flow.name | string | Name of the flow that ran |
| assignments.flow.version | number | Version of the flow that ran |
| assignments.flow.version_durable_id | string | Durable ID of the flow version |
| assignments.flow.interview_guid | string | GUID of the flow interview |
| assignments.distribution | object | Distribution run that produced this assignment (null if not from a distribution) |
| assignments.distribution.id | string | Salesforce ID of the run |
| assignments.distribution.name | string | Name of the distribution or retrieval definition |
| assignments.retrieval | object | Retrieval run that produced this assignment (null if not from a retrieval) |
| assignments.retrieval.id | string | Salesforce ID of the run |
| assignments.retrieval.name | string | Name of the distribution or retrieval definition |
| assignments.detail | string | Additional assignment detail |
| assignments.book_definition_matches | array[object] | Target books and segments matched for this assignment. Only populated for distribution assignments when include_book_matches=true; null for retrievals and manual or queue assignments. |
| 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. |

## Errors

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