Authentication

The Arrowbase REST API authentication begins when you receive an AppraisalWorks issued Public/Private encryption key pair. AppraisalWorks will also issue you a Client ID.

Contact us to get setup.

After you receive your Public and Private keys, all new Requests will need to be signed to create an HMAC signature. Using your private key, generate a hash of the following comma separated elements using the SHA256 algorithm.

"POST,application/json,,/Orders,2022-04-12 16:32:25Z"

"GET,application/json,,/Orders/8189-F16E-03D8-4C3F/Comments/3702215,2022-04-12 16:32:25Z"

Note: The timestamp must be added to the ‘x-request-date’ header of the request.

Note: The timestamp must reflect the time at which the request is prepared for transmission. Basic security protocols will reject the request if it is processed by the server outside of a limited time window.

This string is being used for encryption and is case sensitive, especially to the HTTP Request method and the relative path.

hmac PublicKey:{signature}

Example Signature (C#):

string hmacPrivateKey = … your private key as a GUID
string canonical_string = "POST,application/json,,/Orders,2022-04-12 16:32:25Z";

UTF8Encoding encoder = new ();

var hmachasher = new HMACSHA256(encoder.GetBytes(hmacPrivKey));

byte[] hashedDataBytes = hmachasher.ComputeHash(encoder.GetBytes(canonical_string));

var signature = Convert.ToBase64String(hashedDataBytes);

Replace the ‘{signature}’ portion of the Authorization header with the ‘signature’ string from the code example.

Provider Fee Quote

Endpoint: POST /Orders/{transactionUID}/FeeQuote

The Fee Quote method pre-selects a provider for the order based on the client’s assignment criteria and returns that provider’s fee for the subject property location and product defined. This provides the client an opportunity to receive a provider fee quote before an order is placed.
The call only needs a client ID, the property address and a product code. The API call will then return valid data which the client can use to acquire prepayment from a borrower before placing an order for that property address and product code. When placing the order for a subject property that was previously quoted, the UniqueAssignment value provided in response to a quote request must be used in the new order request. This UniqueAssignment value should be inserted in the Additional Details section of the order request.

{
    "clientId": "123456",
    "address": {
        "streetAddress": "6000 Freedom Square Dr.",
        "city": "Independence",
        "state": "OH"",
        "zip": "44131",
        "county": "Cuyahoga",
    },
    "product": {
    "code": "A001" 
    }
}

The data fields required to fulfill this request are outlined below.

If the Fee Quote request succeeds the following JSON will be returned to the client.

{
    "quoteFee": "250.00",
    "vendorId": 1234,
    "uniqueAssignment": "F16E-81B9-4C3F-03D8",
    "isSuccess": true,
    "description": "Only present if isSuccess is false.",
    "datetime": "2022-04-04 16:58:31Z",
}

Transaction Details

The transaction details segment of the order request includes pertinent information about the new order. A detailed breakdown of the properties and descriptions are provided below.

{
    "referenceNumber": "API-012345",
    "complexProperty": false,
    "priority": true,
    "requestedDueDate": "12/1/2022",
    "fhaCaseNumber": "123456789",
    "internalComment": "Internal Comments for Appraisal Desk and Review Team",
    "duCaseFileID": "0123456789",
    "lpaKey": "01-2345678",
    "manualAssignOverride": true,
    "vendorInstructions": "Please reach out to the property contact to schedule the appointment.",
    "additionalDetails": [{ … }],
    "requestingParty": { … },
    "request": { … }
}

Additional Details

The additional details portion of the order data is an optional array of name/value pairs that can be used to annotate an order or drive additional order logic. Names that are well-defined (i.e. recognized by AppraisalWorks) will be applied to the order data when it is processed. The remaining name/value pairs will be annotated in a note placed on the order.

[
{
    "fieldName": "BorrowerPrepayment",
    "fieldValue": "250.00"
},
{
    "fieldName": "UniqueAssignment",
    "fieldValue": "F16E-81B9-4C3F-03D8"
}
]

In the example shown above the additional details property supports logic to pull a prior payment from the order request and update the payment history in the system accordingly.

Defined Name/Value Pairs

Requesting party

The requestingParty object contains information pertaining to the entity placing the order as defined below.

{
    "clientID": "4645",
    "name": "ABC Lender",
    "contactName": "John Smith"
}

Order Details

This object contains information specific to the transaction and subsequent order request.

{
    "internalAccountID": "12345",
    "branchID": "Branch4567",
    "loanAmount": 150000.00,
    "salesPrice": 210000.00,
    "estimatedValue": 200000.00,
    "loanType": "Refinance",
    "transactionUID": "0987-OB8C-FE36-9AC9",
    "requestData": {
        "action": "Original",
        "loan": {...}
    }
}

Loan Details

The Loan object is contained in the RequestData object and specifies data related to the property, loan, involved parties, and the product ordered.

{
   "application": {
      "property": {
         "streetAddress": "6000 Freedom Square Dr.",
         "city": "Independence",
         "state": "OH"",
         "zip": "44131",
         "county": "Cuyahoga",
         "propertyType": "Single Family"
      }
   },
   "product": {
      "name": "FNMA 1004 Single Family",
      "code": "A001" 
   },
   "embeddedFile": 
   [{
      "typeID": "1010",
      "name": "SalesContract.pdf",
      "description": "Sales Contract",
      "document": "Base64 encoded document"
   }],
   "parties": [{ … }]
}

Order Contacts

The Parties object contains data related to all parties involved in the transaction.

"parties": 
[
{
   "partyType": "Borrower",
   "firstName": "Connie",
   "middleName": "H",
   "lastName": "Borrower",
   "contactMethod": {
      "contactInfo": 
      [
      {
         "contactLabel": "Home",
         "ContactType": "Phone",
         "ContactValue": "(440) 222-3333"
      },
      {
         "contactLabel": "Home",
         "ContactType": "Email",
         "ContactValue": "connie@donotusetest.com"
      }
      ]
   }
},
{
   "partyType": "Appraisal Coordinator",
   "firstName": "Angie",
   "middleName": "T",
   "lastName": "Manage",
   "contactMethod": {
      "contactInfo": 
      [
      {
         "contactLabel": "Mobile",
         "ContactType": "Phone",
         "ContactValue": "(919) 933-7717"
      },
      {
         "contactLabel": "Home",
         "ContactType": "Email",
         "ContactValue": "angie@donotusetest.com"
      }
      ]
   }
},
{
   "partyType": "Property Contact",
   "firstName": "Peter",
   "middleName": "T",
   "lastName": "Proper",
   "contactMethod": {
      "contactInfo": 
      [
      {
         "contactLabel": "Home",
         "ContactType": "Phone",
         "ContactValue": "(919) 933-2517"
      },
      {
         "contactLabel": "Work",
         "ContactType": "Email",
         "ContactValue": "peter@donotusetest.com"
      }
      ]
   }
},
{
   "partyType": "Loan Officer",
   "firstName": "Debbie",
   "middleName": "",
   "lastName": "Officer",
   "contactMethod": {
      "contactInfo": 
      [
      {
         "contactLabel": "Work",
         "ContactType": "Phone",
         "ContactValue": "(984) 219-5641"
      },
      {
         "contactLabel": "Work",
         "ContactType": "Email",
         "ContactValue": "debbie@donotusetest.com"
      }
      ]
   }
},
{
   "partyType": "Loan Processor",
   "firstName": "Martin",
   "middleName": "J",
   "lastName": "Processor",
   "contactMethod": {
      "contactInfo": 
      [
      {
         "contactLabel": "Work",
         "ContactType": "Phone",
         "ContactValue": "(222) 333-5555"
      },
      {
         "contactLabel": "Work",
         "ContactType": "Email",
         "ContactValue": "martin@donotuse.test.com"
      }
      ]
   }
}
]

Response to Placing an Order

Upon placing an order, the integration will return the following response describing the state.

{        
   "orderNumber": "111977-1",
   "condition": "In Progress",        
   "isSuccess": true,
   "description": "Not present if the order was successfully placed.",        
   "datetime": "2022-04-20 13:56:09Z",
}

Adding Comments to an Order

Endpoint: POST /Orders/{TransactionUID}/Comments

Comments enable communication with all stakeholders throughout the order lifecycle. To add a comment to an order, submit a POST request to the specified URL with the following payload.

{
   "comment": "Hello, this is a comment."
   "actionRequired": true
}

Adding Documentation to an Order

Endpoint: POST /Orders/{TransactionUID}/Documents

Clients can also add documents at any point during the order lifecycle. To add documents to an order submit a POST request to the specified URL with the following payload.

{
   "embeddedFile": {
      "typeID": "2060",
      "name": "filename.docnewdocument.PDF",
      "description": "Appraisal Support Document",
      "document": "Base64 encoded document"
   }
}

This request will return standard HTTP responses, typically 200 (Ok).

Managing Contacts for an Order

Endpoint: PUT /Orders/{TransactionUID}/Contacts

Contact objects are established during the order post entry and managed through the Contacts endpoints following your initial order. To add a contact for an order, submit a POST request to the specified URL with the following payload defined below.

{
   "partyType": "Property Contact",
   "firstName": "Jane",
   "LastName": "Smith",
   "emailAddress": "JaneSmith@test.com",
   "phone": "555-555-5555"
}

This request will return standard HTTP responses, typically 200 (Ok).

On Hold

Endpoint: PUT /Orders/{TransactionUID}/Hold

To place an order on hold, submit a PUT request to the specified URL with the following object defined below.

{
   "reason": "Borrower payment not received"
}

This request will generate a standard HTTP response. For successful requests a 200 (Ok) will be generated and if the request is not successful an HTTP response describing the error will be returned.

Resume

Endpoint: PUT /Orders/{TransactionUID}/Resume

To remove a hold from an order and resume the workflow, submit a PUT request to the specified URL with the following object defined below.

{
   "reason": "Borrower payment received."
}

Please note that this request applies only to an order that is on hold. It has no effect on an order that has been cancelled.

Cancelling an Order

Endpoint: PUT /Orders/{TransactionUID}/Cancel

To cancel an order, submit a PUT request to the specified URL with the following object defined below.

{
   "reason": "Borrower has decided not to proceed with the loan."
}

Borrower Delivery

Endpoint: PUT /Orders/{TransactionUID}/DeliverToBorrower

To request report delivery to the borrower, submit a PUT request to the specified URL with the following object defined below.

{
   "borrowerEmail": "JohnHomeowner@test.com",
   "borrowerAddress1": "123 Main St",
   "borrowerAddress2": "Apt 2",
   "borrowerCity": "SomewhereVille",
   "borrowerState": "OH",
   "borrowerZip": "42131"
}

This request will generate a standard HTTP response. For successful requests a 200 (Ok) will be generated and if the request is not successful an HTTP response describing the error will be returned.

Inspection Schedule

Endpoint: PUT /Orders/{TransactionUID}/InspectionSchedule

To request appointment dates for the appraisal inspection, submit a PUT request to the specified URL with the following object defined below.

{
    "option1Date": "2022-08-15",
    "option1TimeSlot": "1",
    "option2Date": "2022-08-16",
    "option2TimeSlot": "1",
    "option3Date": "2022-08-17",
    "option2TimeSlot": "2",
    "comments": "I have a big friendly dog"
}

This request will generate a standard HTTP response. For successful requests a 200 (Ok) will be generated and if the request is not successful an HTTP response describing the error will be returned.

Notes

TimeSlots – there are 3 time slots available: 1 = 8 – Noon, 2 = noon – 5, 3 = 5-9. The requested options are delivered to the appraisal provider by AW. AW will reply back with the “Scheduled” notification which contains the specific data and time the provider will arrive.

Provider Assignment

Endpoint: GET /Orders/{transactionUID}/Assignment/{detailId}

This transaction is generated when a provider has been assigned to the order and accepted that assignment.

{
   "appraiserName": "Jane Appraiser",
   "companyName": "Appraisers INC.",
   "distance": "147.65",
   "appraiserLicenseNumber": "tst-12345"
   "isSuccess": true,
   "datetime": "2022-04-04 16:58:31Z"
}

Fee Changes

Endpoint: GET /Orders/{transactionUID}/FeeChanged/{detailId}

This event is generated if the provider requests a fee change for an order.

{
    "reason": "This property is complex and will require a higher fee to complete."
    "revisedVendorFee": "350.00",
    "isSuccess": true,
    "datetime": "2022-04-04 16:58:31Z"
}

Completed Report

Endpoint: GET /Orders/{transactionUID}/Completed

When the report is delivered and the order has been marked complete, AppraisalWorks will package up the client’s pre-defined delivery documents and submit them through the API with the below defined data payload. Additional data elements not present in the data payload below may also be accessible from the data file of the report that is being delivered.

The ‘detailId’ in the postback request is not used for this GET call into the Arrowbase API.

{
   "property": 
   {
      "assessorsParcelIdentifier": "1234"
      "lotSize": "",
      "livingArea": "",
      "stories": "2",
      "yearBuilt": "1992",
      "totalRooms": "8"
   },
   "valuationResults": 
   {
      "value": "100000.00",
      "valuationDate": "2021-11-03 11:01 AM EST",
      "appraiserName": "Jane Appraiser",
      "appraiserLicenseNumber": "tst-12345"
   },
   "embeddedFile": [
   {
      "typeID": "2010",
      "name": "FinalAppraisalDoc.xml",
      "description": "MISMO 2.6 GSE Appraisal Dataset with embedded PDF file",
      "document": "Base64 encoded document"
   },
   {
      "typeID": "1000",
      "name": "Invoice.PDF",
      "description": "Invoice for service",
      "document": "Base64 encoded document"
   }
   ]
}

Appointment Set

Appointment objects contain all information on the appointment that was set within the order. You can receive the appointment date and request a reschedule of the appointment date.

When the appointment is scheduled, you will receive the appointment date to your specified endpoint destination from your order request as a confirmation. The object sent in this notification is defined below.

{
   
   "appointmentDate": "11/1/2021 12:00PM EST"
}

Reschedule Appointment Request

Endpoint: PUT /Orders/{TransactionUID}/Reschedule

If you need to request that an appointment be rescheduled submit a PUT request to the specified URL..

{
   "orderID": "12345",
   "appointmentDate": "1/1/2021 12:00PM EST",
   "comment": "Property contact needs to reschedule."
}

Standard HTTP responses are generated by this request and will typically be 200 (Ok) for successful request.

Appendix - Document types

Client Documents

The folllowing documents may be added by the client at any time throughout the order process and will aid the provider in completion of the services.

Provider Documents

The following documents may be returned by the provider upon completion of the order request and subsequent deliveries.

Appendix - Contact types

Contact Roles

The following is a list of valid contact roles supported that may be used to define the partyType in the requests.

• Borrower
• Loan Officer
• Loan Processor
• Property Contact
• Appraisal Coordinator
• Attorney
• Builder
• Buyer
• Lender
• Other
• Owner
• Real Estate Agent – Buyer
• Real Estate Agent – Seller
• Seller

Contact Types

The following is a list of valid supported contact types that may be used to define the contactType in the requests and will determine the type of contact information being provided.

• Email
• Phone

Contact Labels

The following is a list of valid supported contact labels that may be used to define the contactLabel in the requests and will determine how the information that is supplied should be used.

• Home
• Work
• Mobile

Appendix - Event Code Dictonary

Each of the notification event codes are detailed below.

Appendix - Product Codes

Appendix - Loan Types

• Acquisition
• Construction
• Default
• Home Equity
• Land Contract
• Purchase
• Refinance
• Renewal
• REO
• Reverse
• Workout
• Unknown

Appendix - Property Types

• Commercial
• Condo
• Duplex
• Farm Property
• Manufactured Home
• Multi-Family
• Other
• PUD
• Single Family
• Town Home
• Vacant Land

Appendix - Note Types

• Accounting
• Appraisal
• Appraisal Correction Requested
• Appraisal QC Request
• Appraisal Report Due
• Appraisal- Appointment Date/time
• Borrower Report Delivery
• Follow Up
• On Hold