Skip to main content

Introduction

The HaulPay API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

API Environments​

Staging​

A staging environment is available for customers to access while developing their client endpoint implementation.
Base API URL: https://api-staging.haulpay.io/v1/external_api/
Broker Dashboard: https://app.staging.comfreight.com

Production​

A staging environment is available for customers to access while developing their client endpoint implementation.
Base API URL: https://api.haulpay.io/v1/external_api/
Broker Dashboard: https://app.haulpay.io

Authentication​

Client should generate an API key using dashboard and share it with the integrated Transportation Management System.

HaulPay API is only accessible if the request has proper authorization. The API server expects Authorization header with a value of Bearer $BEARER_TOKEN.

For example if your access_token is 31ada4fdadec460c809a9e56ceb75269 then it should appear in an HTTP header as shown below.

Authorization: Bearer 31ada4fdadec460c809a9e56ceb75269

Guidelines for external API integration​

How we want you to integrate with our debtors and carriers endpoints​

  1. You should maintain a list of all debtors and carriers that our shared client is actively using.
  2. You should store the external ID for each of these parties.
  3. You should not collect, store, or query for debtor or carrier information from our system outside of debtors and carriers that are actively used by shared clients.
  4. We do not currently communicate changes to debtors and carriers to external systems. These updates, which are rare, should be entered in both systems by hand.
  5. To make sure your list of debtors is up to date with ours, you can query our debtor_relationships_list endpoint. You can query this once a day for each shared client. The main data point you want to query for is debtor status.
  6. Same for carriers, using carrier_relationships_list.
  7. When the shared client wants to connect to a new debtor, you can use our debtors_list endpoint with a search query. Please present the results to our shared client with all the details we provide, to make it easier for the client to connect to the right debtor. Once a debtor is chosen, store their details in your system, including the external id and the debtor status.
  8. Same for carriers, using carrier_list.

Optimal workflow for a shared client​

  • When adding a carrier or a debtor to a load/invoice, your system will have the client search the list of already active carriers (debtors). When they pick an existing, connected carrier, their external ID will be used.
  • When searching for a carrier, there is an option “I cannot find my carrier”, which allows them to add a new carrier.
  • In the new carrier flow, they are asked for some details of the carrier (name, mc, dot) which you use to query our carrier_list endpoint. Same for debtors, name only, debtor_list.
  • When the shared client picks a carrier that we have in our system, you create a connection using a POST to carrier_relationships. This allows you to set an external ID, which you store. Same for debtors, using POST to debtor_relationships.
  • If the carrier (debtor) does not exist in our system, the shared client needs to go into HaulPay and create it there. Then as above. Your system guides the client to our “create carrier” and “create debtor” screens.

Initial sync (per client)​

Case 1: The client used your system before and is new to HaulPay. Please send us a full list of debtors and carriers that are in active use by the new shared client using our standard templates, which we can provide upon request.

Case 2: The client has used HaulPay and is new to your system. You can use the client’s relationships endpoints (see above) to obtain all active debtors and carriers.

Planned expansions​

  • We are considering to expose an endpoint that allows external systems to create debtors and carriers
  • An option on the invoice create endpoint to specify the contract type and a new endpoint that enumerates client properties, including their allowed contract types.
  • HaulPay will be able to set the external ID in your system if you expose an endpoint for this, please inquire. This facilitates the workflow where the client creates the carrier or debtor in our system and sets an external ID on it in our system.
  • Our new client web application will allow deep links to an invoice
  • We will at some point expose the credit limit for each debtor to trusted parties