API REFERENCE

View as Markdown

Beta

Build a Loan Step by Step

This guide builds the loan in A large loan one term at a time. Each step adds to the body from the previous step and describes the fields it introduces. The finished body has seventeen terms: four borrowers, the subject property, three participants, a company, and the loan-level terms.

Steps 1 to 5 show the whole request body. From Step 6, each step shows only the terms it adds to the terms array. At the end of every step, the array is a complete request for Stage a Loan. All values are fabricated.

To send a body you need an access token (Obtaining An Access Token) and a session (Start a Session). Sessions and Workflows walks through the whole flow. Mortgage terms such as REO and LTV are defined in the Glossary.

Step 1: Add a borrower

A loan is an object with a single terms array. Each element is a term: an object with exactly one key, which names the kind of fact it holds. A borrower is a person term.

{
  "terms": [
    {
      "person": {
        "firstName": "Jane",
        "lastName": "Sample",
        "ssn": "000-00-0000",
        "dob": "01/31/1980"
      }
    }
  ]
}
Field Type Description
terms array of objects The loan. Required, and must not be empty.
person object A borrower or co-borrower. Every person term is a borrower. Other parties to the loan are participant terms.
firstName string The borrower’s first name.
lastName string The borrower’s last name.
ssn string The borrower’s Social Security number.
dob string The borrower’s date of birth, in mm/dd/yyyy format.

Keys are camelCase. ssn and dob are two of the six irregular keys. A date in any other format, such as 1980-01-31, is accepted but not recorded as sent.

Step 2: Add contact details

Facts about the borrower go directly on the person object.

{
  "terms": [
    {
      "person": {
        "firstName": "Jane",
        "middleName": "Quinn",
        "lastName": "Sample",
        "ssn": "000-00-0000",
        "dob": "01/31/1980",
        "homePhone": "5555550100",
        "email": "jane.sample@example.com"
      }
    }
  ]
}
Field Type Description
middleName string The borrower’s middle name.
homePhone string The borrower’s home phone number.
email string The borrower’s email address.

All of these fields are optional. An omitted field is recorded as absent.

Step 3: Add a residence

A borrower’s addresses are in the residences array.

{
  "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"
            }
          }
        ]
      }
    }
  ]
}
Field Type Description
residences array of objects The addresses the borrower has lived at.
currentIndicator boolean true for the address the borrower lives at now.
address object A postal address: addressLine1, city, state and postalCode, plus the optional addressLine2, addressLine3 and county. The same object is used on employers, properties and participants.

Arrays hold their objects directly, with no wrapper object. The order of entries has no meaning. Booleans are JSON booleans, true rather than "true".

Step 4: Add an employer

A borrower’s employment is in the employers array.

{
  "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",
              "city": "Sampleton",
              "state": "NY",
              "postalCode": "00000"
            }
          }
        ]
      }
    }
  ]
}
Field Type Description
employers array of objects The borrower’s employment records.
name string The employer’s name.
phone string The employer’s phone number.
ein string The employer’s Employer Identification Number.
monthlyIncome string The borrower’s monthly income from this employer, as a decimal string.
yearsOnJob string The borrower’s tenure with this employer, in years.
currentIndicator boolean true for the borrower’s present employer.
selfEmployedIndicator boolean true if the borrower works for themselves.
address object The employer’s address.

Amounts and counts are strings: "9400.00" and "6", not 9400 and 6. The service ignores keys it doesn’t recognize, so a misspelled key such as employerName is dropped without an error.

Step 5: Add a property the borrower owns

Real estate a borrower already owns (REO, real estate owned) is in the properties array of that borrower’s person. The nesting is what records the ownership. No term refers to another term.

This is the first borrower’s complete term.

{
  "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",
              "city": "Sampleton",
              "state": "NY",
              "postalCode": "00000"
            }
          }
        ],
        "properties": [
          {
            "propertyPurpose": "RealEstateAsset",
            "propertyUsage": "Investment",
            "propertyType": "Condominium",
            "address": {
              "addressLine1": "480 Specimen Road",
              "city": "Sampleton",
              "state": "NY",
              "postalCode": "00000"
            },
            "numberOfUnits": "1",
            "valuations": [
              {
                "valuationType": "AutomatedValuationModel",
                "valuationAmount": "289000.00"
              }
            ]
          }
        ]
      }
    }
  ]
}
Field Type Description
properties array of objects Real estate the borrower owns, other than the subject property.
propertyPurpose string The property’s role on the loan. RealEstateAsset for a property the borrower owns.
propertyUsage string How the property is occupied. Possible values: PrimaryResidence, SecondHome, Investment, Other.
propertyType string The kind of building. Possible values.
numberOfUnits string The number of units in the property.
valuations array of objects The property’s valuations, one entry per method.
valuationType string The valuation method. Possible values.
valuationAmount string The value, as a decimal string.

A value outside a field’s possible values is accepted, but it is recorded as Other or dropped, depending on the field. See Value Vocabularies.

Step 6: Add a co-borrower

A co-borrower is a second person term in the same array. Add this term after the first borrower’s.

{
  "person": {
    "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"
        }
      }
    ]
  }
}

Each borrower has their own residences, employers and properties. John lives at the same address as Jane, so his term repeats it. There is no borrower or co-borrower flag, and the order of the terms has no meaning.

Step 7: Add a prior address and self-employment

Add the third borrower.

