NAV
JSON Key/Value

Introduction

Welcome to the Jetbuilt Vendor API! As a manufacturer or distributor, you can use this API to keep your products, pricing, images and descriptions current for Jetbuilt users - your dealers - to place in their projects.

REST

The Jetbuilt API is a REST-style API over HTTPS that uses JSON for serialization and HTTP Token authentication.

Base URLs

While developing your application, we'd recommend you utilize the sandbox environment at:

https://sandbox.jetbuilt.com/api

When you're ready, switch to production at:

https://app.jetbuilt.com/api

Passing data

Fields are passed with the request body, and can either be:

If sending JSON, be sure to set the Content-Type header to application/json to identify the request format, otherwise it will default to form key/value pairs.

Versioning

Example request header specifying the version

curl -H 'Accept: application/vnd.jetbuilt.v1'
curl -H 'Accept: application/vnd.jetbuilt.v1'

Since the API could change over time, we recommend specifying the version you're using with each request. This will help keep your integration working should a new version be released. Otherwise it will default to the latest version. (Currently there is only Version 1.)

Set the version by specifying application/vnd.jetbuilt.v1 in the Accept header.

Replace v1 with the desired version number. e.g v1, v2, v3, etc...

Rate Limits

Jetbuilt limits the number of API requests made within a period of time.

When the limit is reached, further requests return status code 429 (Rate Limit Exceeded)

The API limit is set at 50 requests within a 10 second window.

Pagination

Sample fetching the 2nd page of clients:

curl --include "https://app.jetbuilt.com/api/clients?page=2" \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1" \
  -H 'Content-Type: application/json'
curl --include "https://app.jetbuilt.com/api/clients?page=2" \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1"

Response header includes 'Link':

Link: <https://app.jetbuilt.com/api/clients?page=1>; rel="first",
  <https://app.jetbuilt.com/api/clients?page=1>; rel="prev",
  <https://app.jetbuilt.com/api/clients?page=4>; rel="last",
  <https://app.jetbuilt.com/api/clients?page=3>; rel="next"

The collection (i.e 'Get all') endpoints paginate their results, with 25 returned per page.

The Jetbuilt API follows the RFC5988 convention of using the Link header to provide URLs for the next page. Use these links to retrieve the next page of data.

Note: You can use curl --include to see your response headers. This is different than the response body.

The response also includes a X-Total-Count header, which is the total number of resources in the collection.

Example Manufacturer Workflow

  1. Find the Product you manufacture
  2. Create the Product if it does not exist in the Jetbuilt Database
  3. Create a Pricing Tier
  4. Add the Price for that Product/PricingTier

Example Distributor Workflow

  1. Find the Product you distribute
  2. Create a Pricing Tier
  3. Add the Price for that Product/PricingTier

Authentication

Sample request with Authorization:

curl "https://app.jetbuilt.com/api/products" \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1" \
  -H 'Content-Type: application/json'
curl "https://app.jetbuilt.com/api/products" \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1"

Make sure to replace YOURAPIKEY with your API key.

The Jetbuilt API uses API keys to allow access. Contact us for an API key and Sandbox access at help@jetbuilt.com.

You should include your API key in all API requests to the server in a header that looks like the following:

Authorization: Token token=YOURAPIKEY

Products

Search all products

curl "https://app.jetbuilt.com/api/products?query=acme-123" \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1" \
  -H 'Content-Type: application/json'
curl "https://app.jetbuilt.com/api/products?query=acme-123" \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1"

Response:

[
  {
    "manufacturer": "ACME",
    "id": 12345,
    "model": "ACME-123",
    "short_description": "Microphone",
    "long_description": "Handheld Microphone",
    "part_number": "ACME-123A",
    "discontinued": false,
    "url": null,
    "msrp": "123.0",
    "mapp": "45.0",
    "currency": "USD",
    "image_url": "https://static.jetbuilt.com/productimages/images/abc.jpg"
  },
  {
    ...
  }
]

Status: 200 OK

This endpoint allows querying all products by model.

HTTP Request

GET https://app.jetbuilt.com/api/products?query=sm57-lc

URL Parameters

Parameter Description
query The model name to search with.
page A specific page of results.

Get your products

curl "https://app.jetbuilt.com/api/products" \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1" \
  -H 'Content-Type: application/json'
