Documentation ▸

API reference

Every endpoint, as the API describes itself. Each answer here is the one the API's own tests hold it to.

Himmel · 77 operations · https://api.gethimmel.com/v1

Checks

POST/v1/checkScope check

Check a transaction, or an action about to be taken

Returns exactly one of four states - determined, undetermined_missing_facts, not_covered, contested - with HTTP 200 for all four. Missing facts, an open recipient match and an unconfirmed rule are answers, never errors.

transaction.status says what the check is: proposed for an action about to be taken, executed for one taken. A key made for an agent says it, and leaving it out is refused (422 invalid-request, required); from your account's own keys, and signed in, it is executed when left out.

The check_id is the receipt: store it against whatever you then do, and GET /v1/checks/{id} reproduces this answer for the full retention window. The answer is stored before it is sent, so the check is there the moment you read it; if the connection drops before you do, send the same request again with the same Idempotency-Key and the stored answer comes back.

For an action a key made for an agent asks about, each person the answer names - a policy's approver, a question's signer - is asked by Himmel, and requests beside the answer says so: whom, when, and where each request stands (GET /v1/approvals/{id}). Ask about the same action again by naming it in transaction.completes with status: proposed: its answer reads what was decided on it, and nobody it names is asked again.

Himmel answers; the caller enforces. No endpoint blocks an action, and none takes one.

Parameters

Idempotency-Keyheader · string or null
Makes a retry safe: the same key with the same request within 24 hours gets the first answer again, and nothing is done twice. The same key with a different request is 409 idempotency-conflict. Keys are per environment and per path.

Request body · application/json

rule_setstringrequired
What to check against: a law set your account has switched on, or one of your own published policies. Either way every rule set of that domain that covers the transaction and that your account has on answers it: the law for the country it falls in, where your account has that law switched on, then your policies. With no law set among them, your policies are the whole answer, and it states no legal consequence.
rule_versionstring or null
The version you expect to answer. The version in force on the transaction's date answers, always: named, it must be that one, and another is refused (rule-version-not-in-force), naming the one in force.
jurisdictionstring or null
Where the transaction falls, as a code of two capital letters (DE, FR, EU), when it may not be the rule set's own. It decides which country's law answers. A transaction outside the rule set's jurisdictions is answered not_covered, and never counts toward that rule set's totals. Against a policy for several countries, or any, it is required wherever your account has law switched on for one of them.
transactionTransactionIn
10 fields
- refstring or null
  The caller's opaque reference, at most 200 characters. Never PII.
- channel"card" | "invoice" | "reimbursement" | "booking" | "agent"
- status"executed" | "proposed"
  executed is something that happened. proposed is an action the caller has not taken yet: checked identically, but out of history until the caller reports the outcome. Left out, it is executed - but a key made for an agent says which, and leaving it out is refused (required): nothing an agent sends is recorded as done because a field was left out.
- actorActorIn or null
  3 fields
  kind"user" | "agent" | "system"
  idstring or null
  The agent's own identifier - or, for a person (kind: user), their Himmel id: from your account's own keys a person of your account (unknown_user, left_the_account).
  on_behalf_ofstring or null
  The person the agent acts for, as your own systems identify them: an opaque id, never a name or an email address. They need no account here.
- provenancemap of string or null
  Opaque references the caller resolves in its own systems - a request reference, an approval it already holds - each name and reference at most 200 characters. Facts about where the instruction came from, never the agent's conclusion about what it means.
- runstring or null
  The run of an agent this action is part of - the task a person dispatched it to do: a conversation, a ticket, a batch - as your own systems identify it: an opaque reference of at most 200 characters, never an email address or an IBAN. Every action of one run names the same, and the check log lists them together (run=). A completion or a correction carries the action's.
- systemstring or null
  The system the action is taken in - the shop, the support desk, the ledger - by a short code your company picks: support_desk, finance. Lowercase letters, digits, _ and -, starting with a letter, at most 40 characters, and never none; anything else is refused (format). An action has one: named on its check, or where that named none by the first request after it that names one, it holds for every booking of the action, and another is refused (changed). No rule reads it: the check log finds by it (system=).
- executed_atstring or null
  When an action sent as taken (status: executed) was taken, a moment with its offset: it places the action in its day and gives it its own moment - an agent's runs, when it last acted. Any moment before the check, on the day the action is dated or a day either side, for time zones (not_its_day otherwise), and at most a minute after the check is received, for clocks that differ (after_it_was_sent). Left out, the moment the check is received. Refused on an action asked about before it is taken (not_taken); a completion or a correction keeps its action's, so it is left out or sent the same (changed).
- completesstring or null
  An action already taken whose missing facts this check sends, by the transaction_id its answers carry. The facts are that booking's with the ones sent added, and the complete booking stands in for it in every total; its answer replaces the one that stood. It is the same action: ref, channel, actor, provenance, jurisdiction, policies and when it happened are the booking's, and may be left out. A fact the booking recorded a value for is left out or sent the same (changed otherwise); one left out or recorded as null may be given. Sent with status: proposed, an action still being asked about, asked about again: the booking that stands for it, its answer reading what was decided on the action.
- correctsstring or null
  An action already taken whose facts were sent wrong, by the transaction_id its answers carry: this check's facts are that booking's with the ones sent in their place, and the corrected booking stands in for it in every total; its answer replaces the one that stood, and a decision made on that one is asked again. It is the same action - ref, channel, actor, jurisdiction, policies and when it happened are the booking's (changed otherwise: an action that was another thing is taken back and sent again). One or the other of completes and corrects.
factsobject
The facts the rule set takes, by name, as the catalogue lists them. An amount is {"amount": <minor units>, "currency": "<ISO 4217>"}; one in another currency than the rule set's carries equivalents, what your own systems record it as in the rule set's currency, which is what the rules read - without it, the answer asks for it. A key made for an agent never sends a person, nor the figure an approval was given for: Himmel holds them for the agent, and one sent with a value is refused (not_the_keys).
policieslist of string or null
Which of your published policies for the domain answer beside the law: left out, all of them; [], none. A policy named as rule_set always answers.
explainboolean

Examples

determined: With every rule confirmed, the same booking is answered.

{
  "rule_set": "de_gifts_entertainment",
  "transaction": {
    "channel": "agent",
    "status": "executed"
  },
  "facts": {
    "booking_date": "2023-03-14",
    "account": "4630",
    "recipient": "r1",
    "amount_net": {
      "amount": 2000,
      "currency": "EUR"
    },
    "amount_gross": {
      "amount": 2380,
      "currency": "EUR"
    }
  }
}

undetermined_missing_facts: Where nothing is recorded about the occasion, the answer is that we cannot tell — not that it is missing.

{
  "rule_set": "de_gifts_entertainment",
  "transaction": {
    "channel": "agent",
    "status": "executed"
  },
  "facts": {
    "booking_date": "2023-03-14",
    "account": "4650",
    "participants": [
      "r1",
      "r2"
    ],
    "participants_recorded": true,
    "restaurant": true,
    "invoice_attached": true,
    "amount_net": {
      "amount": 9500,
      "currency": "EUR"
    },
    "amount_gross": {
      "amount": 11305,
      "currency": "EUR"
    }
  }
}

not_covered: Until your rule owner confirms the rules, a check comes back saying so rather than answering.

{
  "rule_set": "de_gifts_entertainment",
  "transaction": {
    "channel": "agent",
    "status": "executed"
  },
  "facts": {
    "booking_date": "2023-03-14",
    "account": "4630",
    "recipient": "r1",
    "amount_net": {
      "amount": 2000,
      "currency": "EUR"
    },
    "amount_gross": {
      "amount": 2380,
      "currency": "EUR"
    }
  }
}

contested: €250 a head is above the €100 you set for sign-off, so a named person confirms it was appropriate.

{
  "rule_set": "de_gifts_entertainment",
  "transaction": {
    "channel": "agent",
    "status": "executed"
  },
  "facts": {
    "booking_date": "2023-03-14",
    "account": "4650",
    "participants": [
      "r1",
      "r2"
    ],
    "participants_recorded": true,
    "occasion_recorded": true,
    "restaurant": true,
    "invoice_attached": true,
    "amount_net": {
      "amount": 50000,
      "currency": "EUR"
    },
    "amount_gross": {
      "amount": 59500,
      "currency": "EUR"
    }
  }
}

Responses

200 One of the four states, always with HTTP 200.

One of 4, told apart by state.

effective_datestringrequired
The date the rules were applied as of.
as_ofstringrequired
The moment the history was read.
layersLayersrequired
2 fields
- lawLayerAnswer or null
  The law's answer. Left out where no law set is part of the answer - your policy's alone, for a country we hold no law for or one your account has not switched on.
  12 fields
  rule_setstringrequired
  rule_versionstringrequired
  state"determined" | "undetermined_missing_facts" | "not_covered" | "contested"required
  outcomestring or null
  basisstring or null
  law, policy or goodwill.
  consequenceslist of Consequence or null
  5 fields
  keystringrequired
  valueanyrequired
  Money as minor units and currency, or a number, a flag or a date.
  rulestringrequired
  basisstring or null
  law, policy or goodwill.
  citationCitation or null
  not_checkedlist of NotChecked or null
  2 fields
  topicstringrequired
  reasonstringrequired
  approverany
  Who a policy says must approve, where it names one.
  handed_toany
  Whom a policy hands the action to, where its rule names one: a person in your account, by Himmel id. Where an agent asked about the action, Himmel tells them (check.handed_over).
  tenant_facts_usedlist of string or null
  Your settings this answer read.
  reference_versionsmap of integer | string or null
  Which version of each reference table it read, such as dated VAT rates.
  waiting_onstring or null
  A policy rule that reads the law's answer waits for the law to settle: law.
- policieslist of LayerAnswer or null
  Your policies for this domain, in the order they ran.
  12 fields
  rule_setstringrequired
  rule_versionstringrequired
  state"determined" | "undetermined_missing_facts" | "not_covered" | "contested"required
  outcomestring or null
  basisstring or null
  law, policy or goodwill.
  consequenceslist of Consequence or null
  5 fields
  keystringrequired
  valueanyrequired
  Money as minor units and currency, or a number, a flag or a date.
  rulestringrequired
  basisstring or null
  law, policy or goodwill.
  citationCitation or null
  not_checkedlist of NotChecked or null
  2 fields
  topicstringrequired
  reasonstringrequired
  approverany
  Who a policy says must approve, where it names one.
  handed_toany
  Whom a policy hands the action to, where its rule names one: a person in your account, by Himmel id. Where an agent asked about the action, Himmel tells them (check.handed_over).
  tenant_facts_usedlist of string or null
  Your settings this answer read.
  reference_versionsmap of integer | string or null
  Which version of each reference table it read, such as dated VAT rates.
  waiting_onstring or null
  A policy rule that reads the law's answer waits for the law to settle: law.
engine_versionstringrequired
check_idstringrequired
The receipt. GET /v1/checks/{id} gives this answer back.
transactionTransactionSummaryrequired
9 fields
- transaction_idstringrequired
- status"executed" | "proposed"required
  proposed stays out of every total until you report that it executed.
- channel"card" | "invoice" | "reimbursement" | "booking" | "agent"required
- refstring or null
  Your own reference, as you sent it.
- runstring or null
  The run of an agent the action is part of, as your systems identify it.
- systemstring or null
  The system the action is taken in, by your company's code for it.
- actorActor or null
  3 fields
  kind"user" | "agent" | "system"required
  idstring or null
  on_behalf_ofstring or null
  The person an agent acted for.
- completesstring or null
  The booking whose missing facts this check sent, where it completed one: the same action, which this booking stands in for in every total.
- correctsstring or null
  The booking whose facts sent wrong this check corrected, where it corrected one: the same action, as it should have been, which this booking stands in for in every total.
created_atstringrequired
recipientRecipientSummary or null
4 fields
- resolutionstringrequired
  resolved, unresolved, probable_match or missing.
- recipient_idstring or null
- review_itemstring or null
  The open probable match, where there is one.
- fy_totalMoney or null
  This recipient's total for the fiscal year, where the answer's first rule set totals money per recipient per fiscal year: the recipient's other bookings of the year that it counts, as known when the answer was given - this one not included, and later ones too where it counts the whole year. Left out where no such total was read; history_used names every total an answer read.
  2 fields
  amountintegerrequired
  currencystringrequired
history_usedlist of HistoryInput or null
5 fields
- rule_setstringrequired
- inputstringrequired
  The rule set's name for this total, such as recipient_fy_gifts.
- countintegerrequired
- transactionslist of HistoryTransactionrequired
  2 fields
  transaction_idstringrequired
  effective_datestring or null
- totalMoney | integer | string or null
not_checkedlist of NotChecked or null
2 fields
- topicstringrequired
- reasonstringrequired
citationslist of Citation or null
4 fields
- sourcestringrequired
  The source's key within the rule set, such as estg.
- paragraphstring or null
- clausestring or null
- text_refstring or null
  The passage in the rule set's own copy of the source, sources/<file>#<anchor>.
confirmationslist of ConfirmationUsed or null
3 fields
- rulestringrequired
- confirmed_bystring or null
- confirmed_atstring or null
decisionslist of DecisionRead or null
Each question on this action a person decided, read as its answer: where the question's rule says what each answer leads to, a sign-off or an admin's override issues the action's answer again, and every answer to it after reads the decision while the rule asks the very same question. Left out where none was read.
8 fields
- answerstringrequired
  The answer chosen, one of the question's candidates - or approved, for an approval.
- questionstring or null
  The question's id. Null for an approval, which answers none.
- rulestring or null
  The rule that raises the question, as it asks it. Null for an approval.
- decided_bystring or null
  Who decided: a person in your account, by id.
- method"sign_off" | "override" | "approval" or null
  A sign-off by the person the question names, an admin's override of it, or the approval of the person the action's answer named, asked by Himmel.
- resolution_idstring or null
  The decision's record, on the answer it was made on.
- leads_tostring or null
  What the answer led to: continue - on to the rules after the question, which gave the outcome - or the outcome it gives itself. Null for an approval, read from the first rule.
- approvalstring or null
  The fact the decision stood in for as its decider's approval - where the action recorded none, and the rule that gave the outcome read it - so one person who decides and approves is asked once. Null otherwise.
recheckslist of Recheck or null
The earlier answers this booking changed, each issued again before this one was given. Left out when it changed none, and on a proposal, which changes nothing until it is reported as executed.
4 fields
- new_check_idstring or null
- supersedesstring or null
- booking_datestring or null
- outcomestring or null
supersedes_check_idstring or null
The earlier answer for the same transaction that this one replaces.
recheck_reasonstring or null
Why it was issued again: a later transaction, an action taken back (reversal) or corrected (correction), a link or split between recipients, a question raised about its recipient, the rules changing, a question on it decided (decision), or the action approved by the person its answer named (approval).
tracelist of TraceStep or null
Every rule reached, in order. Left out when the check asked explain: false.
6 fields
- rulestringrequired
- stagestringrequired
  scope, outcome or consequence.
- matchedboolean or null
- resolveinteger or null
  Which of the rule's branches applied.
- missinglist of string or null
- notestring or null
sandboxtrue or null
true on an answer given in test. A live answer has no such field.
superseded_bystring or null
The newer answer for the same transaction, when there is one.
resolutionResolution or null
The latest decision your people recorded on it: a sign-off, an override, an approval or a refusal.
6 fields
- resolved_outcomestringrequired
  One of the question's answers, or of the outcomes its rule set declares - or for an approval Himmel asked for, approved or refused.
- resolved_bystringrequired
- method"sign_off" | "override" | "approval"required
  A sign-off by the person a question names, an admin's override, or the approval or refusal of the person Himmel asked (POST /v1/approvals/{id}/approve).
- created_atstringrequired
  When it was decided.
- note_refstring or null
- given_onstring or null
  Where the decision was carried over from an earlier answer that asked the very same question: the answer it was given on. Left out for a decision given on this answer.
resolutionslist of Resolution or null
Every decision recorded on it - sign-offs, overrides, approvals and refusals - in the order recorded: an override leaves the sign-off before it on record. Left out where there is none.
6 fields
- resolved_outcomestringrequired
  One of the question's answers, or of the outcomes its rule set declares - or for an approval Himmel asked for, approved or refused.
- resolved_bystringrequired
- method"sign_off" | "override" | "approval"required
  A sign-off by the person a question names, an admin's override, or the approval or refusal of the person Himmel asked (POST /v1/approvals/{id}/approve).
- created_atstringrequired
  When it was decided.
- note_refstring or null
- given_onstring or null
  Where the decision was carried over from an earlier answer that asked the very same question: the answer it was given on. Left out for a decision given on this answer.
factsobject or null
The facts the booking was sent with, as stored: a recipient by the id it resolved to when it was sent, never a name, and everything else as sent - from a key made for an agent, a person and an approval's figure as Himmel holds them. The booking's, so every answer to it shows the same; the answer's own recipient says which identity that answer used. Read back beside the answer, never part of it.
sent_bySender or null
Who sent the check: a key, or a person signed in - beside who acted, in transaction.actor. Empty on an answer Himmel issued again, which nobody asked for (recheck_reason says why), and on one a person sent before this was kept. Read back beside the stored answer, never part of it; the answer a check returns when it is made does not carry it.
4 fields
- kind"api_key" | "person"required
- idstringrequired
  The key's id, or the person's user id.
- prefixstring or null
  A key's prefix, hk_live_7f3a: what your keys show, never the key itself.
- namestring or null
  The name the key was given, where it was given one.
executionExecution or null
For an action asked about before it was taken: what became of it, and who reported it. The answer itself still says proposed, which is what was answered.
7 fields
- status"proposed" | "executed" | "abandoned" | "expired"required
  proposed until its caller reports; executed, or abandoned when reported not taken; expired when nobody reported within 24 hours. An action taken back since reads executed, as its report said: reversal says the rest.
- executed_atstring or null
  When it was taken, as reported.
- reasonstring or null
  Why it was not taken: abandoned, refused_by_caller, failed or expired.
- refstring or null
  Your own reference for the action taken, as its report sent it - kept beside the action's own transaction.ref, never over it. Empty where the report sent none.
- systemstring or null
  The system the action is taken in, as its check or its report named it. Empty where neither did.
- reported_bySender or null
  Who reported it. Empty until somebody does, and for one that expired.
  4 fields
  kind"api_key" | "person"required
  idstringrequired
  The key's id, or the person's user id.
  prefixstring or null
  A key's prefix, hk_live_7f3a: what your keys show, never the key itself.
  namestring or null
  The name the key was given, where it was given one.
- reported_atstring or null
reversalReversal or null
For an action taken back after it was taken, on every answer to it: when, your reference for it, and who reported it. It counts toward nothing from then; the answer itself stays as it was given.
4 fields
- reversed_atstringrequired
  When it was taken back, as reported.
- refstring or null
  Your own reference for taking it back, where you sent one.
- reported_bySender or null
  Who reported it: a key, or a person.
  4 fields
  kind"api_key" | "person"required
  idstringrequired
  The key's id, or the person's user id.
  prefixstring or null
  A key's prefix, hk_live_7f3a: what your keys show, never the key itself.
  namestring or null
  The name the key was given, where it was given one.
