# Value Vocabularies Source: https://docs.pitchpointsolutions.com/api/sami_terms/vocabularies/ **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](https://docs.pitchpointsolutions.com/api/sami_terms/conventions/#convention-4-fields-that-look-like-enums-are-free-text) 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](https://docs.pitchpointsolutions.com/api/sami_terms/vocabularies/#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`. > **Warning:** **Do not copy values from the Order API enum pages.** [Loan Participant Type](https://docs.pitchpointsolutions.com/api/order/enums/types_loanparticipant/) 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](https://docs.pitchpointsolutions.com/api/sami_terms/vocabularies/#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](https://docs.pitchpointsolutions.com/api/sami_terms/vocabularies/#currentfirstmortgageholdertype). | | `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](https://docs.pitchpointsolutions.com/api/sami_terms/vocabularies/#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. > **Warning:** Only `SSN`, `EIN` and `NMLS` identifiers are recorded. See [Known Issues](https://docs.pitchpointsolutions.com/api/sami_terms/known_issues/#identifier-other). #### 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`. > **Warning:** **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 > **Warning:** **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](https://docs.pitchpointsolutions.com/api/sami_terms/examples/#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`. > **Warning:** **Send `"presentHousingExpense": true` on every line.** A proposed expense is not recorded, and a line without the flag fails. See [Known Issues](https://docs.pitchpointsolutions.com/api/sami_terms/known_issues/#proposed-housing-expense). | 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. > **Warning:** `currentFirstMortgageHolderTypeOtherDescription` is not currently recorded as sent. See [Known Issues](https://docs.pitchpointsolutions.com/api/sami_terms/known_issues/#mortgage-holder-description). | 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`](https://docs.pitchpointsolutions.com/api/sami_terms/vocabularies/#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.