Open a loan file against a borrower.

purpose decides which stages apply. A refinance has no Pre-Approved
stage, so sending purpose: "refinance" narrows the stages this loan can
move through. Fetch GET /api/partner/loan-stages?purpose=refinance to see
which apply before you transition.

Idempotency. Send an Idempotency-Key header and a retry with the same
key returns the original loan rather than creating a second one. Keys are
scoped to your team and retained for 24 hours — use one per logical
creation, not one per HTTP attempt.

Attribution. Loans created through this endpoint are recorded with
source: "api" and the integration name from your token, so the event
history can always distinguish an LOS sync from a human.

An unrecognised purpose is rejected with 422 (changed 18 Aug
2026; it previously fell back to purchase). Purpose decides the stage
path, so guessing it put refinances on the purchase path with no warning
— and because we had already "corrected" the value, nothing downstream
could tell. Map your vocabulary onto purchase or refinance before
calling; the error names both values.

Casing and surrounding whitespace are forgiven ("REFINANCE " is fine).
OMITTING purpose still defaults to purchase — absent is not the same
as wrong, and callers that never sent it are unaffected.