- reported_atstring or null
requestslist of AskedOfAPerson or null
Whom Himmel asked about this action, as each request stands now - for an action a key made for an agent asked about, each person an answer to it names: a policy's approver, a question's signer. Beside the answer, never part of it. Left out where nobody was asked.
11 fields
- idstringrequired
  The request, apr_…: GET /v1/approvals/{id}.
- asked_ofstringrequired
  The person asked: a person in your account, by Himmel id.
- asked_atstringrequired
  When Himmel asked them.
- asks"approval" | "question"required
  What they are asked: their approval of the action, which a policy of yours asks of them - or their answer to the answer's question, which a sign-off gives.
- status"waiting" | "approved" | "refused" | "decided" | "lapsed"required
  waiting for them, a week at most; approved or refused by them; decided by a sign-off or an admin's override; lapsed, reason saying why.
- waits_untilstringrequired
  Until when it waits for its person: a week after it was asked, the proposal held open until then. One still waiting then lapses, no_answer, and a decision after it is 409 nothing-to-decide.
- decided_bystring or null
  Who decided it, by Himmel id: the person asked, or the admin who overruled.
- resolution_idstring or null
  The decision that answered it, on the answer it was recorded on.
- closed_atstring or null
  When it stopped waiting.
- reasonstring or null
  Why it lapsed: the action executed, abandoned or expired; no_answer in a week; no_longer_asked, an answer issued again naming them no more; refused, another person refusing the action.
- emailed_atstring or null
  When Himmel emailed them, linking the request's page in the console: within a minute of the request, in your account's own environment. Null until then, and where it never goes - a request made in test in an account with a live side, one that stopped waiting first, a person with no address, or one whose mail server refused their address.

state: "determined"

The facts, under these rule versions, as of this date, give this outcome.

state: "undetermined_missing_facts"

A rule covers this, and needs facts it did not get. missing names them.

missinglist of MissingFactrequired
7 fields
- factstringrequired
- typestring or null
- currencystring or null
  For an amount, the currency it is wanted in: the rule set's. Send it there, or - for an amount in another currency - beside it, as what your own systems record it as in this one (equivalents).
- descriptionstring or null
- needed_bystring or null
  The rule that needed it.
- review_itemstring or null
  For recipient_identity: the probable match to answer first.
- ofHistoryTransaction or null
  Where the fact is another action's: a booking a total counts and cannot read, by its id and its date. Send the fact by completing that booking (transaction.completes), not in this check.
  2 fields
  transaction_idstringrequired
  effective_datestring or null

state: "not_covered"

No confirmed rule covers this: your policy does not say, or a rule awaits confirmation.

reason"awaiting_confirmation" | "rule_flagged" | "policy_gap" | "no_rule_matched" | "no_rule_set_for_jurisdiction" | "rule_set_broken"required
detailstring or null
unconfirmed_ruleslist of string or null

state: "contested"

A rule covers this, and turns on a word it cannot apply mechanically. A named person decides.

questionQuestionrequired
5 fields
- idstringrequired
- candidateslist of stringrequired
- reasonstringrequired
  Why this one cannot be settled by the rule.
- rulestringrequired
- wordingstring or null
  The rule's wording, as your rule owner confirmed it.
signerSigner or null
1 field
- useranyrequired
  The person who signs off, as your settings name them.

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
409The request conflicts with what is stored: see detail.
413The request's body is larger than the operation takes, refused before any of it is read (body-too-large): a policy's files at most 5 MB, any other body 1 MB - and an uploaded file at most 20 MB (file-too-large).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

POST/v1/checks/{check_id}/executionScope checks:write

What happened to a proposal

Report whether a proposed action was taken, on any answer to it - the one you kept from your first asking included, where you asked about it again. On executed: true the transaction joins history at that moment, and any earlier answer whose totals it moves is issued again with a check.rechecked alert. The action itself is answered again as it stands once taken: where a booking joined its totals, or rules or settings were confirmed, while it was asked about and it comes out otherwise, the new answer replaces the one given, and superseded_by names it; a change your rule owner has not confirmed yet never takes an answer away. On executed: false it is closed and never counts. A proposal with no report within 24 hours of its latest asking is closed as expired, unless a person Himmel asked about it holds it; a report after that is refused. Reporting the same outcome twice is answered the same way twice. ref is your own opaque reference for the action taken, kept beside the action's own transaction.ref and never over it: one that looks like an email address or an IBAN is refused with pii-in-facts. system is where the action was taken: the action's, or where it has none, named for it. A key made for an agent reports on its agent's own actions: on any other it gets 403 not-the-agents-action.

Parameters

check_idpath · stringrequired
Idempotency-Keyheader · string or null
Makes a retry safe: the same key with the same request within 24 hours gets the first answer again, and nothing is done twice. The same key with a different request is 409 idempotency-conflict. Keys are per environment and per path.

Request body · application/json

executedbooleanrequired
refstring or null
Your own reference for the action taken - a credit note's number - opaque and at most 200 characters: one that looks like an email address or an IBAN is refused (pii-in-facts). Kept beside the action's own transaction.ref, never over it, as execution.ref; the check log finds the action by either.
systemstring or null
The system the action was taken in, as on the check (transaction.system): where the action has one, the same or left out - another is refused (changed) - and where it has none, named for the whole action by the first report.
executed_atstring or null
When the action was done, a moment with its offset: it places the action in its day. Between when it was asked about and this report, a minute either side for clocks that differ; else invalid-request. Left out, the moment of the report.
reason"abandoned" | "refused_by_caller" | "failed" or null

Responses

200 Successful response

check_idstringrequired
transaction_idstringrequired
status"executed" | "abandoned" | "expired"required
reasonstring or null
executed_atstring or null
refstring or null
The reference kept for the action taken, beside the action's own - on a repeat, the first report's. Empty where none was sent, and for an action not taken.
systemstring or null
The system the action is recorded as taken in now; empty where none was named.
recheck_jobstring or null
The job re-checking earlier answers this execution moves.
superseded_bystring or null
The answer that replaced the one reported on, as GET /v1/checks/{id} reads it: where the action, answered again as it stood once taken, came out otherwise - a booking joined its totals, or rules or settings were confirmed, while it was asked about. Empty where the answer stands as it was given.

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
409The request conflicts with what is stored: see detail.
413The request's body is larger than the operation takes, refused before any of it is read (body-too-large): a policy's files at most 5 MB, any other body 1 MB - and an uploaded file at most 20 MB (file-too-large).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

POST/v1/checks/{check_id}/reversalScope checks:write

An action taken back

Report that an action taken was taken back afterwards - a credit given by mistake and clawed back, a refund whose payment failed. It counts toward nothing from then: every total it was in is worked out again without it, and each earlier answer that moves is issued again, with a check.rechecked alert where its state or outcome changed - those of actions that came while it stood included. Its own answers stay as they were given. Send it on any answer the action has: the check id you kept, or a later one. Take an action back this way, never by booking its negative, which counts as an action of its own. An action still being asked about is reported taken or not instead (/execution). Reporting it twice the same way is answered the same way twice. A key made for an agent takes back its agent's own actions: on any other it gets 403 not-the-agents-action.

Parameters

check_idpath · stringrequired
Idempotency-Keyheader · string or null
Makes a retry safe: the same key with the same request within 24 hours gets the first answer again, and nothing is done twice. The same key with a different request is 409 idempotency-conflict. Keys are per environment and per path.

Request body · application/json

reversed_atstring or null
When it was taken back: a moment with its offset, or a day. Left out, the moment the report is received.
refstring or null
Your own reference for taking it back, opaque and at most 200 characters: one that looks like an email address or an IBAN is refused (pii-in-facts).

Responses

200 Successful response

check_idstringrequired
transaction_idstringrequired
The booking taken back: the one that stood for the action.
status"reversed"required
reversed_atstringrequired
refstring or null
recheck_jobstring or null
The job issuing again the answers it counted in; empty on a repeat of the same report, which queues nothing.

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
409The request conflicts with what is stored: see detail.
413The request's body is larger than the operation takes, refused before any of it is read (body-too-large): a policy's files at most 5 MB, any other body 1 MB - and an uploaded file at most 20 MB (file-too-large).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

POST/v1/checks/{check_id}/resolutionScope checks:write

A sign-off, or an override

Record what your people decided. A sign-off decides a contested answer's question: only the person it names as signer gives one, choosing one of the question's candidates. An override is an admin overruling a determined answer, choosing one of the outcomes its rule set declares, or a contested one, choosing one of its question's answers. A decision is made on the answer that stands, for an action taken or still open. Where the question's rule says what each answer leads to, a decision on it issues the action's answer again in this request - the rules after the question answering too, the person who decided counting as approving it where the rules ask their approval next - and superseded_by names it; every answer the action is given after reads the decision while its rule asks the very same question. The answer decided on is never changed: the resolution is kept beside it. Supplying missing facts is a new check, not a resolution.

Needs a key with the scope checks:write. It records what a person decided, so a key made for an agent, which names nobody but itself, gets 403 cannot-decide.

Parameters

check_idpath · stringrequired
Idempotency-Keyheader · string or null
Makes a retry safe: the same key with the same request within 24 hours gets the first answer again, and nothing is done twice. The same key with a different request is 409 idempotency-conflict. Keys are per environment and per path.

Request body · application/json

resolved_outcomestringrequired
method"sign_off" | "override"required
resolved_bystring or null
Who did it, when your key acts for a person: their Himmel id, which the console's Developers page shows them, and Settings' People an admin. They must be in your account, with a role that could do this themselves, and the record keeps it as your key's claim. A key made for an agent names nobody but itself: leave it out. Signed in to the console, leave it out: it is you. Required from the account's own keys; a key made for an agent records no decision. For a contested check, the person its signer names.
note_refstring or null
Your own reference to the note behind the decision, opaque and at most 200 characters: one that looks like an email address or an IBAN is refused (pii-in-facts).

Responses

200 Successful response

resolution_idstringrequired
check_idstringrequired
resolved_outcomestringrequired
method"sign_off" | "override"required
superseded_bystring or null
The answer the decision issued for the action, which replaces the one decided on: where the question's rule says what each answer leads to, the decision is read as its answer and the rules after it answer too. Null where the answer stands as it was - a question that says nothing of its answers, or a change still waiting for your rule owner, which issues it once confirmed.

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
409The request conflicts with what is stored: see detail.
413The request's body is larger than the operation takes, refused before any of it is read (body-too-large): a policy's files at most 5 MB, any other body 1 MB - and an uploaded file at most 20 MB (file-too-large).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

GET/v1/checks/{check_id}Scope checks:read

One stored answer, exactly as it was given

The answer as it was stored when it was given, for the whole retention period, with superseded_by when a later answer replaced it, and resolutions, every sign-off or override your people recorded, resolution the latest; facts, what the booking was sent with, a recipient by its id; sent_by, who sent the check - a key or a person signed in, beside who acted - and, for an action asked about before it was taken, execution: what became of it, and who reported it; for an action taken back, on every answer to it, reversal: when, and who reported it; and requests, whom Himmel asked about the action, as each request stands now.

Needs a key with the scope checks:read. From a key made for an agent it reads that agent's own alone: another agent's action is 403 not-the-agents-action, another agent's record 403 insufficient-scope.

Parameters

check_idpath · stringrequired

Responses

200 Successful response

One of 4, told apart by state.

effective_datestringrequired
The date the rules were applied as of.
as_ofstringrequired
The moment the history was read.
layersLayersrequired
2 fields
- lawLayerAnswer or null
  The law's answer. Left out where no law set is part of the answer - your policy's alone, for a country we hold no law for or one your account has not switched on.
  12 fields
  rule_setstringrequired
  rule_versionstringrequired
  state"determined" | "undetermined_missing_facts" | "not_covered" | "contested"required
  outcomestring or null
  basisstring or null
  law, policy or goodwill.
  consequenceslist of Consequence or null
  5 fields
  keystringrequired
  valueanyrequired
  Money as minor units and currency, or a number, a flag or a date.
  rulestringrequired
  basisstring or null
  law, policy or goodwill.
  citationCitation or null
  not_checkedlist of NotChecked or null
  2 fields
  topicstringrequired
  reasonstringrequired
  approverany
  Who a policy says must approve, where it names one.
  handed_toany
  Whom a policy hands the action to, where its rule names one: a person in your account, by Himmel id. Where an agent asked about the action, Himmel tells them (check.handed_over).
  tenant_facts_usedlist of string or null
  Your settings this answer read.
  reference_versionsmap of integer | string or null
  Which version of each reference table it read, such as dated VAT rates.
  waiting_onstring or null
  A policy rule that reads the law's answer waits for the law to settle: law.
- policieslist of LayerAnswer or null
  Your policies for this domain, in the order they ran.
  12 fields
  rule_setstringrequired
  rule_versionstringrequired
  state"determined" | "undetermined_missing_facts" | "not_covered" | "contested"required
  outcomestring or null
  basisstring or null
  law, policy or goodwill.
  consequenceslist of Consequence or null
  5 fields
  keystringrequired
  valueanyrequired
  Money as minor units and currency, or a number, a flag or a date.
  rulestringrequired
  basisstring or null
  law, policy or goodwill.
  citationCitation or null
  not_checkedlist of NotChecked or null
  2 fields
  topicstringrequired
  reasonstringrequired
  approverany
  Who a policy says must approve, where it names one.
  handed_toany
  Whom a policy hands the action to, where its rule names one: a person in your account, by Himmel id. Where an agent asked about the action, Himmel tells them (check.handed_over).
  tenant_facts_usedlist of string or null
  Your settings this answer read.
  reference_versionsmap of integer | string or null
  Which version of each reference table it read, such as dated VAT rates.
  waiting_onstring or null
  A policy rule that reads the law's answer waits for the law to settle: law.
engine_versionstringrequired
check_idstringrequired
The receipt. GET /v1/checks/{id} gives this answer back.
transactionTransactionSummaryrequired
9 fields
- transaction_idstringrequired
- status"executed" | "proposed"required
  proposed stays out of every total until you report that it executed.
- channel"card" | "invoice" | "reimbursement" | "booking" | "agent"required
- refstring or null
  Your own reference, as you sent it.
- runstring or null
  The run of an agent the action is part of, as your systems identify it.
- systemstring or null
  The system the action is taken in, by your company's code for it.
- actorActor or null
  3 fields
  kind"user" | "agent" | "system"required
  idstring or null
  on_behalf_ofstring or null
  The person an agent acted for.
- completesstring or null
  The booking whose missing facts this check sent, where it completed one: the same action, which this booking stands in for in every total.
- correctsstring or null
  The booking whose facts sent wrong this check corrected, where it corrected one: the same action, as it should have been, which this booking stands in for in every total.
created_atstringrequired
recipientRecipientSummary or null
4 fields
- resolutionstringrequired
  resolved, unresolved, probable_match or missing.
- recipient_idstring or null
- review_itemstring or null
  The open probable match, where there is one.
- fy_totalMoney or null
  This recipient's total for the fiscal year, where the answer's first rule set totals money per recipient per fiscal year: the recipient's other bookings of the year that it counts, as known when the answer was given - this one not included, and later ones too where it counts the whole year. Left out where no such total was read; history_used names every total an answer read.
  2 fields
  amountintegerrequired
  currencystringrequired
history_usedlist of HistoryInput or null
5 fields
- rule_setstringrequired
- inputstringrequired
  The rule set's name for this total, such as recipient_fy_gifts.
- countintegerrequired
- transactionslist of HistoryTransactionrequired
  2 fields
  transaction_idstringrequired
  effective_datestring or null
- totalMoney | integer | string or null
not_checkedlist of NotChecked or null
2 fields
- topicstringrequired
- reasonstringrequired
citationslist of Citation or null
4 fields
- sourcestringrequired
  The source's key within the rule set, such as estg.
- paragraphstring or null
- clausestring or null
- text_refstring or null
  The passage in the rule set's own copy of the source, sources/<file>#<anchor>.
confirmationslist of ConfirmationUsed or null
3 fields
- rulestringrequired
- confirmed_bystring or null
- confirmed_atstring or null
decisionslist of DecisionRead or null
Each question on this action a person decided, read as its answer: where the question's rule says what each answer leads to, a sign-off or an admin's override issues the action's answer again, and every answer to it after reads the decision while the rule asks the very same question. Left out where none was read.
8 fields
- answerstringrequired
  The answer chosen, one of the question's candidates - or approved, for an approval.
- questionstring or null
  The question's id. Null for an approval, which answers none.
- rulestring or null
  The rule that raises the question, as it asks it. Null for an approval.
- decided_bystring or null
  Who decided: a person in your account, by id.
- method"sign_off" | "override" | "approval" or null
  A sign-off by the person the question names, an admin's override of it, or the approval of the person the action's answer named, asked by Himmel.
- resolution_idstring or null
  The decision's record, on the answer it was made on.
- leads_tostring or null
  What the answer led to: continue - on to the rules after the question, which gave the outcome - or the outcome it gives itself. Null for an approval, read from the first rule.
- approvalstring or null
  The fact the decision stood in for as its decider's approval - where the action recorded none, and the rule that gave the outcome read it - so one person who decides and approves is asked once. Null otherwise.
recheckslist of Recheck or null
The earlier answers this booking changed, each issued again before this one was given. Left out when it changed none, and on a proposal, which changes nothing until it is reported as executed.
4 fields
- new_check_idstring or null
- supersedesstring or null
- booking_datestring or null
- outcomestring or null
supersedes_check_idstring or null
The earlier answer for the same transaction that this one replaces.
recheck_reasonstring or null
Why it was issued again: a later transaction, an action taken back (reversal) or corrected (correction), a link or split between recipients, a question raised about its recipient, the rules changing, a question on it decided (decision), or the action approved by the person its answer named (approval).
tracelist of TraceStep or null
Every rule reached, in order. Left out when the check asked explain: false.
6 fields
- rulestringrequired
- stagestringrequired
  scope, outcome or consequence.
- matchedboolean or null
- resolveinteger or null
  Which of the rule's branches applied.
- missinglist of string or null
- notestring or null
sandboxtrue or null
true on an answer given in test. A live answer has no such field.
superseded_bystring or null
The newer answer for the same transaction, when there is one.
resolutionResolution or null
The latest decision your people recorded on it: a sign-off, an override, an approval or a refusal.
6 fields
- resolved_outcomestringrequired
  One of the question's answers, or of the outcomes its rule set declares - or for an approval Himmel asked for, approved or refused.
- resolved_bystringrequired
- method"sign_off" | "override" | "approval"required
  A sign-off by the person a question names, an admin's override, or the approval or refusal of the person Himmel asked (POST /v1/approvals/{id}/approve).
- created_atstringrequired
  When it was decided.
- note_refstring or null
- given_onstring or null
  Where the decision was carried over from an earlier answer that asked the very same question: the answer it was given on. Left out for a decision given on this answer.
resolutionslist of Resolution or null
Every decision recorded on it - sign-offs, overrides, approvals and refusals - in the order recorded: an override leaves the sign-off before it on record. Left out where there is none.
6 fields
- resolved_outcomestringrequired
  One of the question's answers, or of the outcomes its rule set declares - or for an approval Himmel asked for, approved or refused.
