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

# Cancel an Appointment Request

> Cancel an appointment request while it is still pending

Cancels one appointment request by the `appointmentRequestId` from [Request an Appointment](https://docs.turrisfi.com/api-reference/v2/appointments/create-appointment-request.md) or [List Appointment Requests](https://docs.turrisfi.com/api-reference/v2/appointments/list-appointment-requests.md). Only a `pending` request can be cancelled: once Turris operations starts filing it with the state, this endpoint refuses. The call takes no request body. Needs the Appointment product feature.

## What You Get Back

`200` with the request, its `status` now `canceled`, `canceledAt` set to the time of the cancel and `canceledBy.type` `api_client`. The fields are the ones [Get an Appointment Request](https://docs.turrisfi.com/api-reference/v2/appointments/get-appointment-request.md) returns.

```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": "canceled",
    "processingMethod": "manual",
    "requestedAt": "2026-11-13T15:04:05.000Z",
    "canceledAt": "2026-11-16T09:59:59.950Z",
    "canceledBy": { "type": "api_client" }
  },
  "requestId": "abcd1234",
  "timestamp": "2026-11-16T10:00:00.000Z"
}
```

The request is kept. Get an Appointment Request returns it with `status` `canceled` from then on, and it stays in List Appointment Requests. A cancelled request no longer counts as open, so it does not block a later [Request an Appointment](https://docs.turrisfi.com/api-reference/v2/appointments/create-appointment-request.md) call for the same agent or agency, state and carrier.

## Refusals

| Status | `details.refusalCode` | When |
| - | - | - |
| `409` | `REQUEST_NOT_PENDING` | The request is not `pending`, so nothing was changed. `details.status` is its current status. `canceled` means it was already cancelled, in the Turris dashboard or by an earlier call. |
| `404` | | The id does not exist, belongs to another organization, or names a termination request. |
| `400` | | A malformed `appointmentRequestId`, or an `idempotency-key` that is not a UUID. |

If Turris operations moves the request on at the moment you cancel, the cancel loses: the answer is `409` with the status the request moved to, and the request goes ahead.

```json theme={null}
{
  "statusCode": 409,
  "requestId": "abcd1234",
  "errorType": "conflict",
  "errorMessage": ["Only a pending appointment request can be canceled."],
  "timestamp": "2026-11-16T10:00:00.000Z",
  "details": {
    "refusalCode": "REQUEST_NOT_PENDING",
    "status": "submitted"
  }
}
```

## Calling It Again

Send an `idempotency-key` header to make a network retry safe. A successful cancel is replayed with `200` and the same body for one hour. A `409` is not stored, so a retry with the same key runs again. A key reused for a different request answers `400`. See [Idempotency](https://docs.turrisfi.com/guides/idempotency.md).

Without a key, a retry after a cancel that went through answers `409` with `details.status` `canceled`. If you retried because the first call timed out, that answer means the cancel worked.


## OpenAPI

````yaml openapi/v2.json POST /v2/upstream/appointment-requests/{appointmentRequestId}/cancel
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/{appointmentRequestId}/cancel:
    post:
      tags:
        - upstream/appointment-requests
      summary: Cancel an appointment request
      description: >-
        Cancels one appointment request while it is pending, before Turris
        operations starts filing it with the state. The request is kept with
        status canceled, and Get an Appointment Request and List Appointment
        Requests return it that way from then on.
      operationId: AppointmentRequestsV2Controller_cancelAppointmentRequest_v2
      parameters:
        - name: appointmentRequestId
          required: true
          in: path
          description: >-
            Appointment request ID, as returned by the List Appointment Requests
            endpoint
          schema:
            example: 6672b1c2d3e4f5a6b7c8d9e0
            type: string
        - 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
      responses:
        '200':
          description: The appointment request, now canceled
          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: >-
            Malformed appointmentRequestId, or an idempotency-key that is not a
            UUID
          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: Appointment request not found in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '409':
          description: >-
            REQUEST_NOT_PENDING: the request is not pending, so nothing was
            changed. details.status is its current status; canceled means an
            earlier cancel already went through.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangeRequestCancelConflictResponse'
        '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
    ChangeRequestCancelConflictResponse:
      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: Why the cancel was refused, and the status the request is in.
          allOf:
            - $ref: '#/components/schemas/ChangeRequestCancelConflictDetailsResponse'
      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
    ChangeRequestCancelConflictDetailsResponse:
      type: object
      properties:
        refusalCode:
          type: string
          description: >-
            Why the cancel was refused. Branch on this; show errorMessage to a
            person.
          enum:
            - REQUEST_NOT_PENDING
          example: REQUEST_NOT_PENDING
        status:
          type: string
          description: >-
            The status the request is in, which is why it was not canceled.
            canceled means an earlier cancel, through the API or the Turris
            dashboard, already went through.
          enum:
            - pending
            - submitting
            - submitted
            - completed
            - failed
            - submission failed
            - rejected
            - canceled
            - archived
          example: submitted
      required:
        - refusalCode
        - status
  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

- [Appointment Request Status Change](https://docs.turrisfi.com/guides/webhooks/appointment-request-status-change.md)
- [List Appointment Requests](https://docs.turrisfi.com/api-reference/v2/appointments/list-appointment-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.