API REFERENCE

View as Markdown

Beta

SAMI v2 Value Vocabularies

The documented values for every SAMI field that reads like an enumeration: participantType, propertyType, propertyPurpose, loanPurpose, housingExpenseType and the rest.

Send the values below, spelled exactly as shown. As Conventions explains, every field on this page accepts any string, and a submission never fails because of one. But when the loan is recorded, each field is mapped onto the list below. A value that is not on the list is not kept as you sent it. Depending on the field, it is recorded as Other with your value moved into the …OtherDescription sibling, replaced by a default, or dropped. At a glance says which, field by field. None of this is reported back to you.

Most fields match their values ignoring case, so purchase is read as Purchase. Three fields match only the exact spelling: participantType, mortgageType and housingExpenseType. participantType and housingExpenseType ignore surrounding spaces.

Do not copy values from the Order API enum pages. Loan Participant Type and its neighbours list the older Order API’s codes, spelled APPRAISER, TITLE_COMPANY and so on. SAMI spells the same roles Appraiser and TitleCompany. An Order API spelling is accepted without complaint, but a participantType of APPRAISER is recorded as OtherIndividual rather than Appraiser, and an upper-case mortgageType is dropped.

At a glance

Field Where it lives Case An unrecognized value is
participantType participant exact recorded as OtherCompany when companyName is set, OtherIndividual otherwise
propertyPurpose person.properties ignored dropped. See propertyPurpose for the property term.
propertyUsage property, and person.properties ignored recorded as Other, with your value in propertyUsageOtherDescription
propertyType property, and person.properties ignored recorded as Other, with your value in propertyTypeOtherDescription
valuationType property.valuations ignored recorded as Other, with your value in valuationTypeOtherDescription
identifierType participant.identifiers ignored dropped, with the whole identifier
loanPurpose loanTerms ignored recorded as Other, with your value in loanPurposeOtherDescription
mortgageType loanTerms exact dropped
housingExpenseType housingExpense exact dropped; the expense line is kept without a type
currentFirstMortgageHolderType refinance ignored recorded as Other. See the warning.
refinanceCashOutDeterminationType refinance ignored dropped
refinancePrimaryPurposeType refinance ignored recorded as Other, with your value in refinancePrimaryPurposeTypeOtherDescription
citizenshipResidencyType person.declarations ignored dropped
priorPropertyTitleType person.declarations ignored dropped
priorPropertyUsageType person.declarations ignored recorded as Other, with your value in priorPropertyUsageTypeOtherDescription
type and roleType participant.contactPoint ignored see Contact points

An …OtherDescription you send is kept only when the field’s value is Other. With a documented value, the description is ignored. With an unrecognized value, the description is replaced by that value, so "loanPurpose": "Construction" with a description of your own reads back as Other and Construction.

Parties

participantType

The role a participant plays in the transaction. It is the longest vocabulary in the model. A participant can be an individual, using the name fields, or an organization, using companyName, and several roles below exist in both forms.

A borrower is never a participant. Each borrower or co-borrower is a person term, and participant is for everyone else on the deal.

Value Value Value
AppraisalCompany FinancialPlanner PledgeSettlementCompany
Appraiser FloodInsurance PledgeSettlementAgent
Assignee GiftDonor PostCloser
Assignor HazardInsurance PowerOfAttorney
Beneficiary HomeownerAssociation Processor
BorrowerAlias Interviewer RESPAServiceProvider
Broker Investor RegulatoryAgent
Builder LandlordCompany ReviewAppraiser
BuyerAttorney LandlordIndividual Seller
BuyerRealEstateAgent Lender SellerAttorney
Closer LoanOfficer SellerRealEstateAgent
ClosingAgent LoanOriginator Servicing
ClosingAttorney MortgageInsuranceCompany SupervisoryAppraiser
ClosingCompany MortgageServicerCompany Surveyor
Compliance Notary ThirdPartyOriginator
CreditCompany OtherCompany TitleAgent
Custodian OtherIndividual TitleCompany
DocPreparer PledgeOriginationCompany Trust
DocSigning   Trustee
Escrow   Underwriter
    Warehouse

