> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Create a business policy > Creates a business policy for the organization. A policy has `conditions` — when it applies — and `actions` — what happens then: approve right away (`APPROVE`), refuse right away (`DENY`), or open an approval request that `approvals` decide (`NONE`). Each condition tests a field of the condition catalog of the policy's `context` (see the payment and spend review conditions endpoints for the fields, the operators each accepts and how values are typed). An empty `conditions.groups` matches everything, which is how you write an organization-wide default. Active policies of a `context` are tried by ascending `order` (the oldest first on a tie) and the first match decides, so give exceptions a lower `order` than the default they override. A payment no policy matches is approved. Before the policy is saved, every user and group in `approvals` and the `moveBalance` funding wallet are checked — and, on `PAYMENT` and `SPEND_REVIEW` policies, every user and wallet a condition names and every custom field a condition uses. Each must belong to the organization; an approver group must not be archived; a user named in a condition must be active; wallets must be active, and the funding wallet must be held by `fromAccountId`; custom fields must be active. Send approvers as `{ type, id }` only. Only organization admins can create policies. ## OpenAPI ````yaml /api-reference/ruleengine.openapi.json post /realms/{realmId}/organizations/{organizationId}/business-policies openapi: 3.0.3 info: title: Ruleengine version: 1.0.0 description: >- Portão 3 ruleengine API. Every endpoint requires a bearer token in the Authorization header (Authorization: Bearer ) unless its page states otherwise; see the Authentication guide. That requirement is not repeated per endpoint. Generated by tools/openapi from code (routes + security) and the hand-written spec (request/response bodies). Confidence tiers: generated:typed=26 copied:manual=0 unknown=0. servers: - url: https://api.ruleengine.v2.portao3.com.br/ description: production - url: https://api.ruleengine.dev.3pers.com.br/ description: development security: [] tags: - name: Business Policies - name: Policy Requests paths: /realms/{realmId}/organizations/{organizationId}/business-policies: post: tags: - Business Policies summary: Create a business policy description: Creates a business policy for the organization. operationId: postRealmsByRealmIdOrganizationsByOrganizationIdBusinessPolicies parameters: - name: realmId in: path required: true description: |- ID of your realm. Format: `UUID` schema: type: string format: uuid example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b - name: organizationId in: path required: true description: |- ID of the organization the policy belongs to. Format: `UUID` schema: type: string format: uuid example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 requestBody: required: true content: application/json: schema: type: object properties: context: type: string enum: - PAYMENT - SPEND_REVIEW - TRAVEL description: >- What the policy governs. `PAYMENT`: a Pix payment, a boleto payment or a wallet transfer request, before it is paid. `SPEND_REVIEW`: the review of a transaction that already happened. `TRAVEL`: accepted, but no travel flow evaluates policies yet. `PAYMENT` and `SPEND_REVIEW` each have a condition catalog — see the payment and spend review conditions endpoints; `TRAVEL` has none. example: PAYMENT name: type: string minLength: 1 maxLength: 120 description: Name of the policy, shown to approvers. example: Payments over R$ 5,000 description: description: >- What the policy does, in plain words. The generate description endpoint can write it for you. example: >- Pagamentos acima de R$ 5.000,00 precisam da aprovação do time financeiro. type: string maxLength: 500 order: description: >- Evaluation order. Active policies of the same `context` are tried from the lowest `order` up — the oldest first on a tie — and the first one whose conditions match decides. Defaults to `0`. example: 10 type: integer minimum: 0 status: description: >- `ACTIVE` policies are evaluated; `DISABLED` ones are kept but never evaluated. Defaults to `ACTIVE`. A policy is archived only through the archive endpoint. example: ACTIVE type: string enum: - ACTIVE - DISABLED actions: type: object properties: hierarchy: type: boolean description: >- `true`: the `approvals` decide one at a time, in the order listed — the next one is asked only after the previous one approved. `false`: all of them are asked at once. example: false autoAction: type: string enum: - APPROVE - DENY - NONE description: >- What happens when the policy matches. `APPROVE`: allowed right away. `DENY`: refused right away. `NONE`: an approval request is opened and `approvals` decide it. `approvals` must list at least one participant for `NONE` and must be empty or absent otherwise. example: NONE moveBalance: description: >- Funds the payment from another wallet of the organization once it is approved. type: object properties: addBalance: type: boolean description: >- `true`: when the policy approves — right away or through its approvers — the amount is first moved from the funding wallet (`fromAccountId` + `fromWalletId`) into the wallet the payment comes from (on a `SPEND_REVIEW` policy, the wallet of the reviewed transaction). Nothing moves for an incoming wallet transfer request, which credits the wallet itself, nor when the funding wallet is that wallet and the money would land in the same balance. example: true fromAccountId: description: >- ID of the account that holds the funding wallet. Required when `addBalance` is `true`. example: 66f2a1c7b4d3e80012c9a0b4 type: string minLength: 1 fromWalletId: description: >- ID of the funding wallet. It must be an active wallet of the organization, held by `fromAccountId`. Required when `addBalance` is `true`. example: 6710b8e4c9e77b0012a4d6f3 type: string minLength: 1 required: - addBalance additionalProperties: false approvals: description: >- Who approves when `autoAction` is `NONE`. Every entry must approve for the request to be approved; one refusal denies it. Send only `type` and `id`: the `name` a read returns is not accepted. type: array items: type: object properties: type: type: string enum: - USER - GROUP description: >- `USER`: one member of the organization. `GROUP`: a user group of the organization — the first member who decides, decides for the group. example: GROUP id: type: string format: uuid description: >- ID of the user or of the group. It must belong to this organization. Format: `UUID` example: 8b0e4c2a-1f6d-4e3b-a9c7-2d5f8e1b6c30 required: - type - id additionalProperties: false description: One approver. required: - hierarchy - autoAction additionalProperties: false description: What the policy does when it matches. conditions: type: object properties: logic: type: string enum: - AND - OR description: >- How the results of `groups` combine: `AND` — every group must match; `OR` — one is enough. example: AND groups: type: array items: type: object properties: logic: type: string enum: - AND - OR description: >- How the group's `items` combine: `AND` — every item must match; `OR` — one is enough. example: AND dependsOn: description: >- Data loaded before the group is evaluated, for items that compare against it through `dynamicFieldValue`. List only what an item of the group reads, and each value once. type: array items: type: string enum: - account - gatewayDocument - gatewayLegalName - creditPixTransactionsByDocument items: minItems: 1 type: array items: type: object properties: field: type: string minLength: 1 description: >- Dot path of the value to test, from the condition catalog of the policy's `context` — for example `amount`, `subjectType` or `customFields.cost-center`. `TRAVEL` has no catalog: any field is accepted. example: amount operator: type: string description: >- How `field` is compared with `value`: `EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `LESS_THAN`, `GTE`, `LTE`, `INCLUDES`, `NOT_INCLUDES`, `IS_ONE_OF`, `BEGINS_WITH`, `ENDS_WITH`, `DATE_WITHIN(n)` (the date falls between today and `n` days from today, in São Paulo time) or `LLM_EVALUATE` (an AI reading of the field against the criteria written in `value`). Each catalog field lists the operators it accepts; `TRAVEL` policies also accept `MAX_COUNT(n)` and `MIN_COUNT(n)`. example: GREATER_THAN value: description: >- What `field` is compared with, typed as the catalog says: an amount is an integer in centavos (`500000` is R$ 5,000.00), a date is `YYYY-MM-DD`, `INCLUDES` and `NOT_INCLUDES` take an array, `LLM_EVALUATE` takes the criteria as text. Required by every operator except `DATE_WITHIN(n)`, `MAX_COUNT(n)` and `MIN_COUNT(n)`, unless `dynamicFieldValue` is sent. example: 500000 dynamicFieldValue: description: >- Compare with a value loaded at evaluation time instead of `value`: a dot path into data the group lists in `dependsOn`. Send `value` or `dynamicFieldValue`, never both. type: string maskType: description: >- Masks both sides of the comparison before it runs — on an `LLM_EVALUATE` condition, before the AI reads the value. `CPF_CNPJ` hides part of an unformatted 11-digit CPF or 14-character CNPJ; `PHONE` hides every digit of a phone number but the first four and the last two; a value in any other format is left as it is. The comparison runs on the masked values, so two documents with the same visible digits compare as equal. type: string enum: - CPF_CNPJ - PHONE required: - field - operator additionalProperties: false description: One condition. description: >- The group's conditions — at least one. A field missing from what is evaluated makes its condition false, whatever the operator. required: - logic - items additionalProperties: false description: A group of conditions. description: >- Condition groups. An empty array matches everything: the way to write an organization-wide default. On `PAYMENT` and `SPEND_REVIEW` policies: at most 50 groups of at most 100 items each, at most 10 `LLM_EVALUATE` items in the whole policy, and at most 200 values in an array. required: - logic - groups additionalProperties: false description: When the policy matches. required: - context - name - actions - conditions additionalProperties: false responses: '201': description: Successful response content: application/json: schema: type: object properties: id: type: string description: ID of the business policy. example: 3f1c9a52-7d4e-4b8a-9c21-5e6f0a8b2d47 format: uuid realmId: type: string description: ID of the realm the policy belongs to. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b format: uuid organizationId: type: string description: ID of the organization the policy belongs to. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 format: uuid context: type: string enum: - PAYMENT - SPEND_REVIEW - TRAVEL description: >- What the policy governs. `PAYMENT`: a Pix payment, a boleto payment or a wallet transfer request, before it is paid. `SPEND_REVIEW`: the review of a transaction that already happened. `TRAVEL`: no travel flow evaluates policies yet. example: PAYMENT name: type: string description: Name of the policy, shown to approvers. example: Payments over R$ 5,000 description: type: string description: >- What the policy does, in plain words. Absent when none was written. example: >- Pagamentos acima de R$ 5.000,00 precisam da aprovação do time financeiro. order: type: number description: >- Evaluation order: active policies of the same `context` are tried from the lowest `order` up — the oldest first on a tie — and the first match decides. example: 10 status: type: string enum: - ACTIVE - DISABLED - ARCHIVED description: >- `ACTIVE`: evaluated. `DISABLED`: kept, never evaluated. `ARCHIVED`: archived for good — never evaluated, can no longer be changed. example: ACTIVE conditions: type: object properties: logic: type: string enum: - AND - OR description: >- How the results of `groups` combine: `AND` — every group must match; `OR` — one is enough. example: AND groups: type: array items: type: object properties: logic: type: string enum: - AND - OR description: >- How the group's `items` combine: `AND` — every item must match; `OR` — one is enough. example: AND dependsOn: type: array items: type: string description: >- Data loaded before the group is evaluated, for items that read it through `dynamicFieldValue`. Absent on most groups. items: type: array items: type: object properties: operator: type: string description: >- How `field` is compared with `value` — see the condition catalog for the operators each field accepts. example: GREATER_THAN field: type: string description: >- Dot path of the value tested, from the condition catalog of the policy's `context` (`TRAVEL` has none). example: amount maskType: type: string description: >- `CPF_CNPJ` or `PHONE`: both sides of the comparison are masked before it runs (an unformatted CPF/CNPJ, or a phone number's middle digits). Absent when nothing is masked. dynamicFieldValue: type: string description: >- Dot path of a value loaded at evaluation time, compared instead of `value`. Absent on most conditions. value: description: >- What `field` is compared with, typed as the catalog says — an amount in centavos, a `YYYY-MM-DD` date, an array for `INCLUDES`, criteria text for `LLM_EVALUATE`. Absent for the operators that take no value. example: 500000 required: - operator - field description: One condition. description: The group's conditions. required: - logic - items description: A group of conditions. description: >- The condition groups. Empty when the policy matches everything — an organization-wide default. required: - logic - groups description: When the policy matches. actions: type: object properties: hierarchy: type: boolean description: >- `true`: the `approvals` decide one at a time, in the order listed. `false`: all of them are asked at once. example: false autoAction: type: string enum: - APPROVE - DENY - NONE description: >- What happens when the policy matches. `APPROVE`: allowed right away. `DENY`: refused right away. `NONE`: an approval request is opened and `approvals` decide it. example: NONE moveBalance: type: object properties: addBalance: type: boolean description: >- `true`: when the policy approves — right away or through its approvers — the amount is first moved from the funding wallet (`fromAccountId` + `fromWalletId`) into the wallet the payment comes from (on a `SPEND_REVIEW` policy, the wallet of the reviewed transaction). Nothing moves for an incoming wallet transfer request, which credits the wallet itself, nor when the funding wallet is that wallet and the money would land in the same balance. example: true fromAccountId: type: string description: >- ID of the account that holds the funding wallet. Present when `addBalance` is `true`. example: 66f2a1c7b4d3e80012c9a0b4 fromWalletId: type: string description: >- ID of the funding wallet. Present when `addBalance` is `true`. example: 6710b8e4c9e77b0012a4d6f3 required: - addBalance description: >- Funding from another wallet of the organization once the payment is approved — money moves only when `addBalance` is `true`. Absent when not configured. approvals: type: array items: type: object properties: type: type: string enum: - USER - GROUP description: >- `USER`: one member of the organization. `GROUP`: a user group of the organization — the first member who decides, decides for the group. example: GROUP id: type: string description: ID of the user or of the group. example: 8b0e4c2a-1f6d-4e3b-a9c7-2d5f8e1b6c30 name: type: string description: >- Current name of the user or group. Absent when the approver can no longer be found. Read-only: remove it before sending the policy back on an update. example: Financeiro required: - id - type description: >- One approver of the policy, with the user's or group's current name. description: >- Who approves when `autoAction` is `NONE` — every entry must approve, and one refusal denies the request. Absent or empty for `APPROVE` and `DENY`. required: - autoAction - hierarchy description: What the policy does when it matches. createdAt: type: string description: When the policy was created. example: '2026-10-14T13:45:12.000Z' format: date-time updatedAt: type: string description: When the policy was last changed. example: '2026-11-03T18:02:40.000Z' format: date-time required: - actions - conditions - context - createdAt - id - name - order - organizationId - realmId - status - updatedAt description: A business policy of the organization. '403': description: >- `BUSINESS_POLICY_FORBIDDEN` — You are not an admin of the organization. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BUSINESS_POLICY_FORBIDDEN description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - RULE_ENGINE description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BUSINESS_POLICY_FORBIDDEN origin: RULE_ENGINE message: You do not have permission to manage business policies '422': description: >- `BAD_REQUEST` — A path parameter or the body is invalid — including a condition its context's catalog does not accept, or `approvals` that do not fit `autoAction`; `fields` lists each problem. `BUSINESS_POLICY_APPROVER_UNRESOLVABLE` — An approver, a user or wallet named in a condition, or the `moveBalance` funding wallet does not belong to the organization, is not active, or could not be verified; the message names it. `BUSINESS_POLICY_CUSTOM_FIELD_UNRESOLVABLE` — A condition's custom field is not an active custom field of the organization for that entity; the message names it. `BUSINESS_POLICY_CUSTOM_FIELD_CONDITION_INVALID` — A condition's operator or value does not fit its custom field's type or options; the message names the condition. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BAD_REQUEST - BUSINESS_POLICY_APPROVER_UNRESOLVABLE - BUSINESS_POLICY_CUSTOM_FIELD_UNRESOLVABLE - BUSINESS_POLICY_CUSTOM_FIELD_CONDITION_INVALID description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - RULE_ENGINE description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. fields: type: array description: >- One entry per invalid request field (validation errors only). items: type: object properties: field: type: string description: >- Path of the invalid field, e.g. `label` or `values[0].value`. example: label message: type: string description: Why the field was rejected. example: label is required code: type: string description: >- `_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`. example: LABEL_REQUIRED values: type: array items: type: string description: >- The accepted values, when the field is an enumeration. required: - field - message - code required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BAD_REQUEST origin: RULE_ENGINE message: >- Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields. fields: - field: context message: >- Invalid option: expected one of "PAYMENT"|"SPEND_REVIEW"|"TRAVEL" code: CONTEXT_ONE_OF values: - PAYMENT - SPEND_REVIEW - TRAVEL '503': description: >- `PARTICIPANT_CHECK_UNAVAILABLE` — The approvers, wallets or custom fields could not be checked in time. Nothing was saved; try again. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - PARTICIPANT_CHECK_UNAVAILABLE description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - RULE_ENGINE description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: PARTICIPANT_CHECK_UNAVAILABLE origin: RULE_ENGINE message: Could not verify the policy's participants — try again ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.