Rules

Guide the fraud engine with workspace rules, and set score cut lines for outcomes.

Rules are workspace guidance the engine evaluates on every document. When a rule triggers, its score_delta moves risk_score, a binding outcome_guidance floors or caps the score into the matching decision band, and the fired rule appears on the check under rules.

Reading rules needs view_documents; creating, editing, and deleting them needs manage_documents. See Permissions.

List rules

curl https://api.sphinxhq.com/api/v1/rules/ \
  -H "Authorization: Bearer $SPHINX_API_KEY"

Create a rule

curl https://api.sphinxhq.com/api/v1/rules/ \
  -H "Authorization: Bearer $SPHINX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Employer must match the application",
    "condition": "The employer on the payslip differs from the one on the application",
    "guidance": "Small spelling differences are fine; a different company is not",
    "outcome_guidance": "REJECTED",
    "score_delta": 25,
    "document_types": ["Payslip"]
  }'

Field	Required	Notes
title	yes	Short name
condition	yes	When the rule applies
guidance	no	How the engine should reason
outcome_guidance	no	ACCEPTED, REJECTED, PENDING, or ADVISORY (default). Binding when triggered: REJECTED floors into fraudulent, PENDING into pending, ACCEPTED caps in clear; ADVISORY is nudge-only via score_delta.
score_delta	no	-100 to 100. Added to risk_score when triggered
document_types	no	Limit to these types; omit to apply to all
status	no	active (default) or disabled

Update / disable / delete

• PATCH /api/v1/rules/{id}/ with any subset of fields (including status: "disabled")
• PUT /api/v1/rules/{id}/ replaces the full rule. Omitted optional fields reset to their defaults, so use PATCH unless you are sending the whole object
• DELETE /api/v1/rules/{id}/ soft-deletes the rule

Edits apply to documents analysed after the change. Checks already completed keep the rules and scores they were given.

Triggered rules on a check

Completed checks include a rules array of rules that fired:

{
  "rules": [
    {
      "id": "rule_01jq8x...",
      "title": "Employer must match the application",
      "outcome_guidance": "REJECTED",
      "score_delta": 25,
      "reasoning": "The payslip lists Acme Ltd; the application lists Beta Inc."
    }
  ]
}

Thresholds

Map risk_score to the check’s decision field (clear / pending / suspicious / fraudulent):

curl https://api.sphinxhq.com/api/v1/thresholds/ \
  -H "Authorization: Bearer $SPHINX_API_KEY"

curl https://api.sphinxhq.com/api/v1/thresholds/ \
  -X PATCH \
  -H "Authorization: Bearer $SPHINX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pending_below": 40, "suspicious_below": 60, "fraudulent_below": 80}'

Score below pending_below → clear. At or above each line → that decision. At or above fraudulent_below → fraudulent. Changes apply to new analyses only; each check snapshots the cut lines it used.

Flag settings

Ignore specific flag codes for this workspace. Ignored flags are omitted from new checks and do not contribute to risk_score. Existing checks are unchanged.

curl https://api.sphinxhq.com/api/v1/flag-settings/ \
  -H "Authorization: Bearer $SPHINX_API_KEY"

curl -X PATCH https://api.sphinxhq.com/api/v1/flag-settings/ \
  -H "Authorization: Bearer $SPHINX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"disabled_flag_codes": ["font_inconsistency", "scrubbed_metadata"]}'

Field	Notes
disabled_flag_codes	Full replace. Empty list re-enables every flag. Unknown codes are rejected.