Policies

Endpoints

Versions are immutable. Creating one never changes what /v1/decide does; activating one does, within about a minute, as cached copies expire. To roll back, create a new version with the old rules and activate it — activating a version older than the active one is a 409.

The rule set

{
  "slug": "default",
  "source": { "kind": "manual" },        // nl | manual | recommendation
  "default_action": "allow",             // used when no rule matches
  "rules": [
    {
      "id": "r_partners",                 // r_ + [a-z0-9_], unique in the version
      "label": "Partners are always allowed",
      "when": { "field": "email.domain", "op": "in_list", "list": "partners" },
      "then": { "action": "allow" },
      "on_unknown": "skip"
    },
    {
      "id": "r_no_disposable",
      "label": "No disposable addresses",
      "when": { "field": "verification.email_type", "op": "eq", "value": "disposable" },
      "then": { "action": "deny" },
      "on_unknown": "skip"
    },
    {
      "id": "r_agents",
      "label": "Agents go to the API-key flow",
      "when": { "field": "verification.actor_class", "op": "eq", "value": "agent_mailbox" },
      "then": { "action": "allow_with_flow", "flow": "agent" },
      "on_unknown": "skip"
    },
    {
      "id": "r_industry_fit",
      "label": "Review companies outside fintech and insurance",
      "when": { "field": "enrichment.company.industry", "op": "not_in", "value": ["fintech", "insurance"] },
      "then": { "action": "review", "tags": ["off_icp"] },
      "on_unknown": "skip"
    }
  ]
}

• then.action is one of allow, allow_with_flow, review, challenge, deny. flow is required with allow_with_flow and forbidden otherwise; it is lowercase letters, digits, - and _.
• on_unknown decides what happens when the rule cannot be evaluated because a field it reads is missing. skip (the default) falls through to the next rule; match treats missing as a match. A rule that denies on missing enrichment is accepted, with a warning that missing data will become lost signups.
• default_action defaults to allow. default_flow is required when it is allow_with_flow.
• requires — which enrichment fields, lists, attributes and whether ICP the rules read — is always computed by the server. A submitted one is ignored. It is what lets /v1/decide skip enrichment for a policy that never needs it.

Email types

verification.email_type is what kind of address it is: business, free, role, disposable, relay or unknown (definitions and precedence in email type). free is the consumer-provider class (Gmail, Outlook, Yahoo, Apple and the rest), the one people also call social, personal or consumer email.

The Email types card at the top of the dashboard’s Policy screen sets Allow, Review or Block for free (the row “Free / social email”), role, relay and disposable addresses (business is always allowed). It is not a separate engine: each setting is one rule with a reserved id in your default policy, placed before your own rules.

{ "id": "r_type_free", "label": "Free email providers",
  "when": { "field": "verification.email_type", "op": "eq", "value": "free" },
  "then": { "action": "deny" }, "on_unknown": "skip" }

• Block is a deny rule, Review a review rule, and Allow is no rule at all. An explicit allow at the top would let those addresses past every rule below it, which a switch labelled Allow must not do.
• The reserved ids are r_type_free, r_type_role, r_type_relay and r_type_disposable. A flip saves a new version that changes that one rule and activates it, with source: { kind: "manual", text: "Email types: free=block" }. You can write the same rules through the API; the card reads them back by id.
• Until your organisation has a default policy, the card shows disposable on Block and everything else on Allow, and the first switch you flip saves those settings as version 1. A policy that already existed without an r_type_disposable rule shows disposable on Allow, because that is what it does; the card never adds a rule you did not flip.
• The rules act in /v1/decide only. /v1/verify and /v1/check keep answering whether the address delivers, so a blocked free address still reads likely_valid there and carries email_type: "free" for you to act on.
• Your Blocklists run before any of this, in the verification itself: a blocked address or domain fails there, and an allowed one is never typed disposable. An allow does not exempt an address from the free, role or relay rules: an allowed Gmail address is still free.

The same card has a Describe a rule box that sends your sentence to compile with the active default version as the base, shows the diff, the compiler’s explanation and a replay, and saves nothing until you activate. The compiler is taught these sentences as worked examples, and they are part of the evaluation set its prompt has to pass:

