Save a rule that changes how matching transactions read, tags included.

Save a rule that changes how matching transactions read, past and as new ones arrive: their category, label, cashflow role, review status, or tags. Tags group money the categories do not, such as a side business, a trip, or one person's costs; a goal measured as tagged reads their monthly net. The shorthand args cover the usual rule: name, a match (match_description_contains, which takes one text or a list of payees, or match_merchant_contains, narrowed by match_direction), one effect (set_category, set_label, set_cashflow_role, or add_tag), authority, and basis_reason. Give every payee that belongs as one list. The full body goes in input. rules.preview takes the same args or input before you save, and lists what the rule would reach; rules apply in the background.

post/v1/rules

Request

  • Base URL: https://api.candor.money
  • URL: https://api.candor.money/v1/rules
  • Auth: HTTP bearer

Headers

Idempotency-Keystring required

Stable opaque identity for one logical POST. Reuse only with the same method, path, actor, and body for transport retries. A completed receipt replays its original result, including a refusal; changed input with the same key is rejected. After a refused action and access recovery, use a new key for the new attempt. Follow retryable and recovery guidance if the operation is still running or its outcome is unknown.

Request body

namestring required

What this rule is for, in the user's terms. It appears when explaining why a transaction reads the way it does.

family'normalization' required

What the rule governs. Normalization is the only family today.

target'transaction_fields' required

What the rule changes.

authority'agent_verified' | 'user_approved' required

Where the rule's meaning came from. user_approved records that the user said so; agent_verified records that you established it from evidence and can show the basis.

prioritynumber
created_bystring

Response

Envelope with rule metadata, caveats, and suggested commands.

schema_versionstring required
generated_atstring date-time required
request_idstring required
status'success' | 'partial_success' | 'action_required' | 'error' required
user_messagestring

Optional concise user-safe message the calling agent may adapt.

warningsobject[] required
dataobject nullable required

Operation-specific result data, or null when the request ends in an error.

Changes

No recorded changes to this operation across all 1 revision of this API.