docs(onboarding): sync KYC/customer examples with schema

[jklein24]

Comprehensive sync of onboarding/KYC documentation examples with the current OpenAPI schema.

Changes

POST /beneficial-owners — now uses roles[] array + nested personalInfo (was singular role + flat fullName).

POST /documents — body uses documentHolder + country (was form fields like customerId= / beneficialOwnerId=).

Webhook event types — corrected to the schema's OBJECT.EVENT dot-notation:

• CUSTOMER.KYC_APPROVED / CUSTOMER.KYC_REJECTED (and KYB_* siblings) — was the invented KYC_STATUS
• INVITATION.CLAIMED — was the invented INVITATION_CLAIMED
• Removed invented CUSTOMER.KYC_SUBMITTED and CUSTOMER.KYC_MANUALLY_* types entirely

kycStatus enum — terminal set is UNVERIFIED | PENDING | APPROVED | REJECTED only; docs that listed EXPIRED / CANCELED / MANUALLY_* corrected.

Bulk CSV import — columns match customers_bulk_csv.yaml; removed bank-account columns (bank accounts are added separately via /customers/external-accounts).

Bulk job-status response — uses id + flat {correlationId, code, message, details} error entries per BulkCustomerImportErrorEntry.

Business customer create/PATCH — uses businessInfo.{legalName, taxId} (was top-level businessName / taxId).

Sibling PRs

Split from a larger sync effort. Two companion draft PRs cover payments and accounts/auth/cards.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	May 25, 2026, 8:36 AM

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ready	Preview, Comment	May 25, 2026 11:34am

[jklein24]

@greptile review

[greptile-apps]

Greptile Summary

This PR comprehensively syncs onboarding/KYC documentation examples with the current OpenAPI schema across 11 MDX files. It corrects webhook event type notation to OBJECT.EVENT dot-notation, updates request body shapes for POST /beneficial-owners and POST /documents, removes bank-account columns from bulk CSV examples, and trims the kycStatus enum to its true terminal set.

• Webhook types corrected throughout: KYC_STATUS → CUSTOMER.KYC_APPROVED/CUSTOMER.KYC_REJECTED, INVITATION_CLAIMED → INVITATION.CLAIMED, and all CUSTOMER.KYC_SUBMITTED/MANUALLY_* invented types removed; KYB_* siblings added for business customers.
• Schema shapes updated: POST /beneficial-owners now uses roles[] + nested personalInfo; POST /documents uses documentHolder + country; business customer create/PATCH uses businessInfo.{legalName, taxId}.
• Bulk CSV and job-status response aligned to customers_bulk_csv.yaml: bank-account columns removed (now managed via /customers/external-accounts), error entries use flat {correlationId, code, message} shape, and id replaces jobId.

Confidence Score: 5/5

Safe to merge — all changes are documentation corrections that align examples with the current schema, with no behavioral or API logic changes.

The PR touches only MDX documentation files and makes well-scoped, schema-driven corrections. The webhook handler in kyc-webhooks.mdx now covers all six documented event types cleanly, previously flagged issues have been addressed, and the structural changes (new envelope shape, corrected field names) are consistent across all affected files.

mintlify/global-p2p/onboarding/invitations.mdx — the step text references amountToSend in the webhook payload but the example data object omits it.

Important Files Changed