curl "https://app.jetbuilt.com/api/products" \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1"

Response: Similar to Search all products

Status: 200 OK

This endpoint retrieves all of your products.

HTTP Request

GET https://app.jetbuilt.com/api/products

URL Parameters

Parameter Description
page A specific page of results.

Get a product

curl "https://app.jetbuilt.com/api/products/<ID>" \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1" \
  -H 'Content-Type: application/json'
curl "https://app.jetbuilt.com/api/products/<ID>" \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1"

Response:

[
  {
    "manufacturer": "ACME",
    "id": 12345,
    "model": "ACME-123",
    "short_description": "Microphone",
    "long_description": "Handheld Microphone",
    "part_number": "ACME-123A",
    "discontinued": false,
    "url": null,
    "msrp": "123.0",
    "mapp": "45.0",
    "currency": "USD",
    "image_url": "https://static.jetbuilt.com/productimages/images/abc.jpg"
  }
]

Status: 200 OK

This endpoint retrieves a product by ID.

HTTP Request

GET https://app.jetbuilt.com/api/products/<ID>

URL Parameters

Parameter Description
ID The ID of the product to retrieve

Create a product

If setting a product image, use cURL's (Key/Value) format

curl "https://app.jetbuilt.com/api/products" \
  -X POST \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1" \
  -H 'Content-Type: application/json' \
  -d '{
        "model": "JBTEST-1",
        "short_description": "JB Test product 1",
        "part_number": "ABC123",
        "msrp": "10.0",
        "mapp": "15.99",
        "currency": "EUR"
      }'
curl "https://app.jetbuilt.com/api/products" \
  -X POST \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1" \
  -F "product[model]=JBTEST-1" \
  -F "product[short_description]=JB Test product 1" \
  -F "product[part_number]=ABC123" \
  -F "product[msrp]=10.0" \
  -F "product[mapp]=15.99" \
  -F "product[currency]=EUR" \
  -F "product[image]=@/path/to/file/test.jpg"

Response: Similar to Get a product

Status: 201 Created

This endpoint creates a new product.

HTTP Request

POST https://app.jetbuilt.com/api/products

Data Parameters

Parameter Description
model The model name (required)
short_description A short product description
long_description A longer product description
part_number The part number
discontinued If the product is active or discontinued. Default is false.
url A product URL
msrp Suggested retail price
mapp Minimum advertised price
currency A 3 letter ISO code (e.g. USD, EUR, JPY). Default is USD.
image A product image

Update a product

curl "https://app.jetbuilt.com/api/products/<ID>" \
  -X PUT \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1" \
  -H 'Content-Type: application/json' \
  -d '{
        "model": "JBTEST-2",
        "short_description": "JB Test product 2",
        "msrp": "12.99"
      }'
curl "https://app.jetbuilt.com/api/products/<ID>" \
  -X PUT \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1" \
  -F "product[model]=JBTEST-2" \
  -F "product[short_description]=JB Test product 2" \
  -F "product[msrp]=12.99"

Response: Similar to Get a product

Status: 200 OK

This endpoint updates one of your products.

HTTP Request

PUT https://app.jetbuilt.com/api/products/<ID>

URL Parameters

Parameter Description
ID The ID of the product to update

Data Parameters

Same as Create a product.

Discontinue a product

curl "https://app.jetbuilt.com/api/products/<ID>" \
  -X DELETE \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1" \
  -H 'Content-Type: application/json'
curl "https://app.jetbuilt.com/api/products/<ID>" \
  -X DELETE \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1"

Status: 204 No Content

This endpoint discontinues a product by ID.

HTTP Request

DELETE https://app.jetbuilt.com/api/products/<ID>

URL Parameters

Parameter Description
ID The ID of the product to discontinue

Pricing Tiers

Get all your pricing tiers

curl "https://app.jetbuilt.com/api/pricing_tiers" \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1" \
  -H 'Content-Type: application/json'
curl "https://app.jetbuilt.com/api/pricing_tiers" \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1"

Response:

[
  {
    "id": 3495,
    "name": "Default",
    "created_at": "2016-08-17T17:14:45.430-07:00",
    "updated_at": "2016-08-17T17:14:45.430-07:00"
  },
  {
    "id": 3496,
    "name": "Tier 2",
    "created_at": "2016-08-17T17:14:45.430-07:00",
    "updated_at": "2016-08-17T17:14:45.430-07:00"
  }
]

