docs(kyc): document direct API onboarding for unregulated platforms

[pengying]

Summary

Unregulated platforms can now onboard customers via direct API calls (beneficial owners, documents, verifications) in addition to the existing hosted KYC/KYB link flow. Updates the docs to reflect both options.

• ramps/quickstart.mdx: drop "unregulated must use hosted flow" claim
• snippets/kyc/kyc-unregulated.mdx: reframe top callout; add Direct API Onboarding Steps section walking through POST /beneficial-owners, POST /documents, POST /verifications
• snippets/creating-customers/onboarding-model.mdx + customers.mdx: mention both onboarding paths

Regulated platform content (kyc-regulated.mdx and tabs structure) unchanged.

Test plan

• Preview the Mintlify build and verify Configuring Customers, ramps Quickstart, and the Creating Customers snippet render correctly
• Confirm the new Steps section under Unregulated > Direct API Onboarding shows the cURL examples in order

[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 23, 2026 10:09pm

[pengying]

• docs(kyc): document direct API onboarding for unregulated platforms #499 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[mintlify]

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

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	May 23, 2026, 9:52 PM

[greptile-apps]

Greptile Summary

This PR documents a new capability for unregulated platforms: in addition to the existing hosted KYC/KYB link flow, they can now submit identity data directly via POST /beneficial-owners, POST /documents, and POST /verifications. Four MDX files are updated consistently to reflect both onboarding paths.

• kyc-unregulated.mdx: replaces the <Warning> with a <Note>, rewrites the intro bullets, and adds a new <Steps> section walking through the full direct API onboarding sequence with curl examples.
• customers.mdx and onboarding-model.mdx: update the platform model descriptions to name both paths and confirm shared KYC_STATUS webhook behavior.
• ramps/quickstart.mdx: drops the outdated "unregulated must use hosted flow" restriction from Step 1.

Confidence Score: 4/5

Documentation-only change that is safe to merge; the new Direct API Onboarding section is accurate and well-structured, with only minor consistency gaps in the curl examples.

The prose and step descriptions across all four files are accurate and consistent. The main gaps are in the new curl examples: POST /beneficial-owners and POST /documents omit Idempotency-Key headers that POST /verifications includes, and the POST /verifications step references a structured error response without showing what it looks like.

mintlify/snippets/kyc/kyc-unregulated.mdx — the new Direct API Onboarding curl examples have inconsistent idempotency header usage and a missing response example.

Important Files Changed

Filename	Overview
mintlify/snippets/kyc/kyc-unregulated.mdx	Rewrites the top callout from Warning to Note and adds a complete Direct API Onboarding Steps section. Idempotency key headers are inconsistently applied across the new curl examples, and the opening Note omits the KYC_STATUS webhook claim present in the other updated files.
mintlify/ramps/quickstart.mdx	Single sentence updated in Step 1 to reflect both onboarding paths for unregulated platforms; change is accurate and consistent with the snippet content.
mintlify/snippets/creating-customers/customers.mdx	Onboarding model bullet updated to describe both paths; adds a cross-reference link to the Configuring Customers guide for the direct API flow. No issues found.
mintlify/snippets/creating-customers/onboarding-model.mdx	Unregulated platforms bullet updated to describe both onboarding paths; pre-existing missing-EOF-newline is unchanged.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Unregulated Platform] --> B{Choose onboarding path}
    B --> C[Hosted KYC/KYB Link Flow]
    B --> D[Direct API Onboarding]
    C --> C1[POST /customers]
    C1 --> C2[POST /customers/id/kyc-link]
    C2 --> C3[Redirect customer to kycUrl or embed SDK]
    C3 --> C4[Customer completes verification]
    D --> D1[POST /customers]
    D1 --> D2{Business customer?}
    D2 -- Yes --> D3[POST /beneficial-owners per owner]
    D2 -- No --> D4[POST /documents]
    D3 --> D4
    D4 --> D5[POST /verifications]
    C4 --> E[KYC_STATUS webhook emitted]
    D5 --> E
    E --> F{Decision}
    F -- APPROVED --> G[Unlock funding and money movement]
    F -- REJECTED or EXPIRED --> H[Surface next step or request manual review]

Loading

Prompt To Fix All With AI

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

---

### Issue 1 of 4
mintlify/snippets/kyc/kyc-unregulated.mdx:2
The opening `<Note>` says "Both paths produce the same `kycStatus` transitions," but the parallel descriptions in `customers.mdx` and `onboarding-model.mdx` say "Both paths emit the same `KYC_STATUS` webhooks." These are two distinct things — `kycStatus` is the field on the customer object, `KYC_STATUS` is the webhook event type. A reader who relies only on this callout may miss that webhooks are also shared across paths, which is the more operationally relevant claim.

```suggestion
**Unregulated platforms** rely on Grid to run KYC/KYB. You can onboard customers either through the **hosted KYC/KYB link flow** below, or by **submitting KYC data directly through the API** — creating beneficial owners, uploading documents, and triggering verification yourself. Both paths produce the same `kycStatus` transitions and emit the same `KYC_STATUS` webhooks.
```

### Issue 2 of 4
mintlify/snippets/kyc/kyc-unregulated.mdx:110-114
The `POST /beneficial-owners` example omits an `Idempotency-Key` header, but the `POST /verifications` example includes one. Without an idempotency key on retried calls, a transient network failure could result in duplicate beneficial owner records being registered for the same customer.

```suggestion
  ```bash
  curl -X POST "https://api.lightspark.com/grid/2025-10-13/beneficial-owners" \
    -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(uuidgen)" \
    -d '{
```

### Issue 3 of 4
mintlify/snippets/kyc/kyc-unregulated.mdx:127-133
The `POST /documents` upload example also omits an `Idempotency-Key`. Retrying a failed document upload without one risks uploading the same file twice. The pattern used in `POST /verifications` should be applied here as well.

```suggestion
  ```bash
  curl -X POST "https://api.lightspark.com/grid/2025-10-13/documents" \
    -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
    -H "Idempotency-Key: $(uuidgen)" \
    -F "customerId=Customer:019542f5-b3e7-1d02-0000-000000000001" \
    -F "documentType=PASSPORT" \
    -F "file=@./passport.jpg"
  ```
```

### Issue 4 of 4
mintlify/snippets/kyc/kyc-unregulated.mdx:136-150
**Missing response example for `POST /verifications`**

The step text says "the response will tell you which fields or documents to collect before retrying" but shows no example of that response. The hosted KYC flow section shows a response body for its key endpoint; showing at least a representative success body and the missing-fields error shape here would let developers know what to expect without needing to test-hit the API first.

_{Reviews (1): Last reviewed commit: "docs(kyc): document direct API onboardin..." | Re-trigger Greptile}

[pengying]

Merge activity

• May 23, 10:25 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• May 23, 10:25 PM UTC: @pengying merged this pull request with Graphite.