{
  "person": {
    "firstName": "Priya",
    "lastName": "Example",
    "ssn": "000-00-0002",
    "dob": "03/22/1981",
    "homePhone": "5555550102",
    "residences": [
      {
        "currentIndicator": true,
        "address": {
          "addressLine1": "12 Example Avenue",
          "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"
      }
    ]
  }
}
Field Type Description
currentIndicator boolean false for an address the borrower no longer lives at.
selfEmployedIndicator boolean true for a borrower who owns the business.
monthsOnJob string The borrower’s tenure with this employer, in months. An alternative to yearsOnJob. Neither is calculated from the other.

Step 8: Add a borrower with fewer details

Add the fourth borrower.

{
  "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",
          "city": "Sampleton",
          "state": "NY",
          "postalCode": "00000"
        }
      }
    ]
  }
}
Field Type Description
nameSuffix string A generational or professional suffix, such as Jr. or III.

Each product sets how many borrowers it analyzes. Staging doesn’t check the count. A loan with more borrowers than the product accepts stages successfully, then fails when the workflow runs. Ask your Pitchpoint Account Representative for your product’s limit.

Step 9: Add the subject property

The subject property is the property the loan is secured by. It is the property term, and it is the property that property products, such as FEMA flood, analyze. Add this term.

{
  "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"
      }
    ]
  }
}
Field Type Description
property object The loan’s property. Recorded as the subject property.
county string The county name, on address.
assessorsParcelNumber string The parcel number recorded by the county assessor.
countyFIPSCode string The five-digit county FIPS code.
saleDate string The date of the last sale, in mm/dd/yyyy format.
saleAmount string The price of the last sale.
assessmentDate string The date of the last assessment, in mm/dd/yyyy format.
assessmentAmount string The assessed value.

propertyPurpose is not needed here: a property term is always recorded as the subject property. A loan has at most one property term. If you send more than one, the last is kept and the others are discarded, without an error. A borrower’s other real estate belongs in that borrower’s properties (Step 5).

Step 10: Add the lender

A party to the loan who is not a borrower is a participant term. Add the lender.

{
  "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"
      }
    ]
  }
}
Field Type Description
participant object A professional or institutional party to the loan.
participantType string The party’s role. Matched exactly. A value that doesn’t match is recorded as OtherCompany, or OtherIndividual when there is no companyName. Possible values.
companyName string The name of the organization.
contactPoint object A single way to reach the party.
roleType string The capacity the contact point applies in. Possible values: Home, Work, Mobile.
type string The channel. Possible values: Phone, Email, Fax, Other. Any other value discards the contact point.
value string The phone number or address.
preferenceIndicator boolean true if this is the party’s preferred contact point.
identifiers array of objects The party’s government and industry identifiers.
identifierType string The kind of identifier. Possible values: SSN, EIN, NMLS. Identifiers of any other type are not recorded.
identifierValue string The identifier.

Step 11: Add an appraiser and an escrow company

A participant can be an individual, an organization, or an individual at an organization. Add both terms.

{
  "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
    }
  }
}
Field Type Description
firstName string The individual’s first name. Used with companyName for an individual at a firm.
lastName string The individual’s last name.
licenses array of objects The party’s professional licenses, one entry per license and state.
licenseNumber string The license number.
licenseType string The kind of license.
licenseState string The two-letter code of the issuing state.

Step 12: Add a company

A company term describes an organization that is itself a subject of the loan. It is used mainly by the bank-account monitoring products. Send one only when your product requires it.

{
  "company": {
    "name": "Example Holdings LLC",
    "address": {
      "addressLine1": "250 Example Boulevard",
      "city": "Sampleton",
      "state": "NY",
      "postalCode": "00000"
    }
  }
}
Field Type Description
company object An organization that is a subject of the loan.
name string The company’s name.

Step 13: Add the loan-level terms

Facts about the loan have their own branches. Add these five terms.

{ "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" } }
Field Type Description
noteAmount string The face amount of the note.
loanAmount string The loan amount. Recorded separately from noteAmount.
noteRatePercent string The note rate, as a percentage: "6.375", not "0.06375".
noteDate string The date of the note, in mm/dd/yyyy format.
loanPurpose string Possible values: Purchase, Refinance, Other, Unknown.
mortgageType string The mortgage program. Matched exactly: Conventional is recorded, CONVENTIONAL is dropped. Possible values.
ltvRatioPercent string The loan-to-value ratio, as a percentage.
cltvRatioPercent string The combined loan-to-value ratio, as a percentage.
purchasePrice string The contract purchase price.
loanOriginatorApplicationDate string The application date, in mm/dd/yyyy format.
totalDebtToIncomeRatioPercent string The total debt-to-income ratio, as a percentage.
settlementDate string The closing date, in mm/dd/yyyy format.

Send at most one of each of these branches. If you send more than one, the last replaces the others. A refinance also has a refinance term, with loanPurpose set to Refinance.

Step 14: Add housing expenses

housingExpense is the loan-level branch that repeats, once per expense. Add three terms.

{ "housingExpense": { "housingExpenseType": "FirstMortgagePrincipalAndInterest", "presentHousingExpense": true, "monthlyAmount": "1850.00" } }

{ "housingExpense": { "housingExpenseType": "HazardInsurance", "presentHousingExpense": true, "monthlyAmount": "140.00" } }

{ "housingExpense": { "housingExpenseType": "RealEstateTax", "presentHousingExpense": true, "monthlyAmount": "410.00" } }
Field Type Description
housingExpenseType string The kind of expense. Matched exactly. Possible values.
presentHousingExpense boolean true for an expense the borrowers pay now. Required.
monthlyAmount string The monthly amount.

Send "presentHousingExpense": true on every line. A proposed expense is not recorded, and a line without the flag fails. See Known Issues.

Step 15: Stage the loan

The body now has seventeen terms. A large loan shows it in full. The order of the terms has no meaning.

Send it to Stage a Loan. Keep your own copy of what you send. The loan is recorded against the field rules and value lists, so what a later read returns can differ from the request.

Copyright © Pitchpoint Solutions. All rights reserved.