National Estimator Cloud (NEC) API is a way to use Craftsman's cost data 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 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.

Environments

The NEC 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 cost data. The data obtained using the Sandbox endpoint should never be used in a live production application.

Sandbox API endpoint is https://nec-api-sandbox.craftsman-book.com

Production environment is the environment that your application should use in the live mode.

Production API endpoint is https://nec-api.craftsman-book.com

Authorization

Every API request must be properly authenticated and authorized. NEC 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 costbooks currently available in NEC.

GET https://nec-api.craftsman-book.com/Costbooks
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

NEC 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.

Data Structure Overview

Below is a diagram of the data structure used by NEC API.

Getting a list of costbooks

At the top level, the data is grouped by the costbooks. To get a list of the costbooks currently provided by NEC, use a GET query to the /Costbooks endpoint:

GET https://nec-api.craftsman-book.com/Costbooks
accept: application/json
API-Key: 4fe9edc9-e5fa-4d8f-bf5c-82085b93adbc

Currently, NEC only supports Construction and Insurance costbooks:

[ 
   { 
      "id": 2545,
      "name": "2023 Construction" 
   }, 
   { 
      "id": 2554, 
      "name": "2023 Renovation & Insurance Repair"
   }
]

Getting cost categories

Below the costbook level, the data is grouped by cost categories. The cost categories are organized as a hierarchical structure. Use the /CostCategories/ByCostbook endpoint to get all cost categories for a given costbook:

GET https://nec-api.craftsman-book.com/CostCategories/ByCostbook/2545
accept: application/json
API-Key: 4fe9edc9-e5fa-4d8f-bf5c-82085b93adbc

Below is a sample response from this endpoint:

[
   { 
      "id": 1, 
      "parentCategoryId": null,
      "name": "Adhesives" 
   }, 
   { 
      "id": 154, 
      "parentCategoryId": 1, 
      "name": "Panel adhesives" 
   },
   ...
]

Getting cost data

To get actual cost data for a given cost category, use the /CostData/ByCostCategory endpoint:

GET https://nec-api.craftsman-book.com/CostData/ByCostCategory/161
accept: application/json
API-Key: 4fe9edc9-e5fa-4d8f-bf5c-82085b93adbc

Sample response:

{ 
   "pageSize": 50, 
   "totalPages": 1, 
   "requestedPage": 0, 
   "result": 
      [ 
         { 
           "id": 38941310, 
           "title": "Cabinets rule of thumb", 
           "description": "Base cabinets, 34-1/2\" high, 24\" deep",
           "mletCosts": 
              { 
                 "unitOfMeasure": "LF", 
                 "craftCode": "BC", 
                 "hours": 0.521, 
                 "materialCost": 196, 
                 "laborCost": 21.4, 
                 "equipmentCost": 0, 
                 "totalCost": 217.4 
              }
        },
        ...
     ]
}

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.
Playground to test your own API requests to the actual API endpoints.