openapi: 3.2.0 info: title: Mortgage Services Orders API version: 1.5.0 servers: - url: https://settlement.stageapi.firstam.com description: Stage Environment variables: {} tags: - name: Orders paths: /orders: post: security: - bearerAuth: [] tags: - Orders summary: Open an Order description: 'Open Title and Escrow orders with First American. Please discuss your business objectives with First American in order to determine which service(s) to order to support your needs. **Note: Property address and external tracking ID has to be unique per transaction.**' operationId: OrdersPost requestBody: description: Order Request content: application/json: schema: $ref: '#/components/schemas/OrderRequest' example: appSource: Replace with FA Provided ID service: EscrowTitle parties: - legalEntity: BusinessEntity contacts: - firstName: Joe lastName: BusinessEntity contactPoints: - contactPointType: Work emailAccount: sample@firstam.com phoneNumber: '1234571425' role: Other primaryName: Sample Business Entity role: Lender - firstName: Joe lastName: REAgent contactPoints: - contactPointType: Work emailAccount: sample@firstam.com phoneNumber: '9876571425' role: SellerRealEstateAgent - firstName: Joe lastName: Seller maritalStatus: aSingleMan contactPoints: - contactPointType: Work emailAccount: sample@firstam.com phoneNumber: '7142568467' role: Seller - firstName: Joe lastName: Buyer maritalStatus: aSinglePerson contactPoints: - contactPointType: Work emailAccount: sample@firstam.com phoneNumber: '7142584685' role: BuyerBorrower - firstName: Joe lastName: CoBuyer maritalStatus: aSingleWoman contactPoints: - contactPointType: Work emailAccount: sample@firstam.com phoneNumber: '8468577142' role: CoBuyerBorrower - firstName: Joe lastName: LoanOfficer contactPoints: - contactPointType: Work emailAccount: sample@firstam.com phoneNumber: '7142571425' role: LoanOfficer - firstName: Michel lastName: LoanProcessor contactPoints: - contactPointType: Work emailAccount: sample@firstam.com phoneNumber: '7142500000' role: LoanProcessor propertyAddress: addressLine1: replace with street address cityName: Santa Ana postalCode: '92706' stateCode: CA countyName: Orange propertyType: Condominium APN: '' transactionType: SaleWithMortgage externalTrackingId: replace with a unique transaction ID officeId: replace with Office Id escrowOfficerCode: replace with Escrow Officer Code titleOfficerCode: replace with Title Officer Code loan: loanNumber: Loan12345-345 loanAmount: '1234' loanType: FHA transactionDetails: contractSignedDate: '2020-02-03T00:00:00.000Z' earnestMoneyDeposit: '234' inspectionEndDate: '2020-02-05T00:00:00.000Z' homeOwnersAssociation: 'false' closeOfEscrowDate: '2020-02-11T00:00:00.000Z' acquisitionPrice: '1290' payoffInformations: - payoffType: LenderOrderSubordinate loanNumber: '787782232' loanAmount: '70000' lienPosition: '1' liabilityType: MortgageLoan lenderName: Wells Fargo lenderPhone: '1112223333' Documents: - Name: TestDocInOrderRequest PageCount: '1' IsFinalized: 'true' FileExtension: pdf EmbeddedContent: Base64 content here responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ResourceResponse' example: ID: e54227d6-27f9-43dd-9dae-0c3c8a370ddd externalReferenceId: same value provided in request. DateTime: '2020-05-06T20:53:25' Status: 1 Message: Successful /orders/{externalTrackingId}/documents: post: summary: Upload a Document description: 'Upload a document for a specific order. ''AppSource'' is required for the customer using the source level credentials.' security: - bearerAuth: [] tags: - Orders operationId: Orders_UploadDocument parameters: - name: externalTrackingId in: path required: true description: Client provided transaction ID used when opening order. schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DocumentPayload' example: appSource: Replace with FA Provided ID name: Sample Document fileExtension: pdf embeddedContent: Base64 content here serviceType: Escrow text/json: schema: $ref: '#/components/schemas/DocumentPayload' application/xml: schema: $ref: '#/components/schemas/DocumentPayload' text/xml: schema: $ref: '#/components/schemas/DocumentPayload' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/DocumentPayload' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ResourceResponse' example: ID: e54227d6-27f9-43dd-9dae-0c3c8a370ddd externalReferenceId: same value provided in request. DateTime: '2020-05-06T20:53:25' Status: 1 Message: Successful /orders/{externalTrackingId}/messages: post: summary: Send a Message description: 'Send a message to the escrow officer of the order. ''AppSource'' is required for the customer using the source level credentials.' security: - bearerAuth: [] tags: - Orders operationId: Orders_PostMessage parameters: - name: externalTrackingId in: path required: true description: Client provided transaction ID used when opening order. schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/MessagePayload' text/json: schema: $ref: '#/components/schemas/MessagePayload' application/xml: schema: $ref: '#/components/schemas/MessagePayload' text/xml: schema: $ref: '#/components/schemas/MessagePayload' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/MessagePayload' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ResourceResponse' example: ID: e54227d6-27f9-43dd-9dae-0c3c8a370ddd externalReferenceId: same value provided in request. DateTime: '2020-05-06T20:53:25' Status: 1 Message: Successful /orders/{externalTrackingId}/cancel: post: summary: Cancel an Order description: 'Cancel an Order previously created **Note:''AppSource'' is required for the customer using the source level credentials.**' security: - bearerAuth: [] tags: - Orders operationId: Orders_Cancel parameters: - name: externalTrackingId in: path required: true description: Client provided transaction ID used when opening order. schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/OrderCancelRequest' text/json: schema: $ref: '#/components/schemas/OrderCancelRequest' application/xml: schema: $ref: '#/components/schemas/OrderCancelRequest' text/xml: schema: $ref: '#/components/schemas/OrderCancelRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/OrderCancelRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/OrderCancelResponse' example: ID: e54227d6-27f9-43dd-9dae-0c3c8a370ddd externalReferenceId: same value provided in request. DateTime: '2020-05-06T20:53:25' Status: 1 Message: Successful components: schemas: OrderRequest: type: object properties: appSource: type: string description: A required unique application ID provided by First American Title to identify clients. service: enum: - Escrow - Title - EscrowTitle type: string description: A required value of available service options provided by First American Title. example: TitleEscrow parties: uniqueItems: false type: array items: anyOf: - $ref: '#/components/schemas/IndividualParty' - $ref: '#/components/schemas/LegalEntityParty' description: List of parties involved in the transaction. Party type can be either LegalEntityParty or IndividualParty propertyAddress: $ref: '#/components/schemas/PropertyAddress' officeId: type: string description: An optional field that can be provided if a preference of service location exists. An officeId can be obtained via the Offices resource. example: 4356 escrowOfficerCode: type: string description: An optional field that can be provided for escrow officer. An escrowOfficerCode can be obtained via the employees/escrowOfficers resource. example: CJCLEMENS titleOfficerCode: type: string description: An optional field that can be provided for title officer. A titleOfficerCode can be obtained via the employees/titleOfficers resource. example: CJCLEMENS transactionType: enum: - SaleWithMortgage - SaleCash - Refinance - EquityLoan - SaleWithConstructionLoan - ConstructionFinance - SearchPackage - Other type: string description: A required value that specifies the purpose for the transaction service request. example: SaleWithMortgage notes: type: string description: An optional free text field for additional service request information. externalTrackingId: type: string description: Client provided transaction ID used to communicate inbound and outbound. loan: $ref: '#/components/schemas/Loan' Documents: type: array items: $ref: '#/components/schemas/Document' description: List of documents involved in the transaction. transactionDetails: $ref: '#/components/schemas/TransactionDetails' required: - appSource - service - parties - propertyAddress - transactionType - externalTrackingId OrderCancelResponse: type: object properties: ID: format: uuid type: string example: 00000000-0000-0000-0000-000000000000 description: A unique message ID used for troubleshooting. externalReferenceId: type: string description: An echo of the externalReferenceId provided in the request. DateTime: $ref: '#/components/schemas/UtcDateTime' Status: format: int32 type: integer description: 1 indicates success. 0 indicates failure. Review Message field for details. Message: type: string description: Provides a detailed desciption of the Status field. OtherRole: enum: - NotApplicable - BuyerBorrower - Seller - BuyerRealEstateAgent - SellerRealEstateAgent - Lender - PayoffLender - MortgageBroker - Other - BuyerRealEstateBroker - BuyerAttorney - BuyerTransactionCoordinator - NewLender - SellerAttorney - SellerRealEstateBroker - SellerTransactionCoordinator - OutsideTitle - OutsideEscrow - Builder - Investor type: string description: Only use this when RequestingSource is provided as the role. Consult with First American before using. example: BuyerBorrower IndividualParty: type: object properties: firstName: type: string description: 'The first name of the party in the transaction. ' lastName: type: string description: 'The last name of the party in the transaction. ' maritalStatus: enum: - aSingleMan - aSingleWoman - aSinglePerson - HusbandAndWife - aMarriedMan - aMarriedWoman - anUnmarriedPerson - aRegisteredDomesticPartner - NotApplicable - Other type: string description: The marital status of the party in the transaction. example: HusbandAndWife middleName: type: string description: The middle name of the party in the transaction. salutation: type: string description: The salutation of the party in the transaction. suffix: type: string description: The suffix of the party in the transaction. spouseName: type: string description: The spouse name of the party in the transaction. contactPoints: uniqueItems: false type: array items: $ref: '#/components/schemas/ContactPoint' description: A list of contact points. primaryName: type: string description: The primary name of the party in the transaction. taxId: type: string description: The tax ID of the party in the transaction. role: $ref: '#/components/schemas/IndividualPartyRole' otherrole: enum: - NotApplicable - BuyerBorrower - Seller - BuyerRealEstateAgent - SellerRealEstateAgent - CoBuyerBorrower - Other - MortgageBroker - BuyerRealEstateBroker - BuyerAttorney - BuyerTransactionCoordinator - NewLender - SellerAttorney - SellerRealEstateBroker - SellerTransactionCoordinator - OutsideTitle - OutsideEscrow - Builder - Investor type: string description: Only use this when RequestingSource is provided as the role. Consult with First American before using. addresses: uniqueItems: false type: array items: $ref: '#/components/schemas/Address' required: - role - firstName - lastName Address: type: object properties: addressType: enum: - Other - Billing - Business - CurrentAddress - ForwardingAddress - Home - Mailing - NotaryAddress - SigningLocation - SubjectProperty type: string description: Address Type example: CurrentAddress addressLine1: type: string description: Address Line 1 example: 2 First American Way addressLine2: type: string description: Address Line 2 example: Unit 123 cityName: type: string description: City of an address example: Santa Ana countyName: type: string description: County Name example: Orange postalCode: type: string description: Postal Code example: 92706 stateCode: type: string description: State Code example: CA description: Address Definition required: - postalCode - stateCode LegalEntityParty: type: object properties: legalEntity: enum: - Trust - BusinessEntity type: string contacts: uniqueItems: false type: array items: $ref: '#/components/schemas/PartyContact' primaryName: type: string description: The primary name of the legal entity in the transaction. taxId: type: string description: The tax ID of the legal entity in the transaction. role: $ref: '#/components/schemas/LegalEntityPartyRole' otherRole: $ref: '#/components/schemas/OtherRole' addresses: uniqueItems: false type: array items: $ref: '#/components/schemas/Address' hoiAccount: type: string description: The unique identifier assigned by a homeowner's insurance company to a customer's policy or account. hoaAccount: type: string description: The unique identifier assigned by a homeowner's association to the owner(s) of a property within the association. required: - role - primaryName - legalEntity LegalEntityPartyRole: enum: - RequestingSource - BuyerBorrower - Seller - BuyerRealEstateAgent - SellerRealEstateAgent - Lender - PayoffLender - MortgageBroker - HomeOwnerAssociation - HomeOwnerInsurance - Other - BuyerRealEstateBroker - BuyerAttorney - BuyerTransactionCoordinator - NewLender - SellerAttorney - SellerRealEstateBroker - SellerTransactionCoordinator type: string description: "The role of the party in the transaction. BuyerBorrower required. \n\nRequestingSource is a special case for supporting iBuyers. Consult with First American before using." ContactPoint: type: object properties: contactPointType: enum: - Work - Mobile - Home - Other type: string description: Type of Contact Point example: Work emailAccount: type: string description: Contact's email address. faxNumber: type: string description: Contact's Fax Number. example: 714-250-0000 faxNumberExt: type: string description: Fax Number Extension phoneNumber: type: string description: Contact's phone number example: 714-250-0000 phoneNumberExt: type: string description: Phone Number Extension description: Contact Point Definition required: - contactPointType Document: type: object properties: Name: type: string maxLength: 256 description: The required document name used by the appSource. Description: type: string description: Optional descriptive name used by the appSource. DocumentType: enum: - TitleSearch - TitleCommitment - EMDReceipt - PayOff - FinalPolicy - LenderPolicy - TrailingDocuments - ExecutedClosingPackage-Piggyback - DisbursementSummaryReport - FeeSheet - ClosingProtectionLetter - TaxDocument - SettlementStatement - RecordedPackage - ClosingDisclosure - FundingTransmittal - ClosingDisclosureDraft - ExecutedClosingPackage - WiringInstructions type: string description: An optional value used to identify the type of document. PageCount: format: int32 type: integer description: An optional field used to provide the total number of pages included in a document upload. IsFinalized: type: boolean description: An optional value that can be used to state the status of a document version. FileExtension: enum: - pdf - doc - tiff - jpg - jpeg - docx - xls - xlsx type: string description: 'A required field used to identify the format of the document. ' EmbeddedContent: type: string description: A required Base64 encoded file within a max size of 20 MB. maxLength: 20971520 required: - Name - FileExtension - EmbeddedContent Loan: type: object properties: loanNumber: type: string description: An optional field that contains a unique loan identifier example: Loan12345-345 loanAmount: type: number format: decimal description: An optional field for the total dollar amount of the mortgage note that is being requested by the borrower example: 1234 LoanType: enum: - Conventional - FHA - VA type: string description: An optional field that contains a unique different loan types example: Conventional PayoffInformation: type: object properties: payoffType: enum: - LenderOrderBothPayoffSubordinate - LenderOrderPayoff - LenderOrderSubordinate - Other - TitleCompanyOrderBothPayoffSubordinate - TitleCompanyOrderPayoff - TitleCompanyOrderSubordinate type: string description: Payoff Type example: LenderOrderSubordinate loanNumber: type: string description: Loan Number example: '787782232' loanAmount: type: number format: decimal description: Loan Amount example: '70000' lienPosition: type: number format: integer description: Lien Position example: '1' liabilityType: enum: - BorrowerEstimatedTotalMonthlyLiabilityPayment - CollectionsJudgementsAndLiens - DeferredStudentLoan - DelinquentTaxes - FirstPositionMortgageLien - Garnishments - HELOC - HomeownersAssociationLien - Installment - LeasePayment - MonetaryJudgment - MortgageLoan - Open30DayChargeAccount - Other - PersonalLoan - Revolving - SecondPositionMortgageLien - Taxes - TaxLien - ThirdPositionMortgageLien - UnsecuredHomeImprovementLoanInstallment - UnsecuredHomeImprovementLoanRevolving type: string description: Payoff Type example: MortgageLoan lenderName: type: string description: Lender Name example: Wells Fargo lenderPhone: type: string description: Lender Phone example: 123-123-1234 LegalEntityPartyContactRole: enum: - BuyerBorrower - Seller - BuyerRealEstateAgent - SellerRealEstateAgent - Lender - PayoffLender - LoanOfficer - LoanProcessor - LoanCloser - MortgageBroker - HomeOwnerAssociation - HomeOwnerInsurance - Other - BuyerRealEstateBroker - BuyerAttorney - BuyerTransactionCoordinator - NewLender - SellerAttorney - SellerRealEstateBroker - SellerTransactionCoordinator type: string description: The role of the party in the transaction. BuyerBorrower required. ResourceResponse: type: object properties: ID: format: uuid type: string example: 00000000-0000-0000-0000-000000000000 description: A unique message ID used for troubleshooting. externalReferenceId: type: string description: An echo of the externalReferenceId provided in the request. DateTime: $ref: '#/components/schemas/UtcDateTime' Status: format: int32 type: integer description: 1 indicates success. 0 indicates failure. Review Message field for details. Message: type: string description: Provides a detailed desciption of the Status field. ServiceType: title: ServiceType enum: - Escrow - Title - EscrowTitle - Other type: string description: The required service type associated with the payload. example: Escrow DocumentPayload: type: object properties: VestingInformation: type: string description: Optional data that describes the way an owner (or owners) of property takes title to their real estate. LegalDescription: type: string description: Optional data that offers a description of real estate that is sufficient to identify it for legal purposes. Name: type: string maxLength: 256 description: The required document name used by the appSource. Description: type: string description: Optional descriptive name used by the appSource. DocumentType: enum: - TitleSearch - TitleCommitment - EMDReceipt - PayOff - FinalPolicy - LenderPolicy - TrailingDocuments - ExecutedClosingPackage-Piggyback - DisbursementSummaryReport - FeeSheet - ClosingProtectionLetter - TaxDocument - SettlementStatement - RecordedPackage - ClosingDisclosure - FundingTransmittal - ClosingDisclosureDraft - ExecutedClosingPackage - WiringInstructions type: string description: An optional value used to identify the type of document. PageCount: format: int32 type: integer description: An optional field used to provide the total number of pages included in a document upload. IsFinalized: type: boolean description: An optional value that can be used to state the status of a document version. FileExtension: enum: - pdf - doc - tiff - jpg - jpeg - docx - xls - xlsx type: string description: 'A required field used to identify the format of the document. ' Version: type: string description: An optional numeric value to identify the version of a document. EmbeddedContent: type: string description: A required Base64 encoded file within a max size of 20 MB. maxLength: 20971520 ServiceType: $ref: '#/components/schemas/ServiceType' Message: type: string description: Optional free form text provided by the application source. required: - Name - ServiceType - FileExtension - EmbeddedContent UtcDateTime: type: string format: date-time example: '2018-03-20T09:12:28Z' PropertyAddress: description: A required field providing the site location of the property in question. type: object properties: addressLine1: type: string description: Address Line 1 example: 2 First American Way addressLine2: type: string description: Address Line 2 example: Unit 123 cityName: type: string description: City of an Address example: Santa Ana countyName: type: string description: County Name example: Orange countyFips: type: string description: County FIPS example: 059 postalCode: type: string pattern: ^[0-9]{5}(-[0-9]{4})?$ description: Postal Code example: 92706 stateCode: type: string description: State Code example: CA PropertyType: enum: - SingleFamilyResidence - MultiResidential - Townhouse - Condominium - ManufacturedHome - VacantLand type: string description: Property Type example: SingleFamilyResidence APN: type: string description: Property APN example: 006-007-001-000 required: - countyName - postalCode - stateCode IndividualPartyRole: enum: - LoanOfficer - LoanProcessor - RequestingSource - BuyerBorrower - CoBuyerBorrower - Seller - BuyerRealEstateAgent - SellerRealEstateAgent - Other - MortgageBroker - BuyerRealEstateBroker - BuyerAttorney - BuyerTransactionCoordinator - NewLender - SellerAttorney - SellerRealEstateBroker - SellerTransactionCoordinator type: string description: "The role of the party in the transaction. BuyerBorrower required. \n\nRequestingSource is a special case for supporting iBuyers. Consult with First American before using." TransactionDetails: type: object properties: contractSignedDate: type: string format: date description: An optional field for the date on which the purchase agreement was signed example: '2020-02-03T00:00:00.000Z' earnestMoneyDeposit: type: number format: decimal description: An optional field for the amount of earnest money specified in the purchase agreement example: 234 inspectionEndDate: type: string format: date description: An optional field for the buyer's inspection deadline as specified in the purchase agreement example: '2020-02-05T00:00:00.000Z' homeOwnersAssociation: type: boolean description: An optional field to indicate whether the subject property is part of an HOA example: false closeOfEscrowDate: type: string format: date description: An optional field for estimated settlement date for the transaction example: '2020-02-11T00:00:00.000Z' acquisitionPrice: type: number format: decimal description: An optional field for sale price of the subject property example: 1290 payoffInformations: type: array items: $ref: '#/components/schemas/PayoffInformation' PartyContact: type: object properties: firstName: type: string description: 'The first name of the party contact. ' lastName: type: string description: 'The last name of the party contact. ' contactPoints: uniqueItems: false type: array items: $ref: '#/components/schemas/ContactPoint' description: A list of contact points. role: $ref: '#/components/schemas/LegalEntityPartyContactRole' OrderCancelRequest: type: object properties: AppSource: type: string example: Replace with FA Provide ID description: Subscription grouping ServiceType: $ref: '#/components/schemas/ServiceType' ReasonForCancel: type: string description: Reason for cancel required: - ServiceType MessagePayload: title: MessagePayload type: object properties: appSource: type: string example: Replace with FA Provided ID ServiceType: $ref: '#/components/schemas/ServiceType' Message: type: string description: The required message content. MessageType: type: string description: The required message type. required: - AppSource - ServiceType - Message securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: OAuth (a.k.a JWT) Authentication is **mandatory**. Please enter a valid access token