docs: add Clients API reference - #15
Merged
Merged
Conversation
Documents the two operations shipped by REF-23846 (serana#4761, talos#849): - POST /api/v1/businesses/:urlKey/clients — create with full detail - GET /api/v1/businesses/:urlKey/clients/:clientId — read one back Written against the merged implementation rather than the task description, and the vocabularies are taken from @refrens/fence so they cannot drift from what the product's own client form offers. Four points where the shipped behaviour differs from the original spec are reflected here: no internal record id in any response, create answers 201, isClient is caller-settable, and 405 carries the status alone with no error code. The record-id fetch fallback is deliberately left out — it ships unpublished. Refrens-owned fields are described under the response shape rather than enumerated as a request-side denylist. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
0xSagaCity
approved these changes
Aug 13, 2026
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.
Adds the public API reference for the two Clients operations shipped by REF-23846 (serana#4761, talos#849), following the house style established by
docs/leads.mdx.POST /api/v1/businesses/:urlKey/clients— create with full billing identity, address, tax ids, shipping addresses, bank accounts and custom fields in one callGET /api/v1/businesses/:urlKey/clients/:clientId— read one back by your own referenceHow this was written
Documented against the merged implementation, not the task description. Vocabularies (client types, bank account types,
additionalIdscodes and formats, tax payer types) are taken from@refrens/fence, so the page cannot drift from what the product's own client form offers.Four places where the shipped behaviour differs from the original spec are reflected here rather than the spec's version:
201, not200isClientisVendorfalse is refused405error.codeA logged-in user session is also documented as
401, not403, matching the service test.Deliberate omissions
Visibilitystates that GET reaches only clients created through this API, andclientIdis not documented as nullable, since that value is unreachable through any published endpoint.Review
Two independent reader-effort editorial passes were applied. The second caught a real defect: the request sample sent
clientTypewhile the201admonition claimed it was derived from the absent field. Fixed by removing it from the sample, so thegstinnow legitimately demonstrates the derivation.Verification
npm run buildpasses — withonBrokenLinks: 'throw'this is the broken-link and anchor checkprettiercleanNot verified
The
201create status is inferred from the Feathers REST default plus the leads staging test report. It has not been confirmed against a live staging call with a real token.🤖 Generated with Claude Code