Creating a rule from a policy

A compliance officer hands over a sentence: “decline card-not-present purchases above BRL 5,000 from a device we have not seen before.” This guide turns that sentence into a rule that evaluates the way the policy reads, rehearses it where it reaches nobody, and puts it live. What changes in your operation: the policy stops living in a ticket and starts living in an endpoint. The person who wrote the sentence can read the rule back, the rehearsal runs through real evaluation instead of a spreadsheet, and each change to the rule leaves an audit event behind it.

Who is this guide for? Risk and fraud analysts authoring rules, and the developers who wire the policy fields into the validation request. Steps 1 and 2 are about the policy; steps 3 to 8 are API calls.

Before you start

Tracer running and reachable, with an API key — see Getting started
The variables and the scope model — see Rules engine
A test account id you can send validations for, that no customer traffic uses
The policy sentence, written down, with whoever wrote it available for one question

All calls below send the API key as X-API-Key.

Step 1: Map the sentence onto fields

A rule reads what the validation request carries. Take the sentence apart clause by clause and put each one in the column it belongs to.

Clause in the policy	Where the value comes from	Reads as
”card … purchases”	`transactionType`, a Tracer enum	`CARD`
”above BRL 5,000”	`amount` and `currency` on the request	`amount`, `currency`
”card-not-present”	`subType`, free-form text your integration sets	`subType`
”a device we have not seen before”	, which your integration sets	`metadata.deviceFirstSeen`

The first two are fields Tracer defines. The last two are fields your integration has to send — Tracer has no opinion about what “card-not-present” or “new device” mean. That is the question to take back to whoever wrote the policy: which flag in our payload says the device is new?

subType reaches expressions in lower case, so "card_not_present" is the form to compare against. If your integration already uses subType for something else, carry the entry mode in metadata instead and match on that — both work the same way in an expression.

For the full variable list and the fields each context map carries, see Rules engine.

Step 2: Split the rule between scope and expression

Two things in that table — the transaction type and the account — are things Tracer can filter on before an expression runs. Those belong in the rule’s scopes. The value comparisons belong in the expression. Scope, which decides whether the rule is considered at all:

"scopes": [{ "transactionType": "CARD" }]

Expression, which decides whether the rule fires:

subType == "card_not_present" && amount > 5000 && metadata.deviceFirstSeen == true

Read the expression against the sentence: entry mode, threshold, and the device flag. amount > 5000 is strictly above, so a transaction of exactly 5000.00 does not fire it — check that against the policy before you go further, because “above” and “from” are different rules. A rule that reads a metadata key the request does not carry does not match, and the other rules still run. So the expression above needs no presence test for deviceFirstSeen; see Rules engine.

Do not repeat scope conditions inside the expression. transactionType == "CARD" in both places is not wrong, but it leaves two places to edit when the policy changes — and the expression is the one that needs a lifecycle round-trip to edit.

Step 3: Create the rule as a draft

POST /v1/rules creates the rule in DRAFT. A draft is not evaluated, so nothing you do here reaches traffic.

curl -X POST http://localhost:4020/v1/rules \
  -H "X-API-Key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deny CNP card purchases above BRL 5,000 from a new device",
    "description": "Compliance policy 2026-14, approved 2026-07-20",
    "expression": "subType == \"card_not_present\" && amount > 5000 && metadata.deviceFirstSeen == true",
    "action": "DENY",
    "scopes": [
      { "transactionType": "CARD", "accountId": "8a1f2c34-5d6e-4a7b-8c9d-0e1f2a3b4c5d" }
    ]
  }'

The accountId in that scope is your test account. It is what keeps Step 4 off customer traffic; Step 5 takes it out. A 201 answers with the stored rule:

{
  "ruleId": "4d9c2e70-8b1a-4f36-9c07-5e2a1b3d4f68",
  "name": "deny cnp card purchases above brl 5,000 from a new device",
  "description": "Compliance policy 2026-14, approved 2026-07-20",
  "expression": "subType == \"card_not_present\" && amount > 5000 && metadata.deviceFirstSeen == true",
  "action": "DENY",
  "scopes": [
    { "transactionType": "CARD", "accountId": "8a1f2c34-5d6e-4a7b-8c9d-0e1f2a3b4c5d" }
  ],
  "status": "DRAFT",
  "createdAt": "2026-07-31T11:04:12.318Z",
  "updatedAt": "2026-07-31T11:04:12.318Z"
}