There is no …OtherDescription for participantType. The list is not exhaustive: the service recognizes more roles, such as Attorney, Spouse and Witness, and keeps each as sent, so send the role you mean. A value it doesn’t recognize, or a blank one, is recorded as OtherCompany when the participant has a companyName, and OtherIndividual otherwise. The match is exact after trimming, so appraiser is recorded as OtherIndividual, not Appraiser.

identifierType

The kind of identifier in one entry of participant.identifiers.

Value Notes
SSN US Social Security Number.
EIN Employer Identification Number.
NMLS Nationwide Multistate Licensing System ID.

These are values, so they are documented upper case, although any case is accepted. The key-casing rule that turns SSN into the key ssn never applies to values.

An identifier with any other identifierType is dropped whole, and the request still succeeds.

Contact points

A participant’s contactPoint carries two type fields. Unlike every other field on this page, type has a closed set of values.

Field Values An unrecognized value
type Phone, Email, Fax, Other The whole contact point is discarded. The request still succeeds.
roleType Home, Work, Mobile The contact point is kept, stored without a location. The same happens when roleType is omitted.

Both are matched ignoring case and surrounding whitespace, so PHONE and ` phone ` are both read as Phone. Pair Other with typeOtherDescription.

A read echoes a participant’s phone and fax contact points, with type as Phone or Fax. roleType is echoed only if the contact point was recorded with one: a phone sent without a recognized roleType comes back without one, and a fax sent through this API always does. A read doesn’t say whether a phone is a landline or a mobile.

An unrecognized type is dropped without an error. The whole contact point is discarded, and the request still succeeds. A dropped phone or fax is missing from the next read, but email and Other contact points are never echoed, so a read can’t confirm them. Check the type you send against the four allowed values: Phone, Email, Fax, Other.

Property

These three fields appear on the subject property term and on each entry of person.properties. They answer different questions, so a property usually carries all three:

  • propertyPurpose: the property’s role on this loan.
  • propertyUsage: how the property is occupied.
  • propertyType: what kind of building it is.

propertyPurpose

The top-level property term is the loan’s subject property, and a loan has one. Real estate a borrower already owns goes inside that borrower’s person.properties.

Value Means
SubjectProperty The property the loan is secured by. The role of the property term.
RealEstateAsset Real estate a borrower already owns, often called REO or real estate owned. The role of an entry of person.properties.
InvestigationFindings A property an investigation product found. The service assigns it to the properties such a product adds while it runs.

How it behaves:

  • On the property term it is not recorded. Every property term is recorded as the subject property, whatever the value, or with none. If you send more than one, the last is kept and the others are discarded, without an error.
  • On an entry of person.properties it is recorded, matched ignoring case. Any of the three values is kept, in its documented spelling. A missing or unrecognized value is recorded as no role. The entry still belongs to the borrower, but isn’t counted as real estate the borrower owns.
  • When you start a workflow, or reconfirm one, with terms, the value you send also picks the property a product such as ADV targets. That includes the value on the property term. The candidates are the kept property term and every person.properties entry.
    • The target is each property whose value is SubjectProperty, ignoring case.
    • If there is none, it is the one property with no value, when exactly one has none.
    • Otherwise there is no property target.
  • A workflow started on a session uses the recorded roles instead, where the property term is always SubjectProperty.
  • Reading the terms back returns the recorded role. The property term reads back as SubjectProperty, whatever you sent. Each person.properties entry comes back nested under its borrower, with the role it was recorded with, in its documented spelling. An entry recorded with no role comes back without propertyPurpose.

So send RealEstateAsset on every entry of person.properties. On the property term, leave propertyPurpose off or send SubjectProperty.

A large loan shows the subject property and RealEstateAsset holdings side by side.

propertyUsage

Value Notes
PrimaryResidence  
SecondHome  
Investment  
Other Pair with propertyUsageOtherDescription.

propertyType

The kind of structure, not the number of units. Send the unit count in numberOfUnits: a two-unit house is Detached or Attached with "numberOfUnits": "2".

Value Notes
Detached  
Attached  
Condominium  
DetachedCondominium  
HighRiseCondominium  
Cooperative  
PUD Planned unit development.
Modular  
ManufacturedHousing  
ManufacturedHousingSingleWide  
ManufacturedHousingDoubleWide  
ManufacturedHousingMultiWide  
ManufacturedHomeCondominium  
ManufacturedHomeCondominiumOrPUDOrCooperative  
Other Pair with propertyTypeOtherDescription.

