> ## 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 Licensed Entities > Every legal entity in your organization, including its branches Returns the legal entities your credential can see: your own organization plus every branch beneath it. This is the endpoint to call first — most other endpoints take a `downstreamEntityId` that comes from here. **Scope is your subtree, not your whole group.** A credential minted at the top company sees the top company and all its branches. A credential minted at a branch sees that branch and nothing above or beside it. See [Downstream Getting Started](/guides/downstream-getting-started) for why. ## Narrowing Pass `downstreamEntityId` to return a single entity. An id outside your subtree returns **404**, the same response as an id that does not exist — we do not confirm that another agency's entity exists. ## OpenAPI ````yaml openapi/v2.json GET /v2/downstream/entities 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/entities: get: tags: - downstream/entities summary: List licensed entities description: >- Returns your organization's legal entities: your entity plus every branch beneath it. Use parentId, ultimateParentId and isTopCompany to rebuild the org structure. Narrow to one entity with downstreamEntityId. Results are paginated and ordered by branch name. operationId: LicensedEntitiesController_getLicensedEntities_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 responses: '200': description: A page of licensed entities content: application/json: schema: type: object properties: data: type: object properties: items: type: array items: $ref: >- #/components/schemas/DownstreamLicensedEntityResponse 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: DownstreamLicensedEntityResponse: type: object properties: downstreamEntityId: type: string description: Unique identifier of the entity example: 6610b3d2c2e0a51b8c0d1f02 legalName: type: string description: Registered legal name example: Example Insurance Services, LLC branchName: type: string description: Name of this specific branch location example: Philadelphia Branch doingBusinessAs: type: string description: Doing-business-as name example: Example Insurance npn: type: string description: >- National Producer Number. Not a key: branches within one group may legitimately share an NPN. example: '1234567' ein: type: string description: Employer Identification Number example: 12-3456789 category: type: string description: Whether this entity is a retail agency or a wholesaler enum: - agency - agency network - wholesale brokerage - third party administrator example: agency parentId: type: string description: The immediate parent entity. Absent on the top company. example: 6610b3d2c2e0a51b8c0d1f01 ultimateParentId: type: string description: The root of this entity group. Absent on the top company itself. example: 6610b3d2c2e0a51b8c0d1f01 isTopCompany: type: boolean description: Whether this entity is the root of the group example: false incorporationStateCodes: type: array description: States and territories of incorporation example: - PA items: 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 dateIncorporated: type: string description: ISO 8601 date of incorporation example: '2015-06-01T00:00:00.000Z' website: type: string description: Website URL example: https://example-insurance.com phoneNumber: type: string description: Primary phone number example: '+12155550100' legalAddress: description: Registered legal address allOf: - $ref: '#/components/schemas/AddressResponse' mailingAddress: description: Mailing address allOf: - $ref: '#/components/schemas/AddressResponse' createdAt: type: string description: ISO 8601 creation timestamp example: '2025-01-15T10:30:00.000Z' updatedAt: type: string description: ISO 8601 last-update timestamp example: '2025-06-02T08:12:44.000Z' required: - downstreamEntityId - branchName - isTopCompany - incorporationStateCodes 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 AddressResponse: type: object properties: line1: type: string description: Street address line 1 example: 1200 Market St line2: type: string description: Street address line 2 example: Suite 400 city: type: string description: City example: Philadelphia zip: type: string description: ZIP code example: '19107' state: type: string description: Two-letter state code 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 example: PA country: type: string description: Country example: USA required: - country ```` ## Related topics - [Get a Licensed Entity](/api-reference/v2/downstream/entities/get-entity.md) - [Error Handling](/guides/error-handling.md) - [Add a Licensed Entity](/api-reference/v2/downstream/entities/add-entity.md)