Bluebook Developer

Documentation

Last Updated: August 09, 2017

Introduction

The Bluebook API uses HTTP verbs and a RESTful endpoint structure. Basic Authentication is used as the API Authorization framework. Request and response payloads are formatted as JSON.

Environments

The Bluebook REST APIs are supported in two environments. Use the Sandbox environment for testing purposes, then move to the live environment for production processing. When testing, use your test credentials to make calls to the Sandbox URIs. When you're set to go live, use the live credentials to be used with the live URIs.

The following endpoints address our two environments:

  1. Sandbox (for testing) : https://testwebapi.bluebook.net
  2. Live (production) : https://webapi.bluebook.net

A complete REST operation is formed by combining an HTTP method (or "verb") with the full URI to the resource you're addressing. For example, here is the operation to create a new order:

POST https://testwebapi.bluebook.net/api/v1/orders

To create a complete request, combine the operation with the appropriate HTTP headers and any required JSON payload.

Authorization

When the user agent wants to send the server authentication credentials it may use the Authorization header.

The Authorization header is constructed as follows:

  1. Username and password are combined into a string "username:password".
  2. The resulting string literal is then encoded using Base64. Online tool here
  3. The authorization method and a space, i.e. "Basic " is then put before the encoded string.

For example, if the user agent uses 'Aladdin' as the username and 'open sesame' as the password then the header is formed as follows:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Bluebook needs to provide explicit access to your account. Therefore, you'll need to contact us before trying to access the API.


Swagger based documentation

Bluebook provides Swagger-based documentation.

Swagger is an emerging standard for describing REST-based APIs, and with this Swagger-compliant endpoint (above), you can make ready-to-go interface libraries for your code via swagger-codegen. For instance, it's easy to generate libraries for Node.js, Java, Ruby, ASP.NET MVC, jQuery, php and more! Microsoft provides a code generator called Autorest for .Net stack.

You can also try out the endpoint calls using basic authentication right on the Bluebook Swagger page. Be sure to enter your authorization credentials to use the "Try it out!" buttons.


Each API call response includes an array of HATEOAS (Hypermedia as the Engine of Application State) links. The beauty of HATEOAS is that it allows you to interact and construct an API flow solely through the hyperlinks we provide you. We provide HATEOAS links for each call and for transactions within a call, if available.

Element Description
href URL of the related HATEOAS link you can use for subsequent calls.
rel Link relation that describes how this link relates to the previous call.
method The HTTP method required for the related call.

HealthChecks

We have created a Ping service to help you verify your client credentials and the availability of the service.

Curl

curl -X GET --header 'Accept: application/json' --header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' 'https://testwebapi.bluebook.net/api/v1/healthchecks/ping'

Request Url

https://testwebapi.bluebook.net/api/v1/healthchecks/ping

Response Body

{
"timeStamp": "2018-03-15T21:43:04.7076205Z"
}

Response Code

200

Getting Started

Bluebook APIs are designed to help clients to integrate their systems with ours. The APIs follow a similar workflow as if the user was interacting with our web page. Therefore, the workflow will have the same initial steps and business rules operations as our application.

Developer Workflow

Please see our Swagger-based and API reference for detail information about models and information of the operations described below. The following is a general overview of the steps required to create estimates along with future operations. These samples are meant to be a general guide on how to interact with the APIs to achieve a specific workflow. The user needs to review the specific operation API documentation for an up to date model and operations.

Catalogs

Some operations require data referenced on other endpoints, for instance Orders require property type values. We have provided catalogs for clients to fetch that information so clients can build objects that depend on other operations. These catalogs are available as part of the list of API operations.

Tools

To provide a hands-on tutorial, Swagger contains sample implementation on CURL which is a widely use tool to execute REST operations. The samples provided below use CURL to execute the REST operations, however you can use any client or server library of your choice.

Create Repair Estimate

Orders are the main objects that contain information about a property, areas, repairs and report generation.

