Rules

Rules are workspace guidance the engine evaluates on every document. When a rule triggers, its score_delta moves risk_score, 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`, or `ADVISORY` (default)
`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 action field (approve / review / reject):

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 '{"pass_below": 40, "review_below": 80}'

Score below pass_below → approve. Below review_below → review. Otherwise → reject. 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.

Get started

Concepts

List rules

Create a rule

Update / disable / delete

Triggered rules on a check

Thresholds

Flag settings

​List rules

​Create a rule

​Update / disable / delete

​Triggered rules on a check

​Thresholds

​Flag settings

List rules

Create a rule

Update / disable / delete

Triggered rules on a check

Thresholds

Flag settings