From 3427f81be6b3779698285bc01b36d59ffd17772e Mon Sep 17 00:00:00 2001 From: Peng Ying Date: Thu, 28 May 2026 17:31:44 -0700 Subject: [PATCH] docs(kyb): add data and document collection requirements snippet --- mintlify/openapi.yaml | 44 +++++++++++++++++- .../snippets/kyc/kyb-data-requirements.mdx | 45 +++++++++++++++++++ mintlify/snippets/kyc/kyc-unregulated.mdx | 5 +++ openapi.yaml | 44 +++++++++++++++++- .../paths/verifications/verifications.yaml | 42 ++++++++++++++++- 5 files changed, 176 insertions(+), 4 deletions(-) create mode 100644 mintlify/snippets/kyc/kyb-data-requirements.mdx diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 8d809111..4aed580d 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -1824,9 +1824,51 @@ paths: post: summary: Submit customer for verification description: | - Trigger KYC (individual) or KYB (business) verification for a customer. The response indicates whether all required information has been provided. If data is missing, the `errors` array describes exactly what needs to be supplied before verification can proceed. + Trigger KYC (individual) or KYB (business) verification for a customer. + The response indicates whether all required information has been provided. + If data is missing, the `errors` array describes exactly what needs to be + supplied before verification can proceed. Call this endpoint again after resolving errors to re-submit. + + ### What to collect for KYB + + Before submitting a `BUSINESS` customer, collect the following via + `POST /customers`, `POST /beneficial-owners`, and `POST /documents`: + + **Business identifying information** + - Entity full legal name + - Doing Business As (DBA) name, if applicable + - Physical address — principal place of business + - Countries of operation + - Identification number — U.S. taxpayer identification number, or, for a + foreign business without one, alternative government-issued documentation + certifying the existence of the business + + **Ownership and control structure** — collected for **one control person** + (an individual with significant responsibility to control, manage, or + direct the legal entity) **and all beneficial owners** (every individual + who owns 25% or more, directly or indirectly). For each, provide: + - Full name + - Date of birth + - Address + - Identification number: + - U.S. persons — SSN or ITIN + - Non-U.S. persons — one or more of: ITIN, passport (with country of + issuance), alien identification card, or another government-issued + photo ID evidencing nationality or residence + + **Required documents** + - Company formation and existence documents (certificate of incorporation, + articles of association, etc.) + - Proof of ownership and control structure (organization and ownership + chart, shareholder agreements, operating agreements, register of members, + or certification of controlling person and beneficial owners) + - Proof of address dated within the last 3 months (utility bill, bank + statement, lease agreement, or official correspondence) + - Tax ID or equivalent identifying-number documents + - For non-U.S. beneficial owners — passport plus one additional + government-issued ID operationId: createVerification tags: - KYC/KYB Verifications diff --git a/mintlify/snippets/kyc/kyb-data-requirements.mdx b/mintlify/snippets/kyc/kyb-data-requirements.mdx new file mode 100644 index 00000000..a57b3e6e --- /dev/null +++ b/mintlify/snippets/kyc/kyb-data-requirements.mdx @@ -0,0 +1,45 @@ +When Grid runs KYB for a business customer, the following information and documents are collected before onboarding completes. Use this list to plan what to gather from the business — provide it via `POST /customers`, `POST /beneficial-owners`, and `POST /documents` (or through the hosted flow). + +#### Business identifying information + +- Entity full legal name +- Doing Business As (DBA) name, if applicable +- Physical address — the principal place of business, local office, or other physical location of the entity opening the account +- Countries of operation +- Identification number — U.S. taxpayer identification number, or, for a foreign business without one, alternative government-issued documentation certifying the existence of the business + +#### Ownership and control structure + +Collected for: + +- **One control person** — a single individual with significant responsibility to control, manage, or direct the legal entity, **and** +- **All beneficial owners** — every individual who owns 25% or more of the legal entity, directly or indirectly. + +For every such individual, provide: + +- Full name +- Date of birth +- Address +- Identification number, by residency: + - **U.S. persons** — Social Security Number (SSN) or Individual Taxpayer Identification Number (ITIN) + - **Non-U.S. persons** — one or more of: ITIN, passport number with country of issuance, alien identification card number, or another government-issued document evidencing nationality or residence and bearing a photograph or similar safeguard + +#### Required documents + +- Company formation and existence documents. For example: + - Certificate of incorporation + - Articles of association +- Proof of ownership and control structure. For example: + - Corporate organization and ownership chart + - Shareholder agreements + - Operating agreements + - Register of members + - Certification of controlling person and beneficial owners +- Proof of address, dated within the last 3 months. For example: + - Utility bill + - Bank statement + - Lease agreement + - Official correspondence +- Tax ID or equivalent identifying-number documents +- For non-U.S. beneficial owners — passport plus one additional government-issued ID. For example: + - National ID diff --git a/mintlify/snippets/kyc/kyc-unregulated.mdx b/mintlify/snippets/kyc/kyc-unregulated.mdx index 73729234..3e4df465 100644 --- a/mintlify/snippets/kyc/kyc-unregulated.mdx +++ b/mintlify/snippets/kyc/kyc-unregulated.mdx @@ -1,3 +1,5 @@ +import KybDataRequirements from '/snippets/kyc/kyb-data-requirements.mdx' + **Unregulated platforms** rely on Grid to run KYC for individuals and KYB for businesses. You can onboard customers either through the **hosted KYC/KYB link flow** below, or by **submitting customer data directly through the API**. Both paths produce the same `kycStatus` transitions and emit the same `CUSTOMER.KYC_APPROVED` / `CUSTOMER.KYC_REJECTED` / `CUSTOMER.KYC_PENDING` (and `CUSTOMER.KYB_*` equivalents) webhooks. @@ -198,6 +200,9 @@ The shape of the flow depends on the customer type: + + + Call `POST /customers` with `customerType: BUSINESS` and the business information (legal name, registration number, tax ID, registered address). diff --git a/openapi.yaml b/openapi.yaml index 8d809111..4aed580d 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1824,9 +1824,51 @@ paths: post: summary: Submit customer for verification description: | - Trigger KYC (individual) or KYB (business) verification for a customer. The response indicates whether all required information has been provided. If data is missing, the `errors` array describes exactly what needs to be supplied before verification can proceed. + Trigger KYC (individual) or KYB (business) verification for a customer. + The response indicates whether all required information has been provided. + If data is missing, the `errors` array describes exactly what needs to be + supplied before verification can proceed. Call this endpoint again after resolving errors to re-submit. + + ### What to collect for KYB + + Before submitting a `BUSINESS` customer, collect the following via + `POST /customers`, `POST /beneficial-owners`, and `POST /documents`: + + **Business identifying information** + - Entity full legal name + - Doing Business As (DBA) name, if applicable + - Physical address — principal place of business + - Countries of operation + - Identification number — U.S. taxpayer identification number, or, for a + foreign business without one, alternative government-issued documentation + certifying the existence of the business + + **Ownership and control structure** — collected for **one control person** + (an individual with significant responsibility to control, manage, or + direct the legal entity) **and all beneficial owners** (every individual + who owns 25% or more, directly or indirectly). For each, provide: + - Full name + - Date of birth + - Address + - Identification number: + - U.S. persons — SSN or ITIN + - Non-U.S. persons — one or more of: ITIN, passport (with country of + issuance), alien identification card, or another government-issued + photo ID evidencing nationality or residence + + **Required documents** + - Company formation and existence documents (certificate of incorporation, + articles of association, etc.) + - Proof of ownership and control structure (organization and ownership + chart, shareholder agreements, operating agreements, register of members, + or certification of controlling person and beneficial owners) + - Proof of address dated within the last 3 months (utility bill, bank + statement, lease agreement, or official correspondence) + - Tax ID or equivalent identifying-number documents + - For non-U.S. beneficial owners — passport plus one additional + government-issued ID operationId: createVerification tags: - KYC/KYB Verifications diff --git a/openapi/paths/verifications/verifications.yaml b/openapi/paths/verifications/verifications.yaml index 76d281ae..ced49ea5 100644 --- a/openapi/paths/verifications/verifications.yaml +++ b/openapi/paths/verifications/verifications.yaml @@ -1,13 +1,51 @@ post: summary: Submit customer for verification - description: > + description: | Trigger KYC (individual) or KYB (business) verification for a customer. The response indicates whether all required information has been provided. If data is missing, the `errors` array describes exactly what needs to be supplied before verification can proceed. - Call this endpoint again after resolving errors to re-submit. + + ### What to collect for KYB + + Before submitting a `BUSINESS` customer, collect the following via + `POST /customers`, `POST /beneficial-owners`, and `POST /documents`: + + **Business identifying information** + - Entity full legal name + - Doing Business As (DBA) name, if applicable + - Physical address — principal place of business + - Countries of operation + - Identification number — U.S. taxpayer identification number, or, for a + foreign business without one, alternative government-issued documentation + certifying the existence of the business + + **Ownership and control structure** — collected for **one control person** + (an individual with significant responsibility to control, manage, or + direct the legal entity) **and all beneficial owners** (every individual + who owns 25% or more, directly or indirectly). For each, provide: + - Full name + - Date of birth + - Address + - Identification number: + - U.S. persons — SSN or ITIN + - Non-U.S. persons — one or more of: ITIN, passport (with country of + issuance), alien identification card, or another government-issued + photo ID evidencing nationality or residence + + **Required documents** + - Company formation and existence documents (certificate of incorporation, + articles of association, etc.) + - Proof of ownership and control structure (organization and ownership + chart, shareholder agreements, operating agreements, register of members, + or certification of controlling person and beneficial owners) + - Proof of address dated within the last 3 months (utility bill, bank + statement, lease agreement, or official correspondence) + - Tax ID or equivalent identifying-number documents + - For non-U.S. beneficial owners — passport plus one additional + government-issued ID operationId: createVerification tags: - KYC/KYB Verifications