> ## Documentation Index
> Fetch the complete documentation index at: https://pay-docs.holdstation.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Field Reference
> Every field on a KYB submission — business details, persons, documents, and files.
The request body for [`POST /partners/kyb`](/api-reference/kyb/submit-kyb) is a single JSON object.
See [Submission Rules](/guides/partner-business-kyb/submission-rules) for the cross-field checks that run on top of these per-field requirements.
## Business Fields
| Field | Type | Required | Notes |
| ----------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subject_type` | int enum | Yes | `1` = partner (self), `2` = sub-merchant |
| `reference_id` | string | No | Your own id for the subject, e.g. your merchant id. Max 128 bytes, stored trimmed. One `subject_type = 2` record per `reference_id`; generated by Holdstation Pay if omitted. Not used for `subject_type = 1`. |
| `legal_name` | string | Yes | Company name exactly as on the incorporation document |
| `registration_number` | string | Yes | Business registration / incorporation number |
| `incorporation_country` | string | Yes | ISO 3166-1 alpha-2 preferred. Alpha-3 (`VNM`) and full names (`Vietnam`) are accepted and normalized to alpha-2. |
| `incorporation_date` | string | Yes | ISO `YYYY-MM-DD` |
| `address` | string | Yes | Registered company address |
| `email` | string | No | Business email |
| `phone` | string | No | Business phone number |
| `website` | string | No | Business website |
| `nature_of_business` | string | Yes | What the company does: industry, products, services, customers, business model |
| `geographic_scope` | string\[] | Yes | Where the business operates and serves customers. ISO 3166-1 alpha-2 preferred, but values are **not** format-checked — region labels such as `EU` or `SEA` are accepted. |
| `persons` | object\[] | Yes | Legal representative and directors — see [Persons](#persons) |
| `documents` | object\[] | Yes | Company documents, types `1`–`9` — see [Documents](#documents) |
Do not send an `id`. The record id is generated by Holdstation Pay and returned in the response.
## Persons
Each entry in `persons[]` is one legal representative or director. Field names match the [Partner Customer KYC](/guides/partner-customer-kyc/kyc-management) API.
| Field | Type | Required | Notes |
| ---------------- | --------- | -------- | ---------------------------------------------------------------------------------------- |
| `role` | int enum | Yes | `1` = Legal representative, `2` = Director. **Exactly one** person must have `role = 1`. |
| `name` | string | Yes | Full name |
| `date_of_birth` | string | Yes | ISO `YYYY-MM-DD` |
| `email` | string | No | Email |
| `phone` | string | No | Phone number |
| `address` | string | Yes | Residential address |
| `id_number` | string | Yes | Identity document number |
| `id_type` | int enum | Yes | `1` = Citizen ID, `2` = Passport |
| `sex` | int enum | Yes | `1` = Male, `2` = Female, `3` = Other |
| `nationality` | string | Yes | ISO 3166-1 alpha-2 preferred. Alpha-3 and full names are accepted and normalized. |
| `date_of_issue` | string | No | Identity document issue date, ISO `YYYY-MM-DD` |
| `date_of_expiry` | string | No | Identity document expiry date, ISO `YYYY-MM-DD` |
| `documents` | object\[] | Yes | **Exactly one** identity document, of type `10` or `11`, matching `id_type` |
A person whose `nationality` differs from the company's `incorporation_country` must use a passport — `id_type: 2` with a type `10` document. See [Submission Rules](/guides/partner-business-kyb/submission-rules#foreign-nationals-must-use-a-passport).
## Documents
The same document object is used in both `documents[]` and `persons[].documents[]` — only the accepted `type` values differ.
| Field | Type | Required | Notes |
| ----------------- | --------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | int enum | Yes | See [Document Types](#document-types) |
| `files` | object\[] | Yes | Up to **10 files** per document — see [Files](#files). An empty array is accepted by the API, but a document with no file cannot be reviewed. |
| `document_number` | string | Conditional | Required for type `4` (import/export licence). Not needed for other types. |
| `date_of_issue` | string | No | ISO `YYYY-MM-DD` |
| `date_of_expiry` | string | No | ISO `YYYY-MM-DD` |
### Document Types
| Value | Document | Required | Belongs in |
| ----- | --------------------------------------------------------------------- | --------------------------- | ----------------------- |
| `1` | Incorporation paper | **Yes** | `documents[]` |
| `2` | Business registration extract | No | `documents[]` |
| `3` | Nature of business & geographic scope declaration, with company stamp | **Yes** | `documents[]` |
| `4` | Import/export licence | No | `documents[]` |
| `5` | Product images | No | `documents[]` |
| `9` | Other company document | No | `documents[]` |
| `10` | Passport | One of `10`/`11` per person | `persons[].documents[]` |
| `11` | Citizen ID | One of `10`/`11` per person | `persons[].documents[]` |
Types `1`–`9` are valid **only** in the top-level `documents[]`; types `10` and `11` are valid **only** in `persons[].documents[]`. Using a type in the wrong array is rejected with `INVALID_DOCUMENT_TYPE`.
Types `4` and `5` are conditional on the company importing, exporting, or selling physical products, but no request field declares that — they are accepted when present and never demanded.
## Files
| Field | Type | Required | Notes |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| `filename` | string | Yes | Original filename |
| `content_type` | string | Yes | `application/pdf`, `image/jpeg`, `image/png`, or `image/heic` |
| `data` | string | Yes | Base64-encoded file contents. Must decode to **at least one byte** and must match `content_type`. |
`data` carries the file itself. A storage path, URL, or reference is not accepted — Holdstation Pay cannot fetch files from a location you supply, and a file sent that way is rejected with `FILE_CORRUPT`.
See [Submitting Documents](/guides/partner-business-kyb/submitting-documents) for encoding rules and size limits.
## Response-Only Fields
[`GET /partners/kyb/{id}`](/api-reference/kyb/get-kyb) echoes every submitted field at the same path, plus:
| Field | Type | Notes |
| ------------------ | -------- | ------------------------------------------------------------- |
| `id` | string | Server-generated record id |
| `partner_id` | string | The partner that owns the record |
| `reference_id` | string | Your id for the subject, or the one Holdstation Pay generated |
| `status` | int enum | `1` = Pending, `2` = Approved, `3` = Rejected |
| `rejection_reason` | string | Set when `status` is `3`, empty string otherwise |
| `submitted_at` | string | ISO 8601 timestamp |
| `reviewed_at` | string | ISO 8601 timestamp. `null` while pending. |
Inside `documents[].files[]` and `persons[].documents[].files[]`, the `data` field is replaced by:
| Field | Type | Notes |
| -------------- | ------- | ----------------------------------------------------------------------- |
| `file_ref` | string | Opaque reference to the stored file: `f_` followed by 12 hex characters |
| `filename` | string | Original filename |
| `content_type` | string | MIME type of the stored file |
| `size` | integer | Size in bytes of the decoded file |