API REFERENCE

Beta

SAMI v2 Term Conventions

SAMI is PitchPoint’s own format for describing a loan. A loan is submitted as an array of terms. The same array shape is used by Stage a Loan and Start a Workflow, and it is echoed back on Read a Workflow.

The four conventions below trap almost every first integration. None of them is enforced by the schema, so getting one wrong produces a submission that is quietly missing information rather than an error you can see.

Field-level descriptions are not published here. Ask your Pitchpoint Account Representative for the term catalog if you need the full list for a branch.

• A term is an object with exactly one key
  • Which branches may repeat
• Convention 1: key casing
• Convention 2: arrays are flat
• Convention 3: numbers and dates are strings
• Convention 4: fields that look like enums are free text
• What is actually validated

A term is an object with exactly one key

That key names which of the eleven kinds of fact it carries; its value holds the fields.

{ "person": { "firstName": "Jane", "lastName": "Sample" } }

Never two keys, and never zero. {"person":{…},"property":{…}} is wrong, and so is {}. Two borrowers are two person terms, not one term with two people in it.

Branch key	Carries
person	A party who is a human being.
property	A property, with its address and valuations.
participant	A party to the transaction other than a borrower.
company	A company party.
loanTerms	The loan’s headline terms.
loanToValue	LTV and CLTV ratios.
transactionDetail	Purchase price and related figures.
loanDetail	Further loan attributes.
refinance	Refinance-specific facts.
housingExpense	One housing expense. Repeat it, one per expense type.
closing	Closing details.

Order carries no meaning, and no term references another — there are no identifiers to wire up between them.

Send exactly one key per term. A term carrying two keys is not currently rejected: one of the two facts is silently dropped and the submission still stages and runs normally. The mistake surfaces as missing information in the result rather than as an error on the request, which makes it expensive to trace.

Which branches may repeat

Any branch may appear more than once, but only some should.

Branch	Repeat?
person, property, participant, company	Yes. One term per party or property.
housingExpense	Yes, and it is meant to — one term per expense type.
loanTerms, loanToValue, transactionDetail, loanDetail, refinance, closing	Send at most one. See below.

Nothing rejects a second loan-level term, and nothing decides between them either. A product reading two loanTerms has no rule for which one wins. Send one.

Convention 1: key casing

Keys are camelCase: lower-case first letter, and an acronym anywhere else keeps its capitals.

Key	Not
firstName		the ordinary case
countyFIPSCode	countyFipsCode	the acronym stays upper
noteRatePercent

That acronym rule is the one most often got wrong, because most camelCase conventions would lower-case it.

Six keys are irregular and are spelled exactly as shown. They are the complete list — there are no others:

ssn · dob · yob · ein · ltvRatioPercent · cltvRatioPercent

The rule governs keys only. Values keep whatever case they are documented with, so an identifier type is sent as SSN or EIN in upper case.

A key this service does not recognize is ignored rather than refused, so a casing mistake is not reported back to you — the field is simply absent from the loan. Casing is the likeliest source of a quietly incomplete submission.

Convention 2: arrays are flat

Repeated things are plain JSON arrays. There is no container object wrapping them.

"residences": [ { "…": "…" } ]

not

"residences": { "residence": [ { "…": "…" } ] }

This applies to residences, employers, properties, bankAccounts, licenses, identifiers, consentTokens, valuations, courtDetails and items.

An empty array means exactly what an omitted key means, and a read gives you the omission rather than []. terms is the one exception: it is the only array whose bounds are enforced, and an empty one is rejected.

Convention 3: numbers and dates are strings

Kind	Form	Example
Any field ending Amount, Percent, Ratio or Price	JSON string	"450000.00"
Percentages	as a percent, not a fraction	"6.375", never "0.06375"
Dates	mm/dd/yyyy, not ISO-8601	"01/31/1980", never "1980-01-31"
Any field ending Indicator	a real JSON boolean	true, never "true"

A malformed date is accepted on submission and fails later. Dates are not validated when you stage or start a workflow, so an ISO-8601 date is taken without complaint and surfaces as a failure much further downstream, where it is far harder to trace back to the request that caused it. Get the format right at the source.

Convention 4: fields that look like enums are free text

Around fifteen fields read like closed vocabularies and are not. Any string is accepted, and an unrecognized value is neither rejected nor reported.

They are deliberately not modelled as enums so that a generated client cannot refuse a value this service accepts. Prefer the documented values for a field, but treat the list as a preference rather than a constraint. Several of these fields have a companion …OtherDescription field for the case where no documented value fits.

What is actually validated

Only three things are checked when you submit:

1. terms must be present and a non-empty array. "terms": [] is rejected.
2. Every element must be a JSON object — never null, never a bare string or number.
3. Every element must carry one of the eleven branch keys above.

Everything else is permissive. An absent field is accepted without complaint, and a key this service does not recognize is ignored rather than refused, so a misspelled field name will not be reported back to you.

One bad term rejects the whole request. A single element carrying an unrecognized branch key fails the entire submission rather than being dropped while the others proceed. Nothing is recorded, and a session keeps whatever snapshot it already had.