> ## 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. # Open a Corporate Registration Filing > Start a state registration for one of your entities Opens a filing in one state for one of your entities and returns it with the checklist Turris will work through. ## What is decided for you A filing is a workflow Turris runs. The statuses past the first are our operational vocabulary, not yours to declare, so the field is not accepted. Which half of the state template the checklist comes from is decided by the entity's recorded type — LLC, S-Corp and so on — not by the request. An entity with no type recorded returns **400**: writing a guess would silently snapshot the wrong checklist. Frozen at this moment. Later template changes never reshape a filing that is already open. ## One open filing per state and type A second filing for the same entity, state and filing type is refused with **409** while the first is still open. Completed and cancelled filings do not block a new one, so this year's annual report after last year's is fine, and so is a fresh registration after an earlier attempt was cancelled. This is stricter than the agency application on purpose: through an API, a retry loop creates real work in a Turris operator's queue. ## States without a template Turris maintains a filing template per state. A state we have not templated yet returns **404** naming the state — a real answer about the platform rather than a malformed request. Send an `Idempotency-Key` header. See [Idempotency](/guides/idempotency). ## OpenAPI ````yaml openapi/v2.json POST /v2/downstream/corporate-registration-filings 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/corporate-registration-filings: post: tags: - downstream/corporate-registrations summary: Open a corporate registration filing description: >- Opens a filing in one state for one of your entities and returns it with the checklist Turris will work through. The checklist and the state's fees are snapshotted from the live template at this moment and stay fixed for the life of the filing. Status is always 'not started' and cannot be set. The entity's variant follows its recorded entity type, so an entity with none returns 400. A second filing for the same entity, state and type is refused while the first is still open. operationId: CorporateRegistrationsController_addFiling_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/AddCorporateRegistrationFilingDto' responses: '201': description: The filing opened content: application/json: schema: type: object properties: data: $ref: >- #/components/schemas/DownstreamCorporateRegistrationFilingResponse 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 the entity has no entity type recorded 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, or Turris has no template for that state content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '409': description: That entity already has an open filing of this type in this state content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' components: schemas: AddCorporateRegistrationFilingDto: type: object properties: stateCode: type: string description: >- The state or territory to register in. Turris must have a filing template for it. 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 filingType: type: string description: >- What kind of filing this is. The state template carries a different checklist per type, so this decides the work the filing is opened with. enum: - initial registration - annual report - withdrawal - amendment - other example: initial registration downstreamEntityId: type: string description: >- Which of your entities the filing is for. Defaults to your own organization. Registration is per legal entity, so a group filing for a branch must name that branch. example: 6610b3d2c2e0a51b8c0d1f02 required: - stateCode - filingType DownstreamCorporateRegistrationFilingResponse: type: object properties: filingId: type: string description: Unique identifier of the filing example: 6710b3d2c2e0a51b8c0d1f44 downstreamEntityId: type: string description: Which of your entities this filing registers example: 6610b3d2c2e0a51b8c0d1f02 stateCode: type: string description: The state the entity is being registered in example: PA filingType: type: string description: What kind of registration this is enum: - initial registration - annual report - withdrawal - amendment - other example: initial registration status: type: string description: Where the filing has got to enum: - not started - in progress - ready to file - filed - completed - on hold - canceled example: not started entityVariant: type: string description: The corporate form the filing was opened against enum: - C-Corp - LLC - Partnership - S-Corp - Sole Proprietor - Non-profit example: C-Corp checklist: description: The work, grouped. Turris-internal categories are not returned. type: array items: $ref: '#/components/schemas/CorporateRegistrationCategoryResponse' stateInfo: description: What the state required when the filing was opened allOf: - $ref: '#/components/schemas/CorporateRegistrationStateInfoResponse' acknowledgedAt: type: string description: ISO 8601, when you acknowledged the completed filing createdAt: type: string description: ISO 8601 creation timestamp example: '2026-01-04T00:00:00.000Z' updatedAt: type: string description: ISO 8601 last-update timestamp example: '2026-02-12T09:00:00.000Z' required: - filingId - downstreamEntityId - stateCode - filingType - status - entityVariant - checklist 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 CorporateRegistrationCategoryResponse: type: object properties: name: type: string description: Category name example: State filing tone: type: string description: How the agency app emphasises the group enum: - primary - secondary - neutral - green - red - yellow example: primary order: type: number description: Position within the checklist example: 1 items: description: The steps in this group type: array items: $ref: '#/components/schemas/CorporateRegistrationTaskResponse' required: - name - tone - order - items CorporateRegistrationStateInfoResponse: type: object properties: filingName: type: string description: What the state calls this filing example: Foreign Qualification filingFee: type: number description: Filing fee in dollars example: 250 annualReportType: type: string description: What kind of annual report the state requires enum: - fixed - anniversary - biennial anniversary - biennial fixed - fiscal - decennial - none example: fixed annualReportFrequency: type: string description: How often the annual report is due enum: - annual - biennial - none example: annual annualReportFee: type: number description: Annual report fee in dollars example: 75 annualReportFiler: type: string description: Who files the annual report example: Registered agent hasFranchiseTax: type: boolean description: Whether the state levies a franchise tax example: false ssnRequirement: type: string description: Whether the state requires an SSN on the filing enum: - none - sos - tax example: none areSharesRequired: type: boolean description: Whether share information is required example: false secretaryOfStateUrl: type: string description: Secretary-of-state URL example: https://www.dos.pa.gov notes: type: string description: Free-text notes about the jurisdiction capturedAt: type: string description: ISO 8601, when the snapshot was taken example: '2026-01-04T00:00:00.000Z' required: - filingName - annualReportType - hasFranchiseTax - ssnRequirement - areSharesRequired - capturedAt CorporateRegistrationTaskResponse: type: object properties: label: type: string description: What the step is example: File the certificate of authority required: type: boolean description: Whether the step is mandatory for this filing example: true order: type: number description: Position within the category example: 2 isComplete: type: boolean description: Whether Turris has completed this step example: false completedAt: type: string description: ISO 8601 completion timestamp example: '2026-02-12T09:00:00.000Z' isAwaitingYourUpload: type: boolean description: >- True when this step is waiting on a file from you rather than from Turris example: false referenceFields: description: Values recorded against this step type: array items: $ref: '#/components/schemas/CorporateRegistrationReferenceFieldResponse' attachments: description: Files attached to this step type: array items: $ref: '#/components/schemas/CorporateRegistrationAttachmentResponse' required: - label - required - order - isComplete - isAwaitingYourUpload - referenceFields - attachments CorporateRegistrationReferenceFieldResponse: type: object properties: label: type: string description: What the value is example: State filing number value: type: string description: The value, always as text example: '7788123' type: type: string description: How to interpret the value enum: - text - textarea - url example: text required: - label - value - type CorporateRegistrationAttachmentResponse: type: object properties: fileDocumentId: type: string description: >- Identifier of the document. Metadata only: no download URL is returned. example: 66a1b2c3d4e5f6a7b8c9d0e3 fileName: type: string description: File name example: certificate-of-authority.pdf uploadedByType: type: string description: Whether your agency or Turris uploaded it enum: - admin - customer example: admin uploadedAt: type: string description: ISO 8601 upload timestamp example: '2026-02-10T14:05:00.000Z' required: - fileDocumentId - fileName - uploadedByType - uploadedAt ```` ## Related topics - [Get a Corporate Registration Filing](/api-reference/v2/downstream/corporate-registrations/get-filing.md) - [List Corporate Registration Filings](/api-reference/v2/downstream/corporate-registrations/list-filings.md) - [List Corporate Registration Profiles](/api-reference/v2/downstream/corporate-registrations/list-profiles.md)