- resolved_bystringrequired
- method"sign_off" | "override" | "approval"required
  A sign-off by the person a question names, an admin's override, or the approval or refusal of the person Himmel asked (POST /v1/approvals/{id}/approve).
- created_atstringrequired
  When it was decided.
- note_refstring or null
- given_onstring or null
  Where the decision was carried over from an earlier answer that asked the very same question: the answer it was given on. Left out for a decision given on this answer.
factsobject or null
The facts the booking was sent with, as stored: a recipient by the id it resolved to when it was sent, never a name, and everything else as sent - from a key made for an agent, a person and an approval's figure as Himmel holds them. The booking's, so every answer to it shows the same; the answer's own recipient says which identity that answer used. Read back beside the answer, never part of it.
sent_bySender or null
Who sent the check: a key, or a person signed in - beside who acted, in transaction.actor. Empty on an answer Himmel issued again, which nobody asked for (recheck_reason says why), and on one a person sent before this was kept. Read back beside the stored answer, never part of it; the answer a check returns when it is made does not carry it.
4 fields
- kind"api_key" | "person"required
- idstringrequired
  The key's id, or the person's user id.
- prefixstring or null
  A key's prefix, hk_live_7f3a: what your keys show, never the key itself.
- namestring or null
  The name the key was given, where it was given one.
executionExecution or null
For an action asked about before it was taken: what became of it, and who reported it. The answer itself still says proposed, which is what was answered.
7 fields
- status"proposed" | "executed" | "abandoned" | "expired"required
  proposed until its caller reports; executed, or abandoned when reported not taken; expired when nobody reported within 24 hours. An action taken back since reads executed, as its report said: reversal says the rest.
- executed_atstring or null
  When it was taken, as reported.
- reasonstring or null
  Why it was not taken: abandoned, refused_by_caller, failed or expired.
- refstring or null
  Your own reference for the action taken, as its report sent it - kept beside the action's own transaction.ref, never over it. Empty where the report sent none.
- systemstring or null
  The system the action is taken in, as its check or its report named it. Empty where neither did.
- reported_bySender or null
  Who reported it. Empty until somebody does, and for one that expired.
  4 fields
  kind"api_key" | "person"required
  idstringrequired
  The key's id, or the person's user id.
  prefixstring or null
  A key's prefix, hk_live_7f3a: what your keys show, never the key itself.
  namestring or null
  The name the key was given, where it was given one.
- reported_atstring or null
reversalReversal or null
For an action taken back after it was taken, on every answer to it: when, your reference for it, and who reported it. It counts toward nothing from then; the answer itself stays as it was given.
4 fields
- reversed_atstringrequired
  When it was taken back, as reported.
- refstring or null
  Your own reference for taking it back, where you sent one.
- reported_bySender or null
  Who reported it: a key, or a person.
  4 fields
  kind"api_key" | "person"required
  idstringrequired
  The key's id, or the person's user id.
  prefixstring or null
  A key's prefix, hk_live_7f3a: what your keys show, never the key itself.
  namestring or null
  The name the key was given, where it was given one.
- reported_atstring or null
requestslist of AskedOfAPerson or null
Whom Himmel asked about this action, as each request stands now - for an action a key made for an agent asked about, each person an answer to it names: a policy's approver, a question's signer. Beside the answer, never part of it. Left out where nobody was asked.
11 fields
- idstringrequired
  The request, apr_…: GET /v1/approvals/{id}.
- asked_ofstringrequired
  The person asked: a person in your account, by Himmel id.
- asked_atstringrequired
  When Himmel asked them.
- asks"approval" | "question"required
  What they are asked: their approval of the action, which a policy of yours asks of them - or their answer to the answer's question, which a sign-off gives.
- status"waiting" | "approved" | "refused" | "decided" | "lapsed"required
  waiting for them, a week at most; approved or refused by them; decided by a sign-off or an admin's override; lapsed, reason saying why.
- waits_untilstringrequired
  Until when it waits for its person: a week after it was asked, the proposal held open until then. One still waiting then lapses, no_answer, and a decision after it is 409 nothing-to-decide.
- decided_bystring or null
  Who decided it, by Himmel id: the person asked, or the admin who overruled.
- resolution_idstring or null
  The decision that answered it, on the answer it was recorded on.
- closed_atstring or null
  When it stopped waiting.
- reasonstring or null
  Why it lapsed: the action executed, abandoned or expired; no_answer in a week; no_longer_asked, an answer issued again naming them no more; refused, another person refusing the action.
- emailed_atstring or null
  When Himmel emailed them, linking the request's page in the console: within a minute of the request, in your account's own environment. Null until then, and where it never goes - a request made in test in an account with a live side, one that stopped waiting first, a person with no address, or one whose mail server refused their address.

state: "determined"

The facts, under these rule versions, as of this date, give this outcome.

state: "undetermined_missing_facts"

A rule covers this, and needs facts it did not get. missing names them.

missinglist of MissingFactrequired
7 fields
- factstringrequired
- typestring or null
- currencystring or null
  For an amount, the currency it is wanted in: the rule set's. Send it there, or - for an amount in another currency - beside it, as what your own systems record it as in this one (equivalents).
- descriptionstring or null
- needed_bystring or null
  The rule that needed it.
- review_itemstring or null
  For recipient_identity: the probable match to answer first.
- ofHistoryTransaction or null
  Where the fact is another action's: a booking a total counts and cannot read, by its id and its date. Send the fact by completing that booking (transaction.completes), not in this check.
  2 fields
  transaction_idstringrequired
  effective_datestring or null

state: "not_covered"

No confirmed rule covers this: your policy does not say, or a rule awaits confirmation.

reason"awaiting_confirmation" | "rule_flagged" | "policy_gap" | "no_rule_matched" | "no_rule_set_for_jurisdiction" | "rule_set_broken"required
detailstring or null
unconfirmed_ruleslist of string or null

state: "contested"

A rule covers this, and turns on a word it cannot apply mechanically. A named person decides.

questionQuestionrequired
5 fields
- idstringrequired
- candidateslist of stringrequired
- reasonstringrequired
  Why this one cannot be settled by the rule.
- rulestringrequired
- wordingstring or null
  The rule's wording, as your rule owner confirmed it.
signerSigner or null
1 field
- useranyrequired
  The person who signs off, as your settings name them.

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

GET/v1/checksScope checks:read

The check log

Your checks, newest first, fifty to a page. Continue with before set to the last page's next_before. Every answer ever given is here, including those a later answer replaced; current=true keeps only the answers that stand, one per booking. Each row says who acted and, in sent_by, who sent the check: a key, or a person signed in; that a later answer replaced it (superseded_by), what your people decided (resolution), and who approves or decides (a layer's approver, a contested answer's signer); and its transaction what is the action's rather than the answer's: who sent it, the latest decision on any of its answers, and the facts it was sent with. order=effective_date lists by the day each action happened, so an answer issued again never moves its row. Find an action by your own reference (ref), a booking's answers by its id (transaction), the actions of some days by the day they happened (effective_from, effective_to), a customer's by any of its records (recipient), who acted - one or several (actor), or every agent (actor_kind) - and for whom (on_behalf_of), an agent's run by its id (run), the actions taken in a system by its code (system), and the actions Himmel asked a person about by where each request stands (request) and whom it asked (asked_of); each row's transaction.requests says whom it asked. answer keeps the answers of a kind and against_rules=true the actions taken against your rules, as GET /v1/map counts them, each of its figures linking here. waiting=true keeps what waits on a person, which GET /v1/review counts in groups; reason finds why an answer is not covered and question the question it asks. state, outcome, policy_outcome and reason take several values, separated by commas. A group of the review queue links to the query here that lists its answers, and a checks.rerun alert to the answers it issued again.

Parameters

statequery · string or null
One state, or several separated by commas.
rule_setquery · string or null
Only the checks that named this rule set.
recipientquery · string or null
Only the checks of this customer, by the id of any of its records: every record you answered to be the same, or a confirmed matching rule linked, counts as one, as a yearly total counts them. A record an open question only proposes does not.
actorquery · string or null
Only what this person or agent did, by the id the check named - or any of several, separated by commas: the agents one person answers for, say.
actor_kindquery · string or null
Only what this kind of actor did, as the check named it (transaction.actor.kind): agent, user or system - or several, separated by commas. actor_kind=agent is what every agent did, which the map counts. Any other value is refused (enum).
on_behalf_ofquery · string or null
Only the actions done for this person, by the id the checks named as actor.on_behalf_of, exactly: your own id for them, or a colleague's Himmel id.
runquery · string or null
Only the actions of this run of an agent, by the transaction.run their checks named, exactly - with actor, one agent's run.
systemquery · string or null
Only the actions taken in this system, by the code their check or report named (transaction.system) - none for those whose system nobody named - or several, separated by commas. A value that is no system's code is refused (format).
transaction_statusquery · string or null
executed, proposed, abandoned, expired or reversed (taken back): what became of the booking.
requestquery · string or null
Only the actions about which Himmel asked a person something whose request is now waiting, approved, refused, decided or lapsed - one, or several separated by commas. With waiting=true, request=waiting is the review queue's approvals.
asked_ofquery · string or null
Only the actions Himmel asked this person about, by their Himmel id - with request, a request of theirs that now stands so: asked_of=usr_…&request=waiting is what waits on them.
refquery · string or null
Only the bookings sent with this transaction.ref, your own reference, or reported taken with it (execution.ref), exactly.
transactionquery · string or null
Only the answers to this booking, by its transaction_id - every one, those a later answer replaced included, unless current=true.
effective_fromquery · string or null
Only the actions that happened on this day or after, as each answer is dated (effective_date): the day its facts give, or where they give none the day it was answered. A date, YYYY-MM-DD.
effective_toquery · string or null
Only the actions that happened on this day or before. A date, YYYY-MM-DD.
outcomequery · string or null
One outcome, or several separated by commas.
policy_outcomequery · string or null
What a policy of yours answered - one outcome, or several separated by commas - whatever the answer as a whole says. Where our law answers too, outcome is the law's, so a gift your policy does not allow is found with policy_outcome=not_allowed.
answerquery · string or null
Only the answers of this kind - or of several, separated by commas - each read as the map counts it (GET /v1/map): by its first policy's layer where a policy answered, and otherwise by the answer itself. allowed: determined, letting the action stand; approval: needs_approval; person: handed to a person, or contested; refused: not_allowed; other: an outcome a policy declares in its own word; open: not covered, or a fact missing. Any other value is refused (enum).
against_rulesquery · boolean
Only the actions taken against your rules, as check.against_rules is raised: reported taken, with an answer one of whose policies is determined with an outcome that does not let the action stand - any but allowed and not_applicable.
currentquery · boolean
Only the answers that stand: none given later replaced them.
waitingquery · boolean
Only the answers that stand and wait on a person at your company: a question nobody has decided, an answer your rules do not give yet, and facts missing from an action that was taken - or from any action, a "same customer?" question. Never an action that was not taken. What GET /v1/review counts.
reasonquery · string or null
Only the not_covered answers not covered for this reason - policy_gap, awaiting_confirmation, rule_flagged, no_rule_matched, no_rule_set_for_jurisdiction or rule_set_broken - or several, separated by commas.
questionquery · string or null
Only the contested answers that ask this question, by its id.
missingquery · string or null
Only answers that name this fact as missing, e.g. recipient.
consequencequery · string or null
Only answers that carry this consequence, e.g. non_deductible_amount.
recheckedquery · boolean
Only answers that replaced an earlier one: re-checks.
rerunquery · string or null
Only the answers one re-run issued again, by the rerun_id its checks.rerun alert names: the answers a decision about the rules changed.
fromquery · string or null
Only the answers given at or after this moment, an ISO 8601 timestamp or a date - a date alone is its midnight, UTC. When the action happened is effective_from.
toquery · string or null
Only the answers given before this moment, which is not included; as from.
limitquery · integer
How many to a page.
beforequery · string or null
The last page's next_before, to continue from.
orderquery · "created_at" | "effective_date"
created_at, the default: newest answer first. effective_date: by the day each action happened, newest first - within a day the one first asked about or booked last first - so an answer issued again never moves its row; with current=true, one row per action.

Responses

200 Successful response

checkslist of CheckLogRowrequired
20 fields
- check_idstringrequired
- created_atstringrequired
- state"determined" | "undetermined_missing_facts" | "not_covered" | "contested"required
- rule_setstringrequired
- effective_datestringrequired
- as_ofstringrequired
- env"live" | "test"required
- consequenceslist of Consequencerequired
  Every layer's consequences, law first.
  5 fields
  keystringrequired
  valueanyrequired
  Money as minor units and currency, or a number, a flag or a date.
  rulestringrequired
  basisstring or null
  law, policy or goodwill.
  citationCitation or null
  4 fields
  sourcestringrequired
  The source's key within the rule set, such as estg.
  paragraphstring or null
  clausestring or null
  text_refstring or null
  The passage in the rule set's own copy of the source, sources/<file>#<anchor>.
- layerslist of CheckLogLayerrequired
  What each rule set made of it, law first. Where our law answers too, outcome is the law's, and what your policy said is here. Empty for an answer given before any rule ran.
  7 fields
  kindstringrequired
  law or policy.
  rule_setstringrequired
  rule_versionstringrequired
  state"determined" | "undetermined_missing_facts" | "not_covered" | "contested"required
  outcomestring or null
  rulestring or null
  The rule whose branch gave this layer its outcome or its question. Empty where it waits on facts - missing names the rules that asked - or is not covered.
  approverstring or null
  Who this layer's answer says must approve - where it needs_approval, the person your settings name for it, by Himmel id. Empty where it names nobody.
- transactionCheckLogTransactionrequired
  18 fields
  transaction_idstringrequired
  statusstringrequired
  executed, proposed, abandoned or expired - or reversed, an action taken back after it was taken, which counts toward nothing.
  measureslist of Measurerequired
  What the action came to in another measure than money: each whole number a figure of its rule set marks as approved covers - a retention discount's percentage, where its policy marks approved_percent: { type: int, approval: discount_percent } - read from the versions that answered it, in their order, each fact once. Empty where none marks one or the booking says none.
  2 fields
  factstringrequired
  The fact, as the rule set declares it: discount_percent.
  valueintegerrequired
  What the action sent for it: 20.
  actorCheckLogActorrequired
  3 fields
  kindstring or null
  idstring or null
  on_behalf_ofstring or null
  factsobjectrequired
  The facts the booking was sent with, as stored: a recipient by the id it resolved to, never a name, and everything else as sent - from a key made for an agent, a person and an approval's figure as Himmel holds them.
  refstring or null
  The action's own reference, as its check sent it.
  executed_refstring or null
  Your own reference for the action taken, as its report sent it, beside the action's own: ref= finds the action by either. Empty where its report sent none.
  recipient_idstring or null
  booking_datestring or null
  amountBookedMoney or null
  What the booking was for: the fact its rule set names as its amount (amount_fact) - for our German gifts rule set amount_gross, what it was booked at, tax included - with the figures sent beside it (equivalents). Empty where the rule set names none or the booking says none.
  3 fields
  amountintegerrequired
  currencystringrequired
  equivalentslist of Money or null
  What the company's own systems record it as in other currencies, as sent beside it - a figure per currency, which a rule set in that currency reads. Never a rate we picked.
  runstring or null
  The run of an agent the action was part of, where its check named one.
  systemstring or null
  The system the action was taken in, by your company's code for it, as its check or a request after it named it: what system= finds. Empty where nobody named one.
  sent_bySender or null
  Who sent the action: the key or the person that sent its first answer - for an action whose facts a later check completed, whoever sent its first booking. The row's own sent_by is the answer's, empty on an answer issued again.
  4 fields
  kind"api_key" | "person"required
  idstringrequired
  The key's id, or the person's user id.
  prefixstring or null
  A key's prefix, hk_live_7f3a: what your keys show, never the key itself.
  namestring or null
  The name the key was given, where it was given one.
  completesstring or null
  The booking whose missing facts this booking's check sent, where it completed one: the same action, which this booking stands in for in every total.
  correctsstring or null
  The booking whose facts sent wrong this booking's check corrected, where it corrected one: the same action, which this booking stands in for in every total.
  reversed_atstring or null
  When the action was taken back, where it was: its status is then reversed.
  resolutionBookingResolution or null
  The latest decision - a sign-off, an override, an approval or a refusal - recorded on any answer to this action's bookings, and the answer it was recorded on - an earlier one where the answer was issued again since asking another question: a decision is carried over only where the same question is asked again.
  7 fields
  resolved_outcomestringrequired
  One of the question's answers, or of the outcomes its rule set declares - or for an approval Himmel asked for, approved or refused.
  resolved_bystringrequired
  method"sign_off" | "override" | "approval"required
  A sign-off by the person a question names, an admin's override, or the approval or refusal of the person Himmel asked (POST /v1/approvals/{id}/approve).
  created_atstringrequired
  When it was decided.
  check_idstringrequired
  The answer it was recorded on.
  note_refstring or null
  given_onstring or null
  Where the decision was carried over from an earlier answer that asked the very same question: the answer it was given on. Left out for a decision given on this answer.
  requestslist of AskedOfAPerson or null
  Whom Himmel asked about this action, as each request stands now - for an action a key made for an agent asked about, each person an answer to it names: a policy's approver, a question's signer. Beside the answer, never part of it. Left out where nobody was asked.
  11 fields
  idstringrequired
  The request, apr_…: GET /v1/approvals/{id}.
  asked_ofstringrequired
  The person asked: a person in your account, by Himmel id.
  asked_atstringrequired
  When Himmel asked them.
  asks"approval" | "question"required
  What they are asked: their approval of the action, which a policy of yours asks of them - or their answer to the answer's question, which a sign-off gives.
  status"waiting" | "approved" | "refused" | "decided" | "lapsed"required
  waiting for them, a week at most; approved or refused by them; decided by a sign-off or an admin's override; lapsed, reason saying why.
  waits_untilstringrequired
  Until when it waits for its person: a week after it was asked, the proposal held open until then. One still waiting then lapses, no_answer, and a decision after it is 409 nothing-to-decide.
  decided_bystring or null
  Who decided it, by Himmel id: the person asked, or the admin who overruled.
  resolution_idstring or null
  The decision that answered it, on the answer it was recorded on.
  closed_atstring or null
  When it stopped waiting.
  reasonstring or null
  Why it lapsed: the action executed, abandoned or expired; no_answer in a week; no_longer_asked, an answer issued again naming them no more; refused, another person refusing the action.
  emailed_atstring or null
  When Himmel emailed them, linking the request's page in the console: within a minute of the request, in your account's own environment. Null until then, and where it never goes - a request made in test in an account with a live side, one that stopped waiting first, a person with no address, or one whose mail server refused their address.
- outcomestring or null
- missinglist of MissingFact or null
  What an undetermined_missing_facts answer asks for, as the answer names it.
  7 fields
  factstringrequired
  typestring or null
  currencystring or null
  For an amount, the currency it is wanted in: the rule set's. Send it there, or - for an amount in another currency - beside it, as what your own systems record it as in this one (equivalents).
  descriptionstring or null
  needed_bystring or null
  The rule that needed it.
  review_itemstring or null
  For recipient_identity: the probable match to answer first.
  ofHistoryTransaction or null
  Where the fact is another action's: a booking a total counts and cannot read, by its id and its date. Send the fact by completing that booking (transaction.completes), not in this check.
  2 fields
  transaction_idstringrequired
  effective_datestring or null