Status: 200 OK

This endpoint retrieves all of your pricing tiers.

HTTP Request

GET https://app.jetbuilt.com/api/pricing_tiers

URL Parameters

Parameter Description
page A specific page of results.

Create a pricing tier

curl "https://app.jetbuilt.com/api/pricing_tiers" \
  -X POST \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1" \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "Gold"
      }'
curl "https://app.jetbuilt.com/api/pricing_tiers" \
  -X POST \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1" \
  -F "pricing_tier[name]=Gold"

Response:

{
  "id":17487,
  "name":"Gold",
  "created_at":"2018-10-02T18:36:59.949-07:00",
  "updated_at":"2018-10-02T18:36:59.949-07:00",
}

Status: 201 Created

This endpoint creates a new pricing tier.

HTTP Request

POST https://app.jetbuilt.com/api/pricing_tiers

Data Parameters

Parameter Description
name The name of the tier (required)

Prices

Get all product prices in your pricing tier

curl "https://app.jetbuilt.com/api/pricing_tiers/<TIER_ID>/prices" \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1" \
  -H 'Content-Type: application/json'
curl "https://app.jetbuilt.com/api/pricing_tiers/<TIER_ID>/prices" \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1"

Response:

[
  {
    "amount": "400.98",
    "created_at": "2016-08-15T13:00:35.492-07:00",
    "updated_at": "2016-08-15T13:27:38.004-07:00",
    "product": {
      "id": 3495
    }
  }
]

Status: 200 OK

This endpoint retrieves all of your product prices for a particular pricing tier.

HTTP Request

GET https://app.jetbuilt.com/api/pricing_tiers/<TIER_ID>/prices

URL Parameters

Parameter Description
TIER_ID The ID of the pricing tier
page A specific page of results.

Create/Update a product price for a pricing tier

curl "https://app.jetbuilt.com/api/pricing_tiers/<TIER_ID>/prices" \
  -X POST \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1" \
  -H 'Content-Type: application/json' \
  -d '{
        "product_id": "1234",
        "amount": "500.5"
      }'
curl "https://app.jetbuilt.com/api/pricing_tiers/<TIER_ID>/prices" \
  -X POST \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1" \
  -F "price[product_id]=1234" \
  -F "price[amount]=500.5"

Response:

{
  "amount": "500.50",
  "created_at": "2016-08-15T13:00:35.492-07:00",
  "updated_at": "2016-08-15T13:27:38.004-07:00",
  "product": {
    "id": 3495
  }
}

Status: 201 Created / 200 OK

This endpoint allows you to create or update a price for a product within a pricing tier.

If a price for the product, on the price tier, doesn't yet exist, then it will be created. Otherwise the existing price is updated.

HTTP Request

POST https://app.jetbuilt.com/api/pricing_tiers/<TIER_ID>/prices

URL Parameters

Parameter Description
TIER_ID The ID of the pricing tier

Data Parameters

Parameter Description
product_id The id of the product to set the price on
amount A decimal representing the price in the currency of the product

Delete a product price from a price tier

curl "https://app.jetbuilt.com/api/pricing_tiers/<TIER_ID>/prices/<ID>" \
  -X DELETE \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1" \
  -H 'Content-Type: application/json'
curl "https://app.jetbuilt.com/api/pricing_tiers/<TIER_ID>/prices/<ID>" \
  -X DELETE \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1"

Status: 204 No Content

This endpoint allows you to delete a price from a pricing tier.

HTTP Request

DELETE https://app.jetbuilt.com/api/pricing_tiers/<TIER_ID>/prices/<ID>

URL Parameters

Parameter Description
TIER_ID The ID of the pricing tier
ID The ID of the product price to delete

Errors

The Jetbuilt API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- You don't have access to the resource.
404 Not Found -- The specified item could not be found.
406 Not Acceptable -- You requested an unsupported format.
422 Unprocessable Entity -- Unable to save because some required data was missing.
429 Too Many Requests -- You're making too many requests. Please slow down.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Rate Limiting

You can perform up to 50 requests per 10 second period from the same IP address when accessing the API. If you exceed this limit, you'll get a 429 Too Many Requests response for subsequent requests.