Two-step creation: the base configuration of the chain (title and general parameters) is created first, without rules and without approvers. Rules are added afterward, one at a time, through their own endpoint — sending rules together with the base configuration is not accepted.
Rules one at a time: the rule-creation endpoint does not accept more than one rule per call. To register several rules, repeat the call once for each one.
Boolean fields always explicit: the base configuration requires all four fields — the title and the three boolean parameters — to be sent explicitly, even when the desired value is false. Omitting any of them results in a validation error.
Approver identification: approvers assigned to a hierarchy level are identified by their user identifier, obtained from the company's user listing (which also returns name and email). Within a rule's conditions, on the other hand, when it's necessary to filter by who performed a previous action on the card — such as the author of a technical opinion — the correct identification is by name or email, not by an internal user identifier.
Updating means full replacement: when updating the base configuration via PUT, the entire object is replaced — it is not a partial update. Fields omitted from the payload revert to their default value. We recommend always fetching the current state before updating, and resending the complete object with the changes applied.
No individual rule deletion: there is no endpoint to remove just one rule. The only way to remove a rule is to delete the entire approval configuration — which erases all associated rules — and recreate it, if needed, with the remaining rules.
Delete path differs from the rest: the configuration-removal endpoint is not nested under flow and phase; it identifies the configuration directly by its identifier.
Querying with no existing configuration: when the phase does not yet have an approval configuration, the query responds with success and an empty body, rather than a not-found error.
Registering a vote requires a prior rule: to register a vote on a card, the phase must have at least one approval rule registered; otherwise, the call returns an error for not finding an applicable rule.
Comment is always required on a vote: when registering or updating a vote, all three fields — decision, value and comment — are required. When the decision is a rejection, the value must be exactly zero; values greater than zero only apply to approvals, representing the approved limit or amount.
Card vote lookup ignores the phase filter: a card's approval lookup returns the approval linked to it regardless of the phase informed in the URL. For cards that go through more than one approval-gated phase, we recommend fetching the full card and iterating over its actions to identify the vote for each phase.