“Gmail, yahoo and social emails” is read as the whole free class, so it also blocks outlook.com and icloud.com; the explanation says so. Name the domains (“only gmail.com and yahoo.com”) to block just those.

Predicates

{ "all": [...] }, { "any": [...] } and { "not": ... } combine leaves. Evaluation is three-valued: a leaf over a missing field is unknown, not false. all is a miss if any child misses, otherwise unknown if any child is unknown; any is a match if any child matches, otherwise unknown if any is unknown; not keeps unknown as unknown. The rule’s on_unknown only applies at the top.

Fields a rule may read

This is the whole vocabulary. The validator and the compiler reject anything else, including a value outside a field’s closed set: company.industry eq "finance" fails because finance is not an industry value. “Replayable” says whether the field is kept on the stored decision; the ones that are not are personal data, and replay evaluates them as unknown.

Attribute names match ^[a-z][a-z0-9_]{0,63}$. Reading an icp.* field is rejected while your account has no active ICP rubric.

Industry values

Every enrichment vendor’s industry label is mapped into this list; a label no mapping recognises becomes other and the vendor’s own text is kept in company.industry_raw for display. An absent industry is null (unknown), never other.

fintech, banking, insurance, investment_management, venture_capital, accounting, crypto_web3, real_estate, saas, software, developer_tools, artificial_intelligence, data_analytics, cybersecurity, it_services, internet, ecommerce, marketplaces, gaming, edtech, health_tech, hr_tech, martech, proptech, legal_tech, hardware, semiconductors, telecommunications, manufacturing, industrial_automation, automotive, aerospace_defense, construction, chemicals, mining_metals, energy, clean_energy, utilities, agriculture, logistics, transportation, travel, hospitality, retail, consumer_goods, food_beverage, sports_fitness, healthcare, pharmaceuticals, biotech, medical_devices, consulting, legal, marketing_advertising, staffing_recruiting, media, entertainment, publishing, education, government, nonprofit, other

POST /v1/policies/compile

English in, a candidate rule set out. Nothing is saved. A model is called exactly here, at authoring time, and never on a decision.

// request
{
  "text": "Don't allow temp emails. Anyone on the partners list is always allowed. Let AI agents in through the API-key flow.",
  "base": { "slug": "default", "version": 13 },   // optional: the version this text amends
  "slug": "default"                                 // optional
}

// 200
{
  "candidate": { /* a rule set, as above, unsaved */ },
  "explanation": [ { "rule_id": "r_partners", "says": "..." } ],
  "warnings": [ "..." ],
  "questions": [ { "id": "...", "question": "...", "options": ["..."], "default": "..." } ],
  "requires": { "enrichment": false, "enrichment_fields": [], "icp": false, "lists": ["partners"], "attributes": [] }
}

• The output is validated by the same code that validates a policy you write by hand. A field, list, value or action the schema does not know is rejected; the model cannot widen the vocabulary.
• When the text is ambiguous, questions is non-empty and the compiler asks rather than guesses. When it cannot produce a valid rule set at all, the answer is 422 compile_failed with the questions inside error.questions.
• The model sees your text, the rules of the base version when you are amending one, the field vocabularies, your list names, kinds and entry counts, and your ICP criterion ids. It never sees a list entry, an enrichment profile or a decision.
• Compile does not activate anything. Replay it, then save and activate it yourself.

POST /v1/policies/replay

Before you activate, run the candidate over your own recent decisions and see what would have changed.

{ "candidate": { /* rule set */ }, "window": { "last_n": 500 } }   // default 500, at most 2,000

Replay reads what each decision stored, which excludes personal fields (email.local_part, enrichment.person.title and the person’s name and LinkedIn URL). Rules over those fields replay as unknown. A list the candidate references but the stored decision did not is loaded as it is now. The cost estimate uses the per-lookup list prices recorded in the worker, which have not been confirmed against every vendor’s current rate card; read it as an order of magnitude.

Limits

Errors