Resolutions

A resolution records what your people decided about an answer: a sign-off on a contested check's question, or an admin's override of what an answer decided. It is kept beside the answer and never changes it; a decision on a question whose rule says what its answers lead to answers the action again, in a new answer (below). The record of what Himmel answered and the record of what your company then decided are two different things, and the second one is yours.

curl https://api.gethimmel.com/v1/checks/chk_01J8.../resolution \
  -H "Authorization: Bearer $HIMMEL_KEY" -H "Content-Type: application/json" \
  -d '{ "resolved_outcome": "exceptional", "resolved_by": "usr_01J9Q4TZ8M...",
        "method": "sign_off", "note_ref": "MEMO-2025-77" }'

GET /v1/checks/{id} returns the answer with its latest resolution beside it, and every one in resolutions.

A decision answers the action

Where the question's rule says what each of its answers leads to - on to the rules after it, or an outcome of its own - a sign-off, or an admin's override of the question, answers the action again in the same request: the decision is read as the question's answer, and the rules after it answer too. A late refund the team lead decides is exceptional is then held to its amount like any other; one they decide is not exceptional is refused, as the playbook says. The response names the new answer:

{ "resolution_id": "res_01J9...", "check_id": "chk_01J8...", "resolved_outcome": "exceptional",
  "method": "sign_off", "superseded_by": "chk_01J9..." }

It replaces the contested answer (supersedes_check_id, recheck_reason: decision), lists the decision it read in decisions - who decided, how, the resolution's id, and what the answer led to - and raises a check.rechecked alert, so software waiting on the decision hears of it. superseded_by is null where the answer stands as it was: a question whose rule says nothing of what its answers lead to, or a change to your rules still waiting for your rule owner, whose confirmation then issues it.

A person who decides and approves is asked once. Where your rule set marks the fact that records an approval (approved_by), a decision that goes on is also its decider's approval in the rules after the question, unless the action records an approval of its own. So the team lead's sign-off on a late €70 refund, which the team lead approves up to €250, allows it; on a late €300 refund the answer names the head of support's approval as the next stage of the same refund. The decision says approval: "approved_by" where it stood in that way. Where your rule set gives approval for an amount - "for this amount or more" - and marks the money fact that records it too (approved_amount), the decider's approval is for the action's own amount, unless the action records an amount of its own.

Every answer the action is given after reads the decision again - when it is reported done, completed with facts it lacked, or issued again because something it depends on moved - for as long as the rule asks the very same question.

Who decides, and what

• A sign-off answers a contested check's question. Only the person the answer names as its signer gives one, and they choose one of the question's candidates.
• An override is an admin overruling your own rules: a determined answer, choosing one of the outcomes its rule set declares, or a contested one, signed off or not, choosing one of its question's answers. A question that names nobody is decided this way.
• On the answer that stands, for an action that was taken or is still open. A decision sent to an answer a later one replaced is refused with 409 answer-replaced, and standing names the answer to decide on - the action's, once a check completed it or asked about it again. One about an action never taken - it expired, or the caller reported it not done - is 409 action-not-taken.

Anybody else is 403 cannot-decide, and so is a key made for an agent, whoever it names (agent_key): a decision is a person's, made signed in to the console or sent by your own software with one of your account's own keys. An answer the question or the rule set does not offer is 422 invalid-request with not_a_choice, and the detail lists the ones it does.

A decision is made once

Himmel issues an answer again when something it depends on moves: a later booking, a new version of your rules confirmed, two customer records answered to be one. A decision the answer read, it reads again, as above. For a question whose rule says nothing of what its answers lead to, the answer stays contested beside its decision, and where the new answer asks the very same question - raised by the same rule, in the words your rule owner confirmed, with the same answers to choose from - the latest decision on the answer it replaces carries over to it. It reads as the decision it carries, with given_on naming the answer it was given on, so the person who decided is never asked twice. An override of a determined answer carries over where the new answer gives the same outcome from the same rules.

Where the question changed - the rule was reworded, or the answer now asks another question or none - the new answer waits for a decision again, and the earlier decision stays on record on the answer it was given to.

Approvals Himmel asks for

When an agent asks before it acts - a check with status: proposed, sent with a key made for it, through the API or the MCP server - and the answer names a person, Himmel asks that person: the approver your policy names where the answer needs_approval, and the signer of a contested answer's question. Every answer to the action then carries requests, beside the answer, as each stands now:

"requests": [ { "id": "apr_01J9...", "asked_of": "usr_01J9Q4TZ8M...", "asked_at": "2026-10-12T09:14:02Z",
                "asks": "approval", "status": "waiting", "decided_by": null, "resolution_id": null,
                "closed_at": null, "reason": null, "emailed_at": null, "waits_until": "2026-10-19T09:14:02Z" } ]

