Sessions and prefill

POST /v1/partner/sessions is the one call that starts or resumes a sale with Before. It runs as the key's user, exactly as if they had clicked "New policy" in Before, and returns a token for Before.open. The sale is attributed to that user, so call it with the key of the user who is selling.

How a request is resolved

Before reopens or creates the sale, then applies prefill section by section.

Request

{
  "partner_reference": "case-1042",
  "location_id": "4b0d8c2e-0a51-4a4f-8f3e-1c2d3e4f5a6b",
  "prefill": { "insured": { "first_name": "Ada", "last_name": "Byron" } }
}

Field	Required	Meaning
partner_reference	yes	Your id for the sale, 1 to 128 characters.
location_id	when the funeral home has several locations	The location the sale belongs to.
prefill	no	What you already know; see Prefill.

Response

{
  "session_token": "es_…",
  "sale_id": "6f1c1f0e-2b7a-4d39-9d0f-2a4f0b1d7c55",
  "expires_at": "2026-10-21T18:00:00.000Z",
  "skipped_prefill": ["insured"],
  "warnings": ["agent-unlicensed"]
}

Field	Meaning
session_token	Pass it to Before.open. It is shown once and only opens this sale.
sale_id	Before's id for the sale. Use it with GET /v1/partner/sales/:id and to match webhooks.
expires_at	The token stops working at this time, two hours after it was issued.
skipped_prefill	Prefill keys Before did not apply, because that part of the sale was already started.
warnings	agent-unlicensed: the user holds no licence in the sale's state. The sale still opens, as it would in Before itself; tell the user.

One sale per reference

partner_reference makes the call idempotent. The first call creates the sale; every later call with the same reference returns the same sale_id with a new session_token. Two calls racing with a new reference still create one sale.

• Reopen a sale whenever the user comes back to it. Tokens are not refreshed; open a new session instead.
• Several sessions on one sale may be open at once.
• A reference used with a test key cannot be reused with a live key, and the reverse: 409 partner-reference-in-use.
• A key whose user may see only their own sales cannot reopen another user's sale: 409 sale-agent-mismatch. Reopen it with the original user's key.

Location

1. If you send location_id, it must be one of the funeral home's active locations, or the call fails with 422 location-inactive.
2. Otherwise, if the funeral home has exactly one active location, Before uses it.
3. Otherwise the call fails with 422 location-required.

Both errors list the active locations, so you can ask the user once and remember the answer:

{
  "type": "https://before.com/problems/location-required",
  "status": 422,
  "detail": "Name the location_id to sell from; this tenant has several active locations.",
  "errors": [
    { "id": "4b0d8c2e-0a51-4a4f-8f3e-1c2d3e4f5a6b", "name": "Main Street Chapel" },
    { "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Riverside" }
  ]
}

On a reopened sale location_id is ignored: a sale keeps its location.

Prefill

Prefill saves the user typing what your platform already holds. It uses plain business terms, and Before maps each key onto the matching step of the wizard.

Prefill never overwrites the user's work. Each key fills its part of the sale only if nobody has started that part yet; otherwise it is listed in skipped_prefill. Once a sale goes out for signature, every key is skipped.

Before checks the whole prefill before writing anything. A value that cannot be applied fails the call with 422 prefill-invalid, naming each field:

{
  "type": "https://before.com/problems/prefill-invalid",
  "status": 422,
  "errors": [{ "field": "prefill.insured.phone", "rule": "us-phone", "detail": "Not a valid 10-digit US phone number." }]
}

insured

The person the policy covers.

Field	Format
first_name, last_name	Required. Letters, spaces, apostrophes, periods and hyphens.
middle_name	Optional.
date_of_birth	YYYY-MM-DD.
sex	female or male.
phone	Any common US format, such as (602) 555-0142 or +1 602 555 0142.
email	An email address.
address	street_1, optional street_2, city, state (two-letter code), postal_code (85014 or 85014-1234).
ssn_last4	Four digits. The user enters the full number in the wizard.

owner

Who owns the policy. Either the insured:

{ "same_as_insured": true }

or someone else, with the same person fields as insured and their relationship to the insured:

{
  "same_as_insured": false,
  "relationship": "daughter",
  "person": { "first_name": "Grace", "last_name": "Byron", "phone": "602-555-0199" }
}

relationship is one of spouse, son, daughter, father, mother, brother, sister, grandson, granddaughter, grandfather, grandmother, aunt, uncle, partner, trust, estate, power_of_attorney, other.

beneficiaries

One to ten named beneficiaries whose percentage values are whole numbers totalling 100.

[
  { "first_name": "Grace", "last_name": "Byron", "relationship": "daughter", "percentage": 60 },
  { "first_name": "Allegra", "last_name": "Byron", "relationship": "daughter", "percentage": 40, "phone": "602-555-0123" }
]

Each takes first_name, last_name, optional middle_name, relationship, percentage, and optional phone and address. relationship is one of assignee, spouse, son, daughter, father, mother, brother, sister, grandson, granddaughter, grandfather, grandmother, aunt, uncle, nephew, niece, cousin, friend, church, partner, trustee, estate, policy_owner, other.

The arrangement, pricing, health questions, funding and signing are never prefilled: the user works through them with the family in the wizard.