.png)
Integration Guide
Go to Swagger API Demo: https://test.bulkloads.com/api/public/v1/
To access this page, you'll need to enter this UN/PW in the basic auth popup box: tester / Hopper2014
Postman can also be used for testing.
Response Format: The response format from the apis will be JSON.
Swagger Tips: Swagger allows you to view all available endpoints, fields, field types, field descriptions and also allows you to 'play' but making test calls directly in swagger. There are a couple of things to note when using Swagger: 1. When you are viewing an endpoint there are 2 very useful views: Example Value and Model. The Example Value view gives you an example call with example data which makes it easy to copy and past to run your own test calls. The Model view gives you a better understanding of the fields by listing out the field type, example data and a description which is helpful when trying to understand how each field should be used. [IMAGE] 2. If you want to run your own test calls inside swagger you will first have to authenticate. To authenticate, click on the Authenticate button. Next, using the 'TMSOAuth2 (OAuth2, password)' method enter your BulkLoads username and password and select Request Body for the 'Client credentials location:' value. The rest of the values can remain blank. Finally, click Authorize. You should see a success message once authorized. You can now use swagger to make test calls.
Authenticating:
To successfully use the endpoints you must use your issued API KEY and your generated ACCESS_TOKEN with every call. This is how we know you are allowed to access the endpoints and which company account the API will affect.
Generating an Access Token:
To generate an Access Token you submit the user's BulkLoads.com username/password to the /login endpoint.
Curl example:
curl -X POST "https://test.bulkloads.com/rest/login" -H "accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password&username=yourusername&password=yourpassword"
If the login is successful, the server will return an `access_token`. You will use this access_token in every subsequent request to the API along with your API KEY. Pass the access token and API KEY in the authorization header like so:
authorization: Bearer {your_ACCESS_TOKEN_here} and your API KEY like so: X-api-key: {your_API_KEY_here}
For example, to get your company's posted loads the curl example would be:
curl -X 'GET' \ 'https://test.bulkloads.com/rest/loads/my_loads?skip=0&limit=100' \ -H 'accept: application/json' \ -H 'X-API-Key: {your API_KEY here}' \ -H 'authorization: Bearer {your ACCESS_TOKEN here}'
The access_token is valid for a period of 14 days and can be renewed by either calling the POST /login endpoint again or the POST /checkin which will return a fresh token.
All fields in the body are optional.
Example:
curl -X POST "https://test.bulkloads.com/rest/checkin" -H "accept: application/json" -H "authorization: Bearer {your ACCESS_TOKEN here}" -H 'X-API-Key: {your API_KEY here}' -H "Content-Type: application/json" -d "{ \"device\": \"ABC ACCOUNTING\"}"
Here's a brief overview of the endpoints:
GET /integration/newbos/authorized_companies
Returns a list of user_company_ids that NewBos is authorized to manage. These ID's correspond to our system ID's of our mutual customers, basically a list of companies who are going to be using the integration. This is how we'll know which company we should add the load for. You'll need to include the user_company_id in the /loads endpoint call URLs.
POST /integration/newbos/{user_company_id}/loads
The main endpoint you'll use to add loads. You'll want to be sure to include your unique Load ID in the `external_load_id` field. We use this in various ways. For example, we do a check against the external_load_id when a POST comes in and if no matches are found we assume it's a new load. If a match is found we assume it's an edit.
GET /cities
Query our cities database, if you'd like to. It's prefered that the origin and destination city/st match a record in our cities database since we use this in various features to get distances, radius, etc. If the city/st submitted isn't accurate, we can't do this.
GET /equipments
List if our Trailer Type IDs. For each load posted, we require a list of Trailer Types (equipment_ids) that would be allowed to haul the load. This is so Carriers can search for loads that would only apply to the type of trailer they run.
GET /products/categories
List of our Product Category IDs. For each load posted, you can optionally include a category/type of product the load is (rate_product_category_id). For example, Grain, Aggregates, etc. This helps Carriers when searching for loads.