Offers and declines
End a case with an offer the applicant signs, or a decline, and read the outcome from the API
Overview
A workflow can end with a decision. When the file is complete, a person on your team sends an offer or a decline from the case. Klarefi drafts both from the case's facts, and nothing goes out until a person sends it.
The decision, its files and how it ended are part of the case. Your systems read them from the case package and follow them through webhook events.
Set up the decision
In the workflow builder, the Decision step holds:
- the offer and the decline: subject and message, with facts placed in the
text by typing
@; - what you call the two, when they are not an offer and a decline. A claims
team can name them "Coverage confirmation" and "Coverage denial". The case
and the queue then use those names, and the case package carries the name
as
decision.name; - who the email goes to, and the fact that is the value of the decision;
- the documents sent with an offer: ones you write in the builder, PDFs of your own that Klarefi fills in for each case, and files sent as they are;
- how long an offer stands, in working days;
- how the applicant answers, if they do;
- who signs for you: a person on your team whose name every offer and decline carries, or whoever sends it. The case keeps who sent it either way.
Fill in a PDF of your own
Attach a PDF you already have, such as a term sheet, and choose Fill in facts beside it. The dialog shows the file page by page:
- where the PDF has fields of its own, they are already drawn. Choose the fact for each one;
- anywhere else, click the page where a value goes and choose the fact. Drag the place to fit the blank.
Each case's values are written there before the offer is sent. A place holds a fact or a calculated fact. A value that is too long for its place is set smaller, down to 7 pt, and on more lines when the place has room. It is never cut off.
On the case, the Decision view shows the filled file before anyone sends it. The offer is held back while a place has no value, or while a value does not fit its place. The case says which fact and which file.
A PDF is paper: its sentences do not move. A value inside a sentence needs a blank wide enough for the longest value. For running text, write the document in the builder instead.
How the applicant answers
| Method | What the applicant does |
|---|---|
| In Klarefi | Opens the offer on a page in your name, confirms a code sent to their email, and signs |
| Your own link | Follows a link to the signing tool you already use |
| No signature | Reads the offer; your team records what happened |
| No answer | Reads the decision. Nothing is asked of them |
With no answer the decision is final when it is sent, the way a decline is. It has no last day, nothing is signed and no reminder goes. Use it for a yes that is not an offer, such as a coverage confirmation or a permit. Its text cannot name a last day or a sign link.
Signing in Klarefi is one signature for the whole offer. It covers the offer letter and every file sent with it. The signed offer is sealed, and a signing record is added that names each file with its SHA-256, who signed, and when.
For an offer answered outside Klarefi, a person on your team records the outcome on the case.
How a decision can end
decision.status on the case package is one of:
| Status | Meaning |
|---|---|
offer_sent | The offer is with the applicant |
accepted | The applicant signed, or a person recorded that they accepted |
approved | A person sent a yes that expects no answer. It was final when it was sent |
declined | A person declined the application |
not_taken | The applicant said no, the last day passed, or a person recorded that it was not taken |
withdrawn | The offer was taken back, or the case was reopened |
Read the decision
import { Klarefi } from "@klarefi/node";
import type { CaseDecision } from "@klarefi/node";
const klarefi = new Klarefi({ apiKey: process.env.KLAREFI_API_KEY! });
const pkg = await klarefi.cases.getPackage("case_abc123");
const decision: CaseDecision | null = pkg.decision;
if (decision?.status === "accepted") {
const signed = decision.documents.find((file) => file.state === "signed");
// signed.sha256 checks the copy you hold against the one Klarefi sealed.
}The package never carries the message itself or the reason a person gave for a
decline. Those stay on the case. The files open from the case file behind
case_file_url.
calculated_facts on the same package are the numbers the workflow worked out
from the facts, such as a maximum amount or a rate, each with the facts it was
calculated from.
Follow it with events
v1.decision.offer_sentv1.decision.acceptedv1.decision.approvedv1.decision.declinedv1.decision.not_takenv1.decision.withdrawn
Each event's payload_summary carries decision_status, and decision_value where
the workflow names a value. valid_until is carried on the events about an
offer with a last day, such as offer_sent, accepted and not_taken, and
on withdrawn only when the offer itself was taken back. It may be absent:
a withdrawal that comes from reopening a case, for one, carries no last day.
When you need the offer's last day, read decision.valid_until from the case
package rather than from an event. Sending an offer or a decline also
completes the case, so v1.case.completed is delivered as well. See
Events.
What applicants' agents can do
An applicant's agent can complete the intake through the agent session or the MCP tools. It cannot accept an offer. An offer is signed by a person, on the offer page, with a code sent to their email.