Tracer stores the rule name in a normalized form, so the name it returns can differ from the string you sent. Take the ruleId from the response — that is the handle every call below uses. See Create a rule. The expression is compiled on this call, so an expression that cannot run never becomes a draft. A syntax error answers 0340, an expression that does not return a boolean answers 0341, and one whose estimated cost is above CEL_COST_LIMIT answers 0342.

Step 4: Rehearse it on an account nobody else uses

The scope you set is what keeps the rehearsal contained: the rule is considered only for transactions on that one test account, so activating it puts it in front of exactly the traffic you send it.

Activate the scoped rule

curl -X POST http://localhost:4020/v1/rules/4d9c2e70-8b1a-4f36-9c07-5e2a1b3d4f68/activate \
  -H "X-API-Key: your-secure-api-key"

The response comes back with status: "ACTIVE" and an activatedAt. See Activate a rule.

Send a transaction the policy should decline

TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)

curl -X POST http://localhost:4020/v1/validations \
  -H "X-API-Key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "c1a7f402-6b93-4d5e-8f10-2a4c6e8b0d31",
    "transactionType": "CARD",
    "subType": "card_not_present",
    "amount": "7500.00",
    "currency": "BRL",
    "transactionTimestamp": "'"$TS"'",
    "account": {
      "accountId": "8a1f2c34-5d6e-4a7b-8c9d-0e1f2a3b4c5d",
      "type": "checking",
      "status": "active"
    },
    "metadata": {
      "deviceFirstSeen": true
    }
  }'

See Validate a transaction.

Read the decision

{
  "validationId": "b7e3d190-4c25-4e8f-9a16-3d5f7b0c2e41",
  "requestId": "c1a7f402-6b93-4d5e-8f10-2a4c6e8b0d31",
  "decision": "DENY",
  "matchedRuleIds": ["4d9c2e70-8b1a-4f36-9c07-5e2a1b3d4f68"],
  "evaluatedRuleIds": ["4d9c2e70-8b1a-4f36-9c07-5e2a1b3d4f68"],
  "reason": "Rule matched with DENY action",
  "totalRulesLoaded": 1,
  "truncated": false,
  "limitUsageDetails": [],
  "processingTimeMs": 6.1,
  "evaluatedAt": "2026-07-31T11:09:44.207Z"
}

Your ruleId in matchedRuleIds is the rehearsal passing.

Send the cases that should not fire

Change one value at a time and repeat the call with a fresh requestId: "amount": "5000.00" for the boundary, "deviceFirstSeen": false for a known device, "subType": "purchase" for a card-present sale. Each should come back without your ruleId in matchedRuleIds.

Send a new requestId for every attempt. requestId is the idempotency key: repeat one and Tracer answers 200 with the decision it already recorded for that key, so the change you just made will look like it did nothing.

A rehearsal is a real validation. It stores a decision record and writes an audit event, and an ALLOW decision consumes the spending limits that cover that account. That is why the test account matters.

If your ruleId is not in matchedRuleIds, work through it in this order: is the rule ACTIVE (GET /v1/rules/{id}), does the transaction match the scope you set, and do the values you sent satisfy the expression.

Step 5: Put it live

Going live means one edit: drop the test account from the scope so the rule applies to the population the policy names.

Stop evaluating the rehearsal version

A scope edit does not require INACTIVE. Deactivating first makes the switch take effect at a moment you control and records a visible gap in the audit trail. Each instance serves rules from a cache it refreshes on a poll (every 10 seconds by default, RULE_SYNC_POLL_INTERVAL_SECONDS), so allow that window for the deactivation to reach every instance; GET /v1/rules confirms the stored status, not that every instance has caught up.

curl -X POST http://localhost:4020/v1/rules/4d9c2e70-8b1a-4f36-9c07-5e2a1b3d4f68/deactivate \
  -H "X-API-Key: your-secure-api-key"

Status goes to INACTIVE. See Deactivate a rule.

Replace the scope

curl -X PATCH http://localhost:4020/v1/rules/4d9c2e70-8b1a-4f36-9c07-5e2a1b3d4f68 \
  -H "X-API-Key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "scopes": [{ "transactionType": "CARD" }] }'

