> ## 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 Entity Appointments > Carrier appointments held by your legal entities Returns the carrier appointments held by your entities: which carrier, which state, which lines, and the appointment's standing. Like entity licences, appointments are keyed on the entity's compliance data subscription rather than on the entity id directly. An entity with no NPN has no subscription and therefore no appointments. ## Narrowing `downstreamEntityId`, `stateCode` and `status`. ## OpenAPI ````yaml openapi/v2.json GET /v2/downstream/entity-appointments 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: [] tags: [] paths: /v2/downstream/entity-appointments: get: tags: - downstream/appointments summary: List entity appointments description: >- Returns the carrier appointments held by your legal entities across your organization. Narrow with downstreamEntityId, stateCode, status or companyCode. Carrier names come from the NIPR record and are not normalised, so group on companyCode. Results are paginated and ordered by state. operationId: AppointmentsController_getEntityAppointments_v2 parameters: - name: page required: false in: query description: 1-based page number schema: minimum: 1 default: 1 example: 1 type: number - name: limit required: false in: query description: Page size (max 100) schema: minimum: 1 maximum: 100 default: 50 example: 50 type: number - name: downstreamEntityId required: false in: query description: >- Narrow the results to a single entity in your organization. Defaults to your whole subtree (your entity plus every branch beneath it). Returns 404 if the id is not in your subtree. schema: example: 6610b3d2c2e0a51b8c0d1f02 type: string - name: stateCode required: false in: query description: Two-letter state or territory code schema: example: PA 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: status required: false in: query description: Appointment status schema: example: appointed type: string enum: - terminated - appointed - name: companyCode required: false in: query description: >- The carrier's company code. Filter on this rather than carrierName, which comes off the NIPR record unnormalised and can spell one carrier several ways. schema: example: '12345' type: string responses: '200': description: A page of entity appointments content: application/json: schema: type: object properties: data: type: object properties: items: type: array items: $ref: '#/components/schemas/DownstreamAppointmentResponse' 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 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: Your organization is not entitled to the public API content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '404': description: downstreamEntityId is not in your organization content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' components: schemas: DownstreamAppointmentResponse: type: object properties: appointmentId: type: string description: Unique identifier of the appointment example: 6627f2b5c2e0a51b8c0d4e7c holderType: type: string description: Whether an agency entity or a producer holds this appointment enum: - entity - producer example: entity holderId: type: string description: >- The entity id for an entity appointment, the producer id for a producer one example: 6610b3d2c2e0a51b8c0d1f02 holderName: type: string description: Name of the holder example: Philadelphia Branch downstreamEntityId: type: string description: The agency this appointment sits under, whichever type holds it example: 6610b3d2c2e0a51b8c0d1f02 stateCode: type: string description: State or territory of the appointment 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: PA carrierName: type: string description: >- Carrier name exactly as the NIPR record spells it. Not joined to a Turris market, and not normalised: group on companyCode instead. example: Example Mutual Insurance Company companyCode: type: string description: The carrier's company code. Stable, unlike carrierName. example: '12345' status: type: string description: Appointment status enum: - terminated - appointed example: appointed lineOfAuthorityName: type: string description: Line-of-authority name example: Property lineOfAuthorityCode: type: string description: Line-of-authority code example: '16' npn: type: string description: The NPN the appointment was issued against example: '1234567' terminationReason: type: string description: Present only when the appointment is terminated example: Voluntary countyName: type: string description: County the appointment covers, where the state records one example: Bucks statusChangeDate: type: string description: ISO 8601 date the status last changed example: '2025-04-01T00:00:00.000Z' renewalDate: type: string description: >- ISO 8601 renewal date. Absence does NOT mean expired: two ingest paths write this field differently, one leaving it null and one leaving it missing. example: '2027-04-01T00:00:00.000Z' updatedAt: type: string description: ISO 8601 last-update timestamp example: '2026-06-02T08:12:44.000Z' required: - appointmentId - holderType - holderId - holderName - downstreamEntityId - stateCode - carrierName - companyCode - status - lineOfAuthorityName - lineOfAuthorityCode - npn 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 - 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 - 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 ```` ## Related topics - [List Producer Appointments](/api-reference/v2/downstream/appointments/producer-appointments.md) - [Get Downstream Entity Appointments](/api-reference/v1/appointments/downstream-entity-appointments.md) - [List Licensed Entities](/api-reference/v2/downstream/entities/list-entities.md)