Skip to main content
POST
Start an automated underwriting run

Authorizations

Authorization
string
header
required

Partner API key issued by Cactus.

Headers

Idempotency-Key
string

Unique key making the request safely retryable.

Maximum string length: 255

Body

application/json
property
object
required
notification_email
string<email>
required

Receives the signed report link on completion.

end_user_ref
string

Your own identifier for the user this underwriting is for. Each distinct value is isolated: one end user never sees another's analyses, and GET /v1/underwritings?end_user_ref= returns only theirs. Use a stable opaque id rather than an email.

Omit it only when underwriting on your own behalf. If your account is configured to require it, omitting it returns 422 (end_user_ref_required).

Required string length: 1 - 255
document_ids
string[]

Optional supporting documents. Validated on acceptance; oversized files are rejected.

options
object

Response

Run queued.

id
string
required
Example:

"uw_01J9ZK3M"

object
string
required
Allowed value: "underwriting"
status
enum<string>
required
Available options:
queued,
ingesting,
underwriting,
calculating,
completed,
failed
sandbox
boolean
required
created_at
string<date-time>
required
progress
object
property
object

Echo of the submitted property.

end_user_ref
string

Echo of the submitted end-user identifier, when one was supplied.

document_ids
string[]
billed_total_usd
string
completed_at
string<date-time>
elapsed_seconds
integer

Whole seconds since created_at. Present while the run is active, so a caller can tell a run that just started from one approaching the 4-hour ceiling without doing date math.

Example:

640

poll_after_seconds
integer

Recommended seconds to wait before polling again. Present while the run is active; mirrors the Retry-After header. Prefer this over a hard-coded interval.

Example:

30

report
object

Present when completed.

summary
object

DRAFT — machine-readable headline results (key underwriting metrics).

error
object