An approver is asked only where your rule set marks the fact that records who approved (approved_by, approval: true), so their approval can be read. Nobody is asked for your own software or a person signed in, which keep their approvals in their own systems and send them as approved_by, nor for an action already taken: that is too late to ask.

Himmel emails the person asked within a minute, at the address they sign in with. The email says what is asked as the answer that stands for the action says it - the action's figure in your rule set's own words, the rule that named them with the clauses it cites, or the question and its answers; which agent asks, for whom and in which run; and until when it waits - and links the request's page in the console, where they decide signed in. A link alone never decides. It names no customer and no person: the email provider is a sub-processor. Several requests found at once for one person go in one message. emailed_at says when it went; it stays null where the person's mail server refused their address, and the request waits for them in the console. In an account with live and test, a request made with a test key is never emailed: it waits in the console for whoever is trying the flow, and nobody's inbox hears of it.

The person asked decides, signed in to the console, in any role - POST /v1/approvals/{id}/approve, or /refuse - and is told what became of the request:

{ "request": { "id": "apr_01J9...", "status": "approved", "decided_by": "usr_01J9Q4TZ8M...", "...": "..." },
  "check_id": "chk_01J8...", "resolution_id": "res_01J9...", "superseded_by": "chk_01J9..." }

An approval is recorded as theirs (method: approval) and answers the action again in the same request, read as the approval the rules ask for: allowed where they need nothing more, replacing the answer that named them (recheck_reason: approval), and listed among the new answer's decisions. It covers the action as asked. POST /v1/approvals/{id}/refuse records a refusal: no answer is issued again, every answer to the action says it was refused, and nobody is asked about it again. A question's request is answered by a sign-off (above), never an approval.

The agent hears what was decided by asking again about the action, naming it, with only the facts an answer asked for: an approval answers it allowed, a refusal leaves the answer as it was, requests saying refused. It never asks the person itself. Your own software hears the answer an approval issued as it hears any answer issued again, by its check.rechecked alert. See When an answer names a person, which also says how to see an approval through in the sandbox, whose team lead and head of support nobody signs in as.

Nobody else decides: a key - an agent's (agent_key) or one of your account's own (a_key) - and another person (not_the_approver) are 403 cannot-decide; an admin may still overrule the answer itself. The same decision sent twice is answered as it stands; once a request no longer waits, any other is 409 nothing-to-decide, with request_status. GET /v1/approvals/{id} reads a request, with the answer that named the person and the one that stands now.

A request waits a week at most - until its waits_until, which every request carries, so you can tell whoever your agent acts for when the person will have answered by - and the agent's proposal waits with it: it is not closed as expired while a request on it waits, and once decided its 24 hours run from the decision. A request lapses, saying why, when its action is reported taken (executed) or not done (abandoned), expires (expired), or gets no answer in a week (no_answer).

What waits on a person

GET /v1/review says what waits on somebody at your company now, in groups, each with how many and the check log query that lists them. It needs checks:read, and reads the environment of the request, as the log does.

curl https://api.gethimmel.com/v1/review -H "Authorization: Bearer $HIMMEL_KEY"

{
  "waiting": 8,
  "checks": "/v1/checks?waiting=true",
  "groups": [
    { "kind": "approval", "count": 1, "checks": "/v1/checks?waiting=true&state=determined&request=waiting" },
    { "kind": "contested", "count": 2, "checks": "/v1/checks?waiting=true&question=policy.example.q.exceptional",
      "question": { "id": "policy.example.q.exceptional", "candidates": ["exceptional", "not_exceptional"],
                    "reason": "...", "rule": "policy.example.refunds.late_is_exceptional", "wording": "..." } },
    { "kind": "match", "count": 1, "matches": "/v1/recipients/matches?status=open",
      "answers": 1, "checks": "/v1/checks?waiting=true&missing=recipient_identity" },
    { "kind": "not_covered", "reason": "policy_gap", "count": 1, "checks": "/v1/checks?waiting=true&reason=policy_gap" },
    { "kind": "undetermined_missing_facts", "fact": "delivered_on", "description": "The day the order was delivered",
      "count": 1, "checks": "/v1/checks?waiting=true&missing=delivered_on&transaction_status=executed" }
  ]
}

The groups come in that order, and within a kind the largest first, then by name — but for not_covered, whose reasons keep the order above. A group with nothing in it is not listed. Every figure is exactly what its link lists. An action never taken waits on nobody, and an action still being asked about waits only on a question for a person: its missing facts are its asker's to send. Nothing here decides anything.

What a resolution is not

Supplying facts that were missing is a check, not a resolution: for an action taken, send a check that completes it, naming its booking in transaction.completes (see Check); for one you are still asking about, ask about it again, naming it the same way, with the facts. An answer waiting on your rules waits for your rule owner to confirm them. A resolution records a person's decision about a question the rules leave open, or an admin overruling them. It never turns a missing fact into an answer.