Skip to main content
POST
Create a business policy
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.

Path Parameters

realmId
string<uuid>
required

ID of your realm.

Format: UUID

organizationId
string<uuid>
required

ID of the organization the policy belongs to.

Format: UUID

Body

application/json
context
enum<string>
required

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.

Available options:
PAYMENT,
SPEND_REVIEW,
TRAVEL
Example:

"PAYMENT"

name
string
required

Name of the policy, shown to approvers.

Required string length: 1 - 120
Example:

"Payments over R$ 5,000"

actions
object
required

What the policy does when it matches.

conditions
object
required

When the policy matches.

description
string

What the policy does, in plain words. The generate description endpoint can write it for you.

Maximum string length: 500
Example:

"Pagamentos acima de R$ 5.000,00 precisam da aprovação do time financeiro."

order
integer

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.

Required range: x >= 0
Example:

10

status
enum<string>

ACTIVE policies are evaluated; DISABLED ones are kept but never evaluated. Defaults to ACTIVE. A policy is archived only through the archive endpoint.

Available options:
ACTIVE,
DISABLED
Example:

"ACTIVE"

Response

Successful response

A business policy of the organization.

id
string<uuid>
required

ID of the business policy.

Example:

"3f1c9a52-7d4e-4b8a-9c21-5e6f0a8b2d47"

realmId
string<uuid>
required

ID of the realm the policy belongs to.

Example:

"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"

organizationId
string<uuid>
required

ID of the organization the policy belongs to.

Example:

"c4bd3f21-dfbd-44e8-8055-68ba15bed410"

context
enum<string>
required

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.

Available options:
PAYMENT,
SPEND_REVIEW,
TRAVEL
Example:

"PAYMENT"

name
string
required

Name of the policy, shown to approvers.

Example:

"Payments over R$ 5,000"

order
number
required

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
enum<string>
required

ACTIVE: evaluated. DISABLED: kept, never evaluated. ARCHIVED: archived for good — never evaluated, can no longer be changed.

Available options:
ACTIVE,
DISABLED,
ARCHIVED
Example:

"ACTIVE"

conditions
object
required

When the policy matches.

actions
object
required

What the policy does when it matches.

createdAt
string<date-time>
required

When the policy was created.

Example:

"2026-10-14T13:45:12.000Z"

updatedAt
string<date-time>
required

When the policy was last changed.

Example:

"2026-11-03T18:02:40.000Z"

description
string

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."