GVRN OneShot API

Update a draft

Fills in the draft a step at a time; every field is optional and an omitted one is left alone. A founder tax-resident in a restricted country is refused outright, since that incorporation could never file. A banking-risk country is accepted and surfaces as a warning on the incorporation. jurisdiction and entityType have to resolve to a catalogue entry together.

patch/public/one-shot/incorporations/{id}

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}
Auth: API key in header x-gvrn-public-api-key

Path parameters

idstring required

Request body

purpose'STARTUP_FOUNDER' | 'INVESTOR' | 'DIGITAL_NOMAD' | 'UNSURE'

kycType'GVRN' | 'EXTERNAL'

founderExternalIdentityReferenceobject nullable

The partner's identity id for the founder; null clears it

founderIsUsPersonboolean

Citizen, green-card holder or US tax resident

founderTaxResidenceCountryCodestring

Country of tax residence, ISO 3166-1 alpha-3. A restricted country is refused.

Sent together with entityType; the pair must be a catalogue entry

entityType'IBC' | 'FOUNDATION' | 'SPC' | 'PTE_LTD' | 'SRL' | 'SA' | 'LIMITED' | 'CORPORATION' | 'LLC'

preferredCompanyNamesstring[]

One to three names in preference order, without the entity suffix; replaces the stored list

Example request

{
  "purpose": "INVESTOR",
  "kycType": "EXTERNAL",
  "founderTaxResidenceCountryCode": "SGP",
  "entityType": "CORPORATION",
  "preferredCompanyNames": [
    "Marlow Holdings",
    "Marlow Labs"
  ]
}

Response

idstring 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

founderEmailstring required

purpose'STARTUP_FOUNDER' | 'INVESTOR' | 'DIGITAL_NOMAD' | 'UNSURE'

kycType'GVRN' | 'EXTERNAL' required

entityType'IBC' | 'FOUNDATION' | 'SPC' | 'PTE_LTD' | 'SRL' | 'SA' | 'LIMITED' | 'CORPORATION' | 'LLC'

entityKeystring

The catalogue entry the pair resolves to

preferredCompanyNamesstring[] required

In preference order

parentCompanyIdstring

Set on a subsidiary; the parent holds every share

quotedPriceUsdnumber

Catalogue price at filing

filedAtstring

ISO 8601

signedAtstring

ISO 8601

createdAtstring required

ISO 8601

updatedAtstring required

ISO 8601

paymentMethod'CARD' | 'USDC'

paymentReferencestring

Exactly what you sent; GVRN records it rather than verifying it

paidAtstring

ISO 8601

signedByNamestring

Example response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "ACTIVE",
  "filingStatus": "SUBMITTED",
  "founderEmail": "qa+founder@gvrn.ai",
  "purpose": "STARTUP_FOUNDER",
  "kycType": "GVRN",
  "jurisdiction": "DELAWARE",
  "entityType": "CORPORATION",
  "entityKey": "delaware-c-corp",
  "preferredCompanyNames": [
    "Marlow Labs",
    "Marlow Holdings"
  ],
  "parentCompanyId": "123e4567-e89b-12d3-a456-426614174000",
  "company": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "displayName": "Marlow Labs",
    "legalName": "Marlow Labs, Inc.",
    "fullDisplayName": "Marlow Labs, Inc.",
    "jurisdiction": "DELAWARE",
    "incorporationStatus": "INCORPORATED",
    "registrationNumber": "7854219",
    "taxNumber": "93-4821570",
    "incorporatedAt": "2026-09-02T09:12:44.000Z"
  },
  "quotedPriceUsd": 500,
  "filedAt": "2026-09-02T09:12:44.000Z",
  "signedAt": "2026-09-02T09:12:44.000Z",
  "createdAt": "2026-09-02T09:12:44.000Z",
  "updatedAt": "2026-09-02T09:12:44.000Z",
  "founder": {
    "firstName": "Casey",
    "lastName": "Marlow",
    "email": "qa+founder@gvrn.ai",
    "externalIdentityReference": "jup_9f3a2c",
    "taxResidenceCountryCode": "SGP"
  },
  "paymentMethod": "CARD",
  "paymentReference": "pi_3Q1x8f2eZvKYlo2C0",
  "paidAt": "2026-09-02T09:12:44.000Z",
  "signedByName": "Casey Marlow",
  "members": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "displayName": "Casey Marlow",
      "firstName": "Casey",
      "lastName": "Marlow",
      "legalName": "Reyes Family Trust",
      "email": "qa+founder@gvrn.ai",
      "role": "BOTH",
      "ownershipPercent": 80,
      "contributionUsd": 100000,
      "externalIdentityReference": "jup_9f3a2c",
      "isFounder": true,
      "personId": "123e4567-e89b-12d3-a456-426614174000",
      "companyId": "123e4567-e89b-12d3-a456-426614174000",
      "addedAt": "2026-09-02T09:12:44.000Z",
      "kycStatus": "COMPLETED"
    }
  ],
  "timeline": [
    {
      "key": "ein-assigned",
      "label": "EIN from the IRS",
      "description": "Non-US founder — Form SS-4 by fax or mail (no SSN needed) · typically 1–2 weeks, sometimes longer",
      "completedAt": "2026-09-02T09:12:44.000Z"
    }
  ],
  "actions": [
    {
      "label": "Sign your bylaws & stock issuance",
      "memberIds": [
        "123e4567-e89b-12d3-a456-426614174000"
      ]
    }
  ],
  "warnings": [
    {
      "key": "OWNERSHIP_NOT_FULLY_ALLOCATED",
      "message": "Ownership totals 80%; it has to reach exactly 100% to file."
    }
  ],
  "unresolvedRequests": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "incorporationId": "123e4567-e89b-12d3-a456-426614174000",
      "companyId": "123e4567-e89b-12d3-a456-426614174000",
      "subject": "Certified copy of the certificate for HSBC",
      "details": "The bank wants a certified copy dated within three months.",
      "createdAt": "2026-09-02T09:12:44.000Z",
      "updatedAt": "2026-09-02T09:12:44.000Z",
      "statusChangedAt": "2026-09-02T09:12:44.000Z"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.