---
title: "Raise a corporate-secretarial request"
method: POST
path: "/public/one-shot/requests"
tags: ["GVRN OneShot API"]
---

# Raise a corporate-secretarial request

`POST /public/one-shot/requests`

## 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/requests`
- Auth: API key in header `x-gvrn-public-api-key`

Everything a founder can ask GVRN for once the company exists: a copy of a document, a change to
the company's details, shareholders or directors, a resolution, a statutory filing, a tax
registration, or anything else. Each one opens a ticket on GVRN's corporate-secretarial queue
carrying the subject, the founder's own words and whatever the partner's form collected.

`kind` comes from the catalogue's `requestKinds`, whose `suggestedFields` say what that kind's
form should collect into `payload` — advisory, never validated, since the partner owns its UI.

**Files are base64 in the body**, at most
5 of them and
10MB decoded across the request —
a signed director's consent, the bank's wording for a certified copy. Each file's media type is
detected from its bytes rather than taken from the request, so one whose type cannot be
determined is refused by name and the whole request fails: a partner told its request was raised
would otherwise have no way to tell which files landed. They are stored against the CRM ticket,
where the operator working the request already looks; `attachmentCount` on every read confirms
what arrived.

**Only on a filed incorporation.** A draft's members, entity and company details are all still
editable through this API, so there is nothing to ask for until the company is filed.

GVRN does the work in its own systems; this API reports the request's status back and nothing
more. A request is not a filing instruction and nothing is charged by raising one.

## Request body

- OneShotRequestApiRequestDto
  - `incorporationId` string, required: The filed incorporation the request is about
  - `kind` 'DOCUMENT' | 'COMPANY_DETAILS' | 'MEMBER_CHANGE' | 'SHARE_CAPITAL' | 'GOVERNANCE' | 'COMPLIANCE_FILING' | 'TAX' | 'ENTITY_CHANGE' | 'OTHER', required
  - `subject` string, required: One line; becomes the CRM ticket's title
  - `details` string: Anything the founder typed in their own words
  - `payload` object: 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.
  - `attachments` PublicApiAttachmentDto[]: Supporting files — a signed consent, the bank's wording for a certified copy. At most 5, and 10MB decoded across the request.
    - `fileName` string, required: What to call the file on the ticket. Any directory part is dropped.
    - `content` string, required: 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.

## Response `201`

Raised

- OneShotRequestApiResponseDto
  - `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`: A limit was exceeded or a file could not be read; the message lists every problem
- `404`: No such incorporation for this key
- `409`: The incorporation is not filed

---

[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)