National Appraisal Estimator (NAE) API is a way to use the NAE's powerful appraisal calculation engine in your own software application. This document explains the basic concepts behind the API and should help you get started with your integration.
In this article:
API overview
The API generally utilizes REST architecture and accepts input data and returns results in JSON.
API methods are implemented as standard GET and POST requests over HTTP protocol.
Typically, your application will need to send the following headers with each request:
Header name | Description |
API-Key | Authentication header so that our API knows who you are. More on this in the Authorization section of this document. |
accept | The acceptable content-type for server responses. Use application/json for your API calls. |
Content-Type | The MIME type of the request body. Include this header in your POST requests to NAE API. Use application/json as the value. |
Environments
The NAE API has two environments: Sandbox and Production.
Sandbox environment can be used for exploring API, making test calls using our playground, or testing your own integration. The Sandbox environment is free but returns demo valuation data. The calculation results obtain using the Sandbox endpoint should never be used in a live production application.
Sandbox API endpoint is https://nae-api-sandbox.craftsman-book.com/
Production environment is the environment that your application should use in the live mode.
Production API endpoint is https://nae-api.craftsman-book.com/
Authorization
Every API request must be properly authenticated and authorized. NAE API uses a simple API-key based authorization. The API key must be sent in the HTTP header of every request like this:
API-Key: <your API key>
The API will return HTTP error "401 Unauthorized" if the API key is missing from the request or incorrect.
Below is a sample properly authenticated request to get a list of California areas supported by NAE.
GET https://nae-api.craftsman-book.com/Cities?state=CA
accept: application/json
API-Key: 4fe9edc9-e5fa-4d8f-bf5c-82085b93adbc
Please be advised that each environment requires its own API key.
Getting your API key
NAE API is currently in a Release Candidate mode and API keys are not available for general public. Please contact us if you wish to explore the API and obtain your API key.
Typical workflow
A valuation must be placed into a certain geographic area so that NAE can apply proper area modification factors. Creating a valuation request is split into two separate operations:
Getting a list of geographic areas and selecting one of them for your valuation
Creating a valuation calculation request
Getting a list of geographic areas
Use the /Cities endpoint to get a list of supported areas. The endpoint has an optional state parameters that can be used to filter the areas by state.
Below is a sample request that retrieves all supported areas in New York state.
GET https://nae-api.craftsman-book.com/Cities?state=NY
accept: application/json
API-Key: 4fe9edc9-e5fa-4d8f-bf5c-82085b93adbc
An extra from the response is shown below. Your application needs to capture the id of the area for use in valuation calculations.
[
{
"id": 71,
"name": "100-102 New York City",
"state": "NY"
},
{
"id": 72,
"name": "103 Staten Island",
"state": "NY"
},
...
]
Calculating a valuation
Use the /Valuations endpoint to send a valuation calculation request. Below is a sample request for a single-family home. Only a portion of the request is displayed for the sake of brevity. Refer to the full API specification for the description of all fields and sample requests.
POST https://nae-api.craftsman-book.com/Valuations
Content-Type: application/json
API-Key: 4fe9edc9-e5fa-4d8f-bf5c-82085b93adbc
{
"homeType": "SingleFamilyHome",
"cityId": 71,
"singleFamilyHome": {
"corners": 4,
"livingArea": 1200,
"stories": 1,
"yearBuilt": 1984,
...
}
}
An extra of the response is shown below.
{
"directCosts": [
{
"title": "Excavation",
"equipment": 671,
"labor": 2328,
"total": 2999
},
{
"title": "Foundation, Piers, Flatwork",
"equipment": 1688,
"labor": 9571,
"materials": 6979,
"total": 18238
},
...
],
"indirectCosts": [
{
"title": "Contractor Markup",
"materials": 34881,
"total": 34881
},
{
"title": "Final Cleanup",
"labor": 1918,
"total": 1918
},
...
],
"totalAppraisedValue": 259502.45,
"costToReplace": 305533,
"documentId": 10
}
Downloading valuation as a PDF document
NAE API provides an endpoint to download a PDF for a previously calculated valuation. The endpoint uses the document Id that is returned by the /Valuations endpoint as a parameter. Below is a sample request to this endpoint.
GET https://nae-api.craftsman-book.com/Valuations/Pdf?documentId=10
accept: */*
API-Key: 4fe9edc9-e5fa-4d8f-bf5c-82085b93adbc
The API returns the PDF with the following headers:
content-disposition: attachment; filename=valuation.pdf; filename*=UTF-8''valuation.pdf
content-length: 55376
content-type: application/pdf
<File content>
What next: API Reference and Playground
Now that you've learned the basics, refer to the API Reference and Playground page. On that page you should find:
Detailed documentation on API methods and data types.
Sample requests for single-family and manufactured homes.
Playground to test your own API requests to the actual API endpoints.