Here is the relationship among the operations:

  1. An order is the initial entry point to create an estimate. It requires basic information about a property such as address and type.
  2. An order contains characteristics such as number of bathrooms, bedrooms, year built, among others.
  3. Areas specify locations where a set of repairs are going to take place within the property. Every order contains a default Area which is the Entire House.
  4. Repairs which describe the specifics of the type of work that needs to be done in that particular location.
  5. Once the order is finished the client can generate a full report in two different formats: xml and pdf.

Step 1: Create Order

Preconditions

  1. Set OrderType=4 which references RepairEstimate, for other order types supported in the future execute the GET api/v1/ordertypescatalog
  2. Execute the GET api/v1/propertytypescatalog operation to retrieve a list of the available property types and select an Id.
  3. Execute the GET api/v1/usstatescatalog operation to retrieve a list of the available property types and select an Id.
POST api/v1/orders

Request

Provide an order object including basic authentication header. Please review the API Reference and Swagger Explorer for specifics on the models and their descriptions.

Curl

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' -d '{
  "orderType": 4,
  "propertyType": 2,
  "address": "26101 Magic Mountain Pkwy.",
  "address2": "",
  "city": "Valencia",
  "state": 6,
  "zip": "91355",
  "organizationCode": "",
  "batchId": "",
  "externalRefId": "YourCompanyEstimateId",
  "fieldSurveyDate": "2016-05-19T16:52:06.151Z",
  "remarks": "This is a repair estimate order for an API demo"
}' 'https://testwebapi.bluebook.net/api/v1/orders'

Request Url

https://testwebapi.bluebook.net/api/v1/orders

Response Body

{
  "id": 22618,
  "orderType": 4,
  "propertyType": 2,
  "address": "26101 Magic Mountain Pkwy.",
  "address2": "",
  "city": "Valencia",
  "state": 6,
  "zip": "91355",
  "organizationCode": "",
  "batchId": "",
  "externalRefId": "YourCompanyEstimateId",
  "fieldSurveyDate": "2016-05-19T16:52:06.151Z",
  "remarks": "This is a repair estimate order for an API demo",
  "orderDate": "2016-05-30T18:01:48.103",
  "orderGuid": "838002a9a66f43aa8a97970624dbf7b3",
  "links": [
    {
      "href": "https://testwebapi.bluebook.net:3443/api/v1/orders/22618",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://testwebapi.bluebook.net:3443/api/v1/orders/22618/characteristics",
      "rel": "update-characteristics",
      "method": "PUT"
    },
    {
      "href": "https://testwebapi.bluebook.net:3443/api/v1/orders/22618/areas",
      "rel": "get-areas",
      "method": "GET"
    },
    {
      "href": "https://testwebapi.bluebook.net:3443/api/v1/orders/22618/areas",
      "rel": "create-area",
      "method": "POST"
    }
  ]
}

Response Code

201

Step 2: Add Characteristics to an existing Order

Preconditions

An order should already exist. Verify that the order is available by executing the GET api/v1/orders/{orderId} 

PUT /api/v1/orders/{orderId}/characteristics

Request

Provide a characteristics object including basic authentication header. Please review the API Reference and Swagger Explorer for specifics on the models and their descriptions.

Curl

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' -d '{
  "siteLotSizeInSqFt": 4500,
  "roofPitch": "Moderate",
  "bedrooms": 5,
  "fullBaths": 4,
  "halfBaths": 2,
  "stories": "2",
  "yearBuilt": 1998,
  "totalLivingArea": 4000,
  "structureQuality": "Q4 - Builder",
  "basementSizeSF": 200,
  "attachedGaragesNumberOfCars": "4 cars",
  "builtInGaragesNumberOfCars": "3 cars",
  "condition": "C4 - Average"
}' 'https://testwebapi.bluebook.net/api/v1/orders/22618/characteristics'

Request Url

https://testwebapi.bluebook.net/api/v1/orders/22618/characteristics