scopes replaces the whole array — send every scope object you want the rule to keep. See Update a rule.

Activate

curl -X POST http://localhost:4020/v1/rules/4d9c2e70-8b1a-4f36-9c07-5e2a1b3d4f68/activate \
  -H "X-API-Key: your-secure-api-key"

Activation reaches the instance that served this call as soon as it commits. When you run several instances behind a load balancer, the others pick the change up on their next rule sync (RULE_SYNC_POLL_INTERVAL_SECONDS, default 10). Deactivation travels the same way. Allow that same window after activation before you treat the rule as enforcing on every instance.

Confirm what is live

GET /v1/rules?status=ACTIVE&transaction_type=CARD&sort_by=updated_at
X-API-Key: {api_key}

The listing answers “what is enforcing on card traffic right now” — see List rules. For one rule, GET /v1/rules/{id} returns the expression and scopes as stored (Retrieve a rule). Both report the stored state, not what each instance’s cache holds.

A validation loads its rule set once, from the cache of the instance that serves it, when the call starts. A rule that activates while a validation is in flight is not part of that decision, and decisions already recorded do not change when rules change afterwards.

Step 6: Know where your rule sits among the others

Rules carry no priority field and no ordering to configure. Rules whose scope matches a transaction are evaluated together, and the decision comes from the strictest action that fired: a DENY rule first, then an exceeded spending limit, then REVIEW, then ALLOW, then the configured no-match default. matchedRuleIds carries every rule that matched, whatever action each one holds. Two consequences for the rule you just wrote:

An ALLOW rule does not exempt anyone from a DENY rule. If the policy has an exception — VIP customers, a partner merchant — the exception belongs inside the DENY expression, as one more condition that makes it narrower:
subType == "card_not_present" && amount > 5000 && metadata.deviceFirstSeen == true && metadata.customerTier != "vip"
Note what that costs: the narrowed rule now reads metadata.customerTier, and a request that does not carry that key does not match it.
Your rule joins the set every matching transaction evaluates. MAX_RULES_PER_REQUEST caps how many rules one validation evaluates; when the set is larger, the response reports truncated: true — see environment variables.

The precedence table and the reasoning behind it are on the Rules engine page.

Step 7: Change the rule when the policy changes

What you do depends on the field, not on how the rule is doing.

What changed	How
The threshold, the entry mode, the device flag — anything inside the expression	Deactivate, then `POST /v1/rules/{id}/draft`, then `PATCH` the expression, then activate
`DENY` becomes `REVIEW`	`PATCH /v1/rules/{id}` with the new `action`
Name, description, or scopes	`PATCH /v1/rules/{id}`

The expression accepts an edit only while the rule is DRAFT. Sending one to a rule in another status answers 422 with error code 0351 — deactivating is not enough on its own, because INACTIVE is not DRAFT. POST /v1/rules/{id}/draft is the step people miss; see Draft a rule.

A PATCH is stored when it answers, and reaches evaluation on the next rule sync. When the change matters to the minute, deactivate first and activate again after — that sequence also puts a visible gap in the audit trail where the rule was not enforcing, which is what a reviewer will look for. The lifecycle is a closed set of moves: DRAFT activates or is deleted; ACTIVE deactivates; INACTIVE goes back to DRAFT, back to ACTIVE, or is deleted; DELETED is the end. Anything else answers 422 with error code 0349 — including a request to draft a rule that is still ACTIVE.

Step 8: Retire or delete the rule

To stop enforcing without losing anything, deactivate. The rule keeps its expression, its scopes, and its history, stops being evaluated, and POST /v1/rules/{id}/activate brings it back. That is the move for a policy that is suspended, seasonal, or under review. To remove it, delete — and only after deactivating, because a rule in ACTIVE cannot be deleted:

DELETE /v1/rules/4d9c2e70-8b1a-4f36-9c07-5e2a1b3d4f68
X-API-Key: {api_key}

A 204 answers on success. See Delete a rule. What deleting removes:

The rule stops answering on GET /v1/rules/{id}, which returns 404 with error code 0347 afterwards.
It no longer appears in GET /v1/rules, and DELETED is not a value the status filter accepts.
DELETED is the end of the lifecycle. No endpoint moves a rule out of it — a deleted rule comes back only as a new rule you create again.

