> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turrisfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Appointment Requests

> Appointment requests for your agents and agencies, wherever they were made

Returns the appointment requests for your agents and agencies, newest first. Requests made anywhere are included, the Turris dashboard too, so this list shows everything Turris operations is working on for you.

Each row carries an `appointmentRequestId`. Use it with [Get an Appointment Request](https://docs.turrisfi.com/api-reference/v2/appointments/get-appointment-request.md) to follow one request until it completes.

> [!NOTE]
>
> The appointments themselves, once granted, are on the agent and downstream entity association appointment endpoints. This list is the requests on their way there.

## Query Parameters

Every filter is optional, and filters combine.

| Parameter | Type | Description |
| - | - | - |
| **`agentId`** | string | Only requests for this agent. Cannot be combined with `downstreamEntityAssociationId`. |
| **`downstreamEntityAssociationId`** | string | Only the requests of the agency behind this association and of your other agencies with the same NPN, closed ones included. One open request covers every agency with that NPN, so the filter returns it whichever of them it was made for. Each row carries the current association id of the agency it was made for, which can differ from the one you sent. An archived association works too. Requests for the agency's producers are **not** included: an agent request does not record the agency it was made through, so filter those by `agentId`. Cannot be combined with `agentId`. |
| **`stateCode`** | string | Only requests in this state or territory, e.g. `TX`. |
| **`productId`** | string | Only requests made under this product. |
| **`status`** | string, repeatable | Only requests in any of these statuses. Repeat the parameter (`?status=pending&status=submitted`) or separate values with commas (`?status=pending,submitted`). |
| **`page`** | number | 1-based page number. Defaults to `1`. |
| **`limit`** | number | Page size, max `100`. Defaults to `50`. |

An `agentId` or `downstreamEntityAssociationId` that is not in your organization returns `404`, not an empty list. Both together return `400`.

## Statuses

| Status | Meaning |
| - | - |
| `pending` | Requested, not yet filed with the state. |
| `submitting` | Being filed with the state. |
| `submitted` | Filed with the state, waiting for the outcome. |
| `completed` | The request is complete. |
| `failed` | The request failed. |
| `submission failed` | Filing with the state failed. |
| `rejected` | The state rejected the request. |
| `canceled` | The request was cancelled. |
| `archived` | The request was archived. |

`pending`, `submitting` and `submitted` are in progress. Every other status is final, so stop polling a request once it reaches one of them. The [Appointment Request Status Change](https://docs.turrisfi.com/guides/webhooks/appointment-request-status-change.md) webhook tells you about each change without polling.

A cancelled request stays in the list with status `canceled`, whether it was cancelled in the Turris dashboard, with [Cancel an Appointment Request](https://docs.turrisfi.com/api-reference/v2/appointments/cancel-appointment-request.md), or because a product was unassigned. To leave cancelled requests out, filter by the statuses you want.

Turris operations moves requests between statuses today. When filing is automated, requests move through the same statuses on their own; no new value is added.

## What the list leaves out

* **Renewal and line-of-authority change requests.**

## Response Shape

> [!NOTE]
>
> All successful responses are wrapped in the standard response envelope. See [Request/Response Conventions](https://docs.turrisfi.com/guides/request-response.md).

At most one of `agentId` and `downstreamEntityAssociationId` is set on each row: a request for an agency that has no association with you left at all carries neither. Fields with no value are left out. `submittedAt` is the time of the request's most recent move to `submitted`. It is kept when the request moves on, and removed if the request goes back to `pending` or `submitting`. A request that never reached `submitted`, and requests submitted before Turris started recording it, lack it, so `status` is the signal that a request has been filed. `completedAt` is set on completion, but some older completed requests lack it, so `status` is the completion signal. `canceledAt` and `canceledBy` are set only on a `canceled` request. `canceledAt` is when it was cancelled. `canceledBy.type` says who cancelled it: `api_client` when it was cancelled through this API, `member` for a person signed in to the Turris dashboard, `admin` for Turris operations, and `system` when Turris cancelled it on its own. Member ids and emails are not included. Requests cancelled before Turris started recording this lack both fields, so `status` is the signal that a request is cancelled.

```json theme={null}
{
  "data": {
    "items": [
      {
        "appointmentRequestId": "6672b1c2d3e4f5a6b7c8d9e0",
        "agentId": "6650a1b2c3d4e5f6a7b8c9d0",
        "stateCode": "TX",
        "productId": "6600a1b2c3d4e5f6a7b8c9d0",
        "carrier": { "name": "Example Mutual Insurance", "companyCode": "12345" },
        "linesOfAuthority": [{ "code": "16", "name": "Property" }],
        "status": "submitted",
        "processingMethod": "manual",
        "requestedAt": "2026-11-10T15:04:05.000Z",
        "submittedAt": "2026-11-11T09:30:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 50,
    "totalPages": 1
  },
  "requestId": "abcd1234",
  "timestamp": "2026-11-11T10:00:00.000Z"
}
```


## OpenAPI

````yaml openapi/v2.json GET /v2/upstream/appointment-requests
openapi: 3.0.0
info:
  title: Turris Public API
  description: API for managing insurance compliance data
  version: 2.0.0
  contact: {}
servers:
  - url: https://public.api.live.turrisfi.com
    description: Production
  - url: https://public.api.sandbox.turrisfi.com
    description: Sandbox
security:
  - bearer: []
  - restricted-access-token: []
tags:
  - name: auth
    description: Shared. Serves either organization category, so no persona applies.
    x-organization-category: null
  - name: downstream/actions-required
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/appointments
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/carriers
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/compliance-configs
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/contacts
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/corporate-registrations
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/documents
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/entities
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/license-overview
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/license-requests
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/licenses
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/markets
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/producers
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/surplus-lines-filings
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: downstream/surplus-lines-states
    description: >-
      Agency surface. Requires a credential whose organization category is
      downstreamEntity.
    x-organization-category: downstreamEntity
  - name: heartbeat
    description: Shared. Serves either organization category, so no persona applies.
    x-organization-category: null
  - name: upstream/agents
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/agents-license-compliance
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/appointment-requests
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/carriers
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/compliance-data-subscriptions
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/contacts
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/contract-container-templates
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/diligent-effort-requests
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/downstream-entity-associations
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/file-documents
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/market-contacts
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/npn-lookup
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/policies
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/products
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/surplus-lines-filings
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/surplus-lines-states
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/termination-requests
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
  - name: upstream/webhooks
    description: >-
      Carrier and MGA surface. Requires a credential whose organization category
      is upstreamEntity.
    x-organization-category: upstreamEntity
paths:
  /v2/upstream/appointment-requests:
    get:
      tags:
        - upstream/appointment-requests
      summary: List appointment requests
      description: >-
        Returns the appointment requests for your agents and agencies, made
        anywhere, the dashboard included. Narrow with agentId or
        downstreamEntityAssociationId, stateCode, productId and status; filters
        combine. Results are paginated, newest first.
      operationId: AppointmentRequestsV2Controller_getAppointmentRequests_v2
      parameters:
        - name: page
          required: false
          in: query
          description: 1-based page number
          schema:
            minimum: 1
            default: 1
            example: 1
            type: integer
        - name: limit
          required: false
          in: query
          description: Page size (max 100)
          schema:
            minimum: 1
            maximum: 100
            default: 50
            example: 50
            type: integer
        - name: agentId
          required: false
          in: query
          description: >-
            Only requests for this agent. Cannot be combined with
            downstreamEntityAssociationId. Returns 404 when the agent is not in
            your organization.
          schema:
            example: 6650a1b2c3d4e5f6a7b8c9d0
            type: string
        - name: downstreamEntityAssociationId
          required: false
          in: query
          description: >-
            Only the requests of the agency behind this downstream entity
            association and of your other agencies with the same NPN, closed
            ones included: one open request covers every agency with that NPN,
            so the filter returns it whichever of them it was made for. Each row
            carries the current association id of the agency it was made for,
            which can differ from the one you sent. An archived association
            works too. Requests for the agency's producers are not included,
            because an agent request does not record the agency it was made
            through. Cannot be combined with agentId. Returns 404 when the
            association is not in your organization.
          schema:
            example: 6651a1b2c3d4e5f6a7b8c9d0
            type: string
        - name: stateCode
          required: false
          in: query
          description: Only requests in this state or territory
          schema:
            example: TX
            type: string
            enum:
              - AL
              - AK
              - AZ
              - AR
              - CA
              - CO
              - CT
              - DE
              - FL
              - GA
              - HI
              - ID
              - IL
              - IN
              - IA
              - KS
              - KY
              - LA
              - ME
              - MD
              - MA
              - MI
              - MN
              - MS
              - MO
              - MT
              - NE
              - NV
              - NH
              - NJ
              - NM
              - NY
              - NC
              - ND
              - OH
              - OK
              - OR
              - PA
              - RI
              - SC
              - SD
              - TN
              - TX
              - UT
              - VT
              - VA
              - WA
              - WV
              - WI
              - WY
              - GU
              - PR
              - VI
              - DC
        - name: productId
          required: false
          in: query
          description: Only requests made under this product
          schema:
            example: 6600a1b2c3d4e5f6a7b8c9d0
            type: string
        - name: status
          required: false
          in: query
          description: >-
            Only requests in any of these statuses. Repeat the parameter
            (status=pending&status=submitted) or separate values with commas.
          schema:
            example:
              - pending
              - submitted
            type: array
            items:
              type: string
              enum:
                - pending
                - submitting
                - submitted
                - completed
                - failed
                - submission failed
                - rejected
                - canceled
                - archived
      responses:
        '200':
          description: A page of appointment requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/AppointmentRequestResponse'
                      total:
                        type: integer
                        description: Total rows matching the query across all pages
                        example: 137
                      page:
                        type: integer
                        description: 1-based page number
                        example: 1
                      limit:
                        type: integer
                        description: Page size
                        example: 50
                      totalPages:
                        type: integer
                        description: Number of pages, or 0 when there are no rows
                        example: 3
                    required:
                      - items
                      - total
                      - page
                      - limit
                      - totalPages
                  requestId:
                    type: string
                    description: Unique request identifier
                    example: dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8
                  timestamp:
                    type: string
                    description: Response timestamp
                    example: '2025-11-12T20:49:03.293Z'
                required:
                  - data
                  - requestId
                  - timestamp
        '400':
          description: >-
            Invalid query parameters, or both agentId and
            downstreamEntityAssociationId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '401':
          description: Invalid or missing auth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '403':
          description: >-
            Returned with `errorType` `invalid_organization_category` when your
            credential's organization category does not match the one this
            endpoint serves; `details` names the expected and actual category.
            This endpoint can return 403 for other reasons too, so branch on
            `errorType`; the Error Handling guide lists them.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '404':
          description: agentId or downstreamEntityAssociationId is not in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '429':
          description: >-
            Too many requests: this credential passed the API-wide limit of 1000
            requests per 10 seconds, counted across every endpoint. The request
            was not processed. Wait the number of seconds in the Retry-After
            header, then retry.
          headers:
            Retry-After:
              description: >-
                Seconds to wait before retrying. Sent when a rate limit refused
                the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
components:
  schemas:
    AppointmentRequestResponse:
      type: object
      properties:
        agentId:
          type: string
          description: >-
            Set when the request is for a producer. At most one of agentId and
            downstreamEntityAssociationId is set.
          example: 6650a1b2c3d4e5f6a7b8c9d0
        downstreamEntityAssociationId:
          type: string
          description: >-
            Set when the request is for an agency. At most one of agentId and
            downstreamEntityAssociationId is set. If the agency is no longer
            associated with you, this is the most recent association you had
            with it; when no association with the agency is left at all, neither
            field is set.
          example: 6651a1b2c3d4e5f6a7b8c9d0
        stateCode:
          type: string
          description: State or territory of the request
          enum:
            - AL
            - AK
            - AZ
            - AR
            - CA
            - CO
            - CT
            - DE
            - FL
            - GA
            - HI
            - ID
            - IL
            - IN
            - IA
            - KS
            - KY
            - LA
            - ME
            - MD
            - MA
            - MI
            - MN
            - MS
            - MO
            - MT
            - NE
            - NV
            - NH
            - NJ
            - NM
            - NY
            - NC
            - ND
            - OH
            - OK
            - OR
            - PA
            - RI
            - SC
            - SD
            - TN
            - TX
            - UT
            - VT
            - VA
            - WA
            - WV
            - WI
            - WY
            - GU
            - PR
            - VI
            - DC
          example: TX
        productId:
          type: string
          description: The product the request was made under
          example: 6600a1b2c3d4e5f6a7b8c9d0
        carrier:
          description: The carrier, as it was when the request was made
          allOf:
            - $ref: '#/components/schemas/AppointmentChangeRequestCarrierResponse'
        linesOfAuthority:
          description: Lines of authority the request covers. Filled by Turris.
          type: array
          items:
            $ref: >-
              #/components/schemas/AppointmentChangeRequestLineOfAuthorityResponse
        status:
          type: string
          description: >-
            Where the request is. Today Turris operations move requests between
            statuses by hand; with filing automation they move on their own.
            Every value is listed so that change adds no new one.
          enum:
            - pending
            - submitting
            - submitted
            - completed
            - failed
            - submission failed
            - rejected
            - canceled
            - archived
          example: pending
        processingMethod:
          type: string
          description: >-
            Whether the request is filed by hand or automatically. Every request
            is filed by hand today.
          enum:
            - automated
            - manual
          example: manual
        requestedAt:
          type: string
          description: When the request was made (ISO 8601)
          example: '2026-11-10T15:04:05.000Z'
        submittedAt:
          type: string
          description: >-
            When the request was filed with the state (ISO 8601): the time of
            its most recent move to submitted. Kept when the request moves on,
            removed if it goes back to pending or submitting, and absent on a
            request that never reached submitted and on requests submitted
            before Turris started recording it.
          example: '2026-11-11T09:30:00.000Z'
        completedAt:
          type: string
          description: >-
            When the request completed (ISO 8601). Absent until then, and on
            some requests completed before Turris recorded the date, so use
            status as the completion signal.
          example: '2026-11-14T16:00:00.000Z'
        canceledAt:
          type: string
          description: >-
            When the request was canceled (ISO 8601). Set only on a canceled
            request, and absent on requests canceled before Turris started
            recording it, so use status as the signal that a request is
            canceled.
          example: '2026-11-16T10:00:00.000Z'
        canceledBy:
          description: >-
            Who canceled the request, as the kind of actor only. Set only on a
            canceled request, together with canceledAt.
          allOf:
            - $ref: '#/components/schemas/AppointmentChangeRequestCanceledByResponse'
        appointmentRequestId:
          type: string
          description: Appointment request ID
          example: 6672b1c2d3e4f5a6b7c8d9e0
      required:
        - stateCode
        - productId
        - carrier
        - linesOfAuthority
        - status
        - processingMethod
        - requestedAt
        - appointmentRequestId
    ErrorResponseDto:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
        requestId:
          type: string
          description: Unique request identifier for debugging
        errorType:
          type: string
          description: >-
            Machine-readable error classification. Branch on this rather than on
            `errorMessage`, which is prose and may change. Authentication
            failures returned by our identity provider are forwarded verbatim,
            so a 401 can carry a code outside this list; treat an unrecognised
            value as a generic failure of its HTTP status.
          enum:
            - conflict
            - contact_not_authorized
            - contract_already_signed
            - document_exceeds_page_limit
            - downstream_entity_member_exists
            - duplicate_external_id_error
            - duplicate_member_email
            - duplicate_producer_code_error
            - forbidden
            - gateway_timeout
            - inactive_email
            - internal_server_error
            - invalid_email
            - invalid_email_for_invites
            - invalid_organization_category
            - invalid_organization_slug
            - invalid_phone_number
            - invalid_token
            - invite_limit_reached
            - jwt_invalid
            - m2m_client_not_found
            - not_found
            - online_signing_in_progress
            - organization_already_exists
            - organization_slug_already_used
            - payment_required
            - producer_agreement_required
            - product_feature_subscription_required
            - service_unavailable
            - session_authorization_error
            - some_custom_error_string
            - throttled
            - too_many_requests
            - unauthorized
            - unauthorized_client
            - unexpected_400_stytch_error
            - unexpected_403_stytch_error
            - unexpected_404_stytch_error
            - unexpected_error
            - unexpected_stytch_error
            - unprocessable_entity
            - validation_error
          example: validation_error
        errorMessage:
          description: Array of error messages
          type: array
          items:
            type: string
        timestamp:
          type: string
          description: ISO timestamp when the error occurred
        details:
          type: object
          description: Additional error context
      required:
        - statusCode
        - requestId
        - errorType
        - errorMessage
        - timestamp
    AppointmentChangeRequestCarrierResponse:
      type: object
      properties:
        name:
          type: string
          description: Carrier name, as it was when the request was made
          example: Example Mutual Insurance
        companyCode:
          type: string
          description: NAIC company code. Absent on older requests that never stored one.
          example: '12345'
      required:
        - name
    AppointmentChangeRequestLineOfAuthorityResponse:
      type: object
      properties:
        code:
          type: string
          description: Line-of-authority code
          example: '16'
        name:
          type: string
          description: Line-of-authority name
          example: Property
      required:
        - code
        - name
    AppointmentChangeRequestCanceledByResponse:
      type: object
      properties:
        type:
          type: string
          description: >-
            Who canceled the request: api_client for a call to the cancel
            endpoint with your API credentials, member for a person signed in to
            the Turris dashboard, admin for Turris operations, and system for
            Turris acting on its own with no person or API call behind it.
            Member ids and emails are not exposed.
          enum:
            - member
            - api_client
            - admin
            - agent
            - system
          example: api_client
      required:
        - type
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
    restricted-access-token:
      type: apiKey
      in: header
      name: x-restricted-access-token
      description: >-
        Alternative authentication: Restricted access token (if not using Bearer
        token)

````

## Related topics

- [Request an Appointment](https://docs.turrisfi.com/api-reference/v2/appointments/create-appointment-request.md)
- [List Termination Requests](https://docs.turrisfi.com/api-reference/v2/appointments/list-termination-requests.md)
- [Get an Appointment Request](https://docs.turrisfi.com/api-reference/v2/appointments/get-appointment-request.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.