- reason"awaiting_confirmation" | "rule_flagged" | "policy_gap" | "no_rule_matched" | "no_rule_set_for_jurisdiction" | "rule_set_broken" or null
  Why a not_covered answer is not covered.
- questionQuestion or null
  The question a contested answer puts to a named person.
  5 fields
  idstringrequired
  candidateslist of stringrequired
  reasonstringrequired
  Why this one cannot be settled by the rule.
  rulestringrequired
  wordingstring or null
  The rule's wording, as your rule owner confirmed it.
- signerSigner or null
  Who decides a contested answer's question: the person your settings name.
  1 field
  useranyrequired
  The person who signs off, as your settings name them.
- supersedes_check_idstring or null
  The earlier answer for the same booking that this one replaced.
- superseded_bystring or null
  The newer answer for the same booking that replaced this one, where one did.
- recheck_reasonstring or null
- sent_bySender or null
  Who sent the check: a key, or a person signed in - beside who acted, in transaction.actor. Empty on an answer Himmel issued again, and on one a person sent before this was kept.
  4 fields
  kind"api_key" | "person"required
  idstringrequired
  The key's id, or the person's user id.
  prefixstring or null
  A key's prefix, hk_live_7f3a: what your keys show, never the key itself.
  namestring or null
  The name the key was given, where it was given one.
- resolutionResolution or null
  The latest decision your people recorded on this answer - a sign-off, an override, an approval or a refusal; GET /v1/checks/{id} gives every one.
  6 fields
  resolved_outcomestringrequired
  One of the question's answers, or of the outcomes its rule set declares - or for an approval Himmel asked for, approved or refused.
  resolved_bystringrequired
  method"sign_off" | "override" | "approval"required
  A sign-off by the person a question names, an admin's override, or the approval or refusal of the person Himmel asked (POST /v1/approvals/{id}/approve).
  created_atstringrequired
  When it was decided.
  note_refstring or null
  given_onstring or null
  Where the decision was carried over from an earlier answer that asked the very same question: the answer it was given on. Left out for a decision given on this answer.
next_beforestring or null
Pass as before for the next page; empty on the last one.

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

GET/v1/reviewScope checks:read

What waits on a person

What waits on somebody at your company, in groups: the approvals Himmel asked of a person about an agent's action, each question the rules leave to a person, the "same customer?" questions open, the answers your rules do not give yet by why, and the facts missing from actions taken, fact by fact. Each group says how many wait in it and links to the check log's query that lists them (waiting=true). An action never taken waits on nobody, and the facts of one still being asked about are its asker's to send. Nothing here decides anything: an approval is given or refused by the person asked, a question is decided with a resolution, "the same customer?" under Recipients, the rules by your rule owner confirming them, and missing facts come in a new check.

Needs a key with the scope checks:read. What it reads is your whole account's, so a key made for an agent, which reads its own agent's alone, gets 403 insufficient-scope.

Responses

200 Successful response

waitingintegerrequired
How many answers wait on a person, each counted once, in whichever groups.
checksstringrequired
The GET /v1/checks query that lists them: waiting=true.
groupslist of ReviewGrouprequired
Approvals Himmel asked for, questions, "the same customer?", the rules, then facts; within a kind the largest first, but for the rules: policy_gap, awaiting_confirmation, rule_flagged, then the rest. A group with nothing in it is not listed.
9 fields
- kind"approval" | "contested" | "match" | "not_covered" | "undetermined_missing_facts"required
  approval: agents' actions whose answer names a person Himmel asked to approve, who has not answered yet. contested: a question the rules leave to a person. match: "the same customer?" questions. not_covered: answers your rules do not give yet, by reason. undetermined_missing_facts: a fact missing from actions taken.
- countintegerrequired
  How many wait in the group: the answers checks lists, or for match the questions open, which matches lists.
- checksstringrequired
  The GET /v1/checks query that lists the group's answers, exactly.
- questionQuestion or null
  For contested: the question, as its newest answer asks it - the answers to choose from, and the rule that raises it in the words your rule owner confirmed.
  5 fields
  idstringrequired
  candidateslist of stringrequired
  reasonstringrequired
  Why this one cannot be settled by the rule.
  rulestringrequired
  wordingstring or null
  The rule's wording, as your rule owner confirmed it.
- reason"awaiting_confirmation" | "rule_flagged" | "policy_gap" | "no_rule_matched" | "no_rule_set_for_jurisdiction" | "rule_set_broken" or null
  For not_covered: why its answers are not covered.
- factstring or null
  For undetermined_missing_facts: the fact.
- descriptionstring or null
  For undetermined_missing_facts: the fact, as its rule set describes it.
- matchesstring or null
  For match: where the open questions are listed, GET /v1/recipients/matches.
- answersinteger or null
  For match: the answers waiting on one of its questions, which checks lists.

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

Confirmations

GET/v1/confirmationsScope rules:read

What your account has to confirm

Every version of every rule set your account has on - our law where it is switched on for your account, your own policies, drafts included, and your matching rules - with how many of each version's rules wait for your rule owner (pending), how many they flagged, and waiting: how many answers that stand wait on a rule of the version, which confirming issues again. Law comes first, then policies, then matching rules, each oldest version first. A version's own page is GET /v1/confirmations/{rule_set}/{version}.

Needs a key with the scope rules:read. What it reads is your whole account's, so a key made for an agent, which reads its own agent's alone, gets 403 insufficient-scope.

Responses

200 Successful response

rule_setslist of ConfirmationSetrequired
5 fields
- rule_setstringrequired
- kindstringrequired
  law, policy or matching.
- domainstringrequired
- titlestringrequired
- versionslist of ConfirmationVersionrequired
  7 fields
  versionstringrequired
  statusstringrequired
  draft, published or superseded.
  effective_fromstringrequired
  rulesintegerrequired
  How many rules the version has.
  pendingintegerrequired
  How many nobody has confirmed or flagged yet.
  flaggedintegerrequired
  How many your rule owner flagged. A flagged rule stays off.
  waitingintegerrequired
  How many answers that stand wait on a rule of this version.

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

GET/v1/confirmations/{rule_set}/{version}Scope rules:read

One page per rule set version: what to confirm, and what carried over

Nothing runs for your account until your rule owner confirms it. Per rule: its wording, each citation with the passage it points at, its worked examples as sentences, and its status - pending, confirmed on this page, flagged, or carried_over: confirmed on another version's page, where the rule reads exactly as it does here, so it runs without being confirmed again; its decision names that version. waiting counts the answers that stand and wait on a rule of this version, which confirming it issues again; each rule's waiting counts those that stopped at that rule, the first they could not pass. A rule set of the law is your account's to read and confirm once it is switched on for your account: before, this is rule-set-not-enabled.

Needs a key with the scope rules:read. What it reads is your whole account's, so a key made for an agent, which reads its own agent's alone, gets 403 insufficient-scope.

Parameters

rule_setpath · stringrequired
versionpath · stringrequired

Responses

200 Successful response

rule_setstringrequired
versionstringrequired
statusstringrequired
effective_fromstringrequired
pendingintegerrequired
How many rules still wait for your rule owner.
waitingintegerrequired
How many answers that stand wait on a rule of this version. Confirming what is pending checks them again.
ruleslist of PageRulerequired
10 fields
- rulestringrequired
- stagestringrequired
- titlestringrequired
- wordingstringrequired
- rule_hashstringrequired
  A confirmation binds to this hash; a changed rule is confirmed again.
- status"pending" | "confirmed" | "flagged" | "carried_over"required
  pending: nobody has confirmed or flagged it. confirmed on this page. flagged: it stays off. carried_over: confirmed on another version's page, where it reads exactly as here, so it runs without being confirmed again.
- waitingintegerrequired
  How many answers that stand stopped at this rule: it is the first they could not pass, unconfirmed or flagged.
- citationslist of PageCitationrequired
  8 fields
  sourcestringrequired
  paragraphstring or null
  clausestring or null
  text_refstring or null
  source_titlestring or null
  source_kindstring or null
  statute, official_guidance, case, policy_document, or default: the documented defaults a matching rule set starts from.
  excerptstring or null
  The passage itself, as the rule set holds it.
  anchors_availablelist of string or null
  Where the citation resolves to no passage: the anchors the source has.
- exampleslist of WorkedExamplerequired
  3 fields
  casestringrequired
  examplestringrequired
  The case as one sentence, for the owner to read.
  sourceobject or null
  What settles the case: its type and reference.
- decisionDecision or null
  5 fields
  action"confirmed" | "flagged"required
  atstringrequired
  versionstringrequired
  The version on whose page this was decided. Where it is another version's, the rule reads there exactly as it does here, and the decision holds for both.
  by_userstring or null
  commentstring or null
previous_versionstring or null

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

POST/v1/confirmations/{rule_set}/{version}Scope confirm

Confirm, or flag, per rule

Each confirmation binds to the rule's hash, so a rule that changes is confirmed again. A flagged rule stays off for your account - checks that reach it answer not_covered with rule_flagged - and the comment reaches whoever maintains it: us for a rule of the law, your policy's draft for one of yours. Every answer your decision may change is checked again, in the background and in live and test alike: answers that waited on these rules, answers that used a rule you flag, and answers given under an earlier version this one now governs. rerun_id names that re-run; its checks.rerun alert says what changed. A rule of your policy that was drafted from its document, flagged with a comment, is drafted again alone, in the background: drafting_again names the document it follows on, the job and the rules, and the rule comes back to this page to be confirmed as it then reads, every rule it did not touch keeping its confirmation. A rule set of the law is confirmed once it is switched on for your account: before, this is rule-set-not-enabled, and nothing is recorded.

Needs a key with the scope confirm. It changes what your account has decided, which live and test share, so it is done from live: in an account with a live side, a test key gets 403 live-only.

Parameters

rule_setpath · stringrequired
versionpath · stringrequired
Idempotency-Keyheader · string or null
Makes a retry safe: the same key with the same request within 24 hours gets the first answer again, and nothing is done twice. The same key with a different request is 409 idempotency-conflict. Keys are per environment and per path.

Request body · application/json

ruleslist of ConfirmationItemrequired
3 fields
- rulestringrequired
- action"confirm" | "flag"required
- commentstring
by_userstring or null
Who did it, when your key acts for a person: their Himmel id, which the console's Developers page shows them, and Settings' People an admin. They must be in your account, with a role that could do this themselves, and the record keeps it as your key's claim. A key made for an agent names nobody but itself: leave it out. Signed in to the console, leave it out: it is you.

Responses

200 Successful response

rule_setstringrequired
versionstringrequired
recordedlist of Recordedrequired
3 fields
- rulestringrequired
- action"confirmed" | "flagged"required
- rule_hashstringrequired
pendinglist of stringrequired
Rules of this version still waiting.
rerun_idstring or null
The re-run that checks again, in the background, every answer this decision may change. Its checks.rerun alert says what changed, and GET /v1/checks?rerun= lists them. Null for matching rules, which match recipients again instead.
drafting_againDraftingAgain or null
The rules of your policy flagged with a comment, drafted again alone from its document and what you said. Null where none is: a rule of the law or of the matching rules, a policy posted as files, a flag without a comment, or a deployment that drafts nothing.
3 fields
- document_idstringrequired
  The document they were drafted from, which says drafting and where while they are drafted again, then what came of each in its latest entry of drafts.
- job_idstringrequired
- ruleslist of stringrequired

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
409The request conflicts with what is stored: see detail.
413The request's body is larger than the operation takes, refused before any of it is read (body-too-large): a policy's files at most 5 MB, any other body 1 MB - and an uploaded file at most 20 MB (file-too-large).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

Rule sets

GET/v1/rulesReadable without a key

Every rule set you can see

The public catalogue: each rule set's title, domain and versions with their effective dates and changelog. Without a key it lists the rule sets of the law; with one, your own policies and matching rules too.

Readable without a key, for the rule sets of the law; with one, it needs the scope rules:read, and your own rule sets are added - except for a key made for an agent, which reads it as anybody does: what its agent is held to is GET /v1/agents/{agent_id}/rules.

Responses

200 Successful response

rule_setslist of RuleSetListItemrequired
5 fields
- rule_setstringrequired
- kindstringrequired
  law, policy or matching.
- domainstringrequired
- titlestringrequired
- versionslist of RuleSetVersionSummaryrequired
  9 fields
  versionstringrequired
  statusstringrequired
  draft, published or superseded.
  effective_fromstringrequired
  effective_basisstringrequired
  What the date is compared with: the transaction's own, or its year's start.
  effective_date_factstringrequired
  jurisdictionslist of stringrequired
  checksumstringrequired
  changelogstring or null
  superseded_bystring or null

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

GET/v1/rules/{rule_set}Readable without a key

One rule set and its versions

Readable without a key for a rule set of the law.

Parameters

rule_setpath · stringrequired

Responses

200 Successful response

rule_setstringrequired
kindstringrequired
domainstringrequired
titlestringrequired
jurisdictionslist of stringrequired
versionslist of RuleSetVersionSummaryrequired
9 fields
- versionstringrequired
- statusstringrequired
  draft, published or superseded.
- effective_fromstringrequired
- effective_basisstringrequired
  What the date is compared with: the transaction's own, or its year's start.
- effective_date_factstringrequired
- jurisdictionslist of stringrequired
- checksumstringrequired
- changelogstring or null
- superseded_bystring or null

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

GET/v1/rules/{rule_set}/{version}Readable without a key

One version: its facts, and its rules

The facts the version takes - name, type, whether required, what it means - so you can build a form or a validator against it; your settings it reads; the currency its limits are in, which an amount in another currency is read in at the figure you send beside it; its outcomes; and what it deliberately does not check. Readable without a key. With a key for an account that has the rule set enabled, each rule's wording and citations too.

Parameters

rule_setpath · stringrequired
versionpath · stringrequired

Responses

200 Successful response

versionstringrequired
statusstringrequired
draft, published or superseded.
effective_fromstringrequired
effective_basisstringrequired
What the date is compared with: the transaction's own, or its year's start.
effective_date_factstringrequired
jurisdictionslist of stringrequired
checksumstringrequired
rule_setstringrequired
kindstringrequired
domainstringrequired
titlestringrequired
factsmap of FactSpecrequired
Every fact the version takes, by name.
tenant_factsmap of TenantFactSpecrequired
outcomeslist of stringrequired
not_checkedlist of NotCheckedrequired
2 fields
- topicstringrequired
- reasonstringrequired
changelogstring or null
superseded_bystring or null
currencystring or null
The currency its limits are in, as an ISO 4217 code: every amount its rules read is read in it, an amount in another currency at the figure sent beside it (equivalents) - never at a rate we pick. Null where its rules read no amount, and for a version stored before rule sets said one.
ruleslist of CatalogueRule or null
Rules and their wording: only for an account with the rule set enabled.
7 fields
- rulestringrequired
- stagestringrequired
- titlestringrequired
- wordingstringrequired
  The plain-language sentence your rule owner confirms.
- rule_hashstringrequired
- citationslist of Citationrequired
  4 fields
  sourcestringrequired
  The source's key within the rule set, such as estg.
  paragraphstring or null
  clausestring or null
  text_refstring or null
  The passage in the rule set's own copy of the source, sources/<file>#<anchor>.
- statusstring or null
rules_visibleboolean or null
false when the rules are left out because no key was sent.

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

GET/v1/rules/{rule_set}/{version}/diffReadable without a key

What changed, in the words the owner confirms in

Per rule: changed, added, removed or unchanged, with the wording before and after. Then the worked examples that come out differently: each is run under both versions, not compared as text. Only changed and added rules need confirming again, and a rule changed says what moved in it beyond its own words (moved): a clause it cites, its examples, what it reads.

Parameters

rule_setpath · stringrequired
versionpath · stringrequired
fromquery · stringrequired

Responses

200 Successful response

fromVersionRefrequired
2 fields
- rule_setstringrequired
- versionstringrequired
toVersionRefrequired
2 fields
- rule_setstringrequired
- versionstringrequired
summaryDiffSummaryrequired
4 fields
- changedintegerrequired
- addedintegerrequired
- removedintegerrequired
- unchangedintegerrequired
ruleslist of RuleChangerequired
8 fields
- rulestringrequired
- status"changed" | "added" | "removed" | "unchanged"required
- titlestringrequired
- wording_beforestring or null
- wording_afterstring or null
- rule_hash_beforestring or null
- rule_hash_afterstring or null
- movedMoved or null
  For a rule changed, what moved in it beyond its words; null for any other.
  6 fields
  titlebooleanrequired
  Whether its title changed.
  wordingbooleanrequired
  Whether its words changed: wording_before and wording_after.
  clauseslist of ClauseMovedrequired
  4 fields
  sourcestringrequired
  clausestringrequired
  Its clause or paragraph, as the rule cites it.
  beforestring or null
  Its text before: null where the rule did not cite it, or it had none.
  afterstring or null
  Its text now: null where the rule cites it no longer, or it has none.
  exampleslist of ExampleMovedrequired
  7 fields
  casestringrequired
  factslist of FactMovedrequired
  The facts of it that moved.
  answerbooleanrequired
  Whether the answer it expects moved.
  historybooleanrequired
  Whether the earlier actions it counts moved.
  otherbooleanrequired
  Whether anything else of it moved: who acts, the settings or decisions it assumes, its source.
  beforestring or null
  Its sentence before: null for an example the rule did not have.
  afterstring or null
  Its sentence now: null for one it has no longer.
  logicbooleanrequired
  Whether its conditions, what each branch decides, what it requires or its place among the rules changed.
  readslist of ReadMovedrequired
  3 fields
  kind"fact" | "setting" | "derived" | "total" | "table"required
  namestringrequired
  changedlist of stringrequired
  What of it changed: new or gone; for a fact or a setting its type, values, pattern, currency, signed or approval (whether it records an approval); for a total its sum, where, group_by, window or days; for a derived value its expression; for a table its rows.
examples_changedlist of ExampleChangerequired
5 fields
- casestringrequired
- examplestringrequired
- beforeExampleResultrequired
  3 fields
  statestringrequired
  outcomestring or null
  consequenceslist of KeyValue or null
  2 fields
  keystringrequired
  valueany
- afterExampleResultrequired
  3 fields
  statestringrequired
  outcomestring or null
  consequenceslist of KeyValue or null
  2 fields
  keystringrequired
  valueany
- rulestring or null

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

Recipients

GET/v1/recipientsScope checks:read

Recipient identities

Each recipient record, newest first, with the identity it counts as once confirmed links are followed. A person signed in to the console as an admin or ops is also shown each record's name, and can search by it with q. A key is shown ids and never a name, so q is refused for it (names-withheld). ids asks for given records - the ones a list of checks names, say - where the listing alone is the newest.

Needs a key with the scope checks:read. What it reads is your whole account's, so a key made for an agent, which reads its own agent's alone, gets 403 insufficient-scope.

Parameters

qquery · string or null
idsquery · string or null
Only these records, by id, separated by commas: up to 200.
limitquery · integer

Responses

200 Successful response