What deleting leaves behind:

The audit trail keeps the rule’s lifecycle, and the RULE_DELETED event carries the definition — name, description, expression, action, scopes — as it stood at deletion. See Audit and compliance.
Decisions the rule produced keep its ruleId in matchedRuleIds. A denial from six months ago still names it — see Reviewing a denied transaction.
The name becomes available again for a new rule in the same context.

Deactivate, then read the audit trail, then delete. Deactivating is reversible in one call and deleting is not reversible at all, so there is no reason to skip the intermediate state.

Common pitfalls

What usually goes wrong turning a policy into a rule:

“The rule is ACTIVE but nothing matches.” Check the field the policy leans on hardest. A rule reading metadata.deviceFirstSeen matches nothing if your integration never sends that key — the rule is correct and the payload is incomplete.
“It fired on a transaction the policy exempts.” An ALLOW rule does not override a DENY. Put the exemption inside the DENY expression (Step 6).
“My second rehearsal returned the first decision.” requestId is the idempotency key. Send a new UUID per attempt.
“PATCH rejected my expression with 422.” The rule was not in DRAFT. Move it there first (Step 7).
“The name I sent is not the name I get back.” Tracer stores names in a normalized form. Reference the rule by ruleId.

Error codes

Code	Status	What to change
`0340`	400	The expression does not parse as CEL
`0341`	400	The expression does not return a boolean — `amount > 5000`, not `amount`
`0342`	422	The expression’s estimated cost is above `CEL_COST_LIMIT`
`0347`	404	No rule has that `ruleId`, or it was deleted
`0349`	422	The lifecycle does not allow that move — for example deleting an `ACTIVE` rule
`0351`	422	An expression edit on a rule that is not `DRAFT`
`0353` / `0355` / `0357`	400	`name`, `expression`, or a valid `action` is missing
`0354` / `0356` / `0359`	400	`name` above 255, `expression` above 5000, or `description` above 1000 characters
`0358`	400	A scope object with no field set — omit `scopes` entirely for a global rule, never send `{}`
`0360`	400	More than 100 scope objects on one rule
`0441`	409	Another rule in the same context already holds that name
`0065`	400	The id in the path is not a UUID
`0082`	400	A filter on `GET /v1/rules` carries a value the endpoint does not accept

The complete list is in the Tracer error list.

Quick reference

Step	Method	Endpoint
Create as a draft	POST	`/v1/rules`
Start evaluating	POST	`/v1/rules/{id}/activate`
Rehearse or verify	POST	`/v1/validations`
Stop evaluating	POST	`/v1/rules/{id}/deactivate`
Reopen for editing	POST	`/v1/rules/{id}/draft`
Change fields	PATCH	`/v1/rules/{id}`
Read one rule	GET	`/v1/rules/{id}`
See what is live	GET	`/v1/rules`
Remove	DELETE	`/v1/rules/{id}`

Overview

Guides

Console

Operations

Creating a rule from a policy

Before you start

Step 1: Map the sentence onto fields

Step 2: Split the rule between scope and expression

Step 3: Create the rule as a draft

Step 4: Rehearse it on an account nobody else uses

Step 5: Put it live

Step 6: Know where your rule sits among the others

Step 7: Change the rule when the policy changes

Step 8: Retire or delete the rule

Common pitfalls

Error codes

Quick reference

​Before you start

​Step 1: Map the sentence onto fields

​Step 2: Split the rule between scope and expression

​Step 3: Create the rule as a draft

​Step 4: Rehearse it on an account nobody else uses

​Step 5: Put it live

​Step 6: Know where your rule sits among the others

​Step 7: Change the rule when the policy changes

​Step 8: Retire or delete the rule

​Common pitfalls

​Error codes

​Quick reference

Before you start

Step 1: Map the sentence onto fields

Step 2: Split the rule between scope and expression

Step 3: Create the rule as a draft

Step 4: Rehearse it on an account nobody else uses

Step 5: Put it live

Step 6: Know where your rule sits among the others

Step 7: Change the rule when the policy changes

Step 8: Retire or delete the rule

Common pitfalls

Error codes

Quick reference