Beta
SAMI v2 Term Examples
Worked terms arrays, in the shape Stage Data and Start a Workflow accept. Read Conventions first — the rules there are what these examples are demonstrating.
All values below are fabricated.
These show the shape, not the full field list. Ask your Pitchpoint Account Representative for the term catalog if you need every field a branch accepts.
- The smallest useful loan
- Two borrowers
- Nested detail on a person
- Loan-level terms
- Housing expenses repeat
- A participant
- A complete submission
- A large loan
- Mistakes that are accepted without complaint
The smallest useful loan
One borrower and one property. Note that each term is an object with exactly one key, and the array is flat.
{
"terms": [
{
"person": {
"firstName": "Jane",
"lastName": "Sample",
"ssn": "000-00-0000",
"dob": "01/31/1980"
}
},
{
"property": {
"propertyUsage": "PrimaryResidence",
"propertyType": "Detached",
"address": {
"addressLine1": "1 Sample Street",
"city": "Sampleton",
"state": "NY",
"postalCode": "00000"
}
}
}
]
}
Two borrowers
Two people are two person terms, not one term carrying two people. Order carries no meaning, and nothing links a person to a property — there are no cross-references between terms.
{
"terms": [
{
"person": {
"firstName": "Jane",
"lastName": "Sample",
"ssn": "000-00-0000",
"dob": "01/31/1980"
}
},
{
"person": {
"firstName": "John",
"lastName": "Sample",
"ssn": "000-00-0001",
"dob": "07/04/1979"
}
}
]
}
Nested detail on a person
Residences and employers are flat arrays inside the person they belong to — no residence or employer container object. currentIndicator is a real boolean, not a string.
{
"terms": [
{
"person": {
"firstName": "Jane",
"lastName": "Sample",
"ssn": "000-00-0000",
"dob": "01/31/1980",
"residences": [
{
"currentIndicator": true,
"address": {
"addressLine1": "1 Sample Street",
"city": "Sampleton",
"state": "NY",
"postalCode": "00000"
}
}
],
"employers": [
{
"name": "Example Corp",
"selfEmployedIndicator": false
}
]
}
}
]
}
Loan-level terms
Amounts, percentages and ratios are strings. A percentage is written as a percent, so a rate of six and three-eighths is "6.375" and not "0.06375". Send at most one of each of these branches.
{
"terms": [
{
"loanTerms": {
"noteAmount": "450000.00",
"noteRatePercent": "6.375",
"noteDate": "03/15/2026",
"loanPurpose": "Purchase",
"mortgageType": "Conventional"
}
},
{
"loanToValue": {
"ltvRatioPercent": "80.00",
"cltvRatioPercent": "80.00"
}
},
{
"transactionDetail": {
"purchasePrice": "562500.00"
}
}
]
}
Note ltvRatioPercent and cltvRatioPercent: both are among the six hand-spelled keys that do not follow the general casing rule.
Housing expenses repeat
housingExpense is the loan-level branch that is meant to appear more than once — one term per expense line, however you might group them in your own model. Every line needs its amount, monthlyAmount, and presentHousingExpense marks whether it is paid now.
{
"terms": [
{
"housingExpense": {
"housingExpenseType": "FirstMortgagePrincipalAndInterest",
"presentHousingExpense": true,
"monthlyAmount": "2810.00"
}
},
{
"housingExpense": {
"housingExpenseType": "HazardInsurance",
"presentHousingExpense": true,
"monthlyAmount": "120.00"
}
},
{
"housingExpense": {
"housingExpenseType": "RealEstateTax",
"presentHousingExpense": true,
"monthlyAmount": "450.00"
}
}
]
}
Send monthlyAmount on every line. A line without it is accepted but not recorded. Send presentHousingExpense true for an expense the borrowers pay now, and false or nothing for one they will pay once the loan closes (other values).
A participant
A party to the transaction who is not a borrower. participantType has a long documented vocabulary, and it is matched exactly, after trimming. Nothing rejects another value, but one that does not match is recorded as OtherIndividual, or OtherCompany when the participant has a companyName.
{
"terms": [
{
"participant": {
"participantType": "Lender",
"companyName": "Example Lending"
}
}
]
}
A complete submission
The pieces above, assembled as one request body, with the loan secured by a condominium.
{
"terms": [
{
"person": {
"firstName": "Jane",
"lastName": "Sample",
"ssn": "000-00-0000",
"dob": "01/31/1980",
"residences": [
{
"currentIndicator": true,
"address": {
"addressLine1": "1 Sample Street",
"city": "Sampleton",
"state": "NY",
"postalCode": "00000"
}
}
]
}
},
{
"property": {
"propertyUsage": "PrimaryResidence",
"propertyType": "Condominium",
"address": {
"addressLine1": "60 Specimen Plaza",
"addressLine2": "Unit 1203",
"city": "Sampleton",
"state": "NY",
"postalCode": "00000"
}
}
},
{
"participant": {
"participantType": "Lender",
"companyName": "Example Lending"
}
},
{
"loanTerms": {
"noteAmount": "450000.00",
"noteRatePercent": "6.375",
"loanPurpose": "Purchase",
"mortgageType": "Conventional"
}
},
{
"loanToValue": {
"ltvRatioPercent": "80.00"
}
}
]
}
A large loan
The examples above show one branch at a time. This is a whole loan as a real submission looks: four borrowers with their employment, address history and the other real estate they own, the loan’s subject property, the parties to the transaction, and every loan-level fact. Seventeen terms. It is the same flat array as the two-term example — there is just more of it. Build a Loan Step by Step assembles it one term at a time.
Everything here is fabricated.
{
"terms": [
{
"person": {
"firstName": "Jane",
"middleName": "Quinn",
"lastName": "Sample",
"ssn": "000-00-0000",
"dob": "01/31/1980",
"homePhone": "5555550100",
"email": "jane.sample@example.com",
"residences": [
{
"currentIndicator": true,
"address": {
"addressLine1": "1 Sample Street",
"city": "Sampleton",
"state": "NY",
"postalCode": "00000"
}
}
],
"employers": [
{
"name": "Example Manufacturing",
"phone": "5555550140",
"ein": "00-0000000",
"monthlyIncome": "9400.00",
"yearsOnJob": "6",
"currentIndicator": true,
"selfEmployedIndicator": false,
"address": {
"addressLine1": "200 Example Parkway",
"addressLine2": "Suite 400",
"city": "Sampleton",
"state": "NY",
"postalCode": "00000"
}
}
],
"properties": [
{
"propertyPurpose": "RealEstateAsset",
"propertyUsage": "Investment",
"propertyType": "Condominium",
"address": {
"addressLine1": "480 Specimen Road",
"addressLine2": "Unit 1203",
"city": "Sampleton",
"state": "NY",
"postalCode": "00000"
},
"numberOfUnits": "1",
"valuations": [
{
"valuationType": "AutomatedValuationModel",
"valuationAmount": "289000.00"
}
]
}
]
}
},
{
"person": {
"correlationId": "LOS-000123-BORROWER-2",
"firstName": "John",
"lastName": "Sample",
"ssn": "000-00-0001",
"dob": "07/04/1979",
"homePhone": "5555550101",
"residences": [
{
"currentIndicator": true,
"address": {
"addressLine1": "1 Sample Street",
"city": "Sampleton",
"state": "NY",
"postalCode": "00000"
}
}
],
"employers": [
{
"name": "Sampleton General Hospital",
"phone": "5555550141",
"monthlyIncome": "7250.00",
"yearsOnJob": "11",
"currentIndicator": true,
"selfEmployedIndicator": false,
"address": {
"addressLine1": "45 Sampleton Square",
"city": "Sampleton",
"state": "NY",
"postalCode": "00000"
}
}
],
"properties": [
{
"propertyPurpose": "RealEstateAsset",
"propertyUsage": "SecondHome",
"propertyType": "PUD",
"address": {
"addressLine1": "77 Placeholder Lane",
"city": "Sampleton",
"state": "NY",
"postalCode": "00000"
}
}
]
}
},
{
"person": {
"firstName": "Priya",
"lastName": "Example",
"ssn": "000-00-0002",
"dob": "03/22/1981",
"homePhone": "5555550102",
"residences": [
{
"currentIndicator": true,
"address": {
"addressLine1": "12 Example Avenue",
"addressLine2": "Apt 4B",
"city": "Sampleton",
"state": "NY",
"postalCode": "00000"
}
},
{
"currentIndicator": false,
"address": {
"addressLine1": "88 Former Street",
"city": "Sampleton",
"state": "NY",
"postalCode": "00000"
}
}
],
"employers": [
{
"name": "Example Logistics",
"monthlyIncome": "6100.00",
"monthsOnJob": "18",
"currentIndicator": true,
"selfEmployedIndicator": true,
"address": {
"addressLine1": "300 Example Industrial Way",
"city": "Sampleton",
"state": "NY",
"postalCode": "00000"
}
}
],
"properties": [
{
"propertyPurpose": "RealEstateAsset",
"propertyUsage": "Investment",
"propertyType": "Attached",
"address": {
"addressLine1": "15 Example Terrace",
"city": "Sampleton",
"state": "NY",
"postalCode": "00000"
},
"numberOfUnits": "2"
}
]
}
},
{
"person": {
"firstName": "Daniel",
"lastName": "Example",
"nameSuffix": "Jr.",
"ssn": "000-00-0003",
"dob": "11/09/1976",
"homePhone": "5555550103",
"residences": [
{
"currentIndicator": true,
"address": {
"addressLine1": "12 Example Avenue",
"addressLine2": "Apt 4B",
"city": "Sampleton",
"state": "NY",
"postalCode": "00000"
}
}
]
}
},
{
"property": {
"propertyUsage": "PrimaryResidence",
"propertyType": "Detached",
"address": {
"addressLine1": "1 Sample Street",
"city": "Sampleton",
"state": "NY",
"postalCode": "00000",
"county": "Sampleton County"
},
"assessorsParcelNumber": "0000-00-000",
"countyFIPSCode": "36029",
"numberOfUnits": "1",
"saleDate": "08/29/2026",
"saleAmount": "562500.00",
"assessmentDate": "01/15/2026",
"assessmentAmount": "540000.00",
"valuations": [
{
"valuationType": "FullAppraisal",
"valuationAmount": "565000.00"
}
]
}
},
{
"participant": {
"participantType": "Lender",
"companyName": "Example Lending",
"address": {
"addressLine1": "3000 Example Center Drive",
"city": "Sampleton",
"state": "NY",
"postalCode": "00000"
},
"contactPoint": {
"roleType": "Work",
"type": "Phone",
"value": "5555550170",
"preferenceIndicator": true
},
"identifiers": [
{
"identifierType": "NMLS",
"identifierValue": "000000"
}
]
}
},
{
"participant": {
"participantType": "Appraiser",
"firstName": "Morgan",
"lastName": "Reed",
"companyName": "Example Appraisal Group",
"address": {
"addressLine1": "18 Example Court",
"city": "Sampleton",
"state": "NY",
"postalCode": "00000"
},
"contactPoint": {
"roleType": "Mobile",
"type": "Phone",
"value": "5555550171",
"preferenceIndicator": true
},
"licenses": [
{
"licenseNumber": "LIC000000",
"licenseType": "Appraiser License",
"licenseState": "NY"
}
]
}
},
{
"participant": {
"participantType": "Escrow",
"companyName": "Example Title & Escrow",
"address": {
"addressLine1": "9 Example Plaza",
"city": "Sampleton",
"state": "NY",
"postalCode": "00000"
},
"contactPoint": {
"roleType": "Work",
"type": "Phone",
"value": "5555550172",
"preferenceIndicator": false
}
}
},
{
"company": {
"name": "Example Holdings LLC",
"address": {
"addressLine1": "250 Example Boulevard",
"city": "Sampleton",
"state": "NY",
"postalCode": "00000"
}
}
},
{
"loanTerms": {
"noteAmount": "450000.00",
"loanAmount": "450000.00",
"noteRatePercent": "6.375",
"noteDate": "08/29/2026",
"loanPurpose": "Purchase",
"mortgageType": "Conventional"
}
},
{
"loanToValue": {
"ltvRatioPercent": "80.00",
"cltvRatioPercent": "85.00"
}
},
{
"transactionDetail": {
"purchasePrice": "562500.00"
}
},
{
"loanDetail": {
"loanOriginatorApplicationDate": "07/12/2026",
"totalDebtToIncomeRatioPercent": "38.50"
}
},
{
"closing": {
"settlementDate": "09/30/2026"
}
},
{
"housingExpense": {
"housingExpenseType": "FirstMortgagePrincipalAndInterest",
"presentHousingExpense": true,
"monthlyAmount": "1850.00"
}
},
{
"housingExpense": {
"housingExpenseType": "HazardInsurance",
"presentHousingExpense": true,
"monthlyAmount": "140.00"
}
},
{
"housingExpense": {
"housingExpenseType": "RealEstateTax",
"presentHousingExpense": true,
"monthlyAmount": "410.00"
}
}
]
}
Reading it against the rules on Conventions:
- Four borrowers are four
personterms. A relationship here is expressed by containment, never by reference. A borrower’s residences, employers and owned property sit inside thatperson, and the nesting is the whole of what assigns them. What no term does is point at another term: nothing ties apersonto the subjectproperty, or to aparticipant, or to anotherperson. A term’scorrelationIdnames that term only; it never points at another. So the subject property belongs to the loan, a holding nested on a borrower belongs to that borrower, and anything you need to relate across two terms you relate yourself. - The second borrower carries a
correlationId. It is optional, and it is your own id for that party: it comes back on thepersonwhen the terms are read, so you can match the echoed term to the one you sent. Give each party its own value. See Correlation ids on terms. - Employment, addresses and owned property all hang off the person.
employers,residencesandpropertiesare flat arrays on thepersonbranch, not terms of their own.currentIndicatormarks which entry is the present one, and a borrower who works for themselves is an ordinary employer entry withselfEmployedIndicatorset. Tenure isyearsOnJobormonthsOnJob— whichever you hold; neither is derived from the other. - The subject property is a term. The borrowers’ other property is not. The loan’s subject property is the
propertyterm, and a loan has at most one. Real estate a borrower already owns hangs off that person inproperties, and nesting is how the ownership is expressed. The branch is the same shape in both places.propertyPurposeisRealEstateAsseton each nested holding, and is left off thepropertyterm, which is always the subject property. Do not reach forproperty.ownerNameto tie a holding to a borrower: it is an unparsed string that is deliberately not linked to anypersonterm, and correlating it is left to whoever consumes the loan. - The loan-level branches appear once each.
loanTerms,loanToValue,transactionDetail,loanDetailandclosingare all send-at-most-one. A second one is not rejected: the last one in the array replaces the others. housingExpenseis the exception, and repeats. One term per expense line. This loan’s lines are all present, so each carries"presentHousingExpense": true. The flag is a genuine JSON boolean, and every monetary and percentage value around it is a string. It separates what the borrowers pay now from what they will pay once the loan closes: present and proposed lines sit side by side, told apart only by the flag.refinanceis absent on purpose.loanPurposehere isPurchase. Nothing ties therefinancebranch toloanPurpose— sending it on a purchase is accepted and simply meaningless — so a purchase loan carries the purchase-side terms and leaves it out.
A product decides how much of this it will read. How many borrowers a product will analyse is part of that product’s configuration, and a loan carrying more than it accepts is refused when the workflow runs, not when you stage it — as a failed status carrying a message such as Expected 1 to 2 ... Borrower. Staging never counts parties, and no endpoint publishes a product’s limits, so a loan that stages cleanly can still be more than the product will take. Ask your Pitchpoint Account Representative what yours accepts.
Mistakes that are accepted without complaint
Each of these submits cleanly and records a loan that is missing something. None produces an error you can catch.
| What you send | What happens |
|---|---|
"dob": "1980-01-31" | Accepted, then rewritten: it reads back as 1980/1/31. A date that cannot be parsed at all is dropped, and the field is simply absent. |
"noteRatePercent": "0.06375" | Accepted as a rate of 0.06%, not 6.375%. |
"mortgageType": "CONVENTIONAL" | Accepted, then dropped: mortgageType matches only the exact spelling Conventional. Other enum-looking fields turn an unrecognized value into Other or a default instead. See Value Vocabularies. |
A second loanTerms term | Accepted; the later term wins and the earlier one is discarded as you stage. A product never sees two. |
The common thread is that this surface validates shape, not meaning. It checks that terms is a non-empty array, that every element is an object carrying exactly one key, that the key is one of the eleven branch keys, and that each value can be read as the type its field declares. Nothing above trips any of those. What a value means — whether a rate is a percent or a fraction, whether a date is the one you intended, which of two loanTerms you wanted — is entirely your responsibility.