> ## 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 Associations > Retrieve all downstream entity associations for your organization Returns all downstream entity associations linked to your upstream entity. ## OpenAPI ````yaml openapi/v2.json GET /v2/upstream/downstream-entity-associations 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/upstream/downstream-entity-associations: get: tags: - upstream/downstream-entity-associations operationId: AssociatedDownstreamEntitiesV2Controller_getAllDownstreamEntities_v2 parameters: - name: downstreamEntityNpn required: false in: query description: >- Downstream entity National Producer Number (NPN). Mutually exclusive with licenseNumber/stateCode, emailDomain, and email. schema: example: '12345678' type: string - name: licenseNumber required: false in: query description: >- Downstream entity license number. Must be provided together with stateCode. Mutually exclusive with downstreamEntityNpn, emailDomain, and email. schema: example: ABC123456 type: string - name: stateCode required: false in: query description: >- State code. Must be provided together with licenseNumber. Mutually exclusive with downstreamEntityNpn, emailDomain, and email. schema: example: CA type: string - name: emailDomain required: false in: query description: >- Email domain to filter downstream entity associations by contact email. Mutually exclusive with downstreamEntityNpn, licenseNumber/stateCode, and email. schema: example: example.com type: string - name: email required: false in: query description: >- Exact email address to filter downstream entity associations by contact email. Mutually exclusive with downstreamEntityNpn, licenseNumber/stateCode, and emailDomain. schema: example: example@test.com type: string responses: '200': description: List of downstream entity associations content: application/json: schema: type: object properties: data: type: array items: $ref: >- #/components/schemas/DownstreamEntityAssociationWithHierarchyResponseDto 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 '401': description: Invalid or missing auth token content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' components: schemas: DownstreamEntityAssociationWithHierarchyResponseDto: type: object properties: _id: type: string description: Association ID producerCode: type: string description: Producer code externalId: type: string description: External ID branchName: type: string description: Branch or office name for this association creationPath: type: string description: >- How this association was created: invitation, addition, bulk-upload, market, or hubspot sync. Immutable once set. downstreamEntity: description: Downstream entity details allOf: - $ref: '#/components/schemas/PopulatedDownstreamEntityResponse' niprDataSubscription: description: NIPR data subscription for this association allOf: - $ref: '#/components/schemas/ComplianceDataSubscriptionResponse' path: type: string description: >- Materialized ancestor chain, "/rootId/parentId/currentId". Segments are association ids, so each one can be looked up through this same endpoint. A top-level agency is "/ownId". Snapshot: moving an agency to a different parent rewrites it. In the rare case where an association has no stored path, this is synthesized as "/ownId" so the field is always present. level: type: number description: Depth in the hierarchy. 0 is a top-level agency. parentAssociationId: type: string description: >- Immediate parent association id. Null for a top-level agency, never absent. nullable: true ultimateParentAssociationId: type: string description: >- First segment of path. A top-level agency is its own ultimate parent. ultimateParentAgreementExecuted: type: boolean description: >- Whether the ultimate parent has an executed producer agreement. Always refers to the ROOT of the chain, never to the nearest ancestor that happens to have signed; at depth two those coincide. Snapshot as of this response. required: - _id - downstreamEntity - niprDataSubscription - path - level - parentAssociationId - ultimateParentAssociationId - ultimateParentAgreementExecuted 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 PopulatedDownstreamEntityResponse: type: object properties: _id: type: string description: Downstream entity ID isNpnRequired: type: boolean description: Whether NPN is required for this downstream entity legalName: type: string description: Legal name of the downstream entity category: type: string description: Category of the downstream entity npn: type: string description: National Producer Number ein: type: string description: Employer Identification Number required: - _id - isNpnRequired - legalName - category - npn - ein ComplianceDataSubscriptionResponse: type: object properties: dataOwnerId: type: string description: Data owner ID dataOwnerModel: type: string description: Data owner model type entityModel: type: string description: Entity model type npn: type: string description: National Producer Number nullable: true entityInfo: description: NIPR entity info details allOf: - $ref: '#/components/schemas/NiprEntityInfoResponse' lastSynchronizationDate: format: date-time type: string description: Last synchronization date pdbAlertsSubscriptionStatus: type: string description: PDB Alerts subscription status pdbAlertsPausedAt: format: date-time type: string description: Date when PDB Alerts was paused required: - dataOwnerId - dataOwnerModel - entityModel - entityInfo NiprEntityInfoResponse: type: object properties: status: type: string description: Status of the NIPR data subscription jobId: type: string description: Job ID for the NIPR entity info request message: type: string description: Message associated with the status rawEntityInfoId: type: string description: Raw entity info document ID required: - status ```` ## Related topics - [Changelog](/changelog.md) - [Agency Deleted](/guides/webhooks/downstream-entity-deleted.md) - [Agency Updated](/guides/webhooks/downstream-entity-updated.md)