{"openapi":"3.0.0","paths":{"/public/one-shot/catalogue":{"get":{"description":"Everything an incorporation flow renders before a founder types anything: the entities on offer with\ntheir first-year and renewal prices, timing, governing documents and filing rules; the purposes a\nfounder can pick and which entity each one recommends; and the country codes that block or\ncomplicate filing.\n\nPrices are GVRN's current ones and can change, so read them when you render a card rather than\nstoring them. An entity GVRN has no price for is left out, along with any purpose recommending it.\n\nPass an entity's `jurisdiction` and `entityType` back on the incorporation; its `key` is how the\nrecommendation and the incorporation's `entityKey` refer to it.\n\n`requestKinds` is the menu of what a founder can ask GVRN for once the company is filed; each\nentry's `suggestedFields` say what that kind's form should collect.","operationId":"PublicOneShotCatalogueController_catalogue","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotCatalogueApiResponseDto"}}}}},"security":[{"x-gvrn-public-api-key":[]}],"summary":"The OneShot catalogue","tags":["GVRN OneShot API"]}},"/public/one-shot/incorporations":{"post":{"description":"Opens a draft for a founder identified by e-mail. The founder is added as the first member —\nshareholder and director with 100% of the company, or director alone on a subsidiary, whose\nparent holds every share. Everything else is filled in step by step with `PATCH` and the member\nroutes, and nothing is filed until `POST …/file`.\n\n`kycType` decides who verifies the members. GVRN runs the checks once the company is filed.\nEXTERNAL says the partner verified them and supplies identity references, so GVRN waives the\nverdict — the paperwork a registry needs is still required.","operationId":"PublicOneShotIncorporationController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotIncorporationCreateApiRequestDto"}}}},"responses":{"201":{"description":"Draft started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotIncorporationDetailsApiResponseDto"}}}},"400":{"description":"Validation error, or EXTERNAL without an identity reference"},"404":{"description":"`parentCompanyId` is not a company filed through this key"}},"security":[{"x-gvrn-public-api-key":[]}],"summary":"Start a incorporation","tags":["GVRN OneShot API"]},"get":{"description":"Every incorporation started through this partner's keys, newest first. Filter by `founderEmail` to show one founder their companies, and by `status` to separate drafts from filed ones.","operationId":"PublicOneShotIncorporationController_list","parameters":[{"name":"limit","required":false,"in":"query","description":"Page size. Defaults to 20, capped at 100.","schema":{"example":20,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"How many to skip; newest first by default","schema":{"example":0,"type":"number"}},{"name":"orderBy","required":false,"in":"query","description":"Order by field: created_at, updated_at, filed_at","schema":{"example":"created_at","type":"string","enum":["created_at","updated_at","filed_at"]}},{"name":"direction","required":false,"in":"query","schema":{"example":"desc","type":"string","enum":["asc","desc"]}},{"name":"founderEmail","required":false,"in":"query","description":"Only incorporations started by this founder, matched case-insensitively","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"example":"SUBMITTED","type":"string","enum":["DRAFT","SUBMITTED","CANCELLED"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotIncorporationListApiResponseDto"}}}}},"security":[{"x-gvrn-public-api-key":[]}],"summary":"List incorporations","tags":["GVRN OneShot API"]}},"/public/one-shot/incorporations/{id}":{"get":{"description":"The draft's answers, the members with their verification state, and — once filed — the\ncompany, its incorporation timeline and what the founder still has to do. `status` becomes ACTIVE\non GVRN's records alone: an EIN for a US entity, a registration for an offshore one. Nothing the\npartner sends changes it, so this is the endpoint to poll.","operationId":"PublicOneShotIncorporationController_details","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotIncorporationDetailsApiResponseDto"}}}},"404":{"description":"No such incorporation for this key. A incorporation started through another partner's key reads the same."}},"security":[{"x-gvrn-public-api-key":[]}],"summary":"Get a incorporation","tags":["GVRN OneShot API"]},"patch":{"description":"Fills in the draft a step at a time; every field is optional and an omitted one is left alone.\nA founder tax-resident in a restricted country is refused outright, since that incorporation could\nnever file. A banking-risk country is accepted and surfaces as a warning on the incorporation.\n`jurisdiction` and `entityType` have to resolve to a catalogue entry together.","operationId":"PublicOneShotIncorporationController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotIncorporationUpdateApiRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotIncorporationDetailsApiResponseDto"}}}},"400":{"description":"Validation error, restricted country, or unknown entity"},"404":{"description":"No such incorporation for this key. A incorporation started through another partner's key reads the same."},"409":{"description":"The incorporation is no longer a draft"}},"security":[{"x-gvrn-public-api-key":[]}],"summary":"Update a draft","tags":["GVRN OneShot API"]}},"/public/one-shot/incorporations/{id}/members":{"post":{"description":"A shareholder, director or both. Individuals are verified as people (KYC); trusts and companies\nas entities (KYB), and can only hold shares. On a draft the member is simply recorded; on a filed\ncompany they become a person or company record on GVRN's side at once, and a register-update\nresolution is generated.","operationId":"PublicOneShotIncorporationController_addMember","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotMemberApiRequestDto"}}}},"responses":{"201":{"description":"Member added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotIncorporationDetailsApiResponseDto"}}}},"400":{"description":"Validation error, or a duplicate e-mail"},"404":{"description":"No such incorporation for this key. A incorporation started through another partner's key reads the same."},"409":{"description":"The incorporation is cancelled"}},"security":[{"x-gvrn-public-api-key":[]}],"summary":"Add a member","tags":["GVRN OneShot API"]}},"/public/one-shot/incorporations/{id}/members/{memberId}":{"put":{"description":"Every field is optional and an omitted one keeps its stored value. `kind` cannot change, and once the company is filed neither can the e-mail — it is what binds the member to their record.","operationId":"PublicOneShotIncorporationController_updateMember","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"memberId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotMemberUpdateApiRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotIncorporationDetailsApiResponseDto"}}}},"400":{"description":"Validation error, unknown member, or a change the member cannot take"},"404":{"description":"No such incorporation for this key. A incorporation started through another partner's key reads the same."},"409":{"description":"The incorporation is cancelled, or the change would leave the filed company invalid"}},"security":[{"x-gvrn-public-api-key":[]}],"summary":"Edit a member","tags":["GVRN OneShot API"]},"delete":{"description":"The founder cannot be removed. On a filed company only the member's relationships to it go; the person or company record itself stays.","operationId":"PublicOneShotIncorporationController_removeMember","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"memberId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotIncorporationDetailsApiResponseDto"}}}},"400":{"description":"Unknown member, or the founder"},"404":{"description":"No such incorporation for this key. A incorporation started through another partner's key reads the same."},"409":{"description":"The incorporation is cancelled, or the removal would leave the filed company invalid"}},"security":[{"x-gvrn-public-api-key":[]}],"summary":"Remove a member","tags":["GVRN OneShot API"]}},"/public/one-shot/incorporations/{id}/file":{"post":{"description":"Confirms the partner took payment and turns the draft into a company: the company record, its\nmembers and their relationships are created on GVRN's side and the incorporation starts moving. The\npayment is recorded, not verified — checkout is the partner's.\n\nEvery rule the draft has to satisfy is checked first and every failure reported together:\nresidency answered and not restricted, an entity chosen, a name given, ownership totalling 100%,\nat least one shareholder and the jurisdiction's minimum number of directors.\n\nSafe to retry: the same `paymentReference` on an already filed incorporation answers with it; a\ndifferent one is a conflict.","operationId":"PublicOneShotIncorporationController_file","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotFileApiRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotIncorporationDetailsApiResponseDto"}}}},"400":{"description":"The draft is incomplete; the message lists every problem"},"404":{"description":"No such incorporation for this key. A incorporation started through another partner's key reads the same."},"409":{"description":"Already filed under another reference, cancelled, or filed concurrently"}},"security":[{"x-gvrn-public-api-key":[]}],"summary":"File the company","tags":["GVRN OneShot API"]}},"/public/one-shot/incorporations/{id}/sign":{"post":{"description":"Records the founder's e-signature on the governing documents (bylaws and initial consent, operating agreement, or the constitutional documents), once, on a filed company. Clears the signing action and marks the organizational resolution executed.","operationId":"PublicOneShotIncorporationController_sign","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotSignApiRequestDto"}}}},"responses":{"201":{"description":"Signed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotIncorporationDetailsApiResponseDto"}}}},"404":{"description":"No such incorporation for this key. A incorporation started through another partner's key reads the same."},"409":{"description":"Not filed yet, or already signed"}},"security":[{"x-gvrn-public-api-key":[]}],"summary":"Sign the governing documents","tags":["GVRN OneShot API"]}},"/public/one-shot/incorporations/{id}/cancel":{"post":{"description":"A draft the founder walked away from. A filed company is cancelled by GVRN, not through this API.","operationId":"PublicOneShotIncorporationController_cancel","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":"Cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotIncorporationDetailsApiResponseDto"}}}},"404":{"description":"No such incorporation for this key. A incorporation started through another partner's key reads the same."},"409":{"description":"The incorporation is no longer a draft"}},"security":[{"x-gvrn-public-api-key":[]}],"summary":"Cancel a draft","tags":["GVRN OneShot API"]}},"/public/one-shot/incorporations/{id}/documents/{key}/download":{"get":{"description":"The file behind one entry of the document list, streamed. `key` is that entry's own `key`,\nand an entry says whether there is anything to download with `downloadable`.\n\nOnly the documents a company's own registry issued can be reached this way — the certificate,\nthe constitutional document and the statutory registers. The paperwork of getting there is\nnot a founder's to download through a partner: the request form GVRN sends a provider, PEP\ndeclarations and certified copies of a member's identity evidence are all unreachable here,\nwhatever key you ask for.\n\nGVRN generates no file for the governance entries yet, so those are never `downloadable` —\ntheir `status` says where the signature has got to, not that a document exists.","operationId":"PublicOneShotIncorporationController_downloadDocument","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"key","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"The document, as a file stream"},"404":{"description":"No such incorporation for this key, no such document, or GVRN holds no file for it yet"}},"security":[{"x-gvrn-public-api-key":[]}],"summary":"Download a company document","tags":["GVRN OneShot API"]}},"/public/one-shot/incorporations/{id}/documents":{"get":{"description":"The founder's registry: the registry's and the IRS's incorporation documents as they arrive on\nGVRN's records, the governing documents the founder signs, and the resolutions generated from\nwhat changed in the company. Empty until the incorporation is filed.","operationId":"PublicOneShotIncorporationController_documents","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotDocumentsApiResponseDto"}}}},"404":{"description":"No such incorporation for this key. A incorporation started through another partner's key reads the same."}},"security":[{"x-gvrn-public-api-key":[]}],"summary":"List a incorporation's documents","tags":["GVRN OneShot API"]}},"/public/one-shot/requests":{"post":{"description":"Everything a founder can ask GVRN for once the company exists: a copy of a document, a change to\nthe company's details, shareholders or directors, a resolution, a statutory filing, a tax\nregistration, or anything else. Each one opens a ticket on GVRN's corporate-secretarial queue\ncarrying the subject, the founder's own words and whatever the partner's form collected.\n\n`kind` comes from the catalogue's `requestKinds`, whose `suggestedFields` say what that kind's\nform should collect into `payload` — advisory, never validated, since the partner owns its UI.\n\n**Files are base64 in the body**, at most\n5 of them and\n10MB decoded across the request —\na signed director's consent, the bank's wording for a certified copy. Each file's media type is\ndetected from its bytes rather than taken from the request, so one whose type cannot be\ndetermined is refused by name and the whole request fails: a partner told its request was raised\nwould otherwise have no way to tell which files landed. They are stored against the CRM ticket,\nwhere the operator working the request already looks; `attachmentCount` on every read confirms\nwhat arrived.\n\n**Only on a filed incorporation.** A draft's members, entity and company details are all still\neditable through this API, so there is nothing to ask for until the company is filed.\n\nGVRN does the work in its own systems; this API reports the request's status back and nothing\nmore. A request is not a filing instruction and nothing is charged by raising one.","operationId":"PublicOneShotRequestController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotRequestApiRequestDto"}}}},"responses":{"201":{"description":"Raised","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotRequestApiResponseDto"}}}},"400":{"description":"A limit was exceeded or a file could not be read; the message lists every problem"},"404":{"description":"No such incorporation for this key"},"409":{"description":"The incorporation is not filed"}},"security":[{"x-gvrn-public-api-key":[]}],"summary":"Raise a corporate-secretarial request","tags":["GVRN OneShot API"]},"get":{"description":"Every request this key's owner raised, newest first. Narrow it to one company with `incorporationId`, or to what is still outstanding with `status`.","operationId":"PublicOneShotRequestController_list","parameters":[{"name":"limit","required":false,"in":"query","description":"Page size. Defaults to 20, capped at 100.","schema":{"example":20,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"How many to skip; newest first by default","schema":{"example":0,"type":"number"}},{"name":"orderBy","required":false,"in":"query","description":"Order by field: created_at, updated_at","schema":{"example":"created_at","type":"string","enum":["created_at","updated_at"]}},{"name":"direction","required":false,"in":"query","schema":{"example":"desc","type":"string","enum":["asc","desc"]}},{"name":"incorporationId","required":false,"in":"query","description":"Only requests raised against this incorporation","schema":{"type":"string"}},{"name":"kind","required":false,"in":"query","schema":{"type":"string","enum":["DOCUMENT","COMPANY_DETAILS","MEMBER_CHANGE","SHARE_CAPITAL","GOVERNANCE","COMPLIANCE_FILING","TAX","ENTITY_CHANGE","OTHER"]}},{"name":"status","required":false,"in":"query","schema":{"example":"OPEN","type":"string","enum":["OPEN","IN_PROGRESS","RESOLVED","CANCELLED"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotRequestListApiResponseDto"}}}},"404":{"description":"No such incorporation for this key"}},"security":[{"x-gvrn-public-api-key":[]}],"summary":"List requests","tags":["GVRN OneShot API"]}},"/public/one-shot/requests/{requestId}":{"get":{"description":"What was asked, and where GVRN has got to with it.","operationId":"PublicOneShotRequestController_details","parameters":[{"name":"requestId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotRequestApiResponseDto"}}}},"404":{"description":"No such request for this key. One raised through another partner's key reads the same."}},"security":[{"x-gvrn-public-api-key":[]}],"summary":"Read one request","tags":["GVRN OneShot API"]}},"/public/one-shot/requests/{requestId}/cancel":{"post":{"description":"Withdraws a request GVRN has not started, and cancels its ticket. Once it is being worked on or is closed, GVRN cancels it rather than the partner.","operationId":"PublicOneShotRequestController_cancel","parameters":[{"name":"requestId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":"Withdrawn","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotRequestApiResponseDto"}}}},"404":{"description":"No such request for this key. One raised through another partner's key reads the same."},"409":{"description":"Already being worked on, or closed"}},"security":[{"x-gvrn-public-api-key":[]}],"summary":"Withdraw a request","tags":["GVRN OneShot API"]}}},"info":{"title":"GVRN OneShot API","description":"OneShot is GVRN's company formation flow, driven end to end. You own the UI, the login, the\nfounder's identity and the payment; GVRN owns the company record and takes it through the\nregistry.\n\nOne draft per company, and a founder's whole journey:\n\n- `GET /catalogue` — what you can offer, priced and with its filing rules\n- `POST /incorporations` — open a draft for a founder\n- `PATCH /incorporations/:id` — fill it in as they answer\n- `POST /incorporations/:id/members` — co-founders, investors, corporate holders\n- `POST /incorporations/:id/file` — you took payment; GVRN takes it from there\n- `GET /incorporations/:id` — where it has got to, and what the founder must do\n- `POST /requests` — anything the founder needs once the company exists\n\nEvery path is relative to `/public/one-shot`. The **Quickstart** below runs the whole flow with\ncurl; the sections after it take one part each in full.\n\n## Authentication\n\nSend the key GVRN issued you in the `x-gvrn-public-api-key` header on every request, from\nyour server — never from the browser a founder is filling your form in.\n\n```bash\ncurl http://localhost:3000/public/one-shot/catalogue \\\n  --header 'x-gvrn-public-api-key: YOUR_KEY'\n```\n\n## Quickstart\n\nThe whole flow, as a founder walks it. `YOUR_KEY` and the ids are the only things to replace.\n\n### 1. Show what they can set up\n\n`GET /public/one-shot/catalogue`, the call under **Authentication** above. `entities` is the\nmenu, each with `priceUsd` for the first year all in and `renewalPriceUsd` for each year after;\n`purposes` maps \"why are you incorporating\" to a recommended entity; the country lists say who\ncannot file and who will find banking harder.\n\nPrices are GVRN's current ones, so read the catalogue when you render rather than caching it. An\nentity GVRN has no price for is left out until it has one, and a draft that chose it carries the\n`ENTITY_NOT_OFFERED` warning.\n\n```json\n{\n  \"entities\": [\n    {\n      \"key\": \"delaware-c-corp\",\n      \"jurisdiction\": \"DELAWARE\",\n      \"entityType\": \"CORPORATION\",\n      \"displayName\": \"Delaware C-Corp\",\n      \"nameSuffix\": \", Inc.\",\n      \"priceUsd\": 700,\n      \"renewalPriceUsd\": 500,\n      \"incorporationTimeLabel\": \"1–3 days\",\n      \"minOfficers\": 1\n    }\n  ],\n  \"purposes\": [{ \"purpose\": \"STARTUP_FOUNDER\", \"recommendedEntityKey\": \"delaware-c-corp\" }],\n  \"restrictedCountryCodes\": [\"IRN\", \"RUS\", \"PRK\", \"SYR\", \"CUB\"]\n}\n```\n\n### 2. Open a draft\n\n```bash\ncurl http://localhost:3000/public/one-shot/incorporations \\\n  --header 'x-gvrn-public-api-key: YOUR_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"founder\": { \"email\": \"qa+founder@gvrn.ai\", \"firstName\": \"Casey\", \"lastName\": \"Marlow\" },\n    \"purpose\": \"STARTUP_FOUNDER\"\n  }'\n```\n\n`201`, and the body is the incorporation. Keep its `id` — everything below hangs off it. The\nfounder is already member one, holding 100% as both shareholder and director, so a solo founder\nneeds no member calls at all as long as their entity asks for a single director.\n\n### 3. Fill the draft in as they answer\n\n```bash\ncurl --request PATCH http://localhost:3000/public/one-shot/incorporations/INCORPORATION_ID \\\n  --header 'x-gvrn-public-api-key: YOUR_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"founderIsUsPerson\": false,\n    \"founderTaxResidenceCountryCode\": \"SGP\",\n    \"jurisdiction\": \"DELAWARE\",\n    \"entityType\": \"CORPORATION\",\n    \"preferredCompanyNames\": [\"Marlow Labs\", \"Marlow Holdings\"]\n  }'\n```\n\nCall it as often as your form has answers: every field is optional and an omitted one is left\nalone. The response's `warnings` is the live list of what still stands between this draft and a\nfiled company, so you never have to reimplement the rules.\n\n### 4. Add everyone else\n\n```bash\ncurl http://localhost:3000/public/one-shot/incorporations/INCORPORATION_ID/members \\\n  --header 'x-gvrn-public-api-key: YOUR_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"kind\": \"INDIVIDUAL\",\n    \"firstName\": \"Alex\",\n    \"lastName\": \"Reyes\",\n    \"email\": \"qa+alex-reyes@gvrn.ai\",\n    \"role\": \"BOTH\",\n    \"ownershipPercent\": 20\n  }'\n```\n\nAdding a member takes nothing off anyone else. Bring the founder down with\n`PUT …/members/:memberId` and `{ \"ownershipPercent\": 80 }`; the list has to total exactly 100\nbefore it can be filed.\n\n### 5. Take payment, then file\n\n```bash\ncurl http://localhost:3000/public/one-shot/incorporations/INCORPORATION_ID/file \\\n  --header 'x-gvrn-public-api-key: YOUR_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{ \"paymentMethod\": \"CARD\", \"paymentReference\": \"pi_3Q1x8f2eZvKYlo2C0\" }'\n```\n\n`200`, and the draft is a company. Checkout is yours — GVRN records the reference rather than\nverifying it — and re-sending the same reference after a timeout answers with the same\nincorporation instead of filing a second one.\n\n### 6. Follow it, and hand over what arrives\n\n```bash\ncurl http://localhost:3000/public/one-shot/incorporations/INCORPORATION_ID \\\n  --header 'x-gvrn-public-api-key: YOUR_KEY'\n```\n\n```json\n{\n  \"status\": \"SUBMITTED\",\n  \"company\": { \"fullDisplayName\": \"Marlow Labs, Inc.\", \"incorporationStatus\": \"IN_PROGRESS\" },\n  \"timeline\": [\n    { \"key\": \"certificate-filed\", \"label\": \"Certificate of Incorporation filed\", \"state\": \"NOW\" }\n  ],\n  \"actions\": [{ \"key\": \"SIGN_GOVERNING_DOCUMENTS\", \"label\": \"Sign your bylaws & stock issuance\" }],\n  \"warnings\": []\n}\n```\n\n`GET …/documents` carries the certificate, the EIN letter and the governing documents as they\nland, and `status` walks `SUBMITTED` → `IN_PROGRESS` → `ACTIVE` as GVRN works. Neither the\ntimeline nor the documents need anything from you to move them — see **How the flow works** next.\n\n## How the flow works\n\n### Who owns what\n\n| Owner | What |\n| --- | --- |\n| You | The UI, the login, the founder's identity, checkout, and when to file |\n| GVRN | The company record, the registry filings, the verification verdicts, everything after filing |\n\n### Progress is GVRN's, not yours\n\nNothing you send advances the company. Filing records your payment rather than verifying it, and\n`status`, the timeline and the documents move as GVRN files with the registry and the answers come\nback. There is no callback: poll `GET /incorporations/:id`, which is why every write returns the\nwhole incorporation rather than an acknowledgement.\n\n### You only ever see your own\n\nEvery route answers for the incorporations you started, and anything else is a `404`, never a\n`403`: another partner's incorporation and an id that never existed read identically, so ids\ncannot be probed. A `parentCompanyId` is held to the same rule.\n\n## Lifecycle and status\n\nTwo fields carry state. `filingStatus` is what is stored, and only ever `DRAFT`, `SUBMITTED` or\n`CANCELLED`. `status` is what to show a founder, and three of its values are read off GVRN's own\nrecords rather than stored anywhere:\n\n```mermaid\nstateDiagram-v2\n  [*] --> DRAFT: POST /incorporations\n  DRAFT --> CANCELLED: POST …/cancel\n  DRAFT --> SUBMITTED: POST …/file\n  SUBMITTED --> IN_PROGRESS: GVRN starts filing\n  IN_PROGRESS --> REQUIRES_INFO: a request opens\n  REQUIRES_INFO --> IN_PROGRESS: last one resolved\n  IN_PROGRESS --> ACTIVE: the registry confirms\n  REQUIRES_INFO --> ACTIVE\n```\n\n| Status | Means |\n| --- | --- |\n| `DRAFT` | Being filled in. Nothing submitted, nothing charged. |\n| `SUBMITTED` | You confirmed payment and the company exists on our side; nobody has picked it up yet. |\n| `IN_PROGRESS` | GVRN has started work on the filing. |\n| `REQUIRES_INFO` | In progress, with a request still open between you and GVRN. |\n| `ACTIVE` | It came back — an EIN for a US entity, a registration number offshore. |\n| `CANCELLED` | The founder walked away before submitting. |\n\nEverything past `SUBMITTED` moves on GVRN's side alone, so those are the statuses nothing you\nsend can produce. `ACTIVE` outranks `REQUIRES_INFO`: a company that exists and operates is live\nwhatever is still open against it, and the open requests are on the response either way.\n\n### REQUIRES_INFO\n\nAn in-progress incorporation reads `REQUIRES_INFO` while any corporate-secretarial request on\nthe company is neither resolved nor cancelled — something is outstanding between you and GVRN.\nYou do not have to go and look for what: **`unresolvedRequests`** on the incorporation carries\nexactly those requests, newest first, as the same objects `GET /requests` returns.\n\n```json\n{\n  \"status\": \"REQUIRES_INFO\",\n  \"unresolvedRequests\": [\n    {\n      \"id\": \"0f5a…\",\n      \"kind\": \"DOCUMENT\",\n      \"status\": \"OPEN\",\n      \"subject\": \"Certified copy of the certificate for HSBC\"\n    }\n  ]\n}\n```\n\nIt clears itself: the status goes back to `IN_PROGRESS` when GVRN resolves the last one, or when\nyou withdraw it.\n\n### What you can still change\n\n| While | You can |\n| --- | --- |\n| `DRAFT` | Change every answer, add and remove members, cancel |\n| Submitted | Change members, sign the governing documents, raise requests |\n\nThe entity, the preferred names and the founder's residency are fixed at submission: afterwards\nthey are a **request**, because a registry can only be told by GVRN. A submitted incorporation is\ncancelled by GVRN too, not through this API.\n\n## Members and ownership\n\nA member is anyone on the company: the founder, co-founders, investors, a holding company, a\nfamily trust.\n\n| Kind | What it is |\n| --- | --- |\n| `INDIVIDUAL` | A person, verified as one (KYC). Shareholder, director, or both. |\n| `TRUST` | A trust, verified as an entity (KYB). Shares only. |\n| `COMPANY` | A corporate holder, verified as an entity (KYB). Shares only. |\n\n`role` is `SHAREHOLDER`, `DIRECTOR` or `BOTH`. Directors are natural persons, so a trust or a\ncompany asking for one is refused.\n\n- `ownershipPercent` takes 0–100 with at most 2 decimals, and\n  the list must total **exactly 100** to file.\n- A `DIRECTOR`-only member holds **no shares**: give them `BOTH` rather than a percentage, or\n  filing refuses the pair.\n- The founder is member one and cannot be removed, though they can be edited like anyone else.\n- E-mails must be distinct, and on a filed company a member's e-mail is fixed — it is what binds\n  them to their record.\n- At most 50 members, the founder included.\n\nOn a **draft** a member is simply recorded. On a **filed** company they become a person or company\nrecord on GVRN's side at once and a register-update resolution is generated; removing one drops\nits relationships to the company, not the record itself.\n\n### Subsidiaries\n\nPass `parentCompanyId` when you open the draft — a company you filed through this API — and the\nparent holds every share. The founder goes in as a director with no shares, no member may hold the\nshareholder role, and ownership must total zero rather than 100.\n\n## Identity verification\n\n| `kycType` | Who verifies |\n| --- | --- |\n| `GVRN` | The default. GVRN runs the checks on every member once the company is filed. |\n| `EXTERNAL` | You already did. Say who you checked with an identity reference; GVRN waives the verdict. |\n\nThe founder's `externalIdentityReference` is the one that is required: an `EXTERNAL` incorporation\ncan be neither opened nor filed without it. Send one per member too — it is what ties a member to\nthe check you ran — but no member other than the founder is refused for want of one.\n\nEvery member carries `kycStatus`. On an `EXTERNAL` incorporation it reads `SKIPPED` throughout;\notherwise it is the latest verdict, or `PENDING` while GVRN waits. GVRN runs the checks once the\ncompany is filed, so it is from then — not on the draft — that an incorporation with anyone\noutstanding carries a `COMPLETE_IDENTITY_VERIFICATION` action naming them.\n\n`EXTERNAL` waives the *verdict*, not the paperwork: a registry still wants identity documents and\nproof of address, and collecting them is still GVRN's.\n\n## Filing and payment\n\n`POST /incorporations/:id/file` is where a draft becomes a company. Every rule is checked first\nand every failure comes back together in one `400`:\n\n- the US-person question answered, and a non-US founder's country of tax residence given and not\n  restricted\n- an entity chosen from the catalogue, and at least one preferred company name\n- ownership totalling exactly 100%, with at least one shareholder\n- at least as many directors as the entity requires — `minOfficers` on its catalogue entry\n- on an `EXTERNAL` incorporation, an identity reference for the founder\n\n…and the rest of what the member list has to satisfy: distinct e-mails, at most\n50 members, no shares on a director-only member, and a subsidiary holding\nnone at all.\n\nYou do not have to reimplement any of it. `warnings` on every draft is that same set of rules,\nkeyed, so you can put them in front of the founder as they go:\n\n```json\n{\n  \"key\": \"OWNERSHIP_NOT_FULLY_ALLOCATED\",\n  \"message\": \"Ownership totals 80%; it has to reach exactly 100% to file.\"\n}\n```\n\nOne exception, and it matters if you gate your pay button on this list: **`BANKING_RISK_COUNTRY`\ndoes not block filing.** It is a note about the founder's bank diligence, it never clears, and it\nis the one warning that outlives filing — so gate on every *other* key being absent rather than on\nthe list being empty.\n\n**Payment is recorded, not verified.** Checkout is yours; `paymentMethod` (`CARD` or `USDC`) and\n`paymentReference` are what you tell GVRN about it, and `quotedPriceUsd` snapshots the catalogue\nprice at the moment you filed.\n\n**Retrying is safe.** The same `paymentReference` on an already filed incorporation answers with\nit — which is exactly what a client that lost the first response sends. A *different* reference is\na `409`, so generate one per incorporation rather than per attempt.\n\nFiling also opens the corporate-secretarial ticket GVRN works from, so nothing further is needed\nfrom you: the next call you make is the one in **After filing** below.\n\n## After filing\n\n`GET /incorporations/:id` is the founder's whole dashboard. Three lists do the work:\n\n| Field | What to render |\n| --- | --- |\n| `timeline` | The steps to a live company, each `DONE`, `NOW`, `NEEDS_YOU` or `PENDING`. |\n| `actions` | What the founder must do: sign the documents, finish verification. |\n| `warnings` | What they should know — a banking-risk residence stays here after filing. |\n| `unresolvedRequests` | The corporate-secretarial requests still open on the company. |\n\nAt most one step is `NOW`, and `NEEDS_YOU` marks the ones waiting on the founder rather than on\nGVRN or a registry — enough to drive a progress bar without interpreting the keys.\n\n### Company documents\n\n`GET /incorporations/:id/documents` is the company's own document set, in two groups —\n`INCORPORATION`, what the registry and the IRS issue as GVRN files them, and `GOVERNANCE`, what\nthe founder signs — alongside the resolutions generated from the company's own changes. It is\nempty until the incorporation is submitted.\n\nAn entry is listed from the moment a founder should expect it, which is well before GVRN holds\nit, so two fields answer two different questions: `status` is where the document has got to, and\n**`downloadable`** is whether there is a file to hand over right now.\n\n```bash\ncurl http://localhost:3000/public/one-shot/incorporations/INCORPORATION_ID/documents/certificate/download \\\\\n  --header 'x-gvrn-public-api-key: YOUR_KEY' \\\\\n  --output certificate.pdf\n```\n\nThe path takes the entry's own `key`, and the response is the file. Gate the button on\n`downloadable` rather than on `status`: asking for an entry GVRN holds no file for is a `404`.\n\nThree entries can carry a file today — the certificate, the constitutional document and the\nstatutory registers, all of them things a registry issued about the company. The rest are listed\nbut never `downloadable`:\n\n| Entry | Why there is no file |\n| --- | --- |\n| `ein-letter` | The IRS letter is not yet filed under its own kind, so it cannot be told apart. |\n| `governing-document` | Signing is recorded as a fact; GVRN does not yet render the document. |\n| `issuance`, `cap-table` | Derived from the members on the incorporation rather than rendered. |\n\n**Only the company's own documents are reachable this way.** The paperwork of getting there is\nnot a founder's to download through a partner — the request form GVRN sends a provider, PEP\ndeclarations, and certified copies of a member's passport and proof of address are unreachable\nwhatever key you ask for, and asking reads as a `404` like any other document we do not have.\n\n### Signing\n\nWhen the governing documents are ready the incorporation carries a `SIGN_GOVERNING_DOCUMENTS`\naction. Record the signature with the founder's typed name:\n\n```bash\ncurl http://localhost:3000/public/one-shot/incorporations/INCORPORATION_ID/sign \\\n  --header 'x-gvrn-public-api-key: YOUR_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{ \"signerName\": \"Casey Marlow\" }'\n```\n\nOnce, on a filed company: the action clears and the organizational resolution is marked executed.\n\n## Requests\n\nOnce the company is filed your dashboard cannot change it — a registry can only be told by GVRN —\nso everything else a founder needs is raised as a request. Each one opens a ticket on GVRN's\ncorporate-secretarial queue carrying the subject, the founder's own words and whatever your form\ncollected.\n\n```bash\ncurl http://localhost:3000/public/one-shot/requests \\\n  --header 'x-gvrn-public-api-key: YOUR_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"incorporationId\": \"INCORPORATION_ID\",\n    \"kind\": \"DOCUMENT\",\n    \"subject\": \"Certified copy of the certificate for HSBC\",\n    \"payload\": { \"Document\": \"Certificate of incorporation\", \"Copy type\": \"Certified\" }\n  }'\n```\n\n| Kind | Covers |\n| --- | --- |\n| `DOCUMENT` | A copy of something GVRN holds — certificate, registers, a certified copy |\n| `COMPANY_DETAILS` | Name, registered address, business activity, financial year end |\n| `MEMBER_CHANGE` | Add, replace or remove a shareholder, director or officer |\n| `SHARE_CAPITAL` | Issue, transfer or restructure shares; authorized capital |\n| `GOVERNANCE` | Minutes, a board or member resolution, a board pack |\n| `COMPLIANCE_FILING` | Annual report, franchise tax, economic substance, Form 5472 |\n| `TAX` | Tax registration, a tax residence certificate |\n| `ENTITY_CHANGE` | Redomiciliation, striking off, dissolution |\n| `OTHER` | Anything the menu does not name |\n\nBuild the form from the catalogue rather than from that table: `requestKinds` carries each kind's\nlabel, description, `suggestedFields` and worked examples, and it can grow. `payload` is a flat\nlabel-to-value map of what those fields collected — advisory, never validated, at most\n30 entries.\n\nStatus is read off the ticket, so the team working the queue moves your view with no write path of\nits own: `OPEN`, then `IN_PROGRESS`, then `RESOLVED` — or `CANCELLED`. You may withdraw one\nnobody has started; past that it is GVRN's to cancel.\n\nWhile any of them is still `OPEN` or `IN_PROGRESS` the incorporation itself reads\n`REQUIRES_INFO` and carries them on `unresolvedRequests`, so a founder's dashboard can show that\nsomething is outstanding without polling this list separately.\n\nA request is an ask, not an instruction. Nothing is filed, changed or charged by raising one, and\nGVRN answers through its own channels.\n\n## Errors\n\nErrors are JSON and carry the status in the body as well as the status line:\n\n```json\n{ \"statusCode\": 400, \"message\": \"...\", \"error\": \"Bad Request\" }\n```\n\n`message` is a string for most failures and an **array of strings** when request validation\nrejects several fields at once, so parse it defensively.\n\n| Status | Means |\n| --- | --- |\n| `400` | Malformed request, or a field we do not accept |\n| `401` | Key missing, disabled, expired, or deleted |\n| `403` | Key is valid but not permitted to do this |\n| `404` | No such resource, or one you cannot reach |\n| `429` | Rate limited — see below |\n| `5xx` | Our fault; retry an idempotent read with backoff |\n\nUnknown body fields are **rejected rather than ignored**, so a typo in a field name is a `400`\nrather than a silently dropped value.\n\n## Rate limits\n\nRequests are rate limited per client IP address and **per endpoint**: each one has\nits own budget, so exhausting a read does not lock you out of the rest of the API.\n\nExceeding a budget returns `429` with a `Retry-After` header giving the seconds to wait. Honour\nit rather than retrying immediately, and back off exponentially if you keep hitting it.\n\nThe ceiling is deliberately not published as a number: it is tuned per environment and we would\nrather you follow `Retry-After` than encode a constant that later changes. If you need sustained\nthroughput above what you are seeing, talk to us instead of parallelising around it.\n\n## Conventions\n\nTimestamps are ISO 8601. Monetary amounts are USD unless the field says otherwise, and prices\ncome back as numbers rather than strings.\n\nEnumerated fields document their full set of values on the endpoint that returns them, and that\nset can grow — decode a member you do not recognise gracefully rather than failing. The same\ngoes for response fields: ignore ones you were not expecting.\n\nWhere a route shape is retired we keep the old one working and mark it deprecated rather than\nremoving it, and answer it with `Deprecation: true` (RFC 8594). Move off one when you see that\nheader rather than when it stops working.","version":"1.49.1-dev.2","contact":{}},"tags":[{"name":"GVRN OneShot API","description":"A white-label incorporation product: take a founder from their first question to a filed\ncompany, under your own brand, login and payment."}],"servers":[],"components":{"schemas":{"OneShotEntityCatalogueItemDto":{"type":"object","properties":{"key":{"type":"string","description":"Stable handle the recommendation and entityKey point at","example":"delaware-c-corp"},"jurisdiction":{"type":"string","enum":["SINGAPORE","PANAMA","BVI","DELAWARE","WYOMING","CAYMAN_ISLANDS","COSTA_RICA","DUBAI","SEYCHELLES","SWITZERLAND","OTHERS"],"example":"DELAWARE"},"entityType":{"type":"string","enum":["IBC","FOUNDATION","SPC","PTE_LTD","SRL","SA","LIMITED","CORPORATION","LLC"],"example":"CORPORATION"},"displayName":{"type":"string","example":"Delaware C-Corp"},"nameSuffix":{"type":"string","description":"Appended to the chosen name","example":", Inc."},"priceUsd":{"type":"number","description":"The first year, all in: what GVRN quotes the founder, and what filing records","example":700},"renewalPriceUsd":{"type":"number","description":"Each year after the first","example":500},"incorporationTimeLabel":{"type":"string","example":"1–3 days"},"governingDocumentLabel":{"type":"string","description":"What the founder signs after filing","example":"Bylaws & stock issuance"},"minOfficers":{"type":"number","description":"Directors required before filing","example":1},"officerTitles":{"example":["President","Secretary","Treasurer"],"type":"array","items":{"type":"string"}},"authorizedAmount":{"type":"number","description":"Shares or units the ownership percentages are converted against","example":10000000},"ownershipUnit":{"type":"string","enum":["SHARES","UNITS"]},"privacy":{"type":"string","enum":["STANDARD","MODERATE","HIGH"]},"banking":{"type":"string","enum":["EXCELLENT","GOOD","MODERATE","HARDER"]},"usTax":{"type":"boolean","description":"Whether the company files US federal tax returns"},"tier":{"type":"string","enum":["US","US_PRIVATE","OFFSHORE"]},"highlights":{"description":"Selling points, written to be rendered on a partner's own entity card","example":["Built for startups that will raise from VCs","Stock options and a clean path to a priced round"],"type":"array","items":{"type":"string"}}},"required":["key","jurisdiction","entityType","displayName","nameSuffix","priceUsd","renewalPriceUsd","incorporationTimeLabel","governingDocumentLabel","minOfficers","authorizedAmount","ownershipUnit","privacy","banking","usTax","tier","highlights"]},"OneShotPurposeCatalogueItemDto":{"type":"object","properties":{"purpose":{"type":"string","enum":["STARTUP_FOUNDER","INVESTOR","DIGITAL_NOMAD","UNSURE"]},"label":{"type":"string","example":"Startup founder"},"description":{"type":"string","example":"Raising from investors, hiring, issuing equity"},"recommendedEntityKey":{"type":"string","example":"delaware-c-corp"}},"required":["purpose","label","description","recommendedEntityKey"]},"OneShotRequestCatalogueItemDto":{"type":"object","properties":{"kind":{"type":"string","enum":["DOCUMENT","COMPANY_DETAILS","MEMBER_CHANGE","SHARE_CAPITAL","GOVERNANCE","COMPLIANCE_FILING","TAX","ENTITY_CHANGE","OTHER"]},"label":{"type":"string","example":"Request a document"},"description":{"type":"string","example":"A copy of a document GVRN holds for the company, certified or apostilled if a bank needs it."},"suggestedFields":{"description":"Labels this kind's form should collect into `payload`. Advisory, never validated.","example":["Document","Copy type","Needed by"],"type":"array","items":{"type":"string"}},"examples":{"description":"Concrete asks this kind covers, ready to offer as suggestions","example":["Certificate of incorporation or formation","Certified true copy for a bank account opening"],"type":"array","items":{"type":"string"}}},"required":["kind","label","description","suggestedFields","examples"]},"OneShotCatalogueApiResponseDto":{"type":"object","properties":{"entities":{"type":"array","items":{"$ref":"#/components/schemas/OneShotEntityCatalogueItemDto"}},"purposes":{"type":"array","items":{"$ref":"#/components/schemas/OneShotPurposeCatalogueItemDto"}},"restrictedCountryCodes":{"description":"ISO 3166-1 alpha-3; a founder tax-resident here cannot file","type":"array","items":{"type":"string"}},"bankingRiskCountryCodes":{"description":"ISO 3166-1 alpha-3; filing is fine, banking takes longer","type":"array","items":{"type":"string"}},"requestKinds":{"description":"What a founder can ask GVRN for once the company is filed","type":"array","items":{"$ref":"#/components/schemas/OneShotRequestCatalogueItemDto"}}},"required":["entities","purposes","restrictedCountryCodes","bankingRiskCountryCodes","requestKinds"]},"OneShotFounderApiRequestDto":{"type":"object","properties":{"email":{"type":"string","description":"The founder's e-mail; also how the partner lists their incorporations","example":"qa+founder@gvrn.ai"},"firstName":{"type":"string","example":"Casey"},"lastName":{"type":"string","example":"Marlow"},"externalIdentityReference":{"type":"string","description":"The partner's identity id for the founder. Required when kycType is EXTERNAL.","example":"jup_9f3a2c"}},"required":["email","firstName","lastName"]},"OneShotIncorporationCreateApiRequestDto":{"type":"object","properties":{"founder":{"$ref":"#/components/schemas/OneShotFounderApiRequestDto"},"kycType":{"type":"string","description":"Who verifies the members. GVRN (the default) runs the checks once the company is filed. EXTERNAL says the partner verified them and supplies identity references, so GVRN waives the verdict — the paperwork a registry needs is still required.","enum":["GVRN","EXTERNAL"],"example":"GVRN"},"purpose":{"type":"string","enum":["STARTUP_FOUNDER","INVESTOR","DIGITAL_NOMAD","UNSURE"],"example":"STARTUP_FOUNDER"},"parentCompanyId":{"type":"string","description":"A company filed through this API by the same partner; it becomes the sole shareholder at filing","example":"123e4567-e89b-12d3-a456-426614174000"}},"required":["founder"]},"OneShotCompanySummaryDto":{"type":"object","properties":{"id":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"displayName":{"type":"string","example":"Marlow Labs"},"legalName":{"type":"string","description":"Set by GVRN once the registry confirms the name","example":"Marlow Labs, Inc."},"fullDisplayName":{"type":"string","description":"Display name with the entity suffix","example":"Marlow Labs, Inc."},"jurisdiction":{"type":"string","enum":["SINGAPORE","PANAMA","BVI","DELAWARE","WYOMING","CAYMAN_ISLANDS","COSTA_RICA","DUBAI","SEYCHELLES","SWITZERLAND","OTHERS"],"example":"DELAWARE"},"incorporationStatus":{"type":"string","enum":["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"],"example":"INCORPORATED"},"registrationNumber":{"type":"string","description":"Issued by the registry","example":"7854219"},"taxNumber":{"type":"string","description":"The EIN for a US entity","example":"93-4821570"},"incorporatedAt":{"type":"string","description":"ISO 8601","example":"2026-09-02T09:12:44.000Z"}},"required":["id","displayName","fullDisplayName","incorporationStatus"]},"OneShotFounderApiResponseDto":{"type":"object","properties":{"firstName":{"type":"string","example":"Casey"},"lastName":{"type":"string","example":"Marlow"},"email":{"type":"string","example":"qa+founder@gvrn.ai"},"externalIdentityReference":{"type":"string","example":"jup_9f3a2c"},"isUsPerson":{"type":"boolean","example":false},"taxResidenceCountryCode":{"type":"string","description":"ISO 3166-1 alpha-3","example":"SGP"}},"required":["firstName","lastName","email"]},"OneShotMemberApiResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The handle for member edits","example":"123e4567-e89b-12d3-a456-426614174000"},"kind":{"type":"string","enum":["INDIVIDUAL","TRUST","COMPANY"]},"displayName":{"type":"string","description":"Name parts or legal name, joined","example":"Casey Marlow"},"firstName":{"type":"string","example":"Casey"},"middleName":{"type":"string"},"lastName":{"type":"string","example":"Marlow"},"legalName":{"type":"string","example":"Reyes Family Trust"},"email":{"type":"string","example":"qa+founder@gvrn.ai"},"role":{"type":"string","enum":["SHAREHOLDER","DIRECTOR","BOTH"],"example":"BOTH"},"ownershipPercent":{"type":"number","example":80},"contributionUsd":{"type":"number","example":100000},"externalIdentityReference":{"type":"string","example":"jup_9f3a2c"},"isFounder":{"type":"boolean","description":"The account holder; never removable","example":true},"personId":{"type":"string","description":"The Person record behind an INDIVIDUAL, once filed","example":"123e4567-e89b-12d3-a456-426614174000"},"companyId":{"type":"string","description":"The Company record behind a TRUST or COMPANY, once filed","example":"123e4567-e89b-12d3-a456-426614174000"},"addedAt":{"type":"string","description":"ISO 8601","example":"2026-09-02T09:12:44.000Z"},"relationshipType":{"type":"string","enum":["PERSON","COMPANY"]},"relationships":{"type":"array","description":"What the role expands to, plus the founder's implied relationships","items":{"type":"string","enum":["FOUNDER","STAKEHOLDER","INVESTOR","SHAREHOLDER","DIRECTOR","NOMINEE_DIRECTOR","CONTROLLER","BENEFICIAL_OWNER","SECRETARY","CORPORATE_REPRESENTATIVE"]}},"kycKind":{"type":"string","enum":["KYC","KYB"]},"kycStatus":{"type":"string","description":"SKIPPED on every member of an EXTERNAL incorporation; otherwise the latest verdict, or PENDING","enum":["PENDING","COMPLETED","SKIPPED","REJECTED","EXPIRED","NOT_APPLICABLE"],"example":"COMPLETED"}},"required":["id","kind","displayName","email","role","ownershipPercent","isFounder","addedAt","relationshipType","relationships","kycKind","kycStatus"]},"OneShotTimelineStepDto":{"type":"object","properties":{"key":{"type":"string","example":"ein-assigned"},"label":{"type":"string","example":"EIN from the IRS"},"description":{"type":"string","description":"Written for the founder, and worded for this entity and this founder's residency","example":"Non-US founder — Form SS-4 by fax or mail (no SSN needed) · typically 1–2 weeks, sometimes longer"},"state":{"type":"string","description":"At most one step is NOW","enum":["DONE","NOW","NEEDS_YOU","PENDING"]},"completedAt":{"type":"string","description":"ISO 8601","example":"2026-09-02T09:12:44.000Z"}},"required":["key","label","description","state"]},"OneShotActionDto":{"type":"object","properties":{"key":{"type":"string","enum":["SIGN_GOVERNING_DOCUMENTS","COMPLETE_IDENTITY_VERIFICATION"]},"label":{"type":"string","example":"Sign your bylaws & stock issuance"},"memberIds":{"description":"The members the action is waiting on","example":["123e4567-e89b-12d3-a456-426614174000"],"type":"array","items":{"type":"string"}}},"required":["key","label"]},"OneShotWarningDto":{"type":"object","properties":{"key":{"type":"string","enum":["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"],"example":"OWNERSHIP_NOT_FULLY_ALLOCATED"},"message":{"type":"string","description":"Ready to show a founder","example":"Ownership totals 80%; it has to reach exactly 100% to file."}},"required":["key","message"]},"OneShotRequestApiResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The handle for reading or withdrawing it","example":"123e4567-e89b-12d3-a456-426614174000"},"incorporationId":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"companyId":{"type":"string","description":"The company the request is about","example":"123e4567-e89b-12d3-a456-426614174000"},"kind":{"type":"string","enum":["DOCUMENT","COMPANY_DETAILS","MEMBER_CHANGE","SHARE_CAPITAL","GOVERNANCE","COMPLIANCE_FILING","TAX","ENTITY_CHANGE","OTHER"]},"status":{"type":"string","enum":["OPEN","IN_PROGRESS","RESOLVED","CANCELLED"],"description":"Derived from the CRM ticket behind the request"},"subject":{"type":"string","example":"Certified copy of the certificate for HSBC"},"details":{"type":"string","example":"The bank wants a certified copy dated within three months."},"payload":{"type":"object","description":"Exactly what was sent, never what an operator has since edited","additionalProperties":{"type":"string"}},"attachmentCount":{"type":"number","description":"Files stored against the request's ticket"},"createdAt":{"type":"string","description":"ISO 8601","example":"2026-09-02T09:12:44.000Z"},"updatedAt":{"type":"string","description":"ISO 8601","example":"2026-09-02T09:12:44.000Z"},"statusChangedAt":{"type":"string","description":"When the ticket last moved; for a RESOLVED request, when it closed","example":"2026-09-02T09:12:44.000Z"},"cancelledAt":{"type":"string","description":"Set when the partner withdrew the request"}},"required":["id","incorporationId","kind","status","subject","payload","attachmentCount","createdAt","updatedAt","statusChangedAt"]},"OneShotIncorporationDetailsApiResponseDto":{"type":"object","properties":{"id":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"status":{"type":"string","description":"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.","enum":["DRAFT","SUBMITTED","IN_PROGRESS","REQUIRES_INFO","ACTIVE","CANCELLED"],"example":"ACTIVE"},"filingStatus":{"type":"string","description":"The stored lifecycle state behind status","enum":["DRAFT","SUBMITTED","CANCELLED"],"example":"SUBMITTED"},"founderEmail":{"type":"string","example":"qa+founder@gvrn.ai"},"purpose":{"type":"string","enum":["STARTUP_FOUNDER","INVESTOR","DIGITAL_NOMAD","UNSURE"],"example":"STARTUP_FOUNDER"},"kycType":{"type":"string","enum":["GVRN","EXTERNAL"],"example":"GVRN"},"jurisdiction":{"type":"string","enum":["SINGAPORE","PANAMA","BVI","DELAWARE","WYOMING","CAYMAN_ISLANDS","COSTA_RICA","DUBAI","SEYCHELLES","SWITZERLAND","OTHERS"],"example":"DELAWARE"},"entityType":{"type":"string","enum":["IBC","FOUNDATION","SPC","PTE_LTD","SRL","SA","LIMITED","CORPORATION","LLC"],"example":"CORPORATION"},"entityKey":{"type":"string","description":"The catalogue entry the pair resolves to","example":"delaware-c-corp"},"preferredCompanyNames":{"description":"In preference order","example":["Marlow Labs","Marlow Holdings"],"type":"array","items":{"type":"string"}},"parentCompanyId":{"type":"string","description":"Set on a subsidiary; the parent holds every share","example":"123e4567-e89b-12d3-a456-426614174000"},"company":{"$ref":"#/components/schemas/OneShotCompanySummaryDto"},"quotedPriceUsd":{"type":"number","description":"Catalogue price at filing","example":500},"filedAt":{"type":"string","description":"ISO 8601","example":"2026-09-02T09:12:44.000Z"},"signedAt":{"type":"string","description":"ISO 8601","example":"2026-09-02T09:12:44.000Z"},"createdAt":{"type":"string","description":"ISO 8601","example":"2026-09-02T09:12:44.000Z"},"updatedAt":{"type":"string","description":"ISO 8601","example":"2026-09-02T09:12:44.000Z"},"founder":{"$ref":"#/components/schemas/OneShotFounderApiResponseDto"},"paymentMethod":{"type":"string","enum":["CARD","USDC"],"example":"CARD"},"paymentReference":{"type":"string","description":"Exactly what you sent; GVRN records it rather than verifying it","example":"pi_3Q1x8f2eZvKYlo2C0"},"paidAt":{"type":"string","description":"ISO 8601","example":"2026-09-02T09:12:44.000Z"},"signedByName":{"type":"string","example":"Casey Marlow"},"members":{"type":"array","items":{"$ref":"#/components/schemas/OneShotMemberApiResponseDto"}},"timeline":{"description":"Empty while DRAFT","type":"array","items":{"$ref":"#/components/schemas/OneShotTimelineStepDto"}},"actions":{"description":"What the founder has to do next","type":"array","items":{"$ref":"#/components/schemas/OneShotActionDto"}},"warnings":{"description":"What would stop filing, or what the founder should know","type":"array","items":{"$ref":"#/components/schemas/OneShotWarningDto"}},"unresolvedRequests":{"description":"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.","type":"array","items":{"$ref":"#/components/schemas/OneShotRequestApiResponseDto"}}},"required":["id","status","filingStatus","founderEmail","kycType","preferredCompanyNames","createdAt","updatedAt","founder","members","timeline","actions","warnings","unresolvedRequests"]},"OneShotIncorporationSummaryApiResponseDto":{"type":"object","properties":{"id":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"status":{"type":"string","description":"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.","enum":["DRAFT","SUBMITTED","IN_PROGRESS","REQUIRES_INFO","ACTIVE","CANCELLED"],"example":"ACTIVE"},"filingStatus":{"type":"string","description":"The stored lifecycle state behind status","enum":["DRAFT","SUBMITTED","CANCELLED"],"example":"SUBMITTED"},"founderEmail":{"type":"string","example":"qa+founder@gvrn.ai"},"purpose":{"type":"string","enum":["STARTUP_FOUNDER","INVESTOR","DIGITAL_NOMAD","UNSURE"],"example":"STARTUP_FOUNDER"},"kycType":{"type":"string","enum":["GVRN","EXTERNAL"],"example":"GVRN"},"jurisdiction":{"type":"string","enum":["SINGAPORE","PANAMA","BVI","DELAWARE","WYOMING","CAYMAN_ISLANDS","COSTA_RICA","DUBAI","SEYCHELLES","SWITZERLAND","OTHERS"],"example":"DELAWARE"},"entityType":{"type":"string","enum":["IBC","FOUNDATION","SPC","PTE_LTD","SRL","SA","LIMITED","CORPORATION","LLC"],"example":"CORPORATION"},"entityKey":{"type":"string","description":"The catalogue entry the pair resolves to","example":"delaware-c-corp"},"preferredCompanyNames":{"description":"In preference order","example":["Marlow Labs","Marlow Holdings"],"type":"array","items":{"type":"string"}},"parentCompanyId":{"type":"string","description":"Set on a subsidiary; the parent holds every share","example":"123e4567-e89b-12d3-a456-426614174000"},"company":{"$ref":"#/components/schemas/OneShotCompanySummaryDto"},"quotedPriceUsd":{"type":"number","description":"Catalogue price at filing","example":500},"filedAt":{"type":"string","description":"ISO 8601","example":"2026-09-02T09:12:44.000Z"},"signedAt":{"type":"string","description":"ISO 8601","example":"2026-09-02T09:12:44.000Z"},"createdAt":{"type":"string","description":"ISO 8601","example":"2026-09-02T09:12:44.000Z"},"updatedAt":{"type":"string","description":"ISO 8601","example":"2026-09-02T09:12:44.000Z"}},"required":["id","status","filingStatus","founderEmail","kycType","preferredCompanyNames","createdAt","updatedAt"]},"OneShotIncorporationListApiResponseDto":{"type":"object","properties":{"limit":{"type":"number","example":20},"offset":{"type":"number","example":0},"total":{"type":"number","description":"Matching the filters, not on this page","example":3},"result":{"type":"array","items":{"$ref":"#/components/schemas/OneShotIncorporationSummaryApiResponseDto"}}},"required":["limit","offset","total","result"]},"OneShotIncorporationUpdateApiRequestDto":{"type":"object","properties":{"purpose":{"type":"string","enum":["STARTUP_FOUNDER","INVESTOR","DIGITAL_NOMAD","UNSURE"],"example":"INVESTOR"},"kycType":{"type":"string","enum":["GVRN","EXTERNAL"],"example":"EXTERNAL"},"founderExternalIdentityReference":{"type":"object","description":"The partner's identity id for the founder; null clears it","nullable":true},"founderIsUsPerson":{"type":"boolean","description":"Citizen, green-card holder or US tax resident","example":false},"founderTaxResidenceCountryCode":{"type":"string","description":"Country of tax residence, ISO 3166-1 alpha-3. A restricted country is refused.","example":"SGP"},"jurisdiction":{"type":"string","description":"Sent together with entityType; the pair must be a catalogue entry","enum":["SINGAPORE","PANAMA","BVI","DELAWARE","WYOMING","CAYMAN_ISLANDS","COSTA_RICA","DUBAI","SEYCHELLES","SWITZERLAND","OTHERS"]},"entityType":{"type":"string","enum":["IBC","FOUNDATION","SPC","PTE_LTD","SRL","SA","LIMITED","CORPORATION","LLC"],"example":"CORPORATION"},"preferredCompanyNames":{"description":"One to three names in preference order, without the entity suffix; replaces the stored list","example":["Marlow Holdings","Marlow Labs"],"type":"array","items":{"type":"string"}}}},"OneShotMemberApiRequestDto":{"type":"object","properties":{"kind":{"type":"string","enum":["INDIVIDUAL","TRUST","COMPANY"],"example":"INDIVIDUAL"},"firstName":{"type":"string","description":"INDIVIDUAL only","example":"Alex"},"middleName":{"type":"string","description":"INDIVIDUAL only"},"lastName":{"type":"string","description":"INDIVIDUAL only","example":"Reyes"},"legalName":{"type":"string","description":"TRUST and COMPANY only","example":"Reyes Family Trust"},"email":{"type":"string","description":"Where this member's verification request goes","example":"qa+alex-reyes@gvrn.ai"},"role":{"type":"string","description":"A trust or company can only be a SHAREHOLDER; directors are natural persons","enum":["SHAREHOLDER","DIRECTOR","BOTH"],"example":"BOTH"},"ownershipPercent":{"type":"number","description":"0–100 with at most two decimals; the list must total exactly 100 to file","example":20},"contributionUsd":{"type":"number","description":"Capital contributed, in USD","example":100000},"externalIdentityReference":{"type":"string","description":"The partner's identity id for this member, on an EXTERNAL-KYC incorporation"}},"required":["kind","email","role","ownershipPercent"]},"OneShotMemberUpdateApiRequestDto":{"type":"object","properties":{"firstName":{"type":"string","description":"INDIVIDUAL only","example":"Alex"},"middleName":{"type":"string","description":"INDIVIDUAL only"},"lastName":{"type":"string","description":"INDIVIDUAL only","example":"Reyes"},"legalName":{"type":"string","description":"TRUST and COMPANY only","example":"Reyes Family Trust"},"email":{"type":"string","description":"Where this member's verification request goes","example":"qa+alex-reyes@gvrn.ai"},"role":{"type":"string","description":"A trust or company can only be a SHAREHOLDER; directors are natural persons","enum":["SHAREHOLDER","DIRECTOR","BOTH"],"example":"BOTH"},"ownershipPercent":{"type":"number","description":"0–100 with at most two decimals; the list must total exactly 100 to file","example":20},"contributionUsd":{"type":"number","description":"Capital contributed, in USD","example":100000},"externalIdentityReference":{"type":"string","description":"The partner's identity id for this member, on an EXTERNAL-KYC incorporation"}}},"OneShotFileApiRequestDto":{"type":"object","properties":{"paymentMethod":{"type":"string","enum":["CARD","USDC"],"example":"CARD"},"paymentReference":{"type":"string","description":"The partner's payment id. Recorded, not verified; re-sending the same one after a timeout is safe.","example":"pi_3Q1x8f2eZvKYlo2C0"}},"required":["paymentMethod","paymentReference"]},"OneShotSignApiRequestDto":{"type":"object","properties":{"signerName":{"type":"string","description":"The founder's name as typed into the signature box","example":"Casey Marlow"}},"required":["signerName"]},"OneShotDocumentDto":{"type":"object","properties":{"key":{"type":"string","example":"certificate"},"group":{"type":"string","enum":["INCORPORATION","GOVERNANCE"]},"title":{"type":"string","example":"Certificate of Incorporation"},"description":{"type":"string","example":"Delaware Division of Corporations · expected within 24h of filing"},"status":{"type":"string","enum":["PENDING","ON_FILE","AWAITING_SIGNATURE","EXECUTED","READY"]},"statusChangedAt":{"type":"string","description":"ISO 8601","example":"2026-09-02T09:12:44.000Z"},"downloadable":{"type":"boolean","description":"Whether `GET incorporations/:id/documents/:key/download` has a file to answer with now. An entry is listed from the moment a founder should expect it, so this is the difference between coming and here.","example":true}},"required":["key","group","title","description","status","downloadable"]},"OneShotResolutionDto":{"type":"object","properties":{"key":{"type":"string","example":"organizational"},"kind":{"type":"string","enum":["ORGANIZATIONAL","OWNERSHIP_AND_REGISTER_UPDATE"]},"title":{"type":"string","example":"Organizational resolution"},"description":{"type":"string","example":"Adopts the bylaws, appoints the directors and issues the founding shares"},"status":{"type":"string","enum":["DRAFT","EXECUTED"]},"date":{"type":"string","description":"ISO 8601","example":"2026-09-02T09:12:44.000Z"},"memberId":{"type":"string","description":"The member a register update records","example":"123e4567-e89b-12d3-a456-426614174000"}},"required":["key","kind","title","description","status","date"]},"OneShotDocumentsApiResponseDto":{"type":"object","properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/OneShotDocumentDto"}},"resolutions":{"type":"array","items":{"$ref":"#/components/schemas/OneShotResolutionDto"}}},"required":["documents","resolutions"]},"PublicApiAttachmentDto":{"type":"object","properties":{"fileName":{"type":"string","description":"What to call the file on the ticket. Any directory part is dropped.","example":"brief.pdf","maxLength":255},"content":{"type":"string","description":"The file's bytes, base64-encoded. The media type is detected from those bytes rather than declared, so a file whose type cannot be determined is refused by name.","example":"JVBERi0xLjQKJc..."}},"required":["fileName","content"]},"OneShotRequestApiRequestDto":{"type":"object","properties":{"incorporationId":{"type":"string","description":"The filed incorporation the request is about"},"kind":{"type":"string","enum":["DOCUMENT","COMPANY_DETAILS","MEMBER_CHANGE","SHARE_CAPITAL","GOVERNANCE","COMPLIANCE_FILING","TAX","ENTITY_CHANGE","OTHER"],"example":"DOCUMENT"},"subject":{"type":"string","description":"One line; becomes the CRM ticket's title","example":"Certified copy of the certificate for HSBC"},"details":{"type":"string","description":"Anything the founder typed in their own words"},"payload":{"type":"object","description":"The answers the partner's form collected, as a flat label → value map, written into the ticket body. At most 30 entries; see the catalogue's `suggestedFields` for what each kind wants.","additionalProperties":{"type":"string"},"example":{"Document":"Certificate of incorporation","Copy type":"Certified","Needed by":"2026-10-15"}},"attachments":{"description":"Supporting files — a signed consent, the bank's wording for a certified copy. At most 5, and 10MB decoded across the request.","type":"array","items":{"$ref":"#/components/schemas/PublicApiAttachmentDto"}}},"required":["incorporationId","kind","subject"]},"OneShotRequestListApiResponseDto":{"type":"object","properties":{"result":{"type":"array","items":{"$ref":"#/components/schemas/OneShotRequestApiResponseDto"}},"total":{"type":"number","description":"Matching the filters, not on this page","example":2},"limit":{"type":"number","example":20},"offset":{"type":"number","example":0}},"required":["result","total","limit","offset"]}},"securitySchemes":{"x-gvrn-public-api-key":{"type":"apiKey","in":"header","name":"x-gvrn-public-api-key"}}},"security":[{"x-gvrn-public-api-key":[]}]}