API REFERENCE
Beta
SAMI v2 Term Examples
Worked terms arrays, in the shape Stage a Loan 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
- 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": [
{
"employerName": "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 type, however you might group them in your own model.
{
"terms": [
{
"housingExpense": {
"housingExpenseType": "FirstMortgagePrincipalAndInterest",
"paymentAmount": "2810.00"
}
},
{
"housingExpense": {
"housingExpenseType": "HazardInsurance",
"paymentAmount": "120.00"
}
},
{
"housingExpense": {
"housingExpenseType": "RealEstateTax",
"paymentAmount": "450.00"
}
}
]
}
A participant
A party to the transaction who is not a borrower. participantType has a long documented vocabulary, but like the other enum-looking fields it is free text — prefer a documented value, and expect no error if you send something else.
{
"terms": [
{
"participant": {
"participantType": "Lender",
"companyName": "Example Lending"
}
}
]
}
A complete submission
Everything above, assembled as one request body.
{
"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": "Detached",
"address": {
"addressLine1": "1 Sample Street",
"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"
}
}
]
}
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 |
|---|---|
{"person":{…},"property":{…}} as one term | Accepted; one of the two facts is silently dropped. |
"firstname" instead of "firstName" | The key is unrecognized, so it is ignored. The name is simply absent. |
"noteAmount": 450000.00 as a number | Not the documented form. Send the string "450000.00". |
"dob": "1980-01-31" | Accepted here; fails later, far from the request that caused it. |
"noteRatePercent": "0.06375" | Accepted as a rate of 0.06%, not 6.375%. |
A second loanTerms term | Accepted; nothing decides which of the two a product reads. |
The common thread is that this surface validates shape, not meaning. Only three things are checked: that terms is a non-empty array, that every element is an object, and that every element carries one of the eleven branch keys. Everything else is your responsibility.