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.

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
• Parties
  • participantType
  • identifierType
  • Contact points
• Property
  • propertyPurpose
  • propertyUsage
  • propertyType
  • valuationType
• Loan
  • loanPurpose
  • mortgageType
  • housingExpenseType
• Refinance
  • currentFirstMortgageHolderType
  • refinanceCashOutDeterminationType
  • refinancePrimaryPurposeType
• Borrower declarations
  • citizenshipResidencyType
  • priorPropertyTitleType
  • priorPropertyUsageType
• Fields with an undocumented closed set
• Fields with no vocabulary

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. For a role that is not listed, use OtherIndividual or OtherCompany, which is what an unrecognized value becomes anyway. The match is exact, 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.
Other	Accepted, but the identifier is not recorded. See below.

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.

Only SSN, EIN and NMLS identifiers are recorded. See Known Issues.

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 discarded email leaves no trace. A read echoes a participant’s phone or fax, though in the service’s own spellings (LANDLINE, MOBILE or FAX, with a role of HOME, BUSINESS or MOBILE) rather than the values you sent. An email or Other contact point is never echoed, so if one is discarded, nothing on a read shows it. Check the type you send against the four values above.

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

On a property term, propertyPurpose is ignored. A property term is always recorded as the subject property, whatever you send. The field is read only on the entries of person.properties, so InvestigationFindings cannot be set on a property term.

Value	Use it for
SubjectProperty	The property the loan is secured by. Implied by the property term, so you don’t need to send it there.
RealEstateAsset	Real estate a borrower already owns, often called REO or real estate owned. Sent inside that borrower’s person.properties.
InvestigationFindings	A property surfaced by an investigation rather than supplied by the borrower.

A large loan shows SubjectProperty and RealEstateAsset 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 "presentHousingExpense": true on every line. A proposed expense is not recorded, and a line without the flag fails. See Known Issues.

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 an undocumented closed set

These fields are not listed in the term catalog, but each is still 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 is read as that letter.
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.