There is no simple listing of a flow's cards. A direct call to GET /v1/flows/{id}/cards returns a 404 error (the route does not exist). To retrieve every card of a flow, iterate over the flow's phases and aggregate the results by calling the phase-scoped listing once per phase, or use the search endpoint when a specific term is available.
Updating card properties rejects phaseId. Moving a card must always be done through the move endpoint — it validates that the current phase's required fields are filled in before allowing the card to leave it; attempting to move a card through the generic update returns a 400 error.
Moving a card validates a restricted set of allowed destination phases from the current phase — this set is more restrictive than the full set of theoretically reachable phases shown in the flow's UI. Moving to a phase outside this set, or to the phase the card is already in, returns a 422 error.
Updating phase fields replaces the entire set of the current phase's fields, it is not incremental: sending only some fields wipes out the ones left out of the call. Entry-form fields included in the same call are silently ignored.
The public-link fields update endpoint should not be used on an already-existing, in-progress card — it can wipe (zero out) the current phase's fields without updating the intended entry-form fields, and without returning any HTTP error. Its correct use is exclusively the initial public submission flow.
Native fields auto-filled from the entry form (for example, the client's name, document and requested amount) become immutable after the card is created — attempts to change them return either a silent no-op or a 500 error, depending on the endpoint used. The only way to correct them is to recreate the card.
Updating the card's assignee requires a full object with the user's identifier, name and email — not just a bare identifier. The name is stored as a frozen snapshot on the card and is not re-resolved from the user's account on later reads.
Labels have no direct write endpoint. The only related route is for reading; labels are applied exclusively by automations configured on the flow. Labels applied at card creation may take a short interval before appearing in a read made immediately afterwards.
The completed-card indicator should not be treated as a function of the current phase alone right after a move: negative-closing phases tend to reflect the new state synchronously, while positive-closing phases may take a short interval. We recommend basing integrations on the card's current phase identifier combined with that phase's own configuration.
Attachment registration stores only metadata (a file reference/path) — uploading the binary content is done through a separate mechanism, not covered by the endpoints in this domain.
Bulk card deletion and group member removal are destructive, irreversible operations — there is no additional confirmation step and no way to restore them afterwards.
When executing the credit engine over a card (documented in the engines domain), the policy identifier used in the call's path is not the identifier of the policy configured in the engine, but rather the identifier returned by the flow's credit-engine policy listing — the two identifiers are different and are not interchangeable.