recipientslist of RecipientRecordrequired
8 fields
- recipient_idstringrequired
- kindstringrequired
- created_fromstringrequired
- created_atstringrequired
- canonical_idstringrequired
  The identity this record counts as, after confirmed links.
- labelstring or null
  The recipient's name as recorded, or its organisation or email address where no name was, read through the pseudonymiser. Shown only to a person signed in to the console as an admin or ops, and left out for a key, whatever its scopes. Null when only a number was recorded, or when the name is no longer kept (name_expired).
- name_expiredboolean or null
  True where a name was recorded and is no longer kept: a customer's names are kept through the end of the fiscal year after the one they were last met in. Their record and numbers stay, and the same spelling sent again finds them and brings the name back. Left out otherwise.
- numbersmap of string or null
  The numbers your systems sent the record with, as sent - customer_number, supplier_number, vendor_number, creditor_number, each kind once - and {} where none was: what the console shows a customer by where no name was sent. Shown to a person signed in to the console, whatever their role, and left out for a key.

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

GET/v1/recipients/matchesScope checks:read

Probable matches waiting for somebody to answer

Two recipient records a confirmed matching rule thinks may be one person. Totals follow recipients, not spellings, and a probable match is never merged without a person saying so: answer each with POST /v1/recipients/matches/{id}. Both records' names are shown to a person signed in to the console as an admin or ops; a key is shown their ids.

Needs a key with the scope checks:read. What it reads is your whole account's, so a key made for an agent, which reads its own agent's alone, gets 403 insufficient-scope.

Parameters

statusquery · string
limitquery · integer

Responses

200 Successful response

matcheslist of ProbableMatchrequired
6 fields
- review_itemstringrequired
- status"open" | "same" | "different"required
- rulestringrequired
  The confirmed matching rule that proposed it.
- created_atstringrequired
- aMatchSiderequired
  3 fields
  recipient_idstringrequired
  labelstring or null
  The recipient's name as recorded, or its organisation or email address where no name was, read through the pseudonymiser. Shown only to a person signed in to the console as an admin or ops, and left out for a key, whatever its scopes. Null when only a number was recorded, or when the name is no longer kept (name_expired).
  name_expiredboolean or null
  True where a name was recorded and is no longer kept: a customer's names are kept through the end of the fiscal year after the one they were last met in. Their record and numbers stay, and the same spelling sent again finds them and brings the name back. Left out otherwise.
- bMatchSiderequired
  3 fields
  recipient_idstringrequired
  labelstring or null
  The recipient's name as recorded, or its organisation or email address where no name was, read through the pseudonymiser. Shown only to a person signed in to the console as an admin or ops, and left out for a key, whatever its scopes. Null when only a number was recorded, or when the name is no longer kept (name_expired).
  name_expiredboolean or null
  True where a name was recorded and is no longer kept: a customer's names are kept through the end of the fiscal year after the one they were last met in. Their record and numbers stay, and the same spelling sent again finds them and brings the name back. Left out otherwise.

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

POST/v1/recipients/matches/{match_id}Scope recipients:write

Same, or different. Never automatic.

same links the two records into one identity and different keeps them apart for good. Either way the answers whose totals depend on it are issued again, in a job - the booking that raised the question among them, answered from then on like any other: with the other record after same, on its own after different.

Parameters

match_idpath · stringrequired
Idempotency-Keyheader · string or null
Makes a retry safe: the same key with the same request within 24 hours gets the first answer again, and nothing is done twice. The same key with a different request is 409 idempotency-conflict. Keys are per environment and per path.

Request body · application/json

decision"same" | "different"required
decided_bystring or null
Who did it, when your key acts for a person: their Himmel id, which the console's Developers page shows them, and Settings' People an admin. They must be in your account, with a role that could do this themselves, and the record keeps it as your key's claim. A key made for an agent names nobody but itself: leave it out. Signed in to the console, leave it out: it is you.

Responses

200 Successful response

review_itemstringrequired
decision"same" | "different"required
recipientslist of stringrequired
recheck_jobstring or null

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
409The request conflicts with what is stored: see detail.
413The request's body is larger than the operation takes, refused before any of it is read (body-too-large): a policy's files at most 5 MB, any other body 1 MB - and an uploaded file at most 20 MB (file-too-large).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

POST/v1/recipients/{recipient_id}/splitScope recipients:write

Undo a link, and re-check what it moved

Undoes this record's links to others. The links stay on record, marked undone, and the answers they moved are issued again.

Parameters

recipient_idpath · stringrequired
Idempotency-Keyheader · string or null
Makes a retry safe: the same key with the same request within 24 hours gets the first answer again, and nothing is done twice. The same key with a different request is 409 idempotency-conflict. Keys are per environment and per path.

Request body · application/json

decision"same" | "different"required
decided_bystring or null
Who did it, when your key acts for a person: their Himmel id, which the console's Developers page shows them, and Settings' People an admin. They must be in your account, with a role that could do this themselves, and the record keeps it as your key's claim. A key made for an agent names nobody but itself: leave it out. Signed in to the console, leave it out: it is you.

Responses

200 Successful response

recipient_idstringrequired
undonelist of stringrequired
The links undone. They stay on record, marked undone.
recheck_jobstring or null

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
409The request conflicts with what is stored: see detail.
413The request's body is larger than the operation takes, refused before any of it is read (body-too-large): a policy's files at most 5 MB, any other body 1 MB - and an uploaded file at most 20 MB (file-too-large).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

Settings

GET/v1/tenant-factsScope rules:read

The settings your checks are answered with

What your rules read about your company - who approves, who signs off, your financial year's start, a limit of your own - each as it applies today (in_force), with every version (history), and settings: each one a rule set of your account reads, with the rule sets that read it and what each says it is for, for an amount the currencies they read it in, and unset where nothing is in force today, so a check reaching a rule that reads it asks for it. Himmel reads your financial year's start itself. Every check records the settings it read.

Needs a key with the scope rules:read. What it reads is your whole account's, so a key made for an agent, which reads its own agent's alone, gets 403 insufficient-scope.

Responses

200 Successful response

in_forceobjectrequired
Each setting as it applies today.
historylist of TenantFactVersionrequired
Every version of every setting, by key, newest first - a day's the latest saved first, so the first dated on or before a day is the one in force that day.
5 fields
- keystringrequired
- valid_fromstringrequired
- valueany
- confirmed_bystring or null
- confirmed_atstring or null
settingslist of Settingrequired
Each setting a rule set of your account reads, or Himmel does, by key, with what reads it - and any other set, which nothing reads. Its values are in in_force and history.
7 fields
- keystringrequired
- read_bylist of SettingReaderrequired
  What reads it, each in its own words: your policies first, then your matching rules, then the law you have switched on, then Himmel. Empty for a setting stored that nothing reads any more, which cannot be changed.
  5 fields
  kind"law" | "policy" | "matching" | "himmel"required
  A law set switched on for your account, one of your policies or your matching rules - or himmel: Himmel itself, which reads your financial year's start and which actions taken against the rules are emailed at once.
  titlestringrequired
  versionslist of stringrequired
  The rule set's versions that declare the setting, drafts included, oldest first.
  descriptionstringrequired
  What this reader says the setting is for, as its newest version declares it.
  rule_setstring or null
  The rule set's key; null for Himmel.
- unsetbooleanrequired
  No value is in force today, or it is none: a check reaching a rule that reads it asks for it.
- typestring or null
  The type a value must have, as what reads it declares it (docs: rule sets) - a person by their Himmel id is user. Null for a setting nothing reads.
- patternstring or null
  For a code - a string, or an account that declares one: a regular expression the whole value must match. A value that does not is refused with invalid-fact.
- valueslist of string or null
  An enum's values.
