Update entities documentation

[ricardobcl]

Description

Fixes drift between the entity object schemas and the current API responses, verified against uphold/backend master.

Account Object

• status: all six enum values (was ok/failed), with the response remapping noted (blocked surfaces as failed, restricted as pending).
• type: actual values are bank, card and exchange; bank accounts surface their network (ach/fps/sepa/swift/wire) as the type in responses; ach/fps/sepa remain accepted as deprecated filter values.
• Added the previously undocumented provider, errors and institution properties.

Authentication Method Object

• type now includes sms; fixed a copy-pasted description ("associated with the account").

Card Object

• settings now documents protected and staking; position is always 0 (kept for backward compatibility only); sample updated.

Currency Pair Object

• Documented both pair encodings: concatenated for the legacy currency set (BTCUSD), hyphenated FROM-TO for everything else (SOL-USD).

Transaction Object

• status: removed the nonexistent pending, added on-hold and waiting.
• Fee type: full enum (adds external, special, transfer, unstake, voucher).
• Added completedAt/failedAt; noted that message and origin/destination description are only returned to applications with PII access.
• Destination table: added AccountId, accountType and address.

User Object

• Removed settings.otp.vmc (no longer exists); added settings.otp.email.update.enabled, settings.theme, top-level fullName and identityCountry; balances sample now shows top-level available/pending and per-currency available.
• Fixed the self-contradictory restricted status description (the "unable to login" sentence described blocked).

User Verifications

• Fixed the flag casing: usTaxPayer → usTaxpayer.
• Reframed the table: each verification is an object with a status (plus optional reason etc.), present only when there is something to communicate.
• Corrected stale values: identity has no retry status; email also returns pending for pending email changes; CDD requirement is driven by the user's CDD status, not European nationality; terms never carries an updated reason in API output.
• Added an aside noting additional verification keys (e.g. livenessCheck, proofOfAddress) follow the same structure.

Notes for reviewers

• Verification keys that are conditional on client versions, org tags or regulatory scopes (authentication-method, citizenships, earlyW9Form, placeOfBirth, taxResidence, …) were deliberately covered by the aside rather than given table rows — their semantics are not obvious enough from the resolver to document tersely.
• identity reasons are open-ended (passthrough codes from providers), so they are listed as "various" rather than enumerated.

Related issues

Follow-up to #250 (documentation audit against uphold/backend master).

Impacted areas

Entities page of the API reference (schemas referenced by most other pages).

Steps to reproduce or test

Development

Every enum and field was traced to the backend models, masks and resolvers (account/card/transaction/user models, user-verifications-resolver.js, handlers' private masks).

QA

Render the page and cross-check a live GET /v0/me and GET /v0/me/accounts response against the updated tables.

Checklist

• Add label Breaking Change if it applies.
• Commits are atomic and logically separated.
• Performance implications have been considered.
• Security implications have been considered.
• API documentation, if required, has been created or updated.
• New dependencies have been added to package.json.
• The README file, if required, has been updated.
• Architectural diagram, if required, has been updated.

Deploy notes

N/A — no files added or removed, so no slate index changes are needed.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Updates entity documentation to match current API schemas and responses.

Changes:

• Expanded account, card, transaction, and user fields and enums.
• Clarified currency-pair formats and PII visibility.
• Reworked user verification documentation.

Suppressed comments (2)

_entities.md:524

• The GET /me response sample in _users.md still omits the fields added here (fullName, identityCountry, top-level/per-currency available, top-level pending, and otp.email.update). That page presents the sample as the endpoint response, so the API reference remains internally inconsistent; update the endpoint sample too.

fullName        | The user's full name.
identityCountry | The country of the user's identity document, as determined during identity verification.

_entities.md:565

• The description says the verification is present when the user "must complete" CDD, but optional is listed as a valid status. That makes the meaning of the optional state contradictory; describe it as applicable when the questionnaire may be completed, and reserve "must" for the required status.

customerDueDiligence | optional, required            | n/a                                | Present when the user must complete the Customer Due Diligence (CDD) questionnaire. Whether it is `required` or `optional` depends on the user's CDD status.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[ricardobcl]

Reworded to characterize the set (currencies supported early in Uphold's history, e.g. BTC, ETH, EUR, USD), matching the Tickers page, and clarified it applies to both the pair response field and request paths. The full list is internal backend configuration — enumerating it here would go stale.

[ricardobcl]

The create-flow line in _transactions.md is actually accurate: an uncommitted transaction (quote) is returned with the transient pending status, which only persisted transactions' statuses replace after commit. Added a note to the status enum here to reconcile the two.

[ricardobcl]

The Accounts page is updated accordingly in #253 — the automated review runs against master in isolation, so it can't see the sibling PR.

[ricardobcl]

Those samples are fixed in #253 (all settings.position values are now 0) — the automated review runs against master in isolation, so it can't see the sibling PR.