valuationType

The method behind one entry of property.valuations. An appraisal and an AVM on the same property are two entries, each with its own valuationType.

Value Notes
FullAppraisal  
DriveBy  
DesktopAppraisal  
PriorAppraisalUsed  
BrokerPriceOpinion  
AutomatedValuationModel An AVM.
TaxValuation  
None  
Other Pair with valuationTypeOtherDescription.

Loan

loanPurpose

On loanTerms.

Value Notes
Purchase  
Refinance The detail goes in a refinance term. Nothing ties the two together or enforces this.
Other Pair with loanPurposeOtherDescription.
Unknown  

mortgageType

On loanTerms. Unlike most fields with an Other value, mortgageType has no …OtherDescription sibling, and a value outside the list is dropped.

Value Value
Conventional LocalAgency
FHA StateAgency
VA PublicAndIndianHousing
HELOC USDARuralDevelopment
FarmersHomeAdministration Other

housingExpenseType

On housingExpense, which is sent once per expense line. OtherHousingExpense is the catch-all, and there is no …OtherDescription.

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).

Value Notes
FirstMortgagePrincipalAndInterest  
OtherMortgageLoanPrincipalAndInterest  
HazardInsurance  
RealEstateTax  
MI Mortgage insurance.
GroundRent  
HomeownersAssociationDuesAndCondominiumFees  
OtherHousingExpense  

Refinance

All three are on the refinance term.

currentFirstMortgageHolderType

Who holds the mortgage being refinanced.

currentFirstMortgageHolderTypeOtherDescription is not currently recorded as sent. See Known Issues.

Value Notes
FNM Fannie Mae.
FRE Freddie Mac.
Other Pair with currentFirstMortgageHolderTypeOtherDescription.
Unknown  

refinanceCashOutDeterminationType

How the cash-out question was answered. There is no …OtherDescription.

Value
CashOut
LimitedCashOut
NoCashOut
Unknown

refinancePrimaryPurposeType

The main reason for the refinance.

Value Value
AssetAcquisition Medical
CapitalizedInterestTaxesInsuranceOrFees PayoffLeaseholdInterest
Cash PrimaryLienPayoff
ChangeInRateTerm SecondaryLienPayoff
Convenience SpecialPurpose
DebtConsolidation UnsecuredLienPayoff
Education Unspecified
EquityBuyout Other
HomeImprovement  

Pair Other with refinancePrimaryPurposeTypeOtherDescription.

Borrower declarations

All three are on person.declarations, the yes-or-no questions from the mortgage application. The other declarations are JSON booleans, apart from priorPropertyUsageTypeOtherDescription.

citizenshipResidencyType

Value
USCitizen
PermanentResidentAlien
NonPermanentResidentAlien
NonResidentAlien
Unknown

priorPropertyTitleType

Value
Sole
JointWithSpouse
JointWithOtherThanSpouse

priorPropertyUsageType

The same values as propertyUsage.

Value Notes
PrimaryResidence  
SecondHome  
Investment  
Other Pair with priorPropertyUsageTypeOtherDescription.

Fields with a closed set

These fields have no …OtherDescription. Each is mapped onto a fixed list, and a value outside it is dropped.

Field Recorded values
person.gender M or F. Any value beginning with either letter, ignoring case, is read as that letter, so Female is recorded as F.
person.ethnicGroup White, Black, Hispanic, Indian, Pacific Islander, Asian, American Indian, Multi-racial, Middle Eastern, Other, ignoring case.
person.eyeColor Amber, Black, Blue, Brown, Gray, Green, Hazel, Violet, Red, Other, ignoring case.
participant.items keys AppraiserLicense, TaxIdentificationSSN, TaxIdentificationEIN, OrganizationIdentifier, NMLSIdentifier, BankAccountNumber, YearOfBirth, MonthOfBirth, DayOfBirth, Gender, EthnicGroup, EyeColor, exact case. An item with any other key is dropped.

Fields with no vocabulary

These are recorded as sent, so send whatever your source system holds:

  • license.licenseType and person.courtDetails[].courtCaseType.
  • consentTokens[].type. The consent regimes a product recognizes are documented with that product.

Copyright © Pitchpoint Solutions. All rights reserved.