> ## 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. # Add a Licensed Entity > Create a branch under your top company Creates a new legal entity as a branch of your top company, and provisions the organization behind it. ## What you cannot set, and why The tree is two levels — a top company and its direct branches — so the parent is always your own organization and there is nothing to choose. A branch cannot have a branch. Inherited from your top company. A branch is on its parent's plan; choosing your own features through the API would be a self-service entitlement change. Platform state, not agency data. ## Notes * `branchName` defaults to `legalName` when omitted. It cannot be stored empty. * NPN is **not** unique across your group: branches may legitimately share one. An NPN already held outside your organization is rejected with **409**. * `isNpnRequired: true` without an `npn` is a **400**. An entity with no NPN gets no compliance data subscription, so no licences or appointments will ever appear for it. Send an `Idempotency-Key` header. See [Idempotency](/guides/idempotency). ## OpenAPI ````yaml openapi/v2.json POST /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: post: tags: - downstream/entities summary: Add a licensed entity description: >- Creates a branch under your top company and returns it in the same shape List Entities uses. The parent is always your own organization: the structure is two levels deep, so a branch cannot have branches and there is no parent to choose. Category and product features are inherited from your top company. An NPN already held outside your organization returns 409. operationId: LicensedEntitiesController_addLicensedEntity_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/AddLicensedEntityDto' responses: '201': description: The entity that was created content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/DownstreamLicensedEntityResponse' 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 request body, or your credential belongs to a branch rather than a top company 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' '409': description: The NPN is already held by an organization outside yours content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' components: schemas: AddLicensedEntityDto: type: object properties: legalName: type: string description: Registered legal name of the new entity. example: Example Insurance Services of Pennsylvania, LLC branchName: type: string description: >- Name of this specific branch location. Defaults to the legal name when omitted — the field is required in storage and rejects an empty string, so there is no way to have no branch name. example: Philadelphia Branch npn: type: string description: >- National Producer Number. Branches within one group may share an NPN, so this is not unique. An NPN already held outside your organization is rejected with 409. example: '1234567' isNpnRequired: type: boolean description: >- Whether this entity is required to hold an NPN. When true, npn must be supplied. An entity with no NPN gets no NIPR subscription and therefore no licence or appointment data. example: true ein: type: string description: Employer Identification Number example: 12-3456789 doingBusinessAs: type: string description: Doing-business-as name example: Example Branch 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 website: type: string description: Website URL example: https://example-insurance.com phoneNumber: type: string description: Primary phone number example: '+12155550100' required: - legalName 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) - [List Licensed Entities](/api-reference/v2/downstream/entities/list-entities.md) - [Add Downstream Entity](/api-reference/v1/downstream-entity-associations/add.md)