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:

JSON
Form Key/Value pairs

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

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

Example Distributor Workflow

Find the Product you distribute
Create a Pricing Tier
Add the Price for that Product/PricingTier
Add details for the Product (Optional)

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

Make sure to replace YOURAPIKEY with your API key.

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",
    "lead_time": 0
  },
  {
    ...
  }
]

Status: 200 OK

This endpoint allows querying all products (active and discontinued) 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 (active and discontinued).

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",
    "lead_time": 0
  }
]

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",
        "lead_time": "0"
      }'

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" \
  -F "product[lead_time]=0"

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
lead_time	lead time in weeks a customer should expect

The image should be a file on your system. In the cURL example, give the file path as form data (Key/Value), rather than as JSON.

Update a product

curl "https://app.jetbuilt.com/api/products/<ID>" \
  -X PATCH \
  -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",
        "lead_time": "1"
      }'

curl "https://app.jetbuilt.com/api/products/<ID>" \
  -X PATCH \
  -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" \
  -F "product[lead_time]=1"

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.

Note: currency cannot be changed after product creation.

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",
    "currency_code": "USD",
    "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",
    "currency_code": "USD",
    "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",
        "currency_code": "USD"
      }'

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" \
  -F "pricing_tier[currency_code]=USD"

Response:

{
  "id":17487,
  "name":"Gold",
  "currency_code": "USD",
  "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)
currency_code	A 3 letter ISO code (e.g. USD, EUR, JPY) (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

Distributor Product Details

Update product distributor details

curl "https://app.jetbuilt.com/api/products/<PRODUCT_ID>/details" \
  -X PATCH \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1" \
  -H 'Content-Type: application/json' \
  -d '{
        "part_number": "ACME-123-D",
        "lead_time": "1"
      }'

curl "https://app.jetbuilt.com/api/products/<PRODUCT_ID>/details" \
  -X PATCH \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1" \
  -F "detail[part_number]=ACME-123-D" \
  -F "detail[lead_time]=1"

Response:

{
  "product_id": 12345,
  "part_number": "ACME-123-D",
  "lead_time": 1
}

Status: 201 Created / 200 OK

This endpoint allows you to create or update distributor details for a particular product.

HTTP Request

PATCH https://app.jetbuilt.com/api/products/<PRODUCT_ID>/details

URL Parameters

Parameter	Description
PRODUCT_ID	The ID of the product

Data Parameters

Parameter	Description
part_number	An optional vendor-specific part number for this product. Will be included on POs
lead_time	An integer number of weeks of lead time needed to ship this product

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

curl "https://app.jetbuilt.com/api/products/<PRODUCT_ID>/details" \
  -H "Authorization: Token token=YOURAPIKEY" \
  -H "Accept: application/vnd.jetbuilt.v1"

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.