Response Body

{
  "bedrooms": 5,
  "fullBaths": 4,
  "halfBaths": 2,
  "stories": "2",
  "yearBuilt": 1998,
  "totalLivingArea": 4000,
  "structureQuality": "Q4 - Builder",
  "basementSizeSF": 200,
  "attachedGaragesNumberOfCars": "4 cars",
  "builtInGaragesNumberOfCars": "3 cars",
  "condition": "C4 - Average",
  "siteLotSizeInSqFt": 4500,
  "roofPitch": "Moderate",
  "links": [
    {
      "href": "https://testwebapi.bluebook.net:3443/api/v1/orders/22618/characteristics",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Response Code

200

Step 3: Add Areas

Preconditions

  1. An order should already exist. Verify that the order is available by executing the GET api/v1/orders/{orderId}
  2. Get a list of the current order Areas. By default the Entire House area is created with the order GET api/v1/orders/{orderId}/areas
  3. Get a list of all the available Areas in the system to select the ones that you'd like to include GET api/v1/areatypescatalog. However, the Entire House area type cannot be added again. 
POST api/v1/orders/{orderId}/areas

Request

Provide an area object including basic authentication header. Add as many areas as you want by repeating the operation. Please review the API Reference and Swagger Explorer for specifics on the models and their descriptions.

Curl

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' -d '{
    "areaType": 7,
  "areaLabel": "Bathroom Visitors"
}' 'https://testwebapi.bluebook.net/api/v1/orders/22618/areas'

Request Url

https://testwebapi.bluebook.net/api/v1/orders/22618/areas

Response Body

{
  "areaId": 30333,
  "areaType": 7,
  "areaLabel": "Bathroom Visitors",
  "links": [
    {
      "href": "https://testwebapi.bluebook.net:3443/api/v1/orders/22618/areas/30333",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://testwebapi.bluebook.net:3443/api/v1/orders/22618/areas",
      "rel": "parent",
      "method": "GET"
    }
  ]
}

Response Code

201

Step 4: Add Repairs

Preconditions

  1. An order should already exist. Verify that the order is available by executing the GET api/v1/orders/{orderId}
  2. Get a list of the current order Areas. By default, the Entire House area is created with the order GET api/v1/orders/{orderId}/areas

Types of Repairs

There are two types of repairs: catalog based and custom repairs.

Catalog Based are created by selecting existing categories and subcategories. Custom repairs are created by the user and are identified by itemXREF=99999 and they required unit of measure (ItemUM), which can be modified at a later update. Catalog based repairs don't require unit of measure because the system already has this value predefined. Therefore, the value cannot be modified.

Catalog Based Repairs

  1. Retrieve the repair item that needs to be included in the area based on the category, subcategory and action type. To get those values the following operations need to be executed sequentially to filter the available repairs
    1. Category: Retrieves all the repair categories in the system GET /api/v1/ordertypes/{orderTypeId}/categories
    2. Category: Select a specific category GET /api/v1/ordertypes/{orderTypeId}/categories/{categoryId}
    3. SubCategories: Retrieves all the subcategories of a specific repair category GET /api/v1/categories/{categoryId}/subcategories
    4. SubCategories: Select a specific subcategory GET /api/v1/categories/{categoryId}/subcategories/{subCategoryId}
    5. Action Types: Retrieves the valid actions that can take place for these types of repairs filtered by their category and subcategory GET /api/v1/actiontypes/categories/{categoryId}/subcategories/{subCategoryId}/actiontypes
  2. Get a list of all the available repairs in the system to select the ones that you'd like to include GET /api/v1/repairscatalog/categories/{categoryId}/subcategories/{subCategoryId}/actiontypes/{actionTypeId}/repairItems
  3. You can also find repair items by filters. This method is faster but it requires to know the filter information in advanced. GET api/v1/repairscatalog/ordertype/{orderType}/search 
POST api/v1/orders/{orderId}/areas/{areaId}/repairs

Request

Provide a repair object including basic authentication header. Add as many repairs for every area as you want by repeating the operation. Please review the API Reference and Swagger Explorer for specifics on the models and their descriptions.

Curl for Catalog based Repairs

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' -d '{
    "itemXREF": 1012901,
    "description": "Install new - cabinets ready made - economy - upper",
    "vendorPPU":0,
    "quantity": 3,
    "comments": "The installation of cabinets needs to get done as soon as possible.",
    "code": "HZ,HL,CR,CL"
}' 'https://testwebapi.bluebook.net/api/v1/orders/22618/areas/30333/repairs'

Unit of measure (itemUM) is not required for catalog based repairs, you can send requests including this property as null or not send it at all. ex. "itemUM": null

{
    "itemXREF": 15019,
    "description": "Replace Towel Bar - Economy",
    "vendorPPU":0,
    "quantity": 2,
    "comments": "The towel bar is old.",
    "code": "HZ",
    "itemUM": null
}

Curl for Custom Repairs

Custom Repairs with an itemXREF:99999 should set the unit of measure from the following valid values: [SET, M/C, HRS, CY, SQ, EA, SFC, CF, SF, SY, SFW, VLF, LF, DAYS, LI, DAY, WIDTH, TOT]

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' -d '{
    "itemXREF": 99999,
    "description": "Wifi enabled wall mirror",
    "vendorPPU":150,
    "quantity": 2,
    "comments": "Installation requires the user to set the mirror with the wifi home password.",
    "code": "HZ",
    "itemUM":"EA"
}' 'https://testwebapi.bluebook.net/api/v1/orders/22618/areas/30333/repairs'

Request Url

https://testwebapi.bluebook.net/api/v1/orders/22618/areas/30333/repairs

Response Body

{
  "id": 55555,
  "itemXREF": 1012901,
  "code": "",
  "itemUM": "LF",
  "description": "Install new - cabinets ready made - economy - upper",
  "vendorPPU": 0,
  "bluebookPPU": 128.24,
  "totalCost": 384.72,
  "quantity": 3,
  "comments": "The installation of cabinets needs to get done as soon as possible.",
  "code": "HZ,HL,CR,CL",
  "links": [
    {
      "href": "https://testwebapi.bluebook.net:3443/api/v1/orders/22618/areas/30333/repairs/55555",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://testwebapi.bluebook.net:3443/api/v1/orders/22618/areas/30333/repairs",
      "rel": "parent",
      "method": "GET"
    }
  ]
}

Response Code

201

Step 5. Option 1: Generate PDF Report

Preconditions

An order should already exist. Verify that the order is available by executing the GET api/v1/orders/{orderId} 

GET api/v1/orders/{orderId}/reports/pdf

Request

Provide a repair object including basic authentication header. Add as many repairs for every area as you want by repeating the operation. Please review the API Reference and Swagger Explorer for specifics on the models and their descriptions.

Curl

curl -X GET --header 'Accept: application/octet-stream' --header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' 'https://testwebapi.bluebook.net/api/v1/orders/22618/reports/pdf'

Request Url

https://testwebapi.bluebook.net/api/v1/orders/22618/reports/pdf

Response Body

PDF Document

Response Code

200

Step 5. Option 2: Generate XML Report

Preconditions

An order should already exist. Verify that the order is available by executing the GET api/v1/orders/{orderId} 

GET api/v1/orders/{orderId}/reports/xml

Request

Provide a repair object including basic authentication header. Add as many repairs for every area as you want by repeating the operation. Please review the API Reference and Swagger Explorer for specifics on the models and their descriptions.

Curl

curl -X GET --header 'Accept: application/octet-stream' --header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' 'https://testwebapi.bluebook.net/api/v1/orders/22618/reports/xml'

Request Url

https://testwebapi.bluebook.net/api/v1/orders/22618/reports/xml

Response Body

XML Document

Response Code

200