- currencieslist of string or null
  For an amount: the currencies the rule sets that read it read it in, as their versions say. A value is in one of them, with what it comes to in each other beside it (equivalents, as a check's amount carries them) - otherwise PUT refuses it.

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

PUT/v1/tenant-facts/{key}Scope confirm

A new version of one setting

Writes a new version from valid_from (today when left out). Nothing is overwritten, and an answer keeps the settings it read as its record. Dated back, a change reaches answers already given: those dated from valid_from on that read the setting are issued again by a re-run (rerun_id), with one checks.rerun alert once it is done - a financial year's start corrected to 1 April reaches the credits of the year it moves. The setting is checked first: something in your account reads it - a key nothing reads, a typo say, is invalid-fact with read_by_nothing, and the problem's settings lists what your rules do read - and its value holds no email address or IBAN (pii-in-facts) and has the type everything that reads it declares (invalid-fact). A signer or an approver is a person in your account, by their Himmel id, never a name (unknown_user when nobody here has it). An amount is in the currency each rule set that reads it reads it in, or carries what it comes to in that one beside it (equivalents) - otherwise invalid-fact, currency. The rules whose actions taken against them you hear of at once (emailed_at_once) are rules of your own policies, by id - otherwise invalid-fact, unknown_rule.

Needs a key with the scope confirm. It changes what your account has decided, which live and test share, so it is done from live: in an account with a live side, a test key gets 403 live-only.

Parameters

keypath · stringrequired

Request body · application/json

valueanyrequired
valid_fromstring or null
confirmed_bystring or null
Who did it, when your key acts for a person: their Himmel id, which the console's Developers page shows them, and Settings' People an admin. They must be in your account, with a role that could do this themselves, and the record keeps it as your key's claim. A key made for an agent names nobody but itself: leave it out. Signed in to the console, leave it out: it is you.

Responses

200 Successful response

keystringrequired
valid_fromstringrequired
rerun_idstringrequired
The re-run this change queued: the answers dated from valid_from on that read the setting are issued again where it changes them, with one checks.rerun alert. A change from today on reaches none given before.
valueany

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
413The request's body is larger than the operation takes, refused before any of it is read (body-too-large): a policy's files at most 5 MB, any other body 1 MB - and an uploaded file at most 20 MB (file-too-large).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

GET/v1/meScope rules:read

Who is calling, for which account, and what it may do

The account your key belongs to - with the country it is established in, the currency its books are kept in, how many years its checks are kept and, for an account opened by signing up, the terms its person accepted - whether this request acts in live or in test, the scopes the key carries, and for a key made for an agent, the agent it acts as. The console reads the same answer for the person signed in to it, whose role decides their scopes.

Responses

200 Successful response

accountAccountrequired
9 fields
- idstringrequired
- slugstringrequired
- namestringrequired
- test_onlybooleanrequired
  true for an account that holds test data only: the sandbox. Every other has live and test.
- retention_yearsintegerrequired
  How many years its checks are kept: the period its country's law sets for its records, stated when the account was opened. GET /v1/checks/{id} reproduces an answer for it.
- countrystring or null
  Where the company is established, as an ISO 3166-1 code: US, AE, DE.
- currencystring or null
  The currency its books are kept in, as an ISO 4217 code: a playbook drafted for it states its limits in this one where its document names none. Never taken from the country: a company may keep its books in another.
- termsTermsAccepted or null
  The terms of Himmel's the account's person accepted - opening it by signing up, or, for an account a builder opened, joining it as its owner - the latest, where its admins have accepted several. Null for an account opened with us, whose terms are in its contract, and for one a builder opened until its owner joins.
  3 fields
  versionstringrequired
  The version accepted, as GET /v1/terms gives it.
  accepted_bystringrequired
  The Himmel id of the person who accepted them.
  accepted_atstringrequired
- opened_byOpenedBy or null
  The account that opened yours, for one a builder opened: its agents act for you, and it registers them and makes their keys here - never more. Null for an account opened with us or by signing up.
  4 fields
  idstringrequired
  Its account's id: what builder says on its agents and keys.
  namestringrequired
  Its company's name.
  cut_off_atstring or null
  When your account cut it off, for good: it acts in your account no more - its agents act on, until you switch them off. Null while it may act.
  cut_off_bystring or null
  The Himmel id of the person who cut it off.
env"live" | "test"required
Where this request acts: a key's own environment, or for a person the account's own unless the request sent Himmel-Env: test.
callerIdentityrequired
4 fields
- kind"api_key" | "person"required
- idstringrequired
  The key's id, or the person's user id.
- role"tenant_admin" | "tenant_engineer" | "tenant_ops" | "author" or null
  A person's role, which decides their scopes. Null for a key.
- actorActor or null
  For a key made for an agent: the agent it acts as, which every check it sends records whatever the request says. Null for your account's own keys, which name who acts in each request, and for a person.
  3 fields
  kind"user" | "agent" | "system"required
  idstring or null
  on_behalf_ofstring or null
  The person an agent acted for.
scopeslist of stringrequired
What this caller may do: one scope per kind of call.

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

Alerts

GET/v1/alertsScope checks:read

What has changed since you last looked

Newest first. check.rechecked means an answer you were given has been issued again - payload.was and payload.now say what moved - and a caller that acted on the earlier answer learns it here. check.against_rules means an action reported as taken was not allowed by your own rules as taken - not_allowed, needs_approval, hand_to_a_person - one alert an action. check.rule_set_broken means an action that happened could not be checked, its rules unable to run on its facts: it is kept, counts in every total, and is answered not_covered until a version that can answer it is confirmed. check.handed_over means an agent asked about an action your rules hand to the person they name, who is told: one alert for each action and person. The others: a new version published, a probable match to answer, and confirmations still pending once a version is in force. Poll it; webhooks come later.

Parameters

typequery · string or null
statusquery · string or null
limitquery · integer

Responses

200 Successful response

alertslist of Alertrequired
9 fields
- alert_idstringrequired
- typestringrequired
  rule_set.version.published, check.rechecked, checks.rerun, recipient.probable_match, confirmation.overdue, check.against_rules, check.rule_set_broken or check.handed_over.
- payloadobjectrequired
  What changed: for rule_set.version.published, the rule_set, its version and the day it applies from (effective_from), the rules still pending, and by_user, the person of yours who published it, null for our law; for check.rechecked, was and now, and by_user, the person whose approval or decision issued it again, null for any other cause; for checks.rerun, its cause, how many answers it checked again (reissued) and changed (changed), how many of them are actions taken that now stand against your rules (against_rules), and checks, the query that lists them; for confirmation.overdue, the rule_set and version, the rules still pending, and how many answers wait on them (waiting); for check.against_rules, an action taken that your own rules did not allow as taken - the check_id of the answer that stands, transaction_id, effective_date, who acted (actor), the cause, whether it is emailed at once or in the day's summary (emailed), and against: each policy that said so, its rule_set, rule_version, the rule and its title, the outcome, and the approver it named, where it named one; for check.rule_set_broken, an action that happened whose rules could not run on its facts, kept and answered not_covered - the check_id, transaction_id, the rule_set its check named, effective_date and the answer's detail; for check.handed_over, an action an agent asked about that your rules hand to the person they name - the check_id that handed it over, transaction_id, action (its first booking), handed_to, effective_date, the agent (actor), and the policy that said so: rule_set, rule_version, the rule, its title and the outcome.
- status"open" | "acknowledged"required
- created_atstringrequired
- acknowledged_bystring or null
- acknowledged_atstring or null
- emailed_atstring or null
- emailed_tointeger or null
  How many people it was emailed to: your admins, and for check.against_rules the approvers it names as well - never the person whose own act it reports (by_user): 0 where they are your only admin; for check.handed_over the person it hands the action to alone. A person whose mail server refused their address is not counted, and the others are emailed all the same.

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

POST/v1/alerts/{alert_id}/acknowledgeScope checks:write

Mark an alert as seen

An alert has one status, shared by every caller of its environment, and is emailed to your admins whatever it is. acknowledged_by names who saw it: yourself, signed in; from one of the account's own keys, a person in the account, or nobody. A key made for an agent names nobody but itself, and naming anybody is 422 invalid-request (not_the_keys).

Parameters

alert_idpath · stringrequired
Idempotency-Keyheader · string or null
Makes a retry safe: the same key with the same request within 24 hours gets the first answer again, and nothing is done twice. The same key with a different request is 409 idempotency-conflict. Keys are per environment and per path.

Request body · application/json

acknowledged_bystring or null
Who did it, when your key acts for a person: their Himmel id, which the console's Developers page shows them, and Settings' People an admin. They must be in your account, with a role that could do this themselves, and the record keeps it as your key's claim. A key made for an agent names nobody but itself: leave it out. Signed in to the console, leave it out: it is you.

Responses

200 Successful response

alert_idstringrequired
status"acknowledged"required

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
409The request conflicts with what is stored: see detail.
413The request's body is larger than the operation takes, refused before any of it is read (body-too-large): a policy's files at most 5 MB, any other body 1 MB - and an uploaded file at most 20 MB (file-too-large).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

Policies

GET/v1/policiesScope rules:read

This account's policies and their versions

Each policy with every version: its status, and the rules still waiting for your rule owner.

Needs a key with the scope rules:read. What it reads is your whole account's, so a key made for an agent, which reads its own agent's alone, gets 403 insufficient-scope.

Responses

200 Successful response

policieslist of PolicyListItemrequired
4 fields
- rule_setstringrequired
- titlestringrequired
- domainstringrequired
- versionslist of PolicyVersionSummaryrequired
  10 fields
  policy_idstringrequired
  rule_setstringrequired
  versionstringrequired
  statusstringrequired
  effective_fromstringrequired
  rulesintegerrequired
  pending_confirmationlist of stringrequired
  flaggedlist of stringrequired
  superseded_bystring or null
  filled_fromFilledFrom or null
  The template that filled this version and the figures it was filled with; null for one posted as files or drafted from a document.
  3 fields
  templatestringrequired
  The template's name, as GET /v1/templates lists it.
  versionstringrequired
  The template's own version when it filled this one.
  valuesobjectrequired
  Each blank's figure, by its name: money as {amount, currency}, the rest whole numbers.

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

POST/v1/policiesScope policies:write

Post a policy as a draft version: its files, or a template filled with your figures

A policy is a rule set of your own, laid out like any other: ruleset.yaml and the files under rules/, tests/ and sources/. It is stored as a draft however it lints, and checks says what would stop it being published. It sits on our law set for its domain and country where we hold one; where we hold none it stands alone, and says what is allowed, what needs whose approval and what a named person decides - no consequence, and nothing read from the law. Or from a template (GET /v1/templates): template and values in place of files, every blank your figure, in your account's currency, and every choice your option. Its document, rules and worked examples say your figures, and it is posted as a draft your rule owner confirms rule by rule - as a new policy's 1.0.0, or the next version of the one you have; a draft of it already there is 409 and is filled again with PUT. filled_from says what filled it. Idempotent on Idempotency-Key.

Needs a key with the scope policies:write. It changes what your account has decided, which live and test share, so it is done from live: in an account with a live side, a test key gets 403 live-only.

Parameters

Idempotency-Keyheader · string or null
Makes a retry safe: the same key with the same request within 24 hours gets the first answer again, and nothing is done twice. The same key with a different request is 409 idempotency-conflict. Keys are per environment and per path.

Request body · application/json

filesmap of string or null
Each file's path within the rule set, and its text - the same layout as any rule set version. Posted as a draft; status: draft in ruleset.yaml. Leave it out to fill a template instead.
templatestring or null
One of our templates, by its name (GET /v1/templates): filled with values, it is your policy's document, rules and worked examples, posted as a draft for your rule owner to confirm. In place of files.
valuesobject or null
Every blank of the template and your figure for it, by the blank's name: money as an integer amount in minor units with your account's currency, days, percent and counts as whole numbers - and every choice and the value of the option you pick, by the choice's name. Each is required: the template proposes no figure and no choice.
by_userstring or null
Who did it, when your key acts for a person: their Himmel id, which the console's Developers page shows them, and Settings' People an admin. They must be in your account, with a role that could do this themselves, and the record keeps it as your key's claim. A key made for an agent names nobody but itself: leave it out. Signed in to the console, leave it out: it is you.

Responses

200 Successful response

policy_idstringrequired
rule_setstringrequired
versionstringrequired
statusstringrequired
effective_fromstringrequired
rulesintegerrequired
pending_confirmationlist of stringrequired
flaggedlist of stringrequired
filled_fromFilledFrom or nullrequired
The template that filled this version and the figures it was filled with; null for one posted as files or drafted from a document.
3 fields
- templatestringrequired
  The template's name, as GET /v1/templates lists it.
- versionstringrequired
  The template's own version when it filled this one.
- valuesobjectrequired
  Each blank's figure, by its name: money as {amount, currency}, the rest whole numbers.
titlestringrequired
domainstringrequired
jurisdictionslist of stringrequired
sits_onlist of stringrequired
The law versions it is layered over, rule_set@version. Empty for a policy that stands alone: one for a domain and country we hold no law for, which states outcomes only.
filesmap of stringrequired
checksPublishChecksrequired
Everything publishing would run, run now.
6 fields
- publishablebooleanrequired
- blockinglist of PublishFindingrequired
  11 fields
  checkstringrequired
  lint, consequence, coverage, cases or floor.
  codestring or null
  rulestring or null
  casestring or null
  messagestring or null
  failureslist of string or null
  lawstring or null
  law_rulestring or null
  policy_rulestring or null
  owedany
  paidany
- warningslist of PublishFindingrequired
  11 fields
  checkstringrequired
  lint, consequence, coverage, cases or floor.
  codestring or null
  rulestring or null
  casestring or null
  messagestring or null
  failureslist of string or null
  lawstring or null
  law_rulestring or null
  policy_rulestring or null
  owedany
  paidany
- casesCaseCountsrequired
  2 fields
  passedintegerrequired
  failedintegerrequired
- coveragemap of integerrequired
  How many cases reach each rule.
- floorFloorSummaryrequired
  2 fields
  lawsintegerrequired
  payments_comparedintegerrequired
drafted_fromDraftedFrom or nullrequired
The document this version was last drafted from; null for one posted as files.
5 fields
- document_idstringrequired
- filenamestringrequired
- titlestringrequired
- created_atstringrequired
  When the document was uploaded.
- drafted_atstringrequired
  When the drafting that wrote this version began.
review_itemslist of ReviewItemrequired
What its latest drafting raised - examples the two drafts decide differently, holes the third pass found, cases that fail, examples a rule could not answer once altered - and each flag of a rule that stands flagged.
5 fields
- review_itemstringrequired
- kindstringrequired
- statusstringrequired
- payloadobjectrequired
- created_atstring or null
superseded_bystring or null

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
409The request conflicts with what is stored: see detail.
413The request's body is larger than the operation takes, refused before any of it is read (body-too-large): a policy's files at most 5 MB, any other body 1 MB - and an uploaded file at most 20 MB (file-too-large).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

GET/v1/templatesScope rules:read

The templates a policy can be filled from

Each of our templates: what it is for, its blanks - each with its measure, the clauses that say it and the least and most it takes - the order its words put them in, its choices - a part you pick between its words, each with its options - the settings its rules read, and its document with each blank and choice shown by its name. Every figure is a blank and every choice yours: a template proposes none. Fill one with POST /v1/policies, template and values in place of files.

Needs a key with the scope rules:read. What it reads is your whole account's, so a key made for an agent, which reads its own agent's alone, gets 403 insufficient-scope.

Responses

200 Successful response

templateslist of Templaterequired
12 fields
- templatestringrequired
  Its name: what POST /v1/policies takes as template.
- versionstringrequired
- titlestringrequired
- summarystringrequired
- languagestringrequired
  The language its document, rules and examples are written in.
- policystringrequired
  The policy a filling is posted as: policy.<your slug>.<policy>.
- domainstringrequired
- blankslist of TemplateBlankrequired
  Every figure it needs, each yours to fill: it proposes none.
  6 fields
  namestringrequired
  The blank's name, as values gives its figure.
  kind"money" | "days" | "percent" | "count"required
  Its measure: money, an integer amount in your account's currency's minor units with that currency; days, whole percent or a count of things, a whole number.
  clauseslist of stringrequired
  The clauses of the template's document that say it.
  saysstringrequired
  What the figure is, in words.
  minimumintegerrequired
  The least it takes - for money, in minor units.
  maximumintegerrequired
  The most it takes - for money, in minor units.
- orderlist of TemplateOrderrequired
  The order its words put figures in: a filling out of it is refused, naming the clauses, never mended.
  5 fields
  lowerstringrequired
  upperstringrequired
  strictbooleanrequired
  Whether upper must be above lower, not only at least it.
  clauseslist of stringrequired
  saysstringrequired
- choiceslist of TemplateChoicerequired
  Each part of the playbook you pick between its words - for online_shop_support, what becomes of the AI assistant's refund above its own limit (clause 2.7) - each yours to pick: it proposes none.
  4 fields
  namestringrequired
  The choice's name, as values gives the option picked.
  clauseslist of stringrequired
  The clauses of the template's document it decides.
  saysstringrequired
  What it decides, in words.
  optionslist of TemplateOptionrequired
  What it may be: one of them, yours to pick.
  2 fields
  valuestringrequired
  What values gives the choice, picking this one.
  saysstringrequired
  What it does, in words.
- settingslist of TemplateSettingrequired
  The settings its rules read - people and a date, which your rule owner names.
  3 fields
  namestringrequired
  typestringrequired
  saysstringrequired
- documentstringrequired
  Its document, each blank and each choice shown by its name in brackets: [refund_days].

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

GET/v1/policies/documentsScope rules:read

This account's uploaded policy documents

Needs a key with the scope rules:read. What it reads is your whole account's, so a key made for an agent, which reads its own agent's alone, gets 403 insufficient-scope.

Responses

200 Successful response

documentslist of PolicyDocumentListItemrequired
Newest first.
7 fields
- document_idstringrequired
- rule_setstringrequired
- domainstringrequired
- titlestringrequired
- filenamestringrequired
- statusstringrequired
- created_atstringrequired

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

POST/v1/policies/documentsScope policies:write

Upload a policy document: stored masked, never drafted yet

PDF, DOCX or Markdown. List every name in it to hide, one names field each. Those names, every name your account's documents hid before, every person of your account, every word that reads as a name - a given name followed by a capitalised word - and every email address, IBAN and phone number are replaced by placeholders before anything is stored; the file itself is not kept. Read the masked text that comes back: a single first name, or a name written otherwise, is still yours to find, and a word hidden as a name that is none is shown again with …/shown. Nothing is drafted until you ask.

Parameters

Idempotency-Keyheader · string or null
Makes a retry safe: the same key with the same request within 24 hours gets the first answer again, and nothing is done twice. The same key with a different request is 409 idempotency-conflict. Keys are per environment and per path.

Request body · multipart/form-data

filestringrequired
policystringrequired
The name it drafts to: policy.<your slug>.<policy>
domainstringrequired
Your name for its set of books - customer_support, say, or a law set's domain where it is to sit on one: short, lower case, parts joined by dots
titlestring
nameslist of string or null
Every name in the document to hide, once per form field, as written.
by_userstring or null
Who did it, when your key acts for a person: their Himmel id, which the console's Developers page shows them, and Settings' People an admin. They must be in your account, with a role that could do this themselves, and the record keeps it as your key's claim. A key made for an agent names nobody but itself: leave it out. Signed in to the console, leave it out: it is you.

Responses

200 Successful response

document_idstringrequired
rule_setstringrequired
domainstringrequired
titlestringrequired
filenamestringrequired
media_typestringrequired
sha256stringrequired
The file's hash. The file itself is not kept.
statusstringrequired
uploaded, drafting, drafted or failed.
textstringrequired
The masked text, one anchor per clause.
clauseslist of stringrequired
maskedlist of MaskedItemrequired
4 fields
- placeholderstringrequired
  What stands in the text, such as [[NAME-1]].
- kindstringrequired
  name, email, iban or phone.
- why"listed" | "person" | "found" | "shape"required
  Why it was hidden: listed - on this upload, or on an earlier document of your account; person - a person of your account, by the name Himmel keeps for them; found - it reads as a name, a given name followed by a capitalised word, and you show it again where it is none; shape - an email address, an IBAN or a phone number.
- valuestring or null
  For a word hidden because it reads as a name, the word, so that you can tell whether it is one: on GET, to a person signed in who is shown names (an admin or ops). Null otherwise - every other value, and to a key, is never returned.
draftslist of objectrequired
One entry per draft run: each call's prompt, prompt_hash, model_ref, outcome and tokens (usage) - the terms (terms), each draft (attempts, each saying where it departs from the terms), the examples asked for (examples) and the hunt for gaps (adversarial) - the version it wrote (policy_id), how many examples the two drafts decide differently (disagreements) and how many one could not run (not_compared), the probe (probe), what publishing would still ask once every rule is confirmed (once_confirmed), the seconds each step took (took), and the ids of the review items it raised (review_items). A run that could not go on says outcome: stopped, why in words (reason), what stopped it (error) and the calls it made (calls): the document is failed, and can be drafted again.
review_itemslist of ReviewItemrequired
5 fields
- review_itemstringrequired
- kindstringrequired
- statusstringrequired
- payloadobjectrequired
- created_atstring or null
created_atstringrequired
updated_atstringrequired
progressDraftingProgress or null
Where its drafting is, while one is under way (drafting); null otherwise.
9 fields
- step"queued" | "terms" | "drafts" | "examples" | "gaps" | "again" | "waiting"required
  queued - asked for, no worker has taken it up yet; terms - the playbook's terms, what every rule and example will name; drafts - the two drafts, side by side; examples - the examples a rule is short of; gaps - the hunt for gaps; again - each rule its owner flagged with a comment, drafted again alone; waiting - to try again (retry_at, why).
- sincestringrequired
  When this step began.
- job_idstring or null
- attemptinteger or null
  Which attempt this is, of of.
- ofinteger or null
- started_atstring or null
  When this attempt began.
- callsmap of CallProgress
  Each call of the step, by its prompt - terms, draft_a, draft_b, ... - or, for a rule drafted again, by the rule's id.
- retry_atstring or null
  Waiting: when the next attempt begins.
- whystring or null
  Waiting: why the last attempt brought no reply.
nextstring or null

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
413The request's body is larger than the operation takes, refused before any of it is read (body-too-large): a policy's files at most 5 MB, any other body 1 MB - and an uploaded file at most 20 MB (file-too-large).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

GET/v1/policies/documents/{document_id}Scope rules:read

One document, masked, and its drafts

The masked text, its clauses, what was masked and why, and what drafting has made of it. No value masked is returned, but a word hidden because it reads as a name: to a person signed in who is shown names - an admin or ops - so that they can tell whether it is one.

Needs a key with the scope rules:read. What it reads is your whole account's, so a key made for an agent, which reads its own agent's alone, gets 403 insufficient-scope.

Parameters

document_idpath · stringrequired

Responses

200 Successful response

document_idstringrequired
rule_setstringrequired
domainstringrequired
titlestringrequired
filenamestringrequired
media_typestringrequired
sha256stringrequired
The file's hash. The file itself is not kept.
statusstringrequired
uploaded, drafting, drafted or failed.
textstringrequired
The masked text, one anchor per clause.
clauseslist of stringrequired
maskedlist of MaskedItemrequired
4 fields
- placeholderstringrequired
  What stands in the text, such as [[NAME-1]].
- kindstringrequired
  name, email, iban or phone.
- why"listed" | "person" | "found" | "shape"required
  Why it was hidden: listed - on this upload, or on an earlier document of your account; person - a person of your account, by the name Himmel keeps for them; found - it reads as a name, a given name followed by a capitalised word, and you show it again where it is none; shape - an email address, an IBAN or a phone number.
- valuestring or null
  For a word hidden because it reads as a name, the word, so that you can tell whether it is one: on GET, to a person signed in who is shown names (an admin or ops). Null otherwise - every other value, and to a key, is never returned.
draftslist of objectrequired
One entry per draft run: each call's prompt, prompt_hash, model_ref, outcome and tokens (usage) - the terms (terms), each draft (attempts, each saying where it departs from the terms), the examples asked for (examples) and the hunt for gaps (adversarial) - the version it wrote (policy_id), how many examples the two drafts decide differently (disagreements) and how many one could not run (not_compared), the probe (probe), what publishing would still ask once every rule is confirmed (once_confirmed), the seconds each step took (took), and the ids of the review items it raised (review_items). A run that could not go on says outcome: stopped, why in words (reason), what stopped it (error) and the calls it made (calls): the document is failed, and can be drafted again.
review_itemslist of ReviewItemrequired
5 fields
- review_itemstringrequired
- kindstringrequired
- statusstringrequired
- payloadobjectrequired
- created_atstring or null
created_atstringrequired
updated_atstringrequired
progressDraftingProgress or null
Where its drafting is, while one is under way (drafting); null otherwise.
9 fields
- step"queued" | "terms" | "drafts" | "examples" | "gaps" | "again" | "waiting"required
  queued - asked for, no worker has taken it up yet; terms - the playbook's terms, what every rule and example will name; drafts - the two drafts, side by side; examples - the examples a rule is short of; gaps - the hunt for gaps; again - each rule its owner flagged with a comment, drafted again alone; waiting - to try again (retry_at, why).
- sincestringrequired
  When this step began.
- job_idstring or null
- attemptinteger or null
  Which attempt this is, of of.
- ofinteger or null
- started_atstring or null
  When this attempt began.
- callsmap of CallProgress
  Each call of the step, by its prompt - terms, draft_a, draft_b, ... - or, for a rule drafted again, by the rule's id.
- retry_atstring or null
  Waiting: when the next attempt begins.
- whystring or null
  Waiting: why the last attempt brought no reply.
nextstring or null

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

POST/v1/policies/documents/{document_id}/draftScope policies:write

Draft rules from a document whose masked text you have read

An optional step: drafting uses a language model on the masked text, and takes minutes, so it runs as a job - the document says drafted or failed when it is done. Before it is queued the stored text is masked again, where nothing drafted from it cites it yet: against your account's people as they are now, the names your other documents hid, and what reads as a name - so a colleague who joined after the upload is hidden too. Two drafts are made independently and compared by what they answer; where they differ, and every hole a third pass finds, becomes a review item. A document is drafted over the law your account has switched on for its domain, or, with none, as your own rules standing alone - covering wherever you act, and dated by a fact of their own. Nothing drafted runs until your rule owner confirms it, and confirming a rule sets the examples drafted for it. A policy changes through its document: drafting a revised one gives the drafter the version it revises, and replaces the policy's draft in place where it has one, so a rule that reads as it did beside the same clause keeps its confirmation. A call that fails costs that call: each reply is kept as it comes back, a retry starts from the first call not done, and an error no retry mends - a key refused, an account out of credit - stops the drafting at once. A drafting that stops says why in its entry of drafts, and the document can be drafted again, reading the replies already back while it reads the same. One document of a policy is drafted at a time (409). Answers 503 in a deployment with no model configured; a policy can always be posted as files instead.

Parameters

document_idpath · stringrequired
Idempotency-Keyheader · string or null
Makes a retry safe: the same key with the same request within 24 hours gets the first answer again, and nothing is done twice. The same key with a different request is 409 idempotency-conflict. Keys are per environment and per path.

Request body · application/json

by_userstring or null
Who did it, when your key acts for a person: their Himmel id, which the console's Developers page shows them, and Settings' People an admin. They must be in your account, with a role that could do this themselves, and the record keeps it as your key's claim. A key made for an agent names nobody but itself: leave it out. Signed in to the console, leave it out: it is you.

Responses

202 The draft is queued.

document_idstringrequired
status"drafting"required
job_idstringrequired

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
409The request conflicts with what is stored: see detail.
413The request's body is larger than the operation takes, refused before any of it is read (body-too-large): a policy's files at most 5 MB, any other body 1 MB - and an uploaded file at most 20 MB (file-too-large).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.
503An optional part of the service is not configured in this deployment, or a service it relies on did not answer: type says which.

POST/v1/policies/documents/{document_id}/namesScope policies:write

Hide more names in a document not drafted yet

Each name is masked where it stands in the stored text, as the upload masks one: the name to the vault, a placeholder in its place, and the clauses read again. For a document not drafted - uploaded, or failed - so a name you find reading the masked text back is hidden before anything reaches a model; one drafted or being drafted is 409, since what was drafted from it cites its text as it was. Idempotent on Idempotency-Key.

Parameters

document_idpath · stringrequired
Idempotency-Keyheader · string or null
Makes a retry safe: the same key with the same request within 24 hours gets the first answer again, and nothing is done twice. The same key with a different request is 409 idempotency-conflict. Keys are per environment and per path.

Request body · application/json

nameslist of stringrequired
Each name to hide, as the document writes it; another way of writing it is another entry.
by_userstring or null
Who did it, when your key acts for a person: their Himmel id, which the console's Developers page shows them, and Settings' People an admin. They must be in your account, with a role that could do this themselves, and the record keeps it as your key's claim. A key made for an agent names nobody but itself: leave it out. Signed in to the console, leave it out: it is you.

Responses

200 Successful response

document_idstringrequired
rule_setstringrequired
domainstringrequired
titlestringrequired
filenamestringrequired
media_typestringrequired
sha256stringrequired
The file's hash. The file itself is not kept.
statusstringrequired
uploaded, drafting, drafted or failed.
textstringrequired
The masked text, one anchor per clause.
clauseslist of stringrequired
maskedlist of MaskedItemrequired
4 fields
- placeholderstringrequired
  What stands in the text, such as [[NAME-1]].
- kindstringrequired
  name, email, iban or phone.
- why"listed" | "person" | "found" | "shape"required
  Why it was hidden: listed - on this upload, or on an earlier document of your account; person - a person of your account, by the name Himmel keeps for them; found - it reads as a name, a given name followed by a capitalised word, and you show it again where it is none; shape - an email address, an IBAN or a phone number.
- valuestring or null
  For a word hidden because it reads as a name, the word, so that you can tell whether it is one: on GET, to a person signed in who is shown names (an admin or ops). Null otherwise - every other value, and to a key, is never returned.
draftslist of objectrequired
One entry per draft run: each call's prompt, prompt_hash, model_ref, outcome and tokens (usage) - the terms (terms), each draft (attempts, each saying where it departs from the terms), the examples asked for (examples) and the hunt for gaps (adversarial) - the version it wrote (policy_id), how many examples the two drafts decide differently (disagreements) and how many one could not run (not_compared), the probe (probe), what publishing would still ask once every rule is confirmed (once_confirmed), the seconds each step took (took), and the ids of the review items it raised (review_items). A run that could not go on says outcome: stopped, why in words (reason), what stopped it (error) and the calls it made (calls): the document is failed, and can be drafted again.
review_itemslist of ReviewItemrequired
5 fields
- review_itemstringrequired
- kindstringrequired
- statusstringrequired
- payloadobjectrequired
- created_atstring or null
created_atstringrequired
updated_atstringrequired
progressDraftingProgress or null
Where its drafting is, while one is under way (drafting); null otherwise.
9 fields
- step"queued" | "terms" | "drafts" | "examples" | "gaps" | "again" | "waiting"required
  queued - asked for, no worker has taken it up yet; terms - the playbook's terms, what every rule and example will name; drafts - the two drafts, side by side; examples - the examples a rule is short of; gaps - the hunt for gaps; again - each rule its owner flagged with a comment, drafted again alone; waiting - to try again (retry_at, why).
- sincestringrequired
  When this step began.
- job_idstring or null
- attemptinteger or null
  Which attempt this is, of of.
- ofinteger or null
- started_atstring or null
  When this attempt began.
- callsmap of CallProgress
  Each call of the step, by its prompt - terms, draft_a, draft_b, ... - or, for a rule drafted again, by the rule's id.
- retry_atstring or null
  Waiting: when the next attempt begins.
- whystring or null
  Waiting: why the last attempt brought no reply.
nextstring or null

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
409The request conflicts with what is stored: see detail.
413The request's body is larger than the operation takes, refused before any of it is read (body-too-large): a policy's files at most 5 MB, any other body 1 MB - and an uploaded file at most 20 MB (file-too-large).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

POST/v1/policies/documents/{document_id}/shownScope policies:write

Show again a word hidden as a name that is none

A word that reads as a name - a given name followed by a capitalised word - is hidden at upload without being listed (why: found), and GET shows it to an admin or ops. Where one is no name - a branch called after a city, a product - list its placeholder here: it is put back where it stands, as it was first written, the clauses are read again, and it is not hidden for reading as a name in this document again. A name you listed, a person of your account and an address or a number stay hidden (422 invalid-request, not_read_as_a_name). For a document not drafted, uploaded or failed; one drafting or drafted is 409, since what was drafted from it cites its text. Idempotent on Idempotency-Key.

Parameters

document_idpath · stringrequired
Idempotency-Keyheader · string or null
Makes a retry safe: the same key with the same request within 24 hours gets the first answer again, and nothing is done twice. The same key with a different request is 409 idempotency-conflict. Keys are per environment and per path.

Request body · application/json

placeholderslist of stringrequired
Each word's placeholder, as the text writes it: [[NAME-3]]. Only a word hidden because it reads as a name (why: found) is shown again.
by_userstring or null
Who did it, when your key acts for a person: their Himmel id, which the console's Developers page shows them, and Settings' People an admin. They must be in your account, with a role that could do this themselves, and the record keeps it as your key's claim. A key made for an agent names nobody but itself: leave it out. Signed in to the console, leave it out: it is you.

Responses

200 Successful response

document_idstringrequired
rule_setstringrequired
domainstringrequired
titlestringrequired
filenamestringrequired
media_typestringrequired
sha256stringrequired
The file's hash. The file itself is not kept.
statusstringrequired
uploaded, drafting, drafted or failed.
textstringrequired
The masked text, one anchor per clause.
clauseslist of stringrequired
maskedlist of MaskedItemrequired
4 fields
- placeholderstringrequired
  What stands in the text, such as [[NAME-1]].
- kindstringrequired
  name, email, iban or phone.
- why"listed" | "person" | "found" | "shape"required
  Why it was hidden: listed - on this upload, or on an earlier document of your account; person - a person of your account, by the name Himmel keeps for them; found - it reads as a name, a given name followed by a capitalised word, and you show it again where it is none; shape - an email address, an IBAN or a phone number.
- valuestring or null
  For a word hidden because it reads as a name, the word, so that you can tell whether it is one: on GET, to a person signed in who is shown names (an admin or ops). Null otherwise - every other value, and to a key, is never returned.
draftslist of objectrequired
One entry per draft run: each call's prompt, prompt_hash, model_ref, outcome and tokens (usage) - the terms (terms), each draft (attempts, each saying where it departs from the terms), the examples asked for (examples) and the hunt for gaps (adversarial) - the version it wrote (policy_id), how many examples the two drafts decide differently (disagreements) and how many one could not run (not_compared), the probe (probe), what publishing would still ask once every rule is confirmed (once_confirmed), the seconds each step took (took), and the ids of the review items it raised (review_items). A run that could not go on says outcome: stopped, why in words (reason), what stopped it (error) and the calls it made (calls): the document is failed, and can be drafted again.
review_itemslist of ReviewItemrequired
5 fields
- review_itemstringrequired
- kindstringrequired
- statusstringrequired
- payloadobjectrequired
- created_atstring or null
created_atstringrequired
updated_atstringrequired
progressDraftingProgress or null
Where its drafting is, while one is under way (drafting); null otherwise.
9 fields
- step"queued" | "terms" | "drafts" | "examples" | "gaps" | "again" | "waiting"required
  queued - asked for, no worker has taken it up yet; terms - the playbook's terms, what every rule and example will name; drafts - the two drafts, side by side; examples - the examples a rule is short of; gaps - the hunt for gaps; again - each rule its owner flagged with a comment, drafted again alone; waiting - to try again (retry_at, why).
- sincestringrequired
  When this step began.
- job_idstring or null
- attemptinteger or null
  Which attempt this is, of of.
- ofinteger or null
- started_atstring or null
  When this attempt began.
- callsmap of CallProgress
  Each call of the step, by its prompt - terms, draft_a, draft_b, ... - or, for a rule drafted again, by the rule's id.
- retry_atstring or null
  Waiting: when the next attempt begins.
- whystring or null
  Waiting: why the last attempt brought no reply.
nextstring or null

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
409The request conflicts with what is stored: see detail.
413The request's body is larger than the operation takes, refused before any of it is read (body-too-large): a policy's files at most 5 MB, any other body 1 MB - and an uploaded file at most 20 MB (file-too-large).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

POST/v1/policies/documents/{document_id}/withdrawScope policies:write

Withdraw a document never sent to drafting

The document is removed, and its text with it; the audit log keeps that it was withdrawn and by whom, never what it said. One sent to drafting is 409: what was drafted from it cites it. Idempotent on Idempotency-Key.

Parameters

document_idpath · stringrequired
Idempotency-Keyheader · string or null
Makes a retry safe: the same key with the same request within 24 hours gets the first answer again, and nothing is done twice. The same key with a different request is 409 idempotency-conflict. Keys are per environment and per path.

Request body · application/json

by_userstring or null
Who did it, when your key acts for a person: their Himmel id, which the console's Developers page shows them, and Settings' People an admin. They must be in your account, with a role that could do this themselves, and the record keeps it as your key's claim. A key made for an agent names nobody but itself: leave it out. Signed in to the console, leave it out: it is you.

Responses

200 Successful response

document_idstringrequired
status"withdrawn"required

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
409The request conflicts with what is stored: see detail.
413The request's body is larger than the operation takes, refused before any of it is read (body-too-large): a policy's files at most 5 MB, any other body 1 MB - and an uploaded file at most 20 MB (file-too-large).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

GET/v1/policies/{policy_id}Scope rules:read

One version: its files, and what blocks publishing it

checks runs everything publishing would run, now: lint, the consequence check, the policy's own cases over the law (or on their own, for a policy that stands alone), ten cases and a worked example per rule, and the law floor.

Needs a key with the scope rules:read. What it reads is your whole account's, so a key made for an agent, which reads its own agent's alone, gets 403 insufficient-scope.

Parameters

policy_idpath · stringrequired

Responses

200 Successful response

policy_idstringrequired
rule_setstringrequired
versionstringrequired
statusstringrequired
effective_fromstringrequired
rulesintegerrequired
pending_confirmationlist of stringrequired
flaggedlist of stringrequired
filled_fromFilledFrom or nullrequired
The template that filled this version and the figures it was filled with; null for one posted as files or drafted from a document.
3 fields
- templatestringrequired
  The template's name, as GET /v1/templates lists it.
- versionstringrequired
  The template's own version when it filled this one.
- valuesobjectrequired
  Each blank's figure, by its name: money as {amount, currency}, the rest whole numbers.
titlestringrequired
domainstringrequired
jurisdictionslist of stringrequired
sits_onlist of stringrequired
The law versions it is layered over, rule_set@version. Empty for a policy that stands alone: one for a domain and country we hold no law for, which states outcomes only.
filesmap of stringrequired
checksPublishChecksrequired
Everything publishing would run, run now.
6 fields
- publishablebooleanrequired
- blockinglist of PublishFindingrequired
  11 fields
  checkstringrequired
  lint, consequence, coverage, cases or floor.
  codestring or null
  rulestring or null
  casestring or null
  messagestring or null
  failureslist of string or null
  lawstring or null
  law_rulestring or null
  policy_rulestring or null
  owedany
  paidany
- warningslist of PublishFindingrequired
  11 fields
  checkstringrequired
  lint, consequence, coverage, cases or floor.
  codestring or null
  rulestring or null
  casestring or null
  messagestring or null
  failureslist of string or null
  lawstring or null
  law_rulestring or null
  policy_rulestring or null
  owedany
  paidany
- casesCaseCountsrequired
  2 fields
  passedintegerrequired
  failedintegerrequired
- coveragemap of integerrequired
  How many cases reach each rule.
- floorFloorSummaryrequired
  2 fields
  lawsintegerrequired
  payments_comparedintegerrequired
drafted_fromDraftedFrom or nullrequired
The document this version was last drafted from; null for one posted as files.
5 fields
- document_idstringrequired
- filenamestringrequired
- titlestringrequired
- created_atstringrequired
  When the document was uploaded.
- drafted_atstringrequired
  When the drafting that wrote this version began.
review_itemslist of ReviewItemrequired
What its latest drafting raised - examples the two drafts decide differently, holes the third pass found, cases that fail, examples a rule could not answer once altered - and each flag of a rule that stands flagged.
5 fields
- review_itemstringrequired
- kindstringrequired
- statusstringrequired
- payloadobjectrequired
- created_atstring or null
superseded_bystring or null

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

PUT/v1/policies/{policy_id}Scope policies:write

New files for a draft, or the draft filled again from its template

A draft changes until it is published; a published version never does. Confirmations of rules the edit did not touch are kept. template and values in place of files fill the draft again from a template - a figure changed, say - under its own version: the rules the change reaches wait for your rule owner again, the rest keep their confirmations.

Parameters

policy_idpath · stringrequired

Request body · application/json

filesmap of string or null
Each file's path within the rule set, and its text - the same layout as any rule set version. Posted as a draft; status: draft in ruleset.yaml. Leave it out to fill a template instead.
templatestring or null
One of our templates, by its name (GET /v1/templates): filled with values, it is your policy's document, rules and worked examples, posted as a draft for your rule owner to confirm. In place of files.
valuesobject or null
Every blank of the template and your figure for it, by the blank's name: money as an integer amount in minor units with your account's currency, days, percent and counts as whole numbers - and every choice and the value of the option you pick, by the choice's name. Each is required: the template proposes no figure and no choice.
by_userstring or null
Who did it, when your key acts for a person: their Himmel id, which the console's Developers page shows them, and Settings' People an admin. They must be in your account, with a role that could do this themselves, and the record keeps it as your key's claim. A key made for an agent names nobody but itself: leave it out. Signed in to the console, leave it out: it is you.

Responses

200 Successful response

policy_idstringrequired
rule_setstringrequired
versionstringrequired
statusstringrequired
effective_fromstringrequired
rulesintegerrequired
pending_confirmationlist of stringrequired
flaggedlist of stringrequired
filled_fromFilledFrom or nullrequired
The template that filled this version and the figures it was filled with; null for one posted as files or drafted from a document.
3 fields
- templatestringrequired
  The template's name, as GET /v1/templates lists it.
- versionstringrequired
  The template's own version when it filled this one.
- valuesobjectrequired
  Each blank's figure, by its name: money as {amount, currency}, the rest whole numbers.
titlestringrequired
domainstringrequired
jurisdictionslist of stringrequired
sits_onlist of stringrequired
The law versions it is layered over, rule_set@version. Empty for a policy that stands alone: one for a domain and country we hold no law for, which states outcomes only.
filesmap of stringrequired
checksPublishChecksrequired
Everything publishing would run, run now.
6 fields
- publishablebooleanrequired
- blockinglist of PublishFindingrequired
  11 fields
  checkstringrequired
  lint, consequence, coverage, cases or floor.
  codestring or null
  rulestring or null
  casestring or null
  messagestring or null
  failureslist of string or null
  lawstring or null
  law_rulestring or null
  policy_rulestring or null
  owedany
  paidany
- warningslist of PublishFindingrequired
  11 fields
  checkstringrequired
  lint, consequence, coverage, cases or floor.
  codestring or null
  rulestring or null
  casestring or null
  messagestring or null
  failureslist of string or null
  lawstring or null
  law_rulestring or null
  policy_rulestring or null
  owedany
  paidany
- casesCaseCountsrequired
  2 fields
  passedintegerrequired
  failedintegerrequired
- coveragemap of integerrequired
  How many cases reach each rule.
- floorFloorSummaryrequired
  2 fields
  lawsintegerrequired
  payments_comparedintegerrequired
drafted_fromDraftedFrom or nullrequired
The document this version was last drafted from; null for one posted as files.
5 fields
- document_idstringrequired
- filenamestringrequired
- titlestringrequired
- created_atstringrequired
  When the document was uploaded.
- drafted_atstringrequired
  When the drafting that wrote this version began.
review_itemslist of ReviewItemrequired
What its latest drafting raised - examples the two drafts decide differently, holes the third pass found, cases that fail, examples a rule could not answer once altered - and each flag of a rule that stands flagged.
5 fields
- review_itemstringrequired
- kindstringrequired
- statusstringrequired
- payloadobjectrequired
- created_atstring or null
superseded_bystring or null

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
409The request conflicts with what is stored: see detail.
413The request's body is larger than the operation takes, refused before any of it is read (body-too-large): a policy's files at most 5 MB, any other body 1 MB - and an uploaded file at most 20 MB (file-too-large).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

POST/v1/policies/{policy_id}/publishScope policies:write

Publish a draft, if nothing stands in the way

Refused with policy-blocked and every finding in blocking when the policy would set a consequence the law decides, when one of its own cases does not come out as it says, when a rule has fewer than ten cases or no worked example (a case naming it), when it would pay less than the law says is owed, or while a drafted example waits for your rule owner to confirm the rule it is an example for. Otherwise the version is published, its drafted examples written as confirmed by the owner, and the one before it superseded. Its rules run once your rule owner confirms them. It applies from effective_from, which a version replacing a published one must give (422), never before that one's date.

Parameters

policy_idpath · stringrequired
Idempotency-Keyheader · string or null
Makes a retry safe: the same key with the same request within 24 hours gets the first answer again, and nothing is done twice. The same key with a different request is 409 idempotency-conflict. Keys are per environment and per path.

Request body · application/json

by_userstring or null
Who did it, when your key acts for a person: their Himmel id, which the console's Developers page shows them, and Settings' People an admin. They must be in your account, with a role that could do this themselves, and the record keeps it as your key's claim. A key made for an agent names nobody but itself: leave it out. Signed in to the console, leave it out: it is you.
changelogstring
What changed, and why, in a sentence or two.
effective_fromstring or null
The date the version applies from: an action of that date or later is checked against it. Required for a version that replaces a published one, and never before that one's date; a first version left without one applies from its own date, its document's. A date in the past is allowed: the actions since then are checked again under it once its rules are confirmed, and every earlier answer stays on record.

Responses

200 Successful response

policy_idstringrequired
rule_setstringrequired
versionstringrequired
status"published"required
effective_fromstringrequired
warningslist of PublishFindingrequired
11 fields
- checkstringrequired
  lint, consequence, coverage, cases or floor.
- codestring or null
- rulestring or null
- casestring or null
- messagestring or null
- failureslist of string or null
- lawstring or null
- law_rulestring or null
- policy_rulestring or null
- owedany
- paidany
supersedesstring or null
diffDiffSummary or null
4 fields
- changedintegerrequired
- addedintegerrequired
- removedintegerrequired
- unchangedintegerrequired

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
409The request conflicts with what is stored: see detail.
413The request's body is larger than the operation takes, refused before any of it is read (body-too-large): a policy's files at most 5 MB, any other body 1 MB - and an uploaded file at most 20 MB (file-too-large).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

POST/v1/policies/{policy_id}/evaluateScope check

Dry-run a version: the law, and the law with it

Send facts, or the id of a stored transaction, and see the law's answer beside the answer with this version layered over it - or, for a policy that stands alone, the policy's answer, with law_only null. A stored transaction is answered with the law its check was answered under, where it fell; a version for other countries than that one is not_covered there, and a transaction of another domain is refused. Nothing is stored, no recipient is created, and confirmations are not applied: it shows what the rules say. A retry is always safe, so it takes no Idempotency-Key.

Needs a key with the scope check. What it reads is your whole account's, so a key made for an agent, which reads its own agent's alone, gets 403 insufficient-scope.

Parameters

policy_idpath · stringrequired

Request body · application/json

factsobject or null
actorActorIn or null
Who acts, as a check's transaction.actor says it: left out, the caller, as a check would record it. A stored transaction says who acted itself, so not beside transaction_id.
3 fields
- kind"user" | "agent" | "system"
- idstring or null
  The agent's own identifier - or, for a person (kind: user), their Himmel id: from your account's own keys a person of your account (unknown_user, left_the_account).
- on_behalf_ofstring or null
  The person the agent acts for, as your own systems identify them: an opaque id, never a name or an email address. They need no account here.
transaction_idstring or null

Responses

200 Successful response

dry_runtruerequired
policy_idstringrequired
rule_setstringrequired
versionstringrequired
statusstringrequired
confirmationsstringrequired
law_onlyDeterminedAnswer | UndeterminedAnswer | NotCoveredAnswer | ContestedAnswer or nullrequired
The law's answer alone; null for a policy that stands alone.
one of 4
One of 4, told apart by state.
- effective_datestringrequired
  The date the rules were applied as of.
- as_ofstringrequired
  The moment the history was read.
- layersLayersrequired
  2 fields
  lawLayerAnswer or null
  The law's answer. Left out where no law set is part of the answer - your policy's alone, for a country we hold no law for or one your account has not switched on.
  12 fields
  rule_setstringrequired
  rule_versionstringrequired
  state"determined" | "undetermined_missing_facts" | "not_covered" | "contested"required
  outcomestring or null
  basisstring or null
  law, policy or goodwill.
  consequenceslist of Consequence or null
  not_checkedlist of NotChecked or null
  approverany
  Who a policy says must approve, where it names one.
  handed_toany
  Whom a policy hands the action to, where its rule names one: a person in your account, by Himmel id. Where an agent asked about the action, Himmel tells them (check.handed_over).
  tenant_facts_usedlist of string or null
  Your settings this answer read.
  reference_versionsmap of integer | string or null
  Which version of each reference table it read, such as dated VAT rates.
  waiting_onstring or null
  A policy rule that reads the law's answer waits for the law to settle: law.
  policieslist of LayerAnswer or null
  Your policies for this domain, in the order they ran.
  12 fields
  rule_setstringrequired
  rule_versionstringrequired
  state"determined" | "undetermined_missing_facts" | "not_covered" | "contested"required
  outcomestring or null
  basisstring or null
  law, policy or goodwill.
  consequenceslist of Consequence or null
  not_checkedlist of NotChecked or null
  approverany
  Who a policy says must approve, where it names one.
  handed_toany
  Whom a policy hands the action to, where its rule names one: a person in your account, by Himmel id. Where an agent asked about the action, Himmel tells them (check.handed_over).
  tenant_facts_usedlist of string or null
  Your settings this answer read.
  reference_versionsmap of integer | string or null
  Which version of each reference table it read, such as dated VAT rates.
  waiting_onstring or null
  A policy rule that reads the law's answer waits for the law to settle: law.
- engine_versionstringrequired
- recipientRecipientSummary or null
  4 fields
  resolutionstringrequired
  resolved, unresolved, probable_match or missing.
  recipient_idstring or null
  review_itemstring or null
  The open probable match, where there is one.
  fy_totalMoney or null
  This recipient's total for the fiscal year, where the answer's first rule set totals money per recipient per fiscal year: the recipient's other bookings of the year that it counts, as known when the answer was given - this one not included, and later ones too where it counts the whole year. Left out where no such total was read; history_used names every total an answer read.
  2 fields
  amountintegerrequired
  currencystringrequired
- history_usedlist of HistoryInput or null
  5 fields
  rule_setstringrequired
  inputstringrequired
  The rule set's name for this total, such as recipient_fy_gifts.
  countintegerrequired
  transactionslist of HistoryTransactionrequired
  2 fields
  transaction_idstringrequired
  effective_datestring or null
  totalMoney | integer | string or null
- not_checkedlist of NotChecked or null
  2 fields
  topicstringrequired
  reasonstringrequired
- citationslist of Citation or null
  4 fields
  sourcestringrequired
  The source's key within the rule set, such as estg.
  paragraphstring or null
  clausestring or null
  text_refstring or null
  The passage in the rule set's own copy of the source, sources/<file>#<anchor>.
- confirmationslist of ConfirmationUsed or null
  3 fields
  rulestringrequired
  confirmed_bystring or null
  confirmed_atstring or null
- decisionslist of DecisionRead or null
  Each question on this action a person decided, read as its answer: where the question's rule says what each answer leads to, a sign-off or an admin's override issues the action's answer again, and every answer to it after reads the decision while the rule asks the very same question. Left out where none was read.
  8 fields
  answerstringrequired
  The answer chosen, one of the question's candidates - or approved, for an approval.
  questionstring or null
  The question's id. Null for an approval, which answers none.
  rulestring or null
  The rule that raises the question, as it asks it. Null for an approval.
  decided_bystring or null
  Who decided: a person in your account, by id.
  method"sign_off" | "override" | "approval" or null
  A sign-off by the person the question names, an admin's override of it, or the approval of the person the action's answer named, asked by Himmel.
  resolution_idstring or null
  The decision's record, on the answer it was made on.
  leads_tostring or null
  What the answer led to: continue - on to the rules after the question, which gave the outcome - or the outcome it gives itself. Null for an approval, read from the first rule.
  approvalstring or null
  The fact the decision stood in for as its decider's approval - where the action recorded none, and the rule that gave the outcome read it - so one person who decides and approves is asked once. Null otherwise.
- recheckslist of Recheck or null
  The earlier answers this booking changed, each issued again before this one was given. Left out when it changed none, and on a proposal, which changes nothing until it is reported as executed.
  4 fields
  new_check_idstring or null
  supersedesstring or null
  booking_datestring or null
  outcomestring or null
- supersedes_check_idstring or null
  The earlier answer for the same transaction that this one replaces.
- recheck_reasonstring or null
  Why it was issued again: a later transaction, an action taken back (reversal) or corrected (correction), a link or split between recipients, a question raised about its recipient, the rules changing, a question on it decided (decision), or the action approved by the person its answer named (approval).
- tracelist of TraceStep or null
  Every rule reached, in order. Left out when the check asked explain: false.
  6 fields
  rulestringrequired
  stagestringrequired
  scope, outcome or consequence.
  matchedboolean or null
  resolveinteger or null
  Which of the rule's branches applied.
  missinglist of string or null
  notestring or null
state: "determined"
A dry run's determined answer: stored nowhere, so it has no id.
state: "undetermined_missing_facts"
A dry run's answer that needs facts it did not get.
missinglist of MissingFactrequired
7 fields
factstringrequired
typestring or null
currencystring or null
For an amount, the currency it is wanted in: the rule set's. Send it there, or - for an amount in another currency - beside it, as what your own systems record it as in this one (equivalents).
descriptionstring or null
needed_bystring or null
The rule that needed it.
review_itemstring or null
For recipient_identity: the probable match to answer first.
ofHistoryTransaction or null
Where the fact is another action's: a booking a total counts and cannot read, by its id and its date. Send the fact by completing that booking (transaction.completes), not in this check.
2 fields
transaction_idstringrequired
effective_datestring or null
state: "not_covered"
A dry run's answer that no rule covers.
reason"awaiting_confirmation" | "rule_flagged" | "policy_gap" | "no_rule_matched" | "no_rule_set_for_jurisdiction" | "rule_set_broken"required
detailstring or null
unconfirmed_ruleslist of string or null
state: "contested"
A dry run's answer that turns on a word a person decides.
questionQuestionrequired
5 fields
idstringrequired
candidateslist of stringrequired
reasonstringrequired
Why this one cannot be settled by the rule.
rulestringrequired
wordingstring or null
The rule's wording, as your rule owner confirmed it.
signerSigner or null
1 field
useranyrequired
The person who signs off, as your settings name them.
with_policyDeterminedAnswer | UndeterminedAnswer | NotCoveredAnswer | ContestedAnswerrequired
one of 4
One of 4, told apart by state.
- effective_datestringrequired
  The date the rules were applied as of.
- as_ofstringrequired
  The moment the history was read.
- layersLayersrequired
  2 fields
  lawLayerAnswer or null
  The law's answer. Left out where no law set is part of the answer - your policy's alone, for a country we hold no law for or one your account has not switched on.
  12 fields
  rule_setstringrequired
  rule_versionstringrequired
  state"determined" | "undetermined_missing_facts" | "not_covered" | "contested"required
  outcomestring or null
  basisstring or null
  law, policy or goodwill.
  consequenceslist of Consequence or null
  not_checkedlist of NotChecked or null
  approverany
  Who a policy says must approve, where it names one.
  handed_toany
  Whom a policy hands the action to, where its rule names one: a person in your account, by Himmel id. Where an agent asked about the action, Himmel tells them (check.handed_over).
  tenant_facts_usedlist of string or null
  Your settings this answer read.
  reference_versionsmap of integer | string or null
  Which version of each reference table it read, such as dated VAT rates.
  waiting_onstring or null
  A policy rule that reads the law's answer waits for the law to settle: law.
  policieslist of LayerAnswer or null
  Your policies for this domain, in the order they ran.
  12 fields
  rule_setstringrequired
  rule_versionstringrequired
  state"determined" | "undetermined_missing_facts" | "not_covered" | "contested"required
  outcomestring or null
  basisstring or null
  law, policy or goodwill.
  consequenceslist of Consequence or null
  not_checkedlist of NotChecked or null
  approverany
  Who a policy says must approve, where it names one.
  handed_toany
  Whom a policy hands the action to, where its rule names one: a person in your account, by Himmel id. Where an agent asked about the action, Himmel tells them (check.handed_over).
  tenant_facts_usedlist of string or null
  Your settings this answer read.
  reference_versionsmap of integer | string or null
  Which version of each reference table it read, such as dated VAT rates.
  waiting_onstring or null
  A policy rule that reads the law's answer waits for the law to settle: law.
- engine_versionstringrequired
- recipientRecipientSummary or null
  4 fields
  resolutionstringrequired
  resolved, unresolved, probable_match or missing.
  recipient_idstring or null
  review_itemstring or null
  The open probable match, where there is one.
  fy_totalMoney or null
  This recipient's total for the fiscal year, where the answer's first rule set totals money per recipient per fiscal year: the recipient's other bookings of the year that it counts, as known when the answer was given - this one not included, and later ones too where it counts the whole year. Left out where no such total was read; history_used names every total an answer read.
  2 fields
  amountintegerrequired
  currencystringrequired
- history_usedlist of HistoryInput or null
  5 fields
  rule_setstringrequired
  inputstringrequired
  The rule set's name for this total, such as recipient_fy_gifts.
  countintegerrequired
  transactionslist of HistoryTransactionrequired
  2 fields
  transaction_idstringrequired
  effective_datestring or null
  totalMoney | integer | string or null
- not_checkedlist of NotChecked or null
  2 fields
  topicstringrequired
  reasonstringrequired
- citationslist of Citation or null
  4 fields
  sourcestringrequired
  The source's key within the rule set, such as estg.
  paragraphstring or null
  clausestring or null
  text_refstring or null
  The passage in the rule set's own copy of the source, sources/<file>#<anchor>.
- confirmationslist of ConfirmationUsed or null
  3 fields
  rulestringrequired
  confirmed_bystring or null
  confirmed_atstring or null
- decisionslist of DecisionRead or null
  Each question on this action a person decided, read as its answer: where the question's rule says what each answer leads to, a sign-off or an admin's override issues the action's answer again, and every answer to it after reads the decision while the rule asks the very same question. Left out where none was read.
  8 fields
  answerstringrequired
  The answer chosen, one of the question's candidates - or approved, for an approval.
  questionstring or null
  The question's id. Null for an approval, which answers none.
  rulestring or null
  The rule that raises the question, as it asks it. Null for an approval.
  decided_bystring or null
  Who decided: a person in your account, by id.
  method"sign_off" | "override" | "approval" or null
  A sign-off by the person the question names, an admin's override of it, or the approval of the person the action's answer named, asked by Himmel.
  resolution_idstring or null
  The decision's record, on the answer it was made on.
  leads_tostring or null
  What the answer led to: continue - on to the rules after the question, which gave the outcome - or the outcome it gives itself. Null for an approval, read from the first rule.
  approvalstring or null
  The fact the decision stood in for as its decider's approval - where the action recorded none, and the rule that gave the outcome read it - so one person who decides and approves is asked once. Null otherwise.
- recheckslist of Recheck or null
  The earlier answers this booking changed, each issued again before this one was given. Left out when it changed none, and on a proposal, which changes nothing until it is reported as executed.
  4 fields
  new_check_idstring or null
  supersedesstring or null
  booking_datestring or null
  outcomestring or null
- supersedes_check_idstring or null
  The earlier answer for the same transaction that this one replaces.
- recheck_reasonstring or null
  Why it was issued again: a later transaction, an action taken back (reversal) or corrected (correction), a link or split between recipients, a question raised about its recipient, the rules changing, a question on it decided (decision), or the action approved by the person its answer named (approval).
- tracelist of TraceStep or null
  Every rule reached, in order. Left out when the check asked explain: false.
  6 fields
  rulestringrequired
  stagestringrequired
  scope, outcome or consequence.
  matchedboolean or null
  resolveinteger or null
  Which of the rule's branches applied.
  missinglist of string or null
  notestring or null
state: "determined"
A dry run's determined answer: stored nowhere, so it has no id.
state: "undetermined_missing_facts"
A dry run's answer that needs facts it did not get.
missinglist of MissingFactrequired
7 fields
factstringrequired
typestring or null
currencystring or null
For an amount, the currency it is wanted in: the rule set's. Send it there, or - for an amount in another currency - beside it, as what your own systems record it as in this one (equivalents).
descriptionstring or null
needed_bystring or null
The rule that needed it.
review_itemstring or null
For recipient_identity: the probable match to answer first.
ofHistoryTransaction or null
Where the fact is another action's: a booking a total counts and cannot read, by its id and its date. Send the fact by completing that booking (transaction.completes), not in this check.
2 fields
transaction_idstringrequired
effective_datestring or null
state: "not_covered"
A dry run's answer that no rule covers.
reason"awaiting_confirmation" | "rule_flagged" | "policy_gap" | "no_rule_matched" | "no_rule_set_for_jurisdiction" | "rule_set_broken"required
detailstring or null
unconfirmed_ruleslist of string or null
state: "contested"
A dry run's answer that turns on a word a person decides.
questionQuestionrequired
5 fields
idstringrequired
candidateslist of stringrequired
reasonstringrequired
Why this one cannot be settled by the rule.
rulestringrequired
wordingstring or null
The rule's wording, as your rule owner confirmed it.
signerSigner or null
1 field
useranyrequired
The person who signs off, as your settings name them.

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
413The request's body is larger than the operation takes, refused before any of it is read (body-too-large): a policy's files at most 5 MB, any other body 1 MB - and an uploaded file at most 20 MB (file-too-large).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

Sandbox

GET/v1/sandbox/examples/{rule_set}Scope rules:read

The rule set's own test cases, as requests you can send

Each example is a sequence: send its requests in order, because an answer can depend on what was sent before it - a customer's third goodwill credit in 90 days is answered in the light of the first two. Each request says who acts where the case does, and one the case asks about before it is taken is a proposal: what then becomes of it is yours to report. A proposal is dated the day it is asked, so an example asked about is served dated today, every date in it moved with it - a refund five days after delivery stays five days after. Recipient ids, and the ids of who acts, carry recipient_suffix, new on every call, so examples sent twice do not add up. expect is the answer the case expects under needs_tenant_facts, and assumes says what else it takes for granted that no request carries - rules not yet confirmed or flagged, recipients linked, when things happened, nobody acting - so where your account differs, its answer does too; rules answer only once your rule owner has confirmed them. Each is served in your account's terms: a person it names through a setting is the person your account names there, an action taken dated before the version starts is moved into it with every date of the example, a key made for an agent is served its agent acting, and one of your account's own keys the one agent your account has switched on - what cannot be is said in assumes (people, before_the_version, agents), and an example served as your agent, where a total counts each agent's actions apart, says it adds to that agent's totals (agent_totals). source: api is one of ours rather than the rule set's: a booking in a country it does not cover, for a rule set that names its countries. A rule set is served to an account that has it on.

Needs a key with the scope rules:read. From a key made for an agent it reads that agent's own alone: another agent's action is 403 not-the-agents-action, another agent's record 403 insufficient-scope.

Parameters

rule_setpath · stringrequired
versionquery · string or null
statequery · string or null
Only examples that expect this state

Responses

200 Successful response

rule_setstringrequired
versionstringrequired
recipient_suffixstringrequired
Appended to every recipient id in this response, and to every id of who acts, and new on every call, so examples sent twice do not add up into one recipient's yearly total, or one actor's day.
exampleslist of SandboxExamplerequired
8 fields
- idstringrequired
- source"case" | "api"required
  case: one of the rule set's own test cases. api: one of ours - a booking in a country the rule set does not cover - which no rule of the set answers.
- examplestringrequired
- expectobjectrequired
  The answer the case expects.
- needs_tenant_factsobjectrequired
  The settings that answer assumes. Your own may differ.
- assumesExampleAssumesrequired
  What else that answer takes for granted: empty where it is nothing.
  12 fields
  unconfirmedlist of string or null
  Rules it takes as not yet confirmed by your rule owner.
  flaggedlist of string or null
  Rules it takes as flagged.
  linkedlist of list of string or null
  Its recipients it takes as one person, linked by your rule owner: each pair a record and the identity it counts as.
  triggerobject or null
  The change it expects answers to be issued again from - reason, and for a link or split its recipients - where no request of its own makes that change.
  as_ofstring or null
  The moment it is answered as of.
  atmap of string or null
  When it takes its transactions to have happened, by the case's own id for each - case for the one it asks about: a request sent now happened now.
  nobody_actsboolean or null
  It takes it that nobody is recorded as acting where it names nobody, and its rules read who acts. Sent signed in to the console, you are recorded instead.
  decisionslist of object or null
  The questions it takes as decided on its action - question, answer, by - which no request carries: the person the question names signs it off on the answer that asked it (POST /v1/checks/{id}/resolution), and the action is answered again.
  peoplelist of string or null
  The people it names - by the case's own ids - that your account has nobody apart for: a setting it names a person through that your account names nobody in, a person in no setting who is nobody of your account's, or two of its people your account names one person for. Every other person it names is served as the person your account names.
  before_the_versionstring or null
  The first day of the version served, where its own action is taken before it and could not be moved into it - the version starting after today, say - so no version of it answers the action.
  agentslist of string or null
  The agents it names acting - by the case's own ids - that it could not be served as an agent of yours: sent with one of your account's own keys, which names only an agent your account has registered, where your account has several switched on or none. Its requests name the case's agent with the fetch's suffix, which that key is refused for (unknown_agent): send it with the key of the agent it is about.
  agent_totalsstring or null
  The agent of yours it is served as, where a total of its rule set counts each agent's actions apart: what it sends adds to that agent's own totals in the environment it is sent in, beside whatever the agent did there, so its answer may differ from what it expects.
- sendlist of ExampleSteprequired
  3 fields
  method"POST"required
  pathstringrequired
  bodyobjectrequired
- rulestring or null

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
404Nothing with that id or name exists for this account.
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

GET/v1/sandbox/policy-sampleScope rules:read

A synthetic company policy, as a document and as the rules it should draft to

"Beispiel GmbH", invented and labelled so in its first line, written to hold the hard cases: a limit with a named approver, a per-recipient cap stricter than the law's, a vague word left to a named signer, a kind of entertainment it never mentions, and a clause that tries to say what is deductible, which publishing refuses. files can be posted to POST /v1/policies as they are.

Needs a key with the scope rules:read. What it reads is your whole account's, so a key made for an agent, which reads its own agent's alone, gets 403 insufficient-scope.

Responses

200 Successful response

synthetictruerequired
rule_setstringrequired
documentstringrequired
The sample policy as a document. Invented, and labelled so.
filesmap of stringrequired
The rule set it drafts to, ready for POST /v1/policies.
noteslist of stringrequired

401No API key was sent, or it is not in use (unauthorized).
403The caller may not do this, and type says why: the key or role lacks the scope, the rule set is not enabled for this account, the person signed in belongs to no account, names were asked for by a caller that is not shown them, or a request acting in test tried to change the account's settings (live-only).
422The request, or a fact in it, is not in the documented shape - a query parameter the operation does not take included, which is named (unknown_parameter) rather than ignored - or its Himmel-Env does not fit the caller. Missing facts are not errors.
429More requests in a minute than the key's or the person's limit (rate-limited) - or, opening an account, more accounts in a day than the deployment opens, with Retry-After saying when to try again.
500Something failed on our side. X-Request-Id identifies it in our logs.

Service

GET/healthzNo key needed

Whether the service can answer

A database ping and a full check run by the engine on fixed facts: 200 and ok when both pass, 503 and degraded when either fails - a database that has not answered within two seconds is unreachable. Needs no key.

Responses

200 The service can answer.

status"ok" | "degraded"required
engine_versionstringrequired
engine"ok" | "failing"required
database"ok" | "unreachable"required

503Degraded: the database or the engine failed, said which.