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.
☝️Before you start
Want to try a request without writing code? Use the API Reference and Playground for full method documentation and a place to test live requests.
Need an API key, or pricing for production access? Start with this form.
API overview
REST API. Standard GET requests over HTTP, JSON in and out.
Send these headers with every request:
Header | Value |
API-Key | Your API key. See Authorization below. |
accept |
|
This page covers the three main endpoints. The complete method list is in the API Reference.
Authorization
Every request needs an API key in the header:
API-Key: <your API key>
A missing or incorrect key returns 401 Unauthorized.
A complete request looks like this:
GET https://nec-api.craftsman-book.com/Costbooks
accept: application/json
API-Key: 4fe9edc9-e5fa-4d8f-bf5c-82085b93adbc # example only — replace with your own key
The key shown above is a placeholder and will not work.
Each environment needs its own key — a Sandbox key won't work in Production.
Environments
Sandbox is free and returns demo data. Use it to explore the API, test in the playground, or build your integration. Never use Sandbox data in a live application.
Production returns real cost data and is what your live application should use. It requires a paid data license — contact us to get set up.
These are base addresses for your code to call, not web pages to open:
Sandbox https://nec-api-sandbox.craftsman-book.com
Production https://nec-api.craftsman-book.com
Data structure
Data is organized in three levels: costbooks, then cost categories, then cost data.
Costbooks
The top level. Get the list with /Costbooks:
GET https://nec-api.craftsman-book.com/Costbooks
accept: application/json
API-Key: <your API key>
NEC currently offers two:
[
{
"id": 2545,
"name": "2023 Construction"
},
{
"id": 2554,
"name": "2023 Renovation & Insurance Repair"
}
]
Cost categories
Each costbook contains cost categories, nested in a hierarchy. parentCategoryId is null for top-level categories and otherwise points at the parent's id.
Get them with /CostCategories/ByCostbook/{costbookId}:
GET https://nec-api.craftsman-book.com/CostCategories/ByCostbook/2545
accept: application/json
API-Key: <your API key>
Response:
[
{
"id": 1,
"parentCategoryId": null,
"name": "Adhesives"
},
{
"id": 154,
"parentCategoryId": 1,
"name": "Panel adhesives"
},
...
]
Cost data
Get the costs for a category with /CostData/ByCostCategory/{categoryId}:
GET https://nec-api.craftsman-book.com/CostData/ByCostCategory/161
accept: application/json
API-Key: <your API key>
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
}
},
...
]
}For abbreviations used in the response, see Abbreviations and symbols used in cost data.
What next
Head to the API Reference and Playground for full documentation on every method and data type, plus a playground for testing your own requests.