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

# Request an Appointment

> Request one appointment, and get the request or the reason it was refused

Requests the appointment of one agent or one agency with the carrier of `productId`, in `stateCode`. The answer is the one the Turris dashboard would give: `201` with the new request, or the reason it was refused. Needs the Appointment product feature.

## Request Body

Send exactly one of `agentId` and `downstreamEntityAssociationId`. Neither or both returns `400`.

For an agent:

```json theme={null}
{
  "agentId": "6650a1b2c3d4e5f6a7b8c9d0",
  "stateCode": "TX",
  "productId": "6600a1b2c3d4e5f6a7b8c9d0"
}
```

For an agency, name it by its association with you:

```json theme={null}
{
  "downstreamEntityAssociationId": "6651a1b2c3d4e5f6a7b8c9d0",
  "stateCode": "TX",
  "productId": "6600a1b2c3d4e5f6a7b8c9d0"
}
```

## What You Get Back

Every request starts as `pending` with `processingMethod` `manual`: Turris operations files it with the state, and its `status` moves from there. Follow it with [Get an Appointment Request](https://docs.turrisfi.com/api-reference/v2/appointments/get-appointment-request.md), which returns the same fields. See [List Appointment Requests](https://docs.turrisfi.com/api-reference/v2/appointments/list-appointment-requests.md) for the statuses.

```json theme={null}
{
  "data": {
    "appointmentRequestId": "6672b1c2d3e4f5a6b7c8d9e0",
    "agentId": "6650a1b2c3d4e5f6a7b8c9d0",
    "stateCode": "TX",
    "productId": "6600a1b2c3d4e5f6a7b8c9d0",
    "carrier": { "name": "Example Mutual Insurance", "companyCode": "12345" },
    "linesOfAuthority": [{ "code": "16", "name": "Property" }],
    "status": "pending",
    "processingMethod": "manual",
    "requestedAt": "2026-11-13T15:04:05.000Z"
  },
  "requestId": "abcd1234",
  "timestamp": "2026-11-13T15:04:05.000Z"
}
```

## Authorization in the Same Request

The licence is checked on every request: the agent or agency must be licensed in the state for the product. If it is licensed but not yet authorized there, the request authorizes it. A refused request authorizes nothing, with two exceptions, described under [Calling It Again](#calling-it-again).

* **An agency** is authorized through the association you named.
* **An agent on exactly one of your agencies** is authorized through that agency.
* **An agent on several of your agencies** can be requested only in a state it is already authorized in, through any of them. Any other state is refused with `NOT_AUTHORIZED`, and the message asks you to authorize the state in Turris first.

## One Request per Call

A request for an agent does not also request the agency's appointment. If the carrier needs both, make a second call with the agency's `downstreamEntityAssociationId`.

## Calling It Again

Only one request can be open for the same NPN, state and carrier. NIPR appoints the NPN, so when two of your agencies have the same NPN, a request made for one of them is the open request for both. A second call answers `409`, and the two `409` codes mean different things:

* **`OPEN_REQUEST_EXISTS`**: a request is already open, for this agent or agency, for another of your agencies with the same NPN, or under another of your products with the same carrier. `details.existingAppointmentRequestId` is its id.
* **`ALREADY_APPOINTED`**: the agent or agency already holds the appointment. No request was made, and there is no id.

Both codes carry `details.isStateAuthorized`: whether the state is authorized for the product you sent, after this call. Both can still authorize it. If the agent or agency is licensed in the state but not yet authorized there for the product, the call authorizes the state, as a created request would, when an open request covers it, or when the appointment it already holds with the carrier covers every line of authority the product needs there. The field is then `true`, and a repeat call answers the same. `ALREADY_APPOINTED` with `isStateAuthorized: false` means the appointment lacks a line of authority the product needs, so the call authorized nothing. So `OPEN_REQUEST_EXISTS` with `isStateAuthorized: true` means the request exists and the state is authorized, and you can call this endpoint on every bind.

A request counts as open while it is `pending`, `submitting` or `submitted`. Once it reaches any other status, a new call creates a new request.

Send an `idempotency-key` header to make a network retry safe. A successful create is replayed with `201` and the same body for one hour. A refusal or a `503` is not stored, so a retry with the same key runs again. See [Idempotency](https://docs.turrisfi.com/guides/idempotency.md).

## Refusals

Every `409` and `422` carries `details.refusalCode`. Branch on the code; show `errorMessage` to a person.

| Status | `details.refusalCode` | When |
| - | - | - |
| `409` | `OPEN_REQUEST_EXISTS` | An open request exists for the same NPN, state and carrier, including one made for another of your agencies with that NPN, under another of your products with that carrier, or in the Turris dashboard. Carries `details.existingAppointmentRequestId` and `details.isStateAuthorized`. |
| `409` | `ALREADY_APPOINTED` | The agent or agency already holds an active appointment with the carrier in the state. No request was made. When the appointment covers every line of authority the product needs, the call authorizes the state. Carries `details.isStateAuthorized`. |
| `422` | `PRODUCT_NOT_IN_ORGANIZATION` | The product does not exist or is not one of your products. This is a `422`, not a `404`. |
| `422` | `PRODUCT_HAS_NO_CARRIER` | The product has no carrier to appoint with. |
| `422` | `STATE_NOT_SOLD` | The product is not sold in the state. |
| `422` | `APPOINTMENT_REQUIREMENT_NOT_SET_UP` | The product's setup for the state has no appointment requirement for this kind of entity (agent or agency). |
| `422` | `APPOINTMENT_FILING_NOT_REQUIRED` | The state takes no appointment filing for this kind of entity (Registry). |
| `422` | `NOT_LICENSED` | The agent or agency is not licensed in the state for the product, according to its NIPR data in Turris. |
| `422` | `LICENSE_DATA_NOT_SYNCED` | Turris has no license data for the agent or agency yet, because its compliance data has not synced from NIPR. Carries `details.syncStatus` and `details.niprDataSubscriptionId`, and `details.awaitingBusinessCopyDate` while the sync waits for NIPR's overnight update. See [License Data Not Synced Yet](#license-data-not-synced-yet). |
| `422` | `NOT_AUTHORIZED` | The agent or agency is not authorized in the state, and this request cannot authorize it, for example because the agent is on several of your agencies. |
| `422` | `NO_NIPR_DATA_SUBSCRIPTION` | Turris has no NIPR data subscription for the agent or agency through this relationship, typically because it has no NPN. |
| `422` | `AGENT_NOT_ACTIVE_ON_AGENCY` | The agent is no longer active on the agency the request would go through. |
| `400` | | Not exactly one of `agentId` and `downstreamEntityAssociationId`, an invalid `stateCode` or id, or an `idempotency-key` that is not a UUID. |
| `404` | | The association is not one of yours or is archived, or the agent is not active on any of your agencies. Unlike List Appointment Requests, an archived association cannot be requested. |
| `503` | | A concurrent change to the same agent or agency kept the request from settling, the request was created but could not be read back, or the call could not confirm that it authorized the state. Retry after the number of seconds in the `Retry-After` header. The retry answers as this call would have: if a request was made, `409` `OPEN_REQUEST_EXISTS` with its id; if the state was authorized on an appointment already held, `409` `ALREADY_APPOINTED`; either with `details.isStateAuthorized`. |

When several refusals apply, which one you get follows the order Turris checks them in. That order is not part of the contract: branch on the code, not on the order.

A `409` for an open request:

```json theme={null}
{
  "statusCode": 409,
  "requestId": "abcd1234",
  "errorType": "conflict",
  "errorMessage": ["An appointment request for this NPN, state and carrier is already open."],
  "timestamp": "2026-11-13T15:04:05.000Z",
  "details": {
    "refusalCode": "OPEN_REQUEST_EXISTS",
    "existingAppointmentRequestId": "6672b1c2d3e4f5a6b7c8d9e0",
    "isStateAuthorized": true
  }
}
```

A `422` has the same shape, with `errorType` `unprocessable_entity` and neither `existingAppointmentRequestId` nor `isStateAuthorized`.

## License Data Not Synced Yet

The license check reads the agent's or agency's NIPR data in Turris. Until its compliance data subscription has synced, Turris has no license on record, so the request is refused with `LICENSE_DATA_NOT_SYNCED` rather than `NOT_LICENSED`. A newly added agent or agency can get this while its first sync runs, and a first sync requested after about 8:45 PM Central waits for NIPR's next overnight update.

`details.syncStatus` says where the sync is and what to do:

| `details.syncStatus` | What to do |
| - | - |
| `queued`, `processing` | Wait for the sync to finish, then request again. The [Compliance Data Synchronized](https://docs.turrisfi.com/guides/webhooks/compliance-data-synchronized.md) webhook tells you when; match it on `niprDataSubscriptionId`. While the sync waits for NIPR's overnight update, `details.awaitingBusinessCopyDate` is the date of that update (YYYY-MM-DD). |
| `not started` | No sync has been requested. Start one with [Sync Agent](https://docs.turrisfi.com/api-reference/v2/compliance-data-subscriptions/sync-agent.md) or [Sync Downstream Entity](https://docs.turrisfi.com/api-reference/v2/compliance-data-subscriptions/sync-downstream-entity.md), then request again after it finishes. |
| `processing error`, `NIPR error` | The last sync failed. A sync that Turris is still retrying can show this status for a short while, so request again a little later; if it stays, contact Turris support to have the sync retried, then request again after it finishes. |

You can also follow the sync with [Get Subscription Status](https://docs.turrisfi.com/api-reference/v2/compliance-data-subscriptions/get-status.md), using `details.niprDataSubscriptionId`. If no webhook has arrived by the end of the next business day, contact Turris support.

Once the sync has finished, an agent or agency that is not licensed in the state is refused with `NOT_LICENSED`.

```json theme={null}
{
  "statusCode": 422,
  "requestId": "abcd1234",
  "errorType": "unprocessable_entity",
  "errorMessage": ["This entity's compliance data has not synced from NIPR yet, so Turris has no license data to check. Request again after the sync completes; the ENTITY_COMPLIANCE_DATA_SYNCHRONIZED webhook tells you when."],
  "timestamp": "2026-11-17T02:52:11.000Z",
  "details": {
    "refusalCode": "LICENSE_DATA_NOT_SYNCED",
    "syncStatus": "queued",
    "niprDataSubscriptionId": "507f1f77bcf86cd799439013",
    "awaitingBusinessCopyDate": "2026-11-17"
  }
}
```


## OpenAPI

````yaml openapi/v2.json POST /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:
    post:
      tags:
        - upstream/appointment-requests
      summary: Request an appointment
      description: >-
        Requests the appointment of one agent or agency with the carrier of a
        product, in one state, and answers with the request or the reason it was
        refused. A licensed state the entity is not yet authorized in is
        authorized in the same request. Every request starts as pending and is
        filed with the state by Turris.
      operationId: AppointmentRequestsV2Controller_createAppointmentRequest_v2
      parameters:
        - name: idempotency-key
          in: header
          description: UUID to ensure idempotent request processing
          required: false
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655440000
        - name: x-idempotency-key
          in: header
          description: Alternative UUID header for idempotent request processing
          required: false
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAppointmentRequestDto'
      responses:
        '201':
          description: The appointment request
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AppointmentRequestResponse'
                  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 body, or not exactly one of 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: >-
            The association is not one of yours or is archived, or the agent is
            not active on any of your agencies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '409':
          description: >-
            OPEN_REQUEST_EXISTS: an open request already exists for this NPN,
            state and carrier, made for this agent or agency, for another of
            your agencies with the same NPN, or under another of your products
            with the same carrier. details.existingAppointmentRequestId is its
            id. ALREADY_APPOINTED: the entity already holds the appointment, so
            no request was made and no id is returned. With either code,
            details.isStateAuthorized says whether the state is authorized for
            the product after the call: a licensed state is authorized by the
            call when an open request covers it, or when the held appointment
            covers every line of authority the product needs. ALREADY_APPOINTED
            with isStateAuthorized false means the appointment lacks such a
            line.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppointmentRequestConflictResponse'
        '422':
          description: >-
            The request is not eligible. details.refusalCode says which rule
            refused it. LICENSE_DATA_NOT_SYNCED: Turris has no license data for
            the agent or agency yet; details.syncStatus says whether to wait for
            the sync, start one, or contact support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppointmentRequestRefusalResponse'
        '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'
        '503':
          description: >-
            A concurrent change to the same entity kept the request from
            settling, or the request was created but could not be read back.
            Retry after Retry-After; if a request exists, the retry answers 409
            with its id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
components:
  schemas:
    CreateAppointmentRequestDto:
      type: object
      properties:
        agentId:
          type: string
          description: >-
            The producer to request the appointment for. Send this or
            downstreamEntityAssociationId, not both. If the agent is on exactly
            one of your agencies, a licensed state it is not yet authorized in
            is authorized through that agency in the same request.
          example: 6650a1b2c3d4e5f6a7b8c9d0
        downstreamEntityAssociationId:
          type: string
          description: >-
            The agency to request the appointment for, as one of your
            associations. Send this or agentId, not both.
          example: 6651a1b2c3d4e5f6a7b8c9d0
        stateCode:
          type: string
          description: The state or territory to be appointed in
          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: >-
            One of your products. Its carrier is the one the appointment is
            requested with.
          example: 6600a1b2c3d4e5f6a7b8c9d0
      required:
        - stateCode
        - productId
    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
    AppointmentRequestConflictResponse:
      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:
          description: >-
            Which rule refused the request, and the open request when one blocks
            it.
          allOf:
            - $ref: '#/components/schemas/AppointmentRequestConflictDetailsResponse'
      required:
        - statusCode
        - requestId
        - errorType
        - errorMessage
        - timestamp
        - details
    AppointmentRequestRefusalResponse:
      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:
          description: >-
            Which rule refused the request, and where the sync is when the
            license data has not synced yet.
          allOf:
            - $ref: '#/components/schemas/AppointmentRequestRefusalDetailsResponse'
      required:
        - statusCode
        - requestId
        - errorType
        - errorMessage
        - timestamp
        - details
    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
    AppointmentRequestConflictDetailsResponse:
      type: object
      properties:
        refusalCode:
          type: string
          description: >-
            Why the request was refused. Branch on this; show errorMessage to a
            person.
          enum:
            - OPEN_REQUEST_EXISTS
            - ALREADY_APPOINTED
            - PRODUCT_NOT_IN_ORGANIZATION
            - PRODUCT_HAS_NO_CARRIER
            - STATE_NOT_SOLD
            - APPOINTMENT_REQUIREMENT_NOT_SET_UP
            - APPOINTMENT_FILING_NOT_REQUIRED
            - NOT_LICENSED
            - LICENSE_DATA_NOT_SYNCED
            - NOT_AUTHORIZED
            - NO_NIPR_DATA_SUBSCRIPTION
            - AGENT_NOT_ACTIVE_ON_AGENCY
          example: NOT_LICENSED
        existingAppointmentRequestId:
          type: string
          description: >-
            The open appointment request that blocks this one. Set whenever
            refusalCode is OPEN_REQUEST_EXISTS. It can belong to another of your
            agencies with the same NPN, or to another of your products with the
            same carrier.
          example: 6672b1c2d3e4f5a6b7c8d9e0
        isStateAuthorized:
          type: boolean
          description: >-
            Whether the state is authorized for the product you sent, after this
            call. Set whenever refusalCode is OPEN_REQUEST_EXISTS or
            ALREADY_APPOINTED. A licensed state is authorized by the call when
            an open request covers it, or when the appointment already held with
            the carrier covers every line of authority the product needs, so
            this is true, and it stays true on a repeat call. With
            ALREADY_APPOINTED, false means the appointment lacks a line of
            authority the product needs, so the call authorized nothing.
          example: true
      required:
        - refusalCode
    AppointmentRequestRefusalDetailsResponse:
      type: object
      properties:
        refusalCode:
          type: string
          description: >-
            Why the request was refused. Branch on this; show errorMessage to a
            person.
          enum:
            - OPEN_REQUEST_EXISTS
            - ALREADY_APPOINTED
            - PRODUCT_NOT_IN_ORGANIZATION
            - PRODUCT_HAS_NO_CARRIER
            - STATE_NOT_SOLD
            - APPOINTMENT_REQUIREMENT_NOT_SET_UP
            - APPOINTMENT_FILING_NOT_REQUIRED
            - NOT_LICENSED
            - LICENSE_DATA_NOT_SYNCED
            - NOT_AUTHORIZED
            - NO_NIPR_DATA_SUBSCRIPTION
            - AGENT_NOT_ACTIVE_ON_AGENCY
          example: NOT_LICENSED
        syncStatus:
          type: string
          description: >-
            Set only with LICENSE_DATA_NOT_SYNCED: the agent's or agency's
            compliance data sync status, the same value Get Subscription Status
            returns. queued or processing: the sync is running; request again
            after it completes. not started: start a sync first. processing
            error or NIPR error: the last sync failed.
          enum:
            - not started
            - queued
            - processing
            - processing error
            - NIPR error
          example: queued
        niprDataSubscriptionId:
          type: string
          description: >-
            Set only with LICENSE_DATA_NOT_SYNCED: the compliance data
            subscription whose sync is awaited. The Compliance Data Synchronized
            webhook carries the same niprDataSubscriptionId, and Get
            Subscription Status takes it.
          example: 507f1f77bcf86cd799439013
        awaitingBusinessCopyDate:
          type: string
          description: >-
            Set only with LICENSE_DATA_NOT_SYNCED while the sync is held for
            NIPR's nightly update: the date of the NIPR update it is waiting for
            (YYYY-MM-DD). The sync runs once that update is available, usually
            early on that date, Central time.
          example: '2026-11-17'
      required:
        - refusalCode
  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

- [Cancel an Appointment Request](https://docs.turrisfi.com/api-reference/v2/appointments/cancel-appointment-request.md)
- [Appointment Request Status Change](https://docs.turrisfi.com/guides/webhooks/appointment-request-status-change.md)
- [Changelog](https://docs.turrisfi.com/changelog.md)


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