---
title: "File the company"
method: POST
path: "/public/one-shot/incorporations/{id}/file"
tags: ["GVRN OneShot API"]
---

# File the company

`POST /public/one-shot/incorporations/{id}/file`

## Request

- Base URL: `https://docs.gvrn.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.gvrn.ai/public/one-shot/incorporations/{id}/file`
- Auth: API key in header `x-gvrn-public-api-key`

Confirms the partner took payment and turns the draft into a company: the company record, its
members and their relationships are created on GVRN's side and the incorporation starts moving. The
payment is recorded, not verified — checkout is the partner's.

Every rule the draft has to satisfy is checked first and every failure reported together:
residency answered and not restricted, an entity chosen, a name given, ownership totalling 100%,
at least one shareholder and the jurisdiction's minimum number of directors.

Safe to retry: the same `paymentReference` on an already filed incorporation answers with it; a
different one is a conflict.

## Path parameters

- `id` string, required

## Request body

- OneShotFileApiRequestDto
  - `paymentMethod` 'CARD' | 'USDC', required
  - `paymentReference` string, required: The partner's payment id. Recorded, not verified; re-sending the same one after a timeout is safe.

## Response `200`

- OneShotIncorporationDetailsApiResponseDto
  - `id` string, required
  - `status` 'DRAFT' | 'SUBMITTED' | 'IN_PROGRESS' | 'REQUIRES_INFO' | 'ACTIVE' | 'CANCELLED', required: SUBMITTED until GVRN starts, then IN_PROGRESS — or REQUIRES_INFO while a request is open against the company. ACTIVE is the company existing on GVRN's records: an EIN for a US entity, a registration offshore.
  - `filingStatus` 'DRAFT' | 'SUBMITTED' | 'CANCELLED', required: The stored lifecycle state behind status
  - `founderEmail` string, required
  - `purpose` 'STARTUP_FOUNDER' | 'INVESTOR' | 'DIGITAL_NOMAD' | 'UNSURE'
  - `kycType` 'GVRN' | 'EXTERNAL', required
  - `jurisdiction` 'SINGAPORE' | 'PANAMA' | 'BVI' | 'DELAWARE' | 'WYOMING' | 'CAYMAN_ISLANDS' | 'COSTA_RICA' | 'DUBAI' | 'SEYCHELLES' | 'SWITZERLAND' | 'OTHERS'
  - `entityType` 'IBC' | 'FOUNDATION' | 'SPC' | 'PTE_LTD' | 'SRL' | 'SA' | 'LIMITED' | 'CORPORATION' | 'LLC'
  - `entityKey` string: The catalogue entry the pair resolves to
  - `preferredCompanyNames` string[], required: In preference order
  - `parentCompanyId` string: Set on a subsidiary; the parent holds every share
  - `company` OneShotCompanySummaryDto
    - `id` string, required
    - `displayName` string, required
    - `legalName` string: Set by GVRN once the registry confirms the name
    - `fullDisplayName` string, required: Display name with the entity suffix
    - `jurisdiction` 'SINGAPORE' | 'PANAMA' | 'BVI' | 'DELAWARE' | 'WYOMING' | 'CAYMAN_ISLANDS' | 'COSTA_RICA' | 'DUBAI' | 'SEYCHELLES' | 'SWITZERLAND' | 'OTHERS'
    - `incorporationStatus` 'INCORPORATED' | 'INCORPORATION_NOT_STARTED' | 'IN_PROGRESS' | 'REGISTERED' | 'LIVE' | 'AMALGAMATED' | 'IN_LIQUIDATION' | 'UNDER_JUDICIAL_MANAGEMENT' | 'REVOKED' | 'STRIKING_OFF' | 'STRUCK_OFF' | 'GAZETTED_TO_BE_STRUCK_OFF' | 'SUSPENDED' | 'CONVERTED' | 'DISSOLVED' | 'CANCELLED' | 'UNKNOWN_EXTERNAL', required
    - `registrationNumber` string: Issued by the registry
    - `taxNumber` string: The EIN for a US entity
    - `incorporatedAt` string: ISO 8601
  - `quotedPriceUsd` number: Catalogue price at filing
  - `filedAt` string: ISO 8601
  - `signedAt` string: ISO 8601
  - `createdAt` string, required: ISO 8601
  - `updatedAt` string, required: ISO 8601
  - `founder` OneShotFounderApiResponseDto, required
    - `firstName` string, required
    - `lastName` string, required
    - `email` string, required
    - `externalIdentityReference` string
    - `isUsPerson` boolean
    - `taxResidenceCountryCode` string: ISO 3166-1 alpha-3
  - `paymentMethod` 'CARD' | 'USDC'
  - `paymentReference` string: Exactly what you sent; GVRN records it rather than verifying it
  - `paidAt` string: ISO 8601
  - `signedByName` string
  - `members` OneShotMemberApiResponseDto[], required
    - `id` string, required: The handle for member edits
    - `kind` 'INDIVIDUAL' | 'TRUST' | 'COMPANY', required
    - `displayName` string, required: Name parts or legal name, joined
    - `firstName` string
    - `middleName` string
    - `lastName` string
    - `legalName` string
    - `email` string, required
    - `role` 'SHAREHOLDER' | 'DIRECTOR' | 'BOTH', required
    - `ownershipPercent` number, required
    - `contributionUsd` number
    - `externalIdentityReference` string
    - `isFounder` boolean, required: The account holder; never removable
    - `personId` string: The Person record behind an INDIVIDUAL, once filed
    - `companyId` string: The Company record behind a TRUST or COMPANY, once filed
    - `addedAt` string, required: ISO 8601
    - `relationshipType` 'PERSON' | 'COMPANY', required
    - `relationships` string[], required: What the role expands to, plus the founder's implied relationships
    - `kycKind` 'KYC' | 'KYB', required
    - `kycStatus` 'PENDING' | 'COMPLETED' | 'SKIPPED' | 'REJECTED' | 'EXPIRED' | 'NOT_APPLICABLE', required: SKIPPED on every member of an EXTERNAL incorporation; otherwise the latest verdict, or PENDING
  - `timeline` OneShotTimelineStepDto[], required: Empty while DRAFT
    - `key` string, required
    - `label` string, required
    - `description` string, required: Written for the founder, and worded for this entity and this founder's residency
    - `state` 'DONE' | 'NOW' | 'NEEDS_YOU' | 'PENDING', required: At most one step is NOW
    - `completedAt` string: ISO 8601
  - `actions` OneShotActionDto[], required: What the founder has to do next
    - `key` 'SIGN_GOVERNING_DOCUMENTS' | 'COMPLETE_IDENTITY_VERIFICATION', required
    - `label` string, required
    - `memberIds` string[]: The members the action is waiting on
  - `warnings` OneShotWarningDto[], required: What would stop filing, or what the founder should know
    - `key` 'BANKING_RISK_COUNTRY' | 'RESIDENCY_UNANSWERED' | 'ENTITY_NOT_CHOSEN' | 'ENTITY_NOT_OFFERED' | 'NAME_MISSING' | 'OWNERSHIP_NOT_FULLY_ALLOCATED' | 'NO_SHAREHOLDER' | 'SUBSIDIARY_SHAREHOLDER_ROLE' | 'INSUFFICIENT_DIRECTORS' | 'EXTERNAL_IDENTITY_REFERENCE_MISSING', required
    - `message` string, required: Ready to show a founder
  - `unresolvedRequests` OneShotRequestApiResponseDto[], required: The corporate-secretarial requests still open on this company — what REQUIRES_INFO is derived from, so the status can be acted on without a second call. Newest first, and empty until the company is filed.
    - `id` string, required: The handle for reading or withdrawing it
    - `incorporationId` string, required
    - `companyId` string: The company the request is about
    - `kind` 'DOCUMENT' | 'COMPANY_DETAILS' | 'MEMBER_CHANGE' | 'SHARE_CAPITAL' | 'GOVERNANCE' | 'COMPLIANCE_FILING' | 'TAX' | 'ENTITY_CHANGE' | 'OTHER', required
    - `status` 'OPEN' | 'IN_PROGRESS' | 'RESOLVED' | 'CANCELLED', required: Derived from the CRM ticket behind the request
    - `subject` string, required
    - `details` string
    - `payload` object, required: Exactly what was sent, never what an operator has since edited
    - `attachmentCount` number, required: Files stored against the request's ticket
    - `createdAt` string, required: ISO 8601
    - `updatedAt` string, required: ISO 8601
    - `statusChangedAt` string, required: When the ticket last moved; for a RESOLVED request, when it closed
    - `cancelledAt` string: Set when the partner withdrew the request

## Other responses

- `400`: The draft is incomplete; the message lists every problem
- `404`: No such incorporation for this key. A incorporation started through another partner's key reads the same.
- `409`: Already filed under another reference, cancelled, or filed concurrently

---

[API](https://skmtc.dev/gvrn/apis/gvrn-oneshot-api.md) · [All operations](https://skmtc.dev/gvrn/apis/gvrn-oneshot-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gvrn/apis/gvrn-oneshot-api/revisions/31a2ef047b90?raw)