> ## Documentation Index > Fetch the complete documentation index at: https://docs.trycherry.ai/llms.txt > Use this file to discover all available pages before exploring further. # Form a new company (write scope) > Start a company formation in any US state — LLC or corporation — optionally bundling an EIN order. **This files real state paperwork and incurs filing costs.** **International founders:** the company's principal/mailing addresses and every officer address accept ANY country — set the `*Country` fields to a two-letter ISO code (default `US`). For non-US addresses the state field is free text (e.g. `CDMX`) and the zip field takes any postal code. Only `filingState` must be a US state. **LLCs must set `structureType`** (`MEMBER` or `MANAGER`). A registered agent in the filing state is required: supply your own via `registeredAgent`, or leave `useRegisteredAgentService` at its default (true) and Cherry provides one. **EIN:** include `ein` to apply for the company's EIN in the same bundle. When the responsible party has no SSN or ITIN, omit `responsiblePartySsn` and set `einNoSsn: true` — Cherry then prepares and files the EIN application with the IRS on the company's behalf, and the response carries an `einApplication` describing its status. The flag is required rather than inferred: dropping an SSN by accident and silently taking the slower route would be the wrong default, so the two are rejected as a pair (send the SSN, or send `einNoSsn`, never both). **Idempotency:** send an `Idempotency-Key` header; a retried POST with the same key replays the original result instead of forming a second company. ## OpenAPI ````yaml /openapi.json post /incorporations openapi: 3.0.3 info: title: Cherry API version: 1.0.0 description: >- Cherry's public developer API — programmatic access to a business's books as Cherry keeps them: bank transactions with their categorizations, the chart of accounts, the double-entry journal, financial statements, legal entities, the tax-obligation calendar, the fiscal health score, and company incorporations (formation, EIN, and state filings). Authenticate every request with an API key: `Authorization: Bearer ck_live_…`. Keys are created in the Cherry app and are scoped to one business (tenant) — there is no tenant id in any URL. Keys carry a `read` and/or `write` scope; every GET needs `read`, mutations need `write`. Conventions: successful responses wrap the payload in `{ "data": … }`; list endpoints add `{ "meta": { "pagination": { limit, offset, nextOffset } } }` — pass `nextOffset` back as `offset` until it is null. Errors are `{ "error": string, "reason"?: string }` with conventional status codes. Dates are `YYYY-MM-DD`; money amounts are numbers in the row's currency. Requests are rate-limited per key with token buckets (429 + `Retry-After` when exhausted); report generation has a smaller budget than plain reads. servers: - url: https://api.trycherry.ai/v1 security: - bearerAuth: [] tags: - name: Transactions description: Bank feed rows and their categorizations. - name: Accounts description: The tenant's chart of accounts. - name: Bank accounts description: >- Connected bank accounts — Plaid-linked and manual. Manual institutions are how developers without a Plaid connection bring their own accounts and transactions. - name: Bank statements description: >- Statement uploads — send a statement PDF/image and Cherry transcribes it, verifies the balances reconcile, and lands the transactions on a manual bank account. The no-export alternative to pushing rows yourself. - name: Journal description: The double-entry journal (entries and lines). - name: Reports description: Trial balance and financial statements. - name: Entities description: Legal entities behind the tenant. - name: Obligations description: The tax/compliance calendar Cherry tracks. - name: Health description: Cherry's composite fiscal readiness score. - name: Incorporations description: >- Company formation, EIN orders, and the state filings that follow — start a formation and track every filing to completion. - name: Meta description: The API's own machine-readable contract. paths: /incorporations: post: tags: - Incorporations summary: Form a new company (write scope) description: >- Start a company formation in any US state — LLC or corporation — optionally bundling an EIN order. **This files real state paperwork and incurs filing costs.** **International founders:** the company's principal/mailing addresses and every officer address accept ANY country — set the `*Country` fields to a two-letter ISO code (default `US`). For non-US addresses the state field is free text (e.g. `CDMX`) and the zip field takes any postal code. Only `filingState` must be a US state. **LLCs must set `structureType`** (`MEMBER` or `MANAGER`). A registered agent in the filing state is required: supply your own via `registeredAgent`, or leave `useRegisteredAgentService` at its default (true) and Cherry provides one. **EIN:** include `ein` to apply for the company's EIN in the same bundle. When the responsible party has no SSN or ITIN, omit `responsiblePartySsn` and set `einNoSsn: true` — Cherry then prepares and files the EIN application with the IRS on the company's behalf, and the response carries an `einApplication` describing its status. The flag is required rather than inferred: dropping an SSN by accident and silently taking the slower route would be the wrong default, so the two are rejected as a pair (send the SSN, or send `einNoSsn`, never both). **Idempotency:** send an `Idempotency-Key` header; a retried POST with the same key replays the original result instead of forming a second company. operationId: startIncorporation requestBody: required: true content: application/json: schema: type: object required: - legalName - entityType - filingState - addressStreet - addressCity - addressState - addressZip - mailingAddressStreet - mailingAddressCity - mailingAddressState - mailingAddressZip - officers properties: legalName: type: string description: Exact legal name including the suffix (LLC, Inc.). entityType: type: string enum: - LLC - CORP filingState: type: string description: Two-letter US state to form in. structureType: type: string enum: - MEMBER - MANAGER description: Required for LLCs. taxElection: type: string enum: - C Corporation - S Corporation description: Corporations only. fiscalEndMonth: type: string description: e.g. December. addressStreet: type: string addressCity: type: string addressState: type: string description: Two-letter state code for US addresses; free text elsewhere. addressZip: type: string description: ZIP for US addresses; any postal code elsewhere. addressCountry: type: string description: Two-letter ISO country code, uppercase. Default US. mailingAddressStreet: type: string mailingAddressCity: type: string mailingAddressState: type: string mailingAddressZip: type: string mailingAddressCountry: type: string officers: type: array minItems: 1 description: >- At least one officer (PERSON or COMPANY), each with their own address — any country. items: type: object registeredAgent: type: object description: >- Bring your own registered agent (must be in the filing state). Omit to use Cherry's registered-agent service. useRegisteredAgentService: type: boolean description: >- Default true when no registeredAgent is supplied: Cherry provides the agent as a separate order line. ein: type: object description: >- Apply for the company's EIN in the same bundle. Omit responsiblePartySsn when the responsible party has no SSN/ITIN, and set einNoSsn alongside it. einNoSsn: type: boolean description: >- The responsible party has no US SSN or ITIN, so Cherry prepares and files the EIN application itself and the EIN arrives later. Required when ein omits responsiblePartySsn, and rejected when sent alongside one. responses: '201': description: The incorporation order bundle content: application/json: schema: type: object properties: data: type: object properties: companyId: type: string items: type: array items: $ref: '#/components/schemas/IncorporationOrderItem' einApplication: type: object nullable: true description: >- Present when Cherry is filing the EIN application on the company's behalf (responsible party without an SSN/ITIN). example: data: companyId: comp_x1y2z3a4b5c6d7e8 items: - orderId: ord_a1b2c3d4e5f6a7b8 orderType: formation filingStatus: submitted - orderId: ord_b2c3d4e5f6a7b8c9 orderType: registered_agent filingStatus: submitted '400': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: IncorporationOrderItem: type: object description: One order line inside an incorporation bundle. properties: orderId: type: string description: Stable order id. orderType: type: string description: >- formation, registered_agent, ein, annual_report, foreign_qualification. filingStatus: type: string enum: - submitted - pending - filed - exception - cancelled filingDate: type: string format: date nullable: true Error: type: object required: - error properties: error: type: string description: Stable machine-readable error code. reason: type: string description: Human-readable explanation. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: ck_live_… description: >- Cherry API key, created in the app. Sent as `Authorization: Bearer ck_live_…`. ````