Filename	Overview
mintlify/global-p2p/onboarding/invitations.mdx	Corrects webhook type from INVITATION_CLAIMED to INVITATION.CLAIMED and restructures payload to new envelope shape (id/type/timestamp/data); amountToSend is referenced in the step instructions but not present in the example payload's data object.
mintlify/snippets/kyc/kyc-webhooks.mdx	Replaces invented CUSTOMER.KYC_SUBMITTED/MANUALLY_* types with correct PENDING/KYB_* siblings; switch handler now covers all 6 documented event types; stale "only final states" comment replaced with accurate description.
mintlify/snippets/kyc/kyc-unregulated.mdx	Updates hosted flow and direct API steps to use correct CUSTOMER.KYC_* / CUSTOMER.KYB_* event names; adds documentHolder + country to POST /documents; POST /beneficial-owners now uses roles[] + personalInfo object.
mintlify/snippets/creating-customers/customers.mdx	Replaces KYC_STATUS with correct dot-notation event names; clarifies PENDING as intermediate vs APPROVED/REJECTED as terminal; removes EXPIRED, CANCELED, and MANUALLY_* from terminal status note; bulk CSV columns synced with schema.
mintlify/ramps/platform-tools/webhooks.mdx	Renames tab from KYC_STATUS to CUSTOMER.KYC_*; restructures webhook payload to new envelope with nested data object containing full customer fields including customerType, fullName, createdAt, and updatedAt.
mintlify/payouts-and-b2b/onboarding/configuring-customers.mdx	PATCH example replaced with address/currencies update (removing inline bankAccountInfo); bulk CSV columns synced to schema by adding umaAddress and removing bank-account columns; error entry shape updated to flat {correlationId, code, message}.
mintlify/payouts-and-b2b/quickstart.mdx	One-line change: replaces KYC_STATUS with CUSTOMER.KYC_APPROVED / CUSTOMER.KYC_REJECTED (and KYB_* siblings) in the "Track the decision" step.
mintlify/ramps/onboarding/configuring-customers.mdx	Moves business customer fields from top-level businessName/taxId to nested businessInfo.legalName/taxId; required fields note updated to customerType as the sole truly-required field.
mintlify/snippets/creating-customers/onboarding-model.mdx	Updates KYC_STATUS reference to the full set of CUSTOMER.KYC_APPROVED / CUSTOMER.KYC_REJECTED / CUSTOMER.KYC_PENDING event names.
mintlify/rewards/onboarding/configuring-customers.mdx	Fixes heading typo ("Hanlding KYC/KYC" → "Handling KYC/KYB") and adds three new GET /customers query param fields: region, currency, and umaAddress.
mintlify/global-p2p/onboarding/configuring-customers.mdx	Syncs webhook type to CUSTOMER.KYC_APPROVED / CUSTOMER.KYC_REJECTED; removes bank-account columns from bulk CSV; updates job-status response to use id and flat error entry shape.

Sequence Diagram

sequenceDiagram
    participant Dev as Developer Platform
    participant Grid as Grid API
    participant KYCProv as KYC Provider

    Dev->>Grid: POST /customers (with personalInfo)
    Grid-->>Dev: "{ id, kycUrl, token, kycStatus: UNVERIFIED }"

    alt Hosted flow
        Dev->>KYCProv: Redirect customer to kycUrl
        KYCProv-->>Dev: Customer redirected back (redirectUri)
    else Direct API
        Dev->>Grid: POST /documents (documentHolder, country, file)
        Dev->>Grid: POST /verifications
    end

    Grid->>Grid: KYC review begins
    Grid-->>Dev: Webhook: CUSTOMER.KYC_PENDING (intermediate)
    Note over Dev: Surface under review state, block funding

    alt Individual approved
        Grid-->>Dev: Webhook: CUSTOMER.KYC_APPROVED
        Note over Dev: Activate account, unlock funding
    else Individual rejected
        Grid-->>Dev: Webhook: CUSTOMER.KYC_REJECTED
        Note over Dev: Surface next steps to customer
    end

    alt Business approved
        Grid-->>Dev: Webhook: CUSTOMER.KYB_APPROVED
        Note over Dev: Activate business account
    else Business rejected
        Grid-->>Dev: Webhook: CUSTOMER.KYB_REJECTED
    end

Loading

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
mintlify/global-p2p/onboarding/invitations.mdx:103
**`amountToSend` referenced in step but absent from webhook payload example**

Step 1 instructs developers to "Check the `amountToSend` field in the webhook payload," but the `INVITATION.CLAIMED` example (lines 188–203) only includes `code`, `createdAt`, `claimedAt`, `inviterUma`, `inviteeUma`, `url`, and `status` inside `data`. A developer following the numbered steps will look for `amountToSend` in the example and not find it — and a developer who copies the example as-is would fail to read the field needed to create the payment quote. If `amountToSend` is part of the webhook schema, it should appear in the `data` object of the example.

_{Reviews (3): Last reviewed commit: "add KYB_* cases to webhook handler examp..." | Re-trigger Greptile}

[jklein24]

@greptile review

[jklein24]

@greptile review