docs(kyc): add a KYC/KYB verification page covering both onboarding paths - #831
Open
JasonCWang wants to merge 1 commit into
Open
docs(kyc): add a KYC/KYB verification page covering both onboarding paths#831JasonCWang wants to merge 1 commit into
JasonCWang wants to merge 1 commit into
Conversation
…aths
The API reference documented the hosted link flow only in passing, and
only for individual customers. Integrators had no way to discover that
the same link endpoint runs KYB for business customers, or how to choose
between the hosted flow and submitting verification data through the API.
Add an "KYC & KYB verification" page to the API reference that leads with
the choice between the two paths and then covers what each one needs:
- A comparison of the hosted link and direct API paths, noting that both
cover KYC and KYB, produce the same status transitions and webhooks,
and can be mixed.
- Hosted link generation, including that POST /customers/{id}/kyc-link
serves both customer types and that customerType selects the flow.
- Required versus optional fields for creating a business customer, and
the three groups (contact channels, currency-driven, review-driven)
that are optional to the schema but required in practice.
- kycStatus/kybStatus transitions and the CUSTOMER.KYC_* / CUSTOMER.KYB_*
webhooks.
- The sandbox registration-number suffixes, extracted into a shared
snippet so the sandbox testing page and the new page stay in sync.
Document the 003 suffix explicitly: any other suffix auto-approves a
business customer on the spot, leaving the hosted flow with nothing to
verify, so it requests no documents and no beneficial owners. That reads
as a broken KYB flow but isn't, and 003 is what avoids it.
Also broaden the kyc-link endpoint description to cover the KYB case and
point at the direct API alternative.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
|
The latest updates on your projects. Learn more about Vercel for GitHub. 2 Skipped Deployments
|
Contributor
✱ Stainless preview builds for gridThis PR will update the cli go kotlin openapi php python ruby typescript Edit this comment to update them. They will appear in their respective SDK's changelogs. ✅ grid-typescript studio · code · diff
✅ grid-openapi studio · code · diff
✅ grid-ruby studio · code · diff
✅ grid-go studio · code · diff
✅ grid-kotlin studio · code · diff
✅ grid-python studio · code · diff
✅ grid-php studio · code · diff
✅ grid-cli studio · code · diff
This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push. |
JasonCWang
force-pushed
the
docs/kyc-kyb-verification-options
branch
from
August 14, 2026 00:39
db2b832 to
fb4495e
Compare
github-actions
Bot
added
the
breaking-change
Contributor
|
JasonCWang
force-pushed
the
docs/kyc-kyb-verification-options
branch
from
August 14, 2026 00:46
fb4495e to
c61a67f
Compare
JasonCWang
marked this pull request as ready for review
August 14, 2026 20:29
Contributor
Greptile SummaryThis PR adds a shared KYC/KYB verification guide covering hosted and direct onboarding, expands the hosted-link endpoint description for business verification, and centralizes sandbox KYB suffix guidance.
Confidence Score: 4/5The documentation should be corrected before merging because it tells unregulated platforms that verification approval alone unlocks money movement, although End User Terms consent remains a separate prerequisite. The new status table can lead an otherwise correctly verified customer into rejected transaction attempts by omitting an additional required onboarding gate. Files Needing Attention: mintlify/snippets/kyc/verification-options.mdx
|
| Filename | Overview |
|---|---|
| mintlify/snippets/kyc/verification-options.mdx | Adds the principal hosted/direct verification guide, but overstates APPROVED as sufficient to unlock customer money movement. |
| mintlify/snippets/kyc/kyb-sandbox-suffixes.mdx | Centralizes business sandbox suffix outcomes and highlights the suffix needed to exercise document and beneficial-owner collection. |
| mintlify/api-reference/kyc-kyb-verification.mdx | Adds a correctly structured API-reference page that renders the shared verification guide. |
| mintlify/docs.json | Adds the new verification page to the Using the API navigation group. |
| openapi/paths/customers/customers_{customerId}_kyc-link.yaml | Expands the hosted-link description to cover both individual KYC and business KYB paths. |
| mintlify/snippets/sandbox-verification.mdx | Replaces duplicated business suffix content with the shared snippet and retains direct-API-specific guidance. |
| openapi.yaml | Keeps the committed generated OpenAPI bundle synchronized with the source endpoint description. |
| mintlify/openapi.yaml | Keeps the Mintlify OpenAPI build output synchronized with the source endpoint description. |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Create customer] --> B{Verification path}
B -->|Hosted| C[POST customer kyc-link]
C --> D[Customer completes hosted KYC or KYB]
B -->|Direct API| E[Submit customer, owner, and document data]
E --> F[POST verifications]
F -->|RESOLVE_ERRORS| E
D --> G[Customer verification status]
F --> G
G --> H[Customer KYC or KYB webhooks]
Prompt To Fix All With AI
### Issue 1
mintlify/snippets/kyc/verification-options.mdx:90
**Approval omits the consent gate**
When an unregulated platform has not recorded End User Terms consent, this row incorrectly presents KYC/KYB approval as sufficient to unlock funding and money movement, causing customer-scoped transactions to be rejected despite the documented guidance.
```suggestion
| `APPROVED` | Passed verification. For unregulated platforms, record End User Terms consent before enabling funding and money movement |
```
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Reviews (1): Last reviewed commit: "docs(kyc): add a KYC/KYB verification pa..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| |--------|---------| | ||
| | `UNVERIFIED` | Created, not yet submitted. Generating a link does not move it off this value | | ||
| | `PENDING` | Submitted; review under way | | ||
| | `APPROVED` | Passed — unlock funding and money movement | |
Contributor
There was a problem hiding this comment.
When an unregulated platform has not recorded End User Terms consent, this row incorrectly presents KYC/KYB approval as sufficient to unlock funding and money movement, causing customer-scoped transactions to be rejected despite the documented guidance.
Suggested change
| | `APPROVED` | Passed — unlock funding and money movement | | |
| | `APPROVED` | Passed verification. For unregulated platforms, record End User Terms consent before enabling funding and money movement | |
Knowledge Base Used: Customers and KYC
Prompt To Fix With AI
This is a comment left during a code review.
Path: mintlify/snippets/kyc/verification-options.mdx
Line: 90
Comment:
**Approval omits the consent gate**
When an unregulated platform has not recorded End User Terms consent, this row incorrectly presents KYC/KYB approval as sufficient to unlock funding and money movement, causing customer-scoped transactions to be rejected despite the documented guidance.
```suggestion
| `APPROVED` | Passed verification. For unregulated platforms, record End User Terms consent before enabling funding and money movement |
```
**Knowledge Base Used:** [Customers and KYC](https://app.greptile.com/lightspark/-/custom-context/knowledge-base/lightsparkdev/grid-api/-/docs/customers-and-kyc.md)
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a KYC & KYB verification page to the API reference, under Using the API.
The hosted verification link was only documented in passing, and only for individual customers. Nothing told integrators that the same endpoint runs KYB for business customers, or how to pick between the hosted flow and submitting verification data through the API — so that choice had to be explained by hand.
The page leads with the choice and then covers what each path needs:
POST /customers/{customerId}/kyc-linkserves both customer types withcustomerTypeselecting the flow. There is no dedicated KYB link endpoint.providerRequiredCustomerFields, and everything the review needs).kycStatus/kybStatusvalues and theCUSTOMER.KYC_*/CUSTOMER.KYB_*events.The sandbox suffix table moved into a shared snippet so this page and the sandbox testing page can't drift apart.
The 003 suffix
Called out explicitly, because not knowing it is genuinely misleading: a business registration number not ending in
001,002, or003is auto-approved on the spot in sandbox. The hosted flow then has nothing left to verify, so it asks for no documents and no beneficial owners — which looks exactly like a broken KYB flow.003is what avoids the auto-decision so document and UBO collection actually run.Also
Broadens the
kyc-linkendpoint description to cover the KYB case and to name the direct API alternative, rather than describing only individual identity verification.Verification
make build+make lint— spec valid, 0 errors. Bundle diff is scoped to this one endpoint.mint broken-linksreports no broken links from any new or changed file.Docs-only — no schema or behavior changes.
🤖 Generated with Claude Code