docs: sync external account docs with new GET/PATCH/DELETE endpoints - #359
Closed
claude[bot] wants to merge 1 commit into
Closed
docs: sync external account docs with new GET/PATCH/DELETE endpoints#359claude[bot] wants to merge 1 commit into
claude[bot] wants to merge 1 commit into
Conversation
Adds documentation for the new external account endpoints introduced in commit b916f15: - GET /customers/external-accounts/{externalAccountId} - PATCH /customers/external-accounts/{externalAccountId} - DELETE /customers/external-accounts/{externalAccountId} These endpoints allow retrieving, updating (platformAccountId and beneficiary only), and deleting external accounts by their ID. Note: Kotlin sample updates deferred until Grid SDK is updated to support these new endpoints (currently SDK v1.6.0). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
Greptile SummaryThis PR adds documentation for the new
Confidence Score: 3/5Docs are accurate and safe to render, but incomplete — platform external account CRUD endpoints are absent despite existing in the OpenAPI spec. The customer endpoint examples are technically correct (verified against OpenAPI spec), but the stated goal of the PR is to sync docs with the new GET/PATCH/DELETE endpoints, and the platform variants are equally new. Leaving them out creates a visible documentation gap for platform-level integrators. mintlify/snippets/external-accounts.mdx — needs platform external account GET/PATCH/DELETE sections and a PATCH response example
|
| Filename | Overview |
|---|---|
| mintlify/snippets/external-accounts.mdx | Adds GET/PATCH/DELETE docs for customer external accounts, but omits equivalent platform external account endpoints that also exist in the OpenAPI spec; PATCH response example is also missing. |
Sequence Diagram
sequenceDiagram
participant Client
participant GridAPI as Grid API
Note over Client,GridAPI: GET by ID
Client->>GridAPI: GET /customers/external-accounts/{id}
GridAPI-->>Client: 200 ExternalAccount
Note over Client,GridAPI: PATCH (update)
Client->>GridAPI: PATCH /customers/external-accounts/{id}
GridAPI-->>Client: 200 Updated ExternalAccount
Note over Client,GridAPI: DELETE
Client->>GridAPI: DELETE /customers/external-accounts/{id}
GridAPI-->>Client: 204 No Content
Note over Client,GridAPI: Platform variants (undocumented in PR)
Client--xGridAPI: GET /platform/external-accounts/{id}
Client--xGridAPI: PATCH /platform/external-accounts/{id}
Client--xGridAPI: DELETE /platform/external-accounts/{id}
Prompt To Fix All With AI
This is a comment left during a code review.
Path: mintlify/snippets/external-accounts.mdx
Line: 787-876
Comment:
**Platform external account endpoints not documented**
The OpenAPI spec (`openapi/openapi.yaml` line 110-111) defines equivalent `GET`, `PATCH`, and `DELETE` endpoints for `/platform/external-accounts/{externalAccountId}` — identical in capability to the customer variants just added. The existing "Listing external accounts" section already covers both customer and platform list operations side-by-side (lines 764-785), so users will expect parity here too. Without platform-scoped GET/PATCH/DELETE examples, platform-level integrations are left without guidance after the listing section ends.
How can I resolve this? If you propose a fix, please make it concise.
---
This is a comment left during a code review.
Path: mintlify/snippets/external-accounts.mdx
Line: 819-857
Comment:
**Missing PATCH response example**
The PATCH endpoint returns `200` with the full updated `ExternalAccount` object (per `customers_external_accounts_{externalAccountId}.yaml` lines 76-82). The style guide requires showing complete request/response cycles ("Cover complete request/response cycles", "Show both success and error response examples"), but both PATCH tabs only show the request. Consider adding a response block after `</Tabs>` similar to the GET section's `**Response:**` block.
**Context Used:** mintlify/CLAUDE.md ([source](https://app.greptile.com/review/custom-context?memory=8705e0ee-b98a-4325-9b4d-e1f5638b408a))
How can I resolve this? If you propose a fix, please make it concise.Reviews (1): Last reviewed commit: "docs: add GET/PATCH/DELETE documentation..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Comment on lines
+787
to
+876
| ## Get external account by ID | ||
|
|
||
| Retrieve a specific external account by its system-generated ID: | ||
|
|
||
| ```bash cURL | ||
| curl -X GET 'https://api.lightspark.com/grid/2025-10-13/customers/external-accounts/{externalAccountId}' \ | ||
| -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET' | ||
| ``` | ||
|
|
||
| **Response:** | ||
|
|
||
| ```json | ||
| { | ||
| "id": "ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965", | ||
| "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001", | ||
| "status": "ACTIVE", | ||
| "currency": "USD", | ||
| "platformAccountId": "user_123_primary_bank", | ||
| "accountInfo": { | ||
| "accountType": "US_ACCOUNT", | ||
| "accountNumber": "123456789", | ||
| "routingNumber": "021000021", | ||
| "accountCategory": "CHECKING", | ||
| "bankName": "Chase Bank", | ||
| "beneficiary": { | ||
| "beneficiaryType": "INDIVIDUAL", | ||
| "fullName": "John Doe" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Update external account | ||
|
|
||
| Update mutable fields on an external account. Only `platformAccountId` and `beneficiary` can be updated: | ||
|
|
||
| <Tabs> | ||
| <Tab title="Update platformAccountId"> | ||
| ```bash cURL | ||
| curl -X PATCH 'https://api.lightspark.com/grid/2025-10-13/customers/external-accounts/{externalAccountId}' \ | ||
| -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET' \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{ | ||
| "platformAccountId": "new_account_id_456" | ||
| }' | ||
| ``` | ||
| </Tab> | ||
|
|
||
| <Tab title="Update beneficiary"> | ||
| ```bash cURL | ||
| curl -X PATCH 'https://api.lightspark.com/grid/2025-10-13/customers/external-accounts/{externalAccountId}' \ | ||
| -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET' \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{ | ||
| "beneficiary": { | ||
| "beneficiaryType": "INDIVIDUAL", | ||
| "fullName": "Jane Doe", | ||
| "birthDate": "1990-01-15", | ||
| "nationality": "US", | ||
| "address": { | ||
| "line1": "456 Market Street", | ||
| "city": "San Francisco", | ||
| "state": "CA", | ||
| "postalCode": "94105", | ||
| "country": "US" | ||
| } | ||
| } | ||
| }' | ||
| ``` | ||
| </Tab> | ||
| </Tabs> | ||
|
|
||
| <Warning> | ||
| Updates to beneficiary data may trigger account re-review, temporarily changing the status to `UNDER_REVIEW`. | ||
| </Warning> | ||
|
|
||
| ## Delete external account | ||
|
|
||
| Delete an external account by its ID: | ||
|
|
||
| ```bash cURL | ||
| curl -X DELETE 'https://api.lightspark.com/grid/2025-10-13/customers/external-accounts/{externalAccountId}' \ | ||
| -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET' | ||
| ``` | ||
|
|
||
| Returns `204 No Content` on success. | ||
|
|
||
| <Warning> | ||
| Deleting an external account is permanent. Ensure no pending transactions reference this account before deletion. | ||
| </Warning> |
Contributor
There was a problem hiding this comment.
The OpenAPI spec (openapi/openapi.yaml line 110-111) defines equivalent GET, PATCH, and DELETE endpoints for /platform/external-accounts/{externalAccountId} — identical in capability to the customer variants just added. The existing "Listing external accounts" section already covers both customer and platform list operations side-by-side (lines 764-785), so users will expect parity here too. Without platform-scoped GET/PATCH/DELETE examples, platform-level integrations are left without guidance after the listing section ends.
Prompt To Fix With AI
This is a comment left during a code review.
Path: mintlify/snippets/external-accounts.mdx
Line: 787-876
Comment:
**Platform external account endpoints not documented**
The OpenAPI spec (`openapi/openapi.yaml` line 110-111) defines equivalent `GET`, `PATCH`, and `DELETE` endpoints for `/platform/external-accounts/{externalAccountId}` — identical in capability to the customer variants just added. The existing "Listing external accounts" section already covers both customer and platform list operations side-by-side (lines 764-785), so users will expect parity here too. Without platform-scoped GET/PATCH/DELETE examples, platform-level integrations are left without guidance after the listing section ends.
How can I resolve this? If you propose a fix, please make it concise.
Comment on lines
+819
to
+857
| ## Update external account | ||
|
|
||
| Update mutable fields on an external account. Only `platformAccountId` and `beneficiary` can be updated: | ||
|
|
||
| <Tabs> | ||
| <Tab title="Update platformAccountId"> | ||
| ```bash cURL | ||
| curl -X PATCH 'https://api.lightspark.com/grid/2025-10-13/customers/external-accounts/{externalAccountId}' \ | ||
| -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET' \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{ | ||
| "platformAccountId": "new_account_id_456" | ||
| }' | ||
| ``` | ||
| </Tab> | ||
|
|
||
| <Tab title="Update beneficiary"> | ||
| ```bash cURL | ||
| curl -X PATCH 'https://api.lightspark.com/grid/2025-10-13/customers/external-accounts/{externalAccountId}' \ | ||
| -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET' \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{ | ||
| "beneficiary": { | ||
| "beneficiaryType": "INDIVIDUAL", | ||
| "fullName": "Jane Doe", | ||
| "birthDate": "1990-01-15", | ||
| "nationality": "US", | ||
| "address": { | ||
| "line1": "456 Market Street", | ||
| "city": "San Francisco", | ||
| "state": "CA", | ||
| "postalCode": "94105", | ||
| "country": "US" | ||
| } | ||
| } | ||
| }' | ||
| ``` | ||
| </Tab> | ||
| </Tabs> |
Contributor
There was a problem hiding this comment.
The PATCH endpoint returns 200 with the full updated ExternalAccount object (per customers_external_accounts_{externalAccountId}.yaml lines 76-82). The style guide requires showing complete request/response cycles ("Cover complete request/response cycles", "Show both success and error response examples"), but both PATCH tabs only show the request. Consider adding a response block after </Tabs> similar to the GET section's **Response:** block.
Context Used: mintlify/CLAUDE.md (source)
Prompt To Fix With AI
This is a comment left during a code review.
Path: mintlify/snippets/external-accounts.mdx
Line: 819-857
Comment:
**Missing PATCH response example**
The PATCH endpoint returns `200` with the full updated `ExternalAccount` object (per `customers_external_accounts_{externalAccountId}.yaml` lines 76-82). The style guide requires showing complete request/response cycles ("Cover complete request/response cycles", "Show both success and error response examples"), but both PATCH tabs only show the request. Consider adding a response block after `</Tabs>` similar to the GET section's `**Response:**` block.
**Context Used:** mintlify/CLAUDE.md ([source](https://app.greptile.com/review/custom-context?memory=8705e0ee-b98a-4325-9b4d-e1f5638b408a))
How can I resolve this? If you propose a fix, please make it concise.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
pengying
reviewed
Apr 24, 2026
|
|
||
| <Tab title="Update beneficiary"> | ||
| ```bash cURL | ||
| curl -X PATCH 'https://api.lightspark.com/grid/2025-10-13/customers/external-accounts/{externalAccountId}' \ |
Contributor
There was a problem hiding this comment.
@claude we updated the schema to remove patch, can you update this PR to reflect the latest external account schema?
Contributor
|
will create a new pr -- this is out of date |
shreyav
added a commit
that referenced
this pull request
Aug 4, 2026
… examples (#793) ## Summary Two things, both docs-only. Generated bundles untouched. 1. **Documents `GET` and `DELETE` for a single external account** — `external-accounts.mdx` covered create and list but neither by-id operation. 2. **Fixes all 85 remaining broken curl auth examples** across 17 files. **Replaces #359**, which should be closed. ## Part 1 — the new sections | Section | Covers | |---|---| | Retrieving a single external account | `GET /customers/external-accounts/{externalAccountId}`, full response example, `404` | | Deleting an external account | `DELETE /customers/external-accounts/{externalAccountId}`, `204`, and the `409 BENEFICIARY_TRUSTED` path | **Why a rewrite rather than a rebase of #359.** That PR has been open since April and the spec moved under it in four ways: 1. **It documents a `PATCH` endpoint that does not exist.** The path exposes only `get:` and `delete:` — verified in both the source path file and the bundled `openapi.yaml`. About a third of that PR describes an operation the API doesn't have. 2. **`"accountType": "US_ACCOUNT"`** is not a member of `ExternalAccountType`. The value is `USD_ACCOUNT`. 3. **`"accountCategory": "CHECKING"`** is not a field on `UsdAccountInfoBase`. The real field is `bankAccountType`. 4. **Delete's contract changed.** #770 added a `409`, which #359 predates. **The `409` is why the delete section earns its place.** `BENEFICIARY_TRUSTED` fires when the account is a trusted SCA beneficiary, and the caller must untrust *and* confirm before delete succeeds. Nothing at the call site hints at that. **The GET example includes `paymentRails`** because the response genuinely carries it — `UsdExternalAccountInfo` composes `UsdAccountInfo`, which requires it. A short `<Info>` notes it's returned rather than sent; that distinction has already caused one real bug. Every field traces to a schema: `ExternalAccount` for the envelope, `UsdAccountInfoBase` for account fields, `UsdAccountInfo` for `paymentRails` (`ACH`/`WIRE`/`RTP`/`FEDNOW`), `UsdBeneficiary` for the minimum beneficiary shape. ## Part 2 — the curl auth sweep Greptile flagged the auth header on the new examples. It was right, and the problem turned out to be repo-wide: **85 curl examples across 17 files** used ```bash -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET' ``` which fails **two** independent ways. The single quotes stop the shell expanding the variables; and Basic auth requires `base64(user:pass)`, not the raw pair, so the header is rejected even once expanded. Every one of these failed on copy-paste — which is the entire point of a curl example. All 85 now use `-u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"`. **This converges on the existing majority rather than introducing a style.** `api-reference/authentication.mdx` documents `curl -u "{client_id}:{client_secret}"`, and 178 examples across 40 other files already use `-u`. The `-H` form was the minority pattern. Biggest concentrations: `snippets/external-accounts.mdx` (26), `payouts-and-b2b/payment-flow/list-transactions.mdx` (15), `rewards/developer-guides/listing-transactions.mdx` (8). ## Verification - **85 replacements, 85 lines added, 85 deleted** — strictly 1:1, no line lost or merged - Zero occurrences of the broken form remain - **Only auth lines changed** — diff contains no other removals, so no `-H 'Content-Type'` was clobbered - **The 11 JS/Python `Basic ${credentials}` usages are untouched.** Those build the header from a pre-encoded value and are correct; the sweep matched only `-H` lines carrying the raw credential pair - No curl block ended up with a duplicate `-u` - MDX component tags and code fences balance across every `.mdx` in `mintlify/` - The new JSON example parses - Generated bundles byte-identical to `main` **Not verified:** no visual render check, and `make lint` was not run — it fails on `main` regardless, because `npx spectral lint` resolves to a stub `spectral@0.0.0` rather than `@stoplight/spectral-cli`. This change touches no OpenAPI source, so the Mintlify preview is the meaningful check. ## Still open in this file `external-accounts.mdx` documents 21 of ~37 account types in `account-types.ts`. Missing: `XAF`, `BWP`, `AED`, `BDT`, `EGP`, `GHS`, `GTQ`, `HTG`, `JMD`, `PKR`, `CNY`, plus wallet types `BASE_WALLET`, `POLYGON_WALLET`, `PLASMA_WALLET`, `SOLANA_WALLET`, `TRON_WALLET`, `ETHEREUM_WALLET`. Out of scope here, but it's the largest remaining documentation gap in this area. --------- Co-authored-by: Claude <noreply@anthropic.com>
shreyav
added a commit
that referenced
this pull request
Aug 4, 2026
## Summary `external-accounts.mdx` documented **21 of the 45** account types in `ExternalAccountType`. Because the page reads as an enumeration — a tab per country or rail — a developer scanning it would reasonably conclude the other 24 aren't supported. This documents all of them. Docs-only, one file, +927 lines. Generated bundles untouched. **Coverage is now 45/45**, verified by diffing the `accountType` values in the page against `account-types.ts`. | Added | Types | |---|---| | 18 fiat tabs | `AED` `BDT` `BWP` `CNY` `DKK` `EGP` `GHS` `GTQ` `HKD` `HTG` `IDR` `JMD` `MYR` `PKR` `SGD` `THB` `VND` `XAF` | | Cryptocurrency tab | Ethereum L1, Base, Polygon, Solana, Tron, Plasma, Lightning — it previously showed Spark alone | ## Scope grew during the work — worth knowing I started from a list of 17 missing types. A mechanical diff against `account-types.ts` found **24**: `DKK`, `HKD`, `IDR`, `MYR`, `SGD`, `THB`, `VND` and `LIGHTNING` weren't on my list. Stopping at 17 would have reproduced the same partial-coverage problem in a PR whose entire purpose is fixing it, so all 24 are here. ## Where the content comes from Nothing is inferred from existing examples — each type was read from its schema: - **Fields and required/optional split** — `<Ccy>AccountInfoBase.yaml` - **Beneficiary shape** — `<Ccy>Beneficiary.yaml`, which is where the real variation lives. Most need only `fullName`, but **AED** and **JMD** also require an `address`, **GTQ** requires `countryOfResidence` and `phoneNumber`, and **JMD** requires `phoneNumber`. Those are easy to miss and produce confusing validation failures. - **Per-chain asset support** — each `Payment<Chain>WalletInfo.yaml`. Ethereum carries `USDC` and `USDT`; Base and Polygon are USDC-only. Stated per chain rather than assumed uniform. - **Dual-rail currencies** (BDT, CNY, EGP, GHS, PKR) get separate bank-transfer and mobile-money examples, following the existing Colombia and El Salvador tabs. **No example sends `paymentRails`.** It's response-only, and three separate PRs (#351, #661, and the original #359 lineage) got that wrong. The single occurrence of it in this file remains where it belongs — the `GET` **response** example. Example people match the entries added to `currencies.ts` in #791, so the docs and the visualizer describe the same fictional customers. ## Verification - **All 54 curl payloads in the file parse as JSON** — not just the new ones - **Every `accountType` used is a valid `ExternalAccountType` member** - **Coverage diff is empty**: no type in `account-types.ts` is undocumented - MDX component tags and code fences balance - All new curl examples use `-u`, consistent with #793 - `openapi.yaml` and `mintlify/openapi.yaml` byte-identical to `main` **Not verified:** no visual render. This is 927 lines of new tabs, so the **Mintlify preview is the meaningful review** — worth checking that the tab strip doesn't overflow badly now that it holds 32 tabs. `make lint` was not run; it fails on `main` regardless (`npx spectral lint` resolves to a stub `spectral@0.0.0`). ## One thing this surfaces `SWIFT_ACCOUNT` is documented here but **absent from `account-types.ts`**, so the visualizer still can't produce it. That's the known gap from closed #775 — the entry was correct but unreachable without widening `FiatCurrency` past a single `accountType`. Unchanged by this PR, but the asymmetry is now visible: the docs describe a type the visualizer can't build. ## Left out deliberately I had also listed adding SWIFT to `account-model.mdx`. **That item doesn't hold up.** My earlier check used the wrong path — the file is at `platform-overview/core-concepts/account-model.mdx`, not `snippets/`. Looking at the real file, it's an explicitly illustrative page showing 8 representative types, not an enumeration. Singling out SWIFT there would recreate the curated-list problem rather than fix one. Left alone. --- _Generated by [Claude Code](https://claude.ai/code/session_01MMnjJ8yWJsui7jLqqrDrL4)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
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
2 participants
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.
Summary
Changes
Notes
Test plan
mint dev🤖 Generated with Claude Code