# Term Examples

Source: https://docs.pitchpointsolutions.com/api/sami_terms/examples/

**Beta**

## SAMI v2 Term Examples

Worked `terms` arrays, in the shape [Stage Data](https://docs.pitchpointsolutions.com/api/session/stage_session_sami/) and [Start a Workflow](https://docs.pitchpointsolutions.com/api/workflow/start_workflow/) accept. Read [Conventions](https://docs.pitchpointsolutions.com/api/sami_terms/conventions/) first — the rules there are what these examples are demonstrating.

All values below are fabricated.

> **Before Starting:** 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

One borrower and one property. Note that each term is an object with exactly one key, and the array is flat.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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"
      }
    }
  ]
}
```

> **Warning:** **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](https://docs.pitchpointsolutions.com/api/sami_terms/conventions/#presenthousingexpense)).

### A participant

A party to the transaction who is not a borrower. `participantType` has [a long documented vocabulary](https://docs.pitchpointsolutions.com/api/sami_terms/vocabularies/#participanttype), 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`.

```json
{
  "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.

```json
{
  "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](https://docs.pitchpointsolutions.com/api/sami_terms/build_a_loan/) assembles it one term at a time.

Everything here is fabricated.

```json
{
  "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](https://docs.pitchpointsolutions.com/api/sami_terms/conventions/):

* **Four borrowers are four `person` terms.** A relationship here is expressed by containment, never by reference. A borrower's residences, employers and owned property sit *inside* that `person`, and the nesting is the whole of what assigns them. What no term does is point at another term: nothing ties a `person` to the subject `property`, or to a `participant`, or to another `person`. A term's `correlationId` names 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 the `person` when 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](https://docs.pitchpointsolutions.com/api/sami_terms/conventions/#correlation-ids-on-terms).
* **Employment, addresses and owned property all hang off the person.** `employers`, `residences` and `properties` are flat arrays on the `person` branch, not terms of their own. `currentIndicator` marks which entry is the present one, and a borrower who works for themselves is an ordinary employer entry with `selfEmployedIndicator` set. Tenure is `yearsOnJob` or `monthsOnJob` — 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 `property` term, and a loan has at most one. Real estate a borrower already owns hangs off that person in `properties`, and nesting is how the ownership is expressed. The branch is the same shape in both places. `propertyPurpose` is `RealEstateAsset` on each nested holding, and is left off the `property` term, which is always the subject property. Do not reach for `property.ownerName` to tie a holding to a borrower: it is an unparsed string that is deliberately not linked to any `person` term, and correlating it is left to whoever consumes the loan.
* **The loan-level branches appear once each.** `loanTerms`, `loanToValue`, `transactionDetail`, `loanDetail` and `closing` are all send-at-most-one. A second one is not rejected: the last one in the array replaces the others.
* **`housingExpense` is 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.
* **`refinance` is absent on purpose.** `loanPurpose` here is `Purchase`. Nothing ties the `refinance` branch to `loanPurpose` — sending it on a purchase is accepted and simply meaningless — so a purchase loan carries the purchase-side terms and leaves it out.

> **Warning:** **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](https://docs.pitchpointsolutions.com/api/sami_terms/vocabularies/#at-a-glance). |
| 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.