Partner Integration

The partner integration is a little more complex to set up, but it’s more powerful. In order to use the Partner Integration, you will need to be initially configured by Loadsmart, just as if you were using the Carrier Integration, however, some data is dynamically generated.

The main difference between these two integrations, is that with a Carrier Integration, we will inform you once you are set up on our side, two pieces of information: issuer and account uuid.

With the partner integration, you still need both pieces, both you are required to make a separate set of calls to determine or get the account uuid - in order to be able to sign User-JWT calls.

The authentication and authorization of our API, when we discuss User-JWT API calls is determined by both of those claims signed in the token.

When you sign up a token with a usr:<account uuid>, we will verify if you are allowed to impersonate such carrier. This is controlled by a set of integration requests.

Initial Workflow

The initial workflow for the Partner Integration is quite similar with the Carrier Integration:

1. Send our team your public key

2. We will set you up on our sandbox environment and will return you a single piece of information: issuer. This will only allow you to do sys calls to our API.

3. In your application, configure this value. You will need this information to integrate with new carriers and determine subsequent account uuid needed to do User-JWT calls.

Scopes

There are scopes for each sys endpoint that you must have enabled.

For all partners going this route, the minimum set of scopes necessary are:

1. carrier_search

2. carrier_read

3. request_integration_write

4. request_integration_read

These scopes should be configured by the Loadsmart team to you. You don’t have to do anything on that regard.

Once your token is configured, you can move on to making calls to integrate with carriers and impersonating them in our platform.

The scopes for the integrated carriers will be determined by Loadsmart’s application at runtime, but usually they will contain the scopes necessary to fully operate the features for Carrier Management APIs, Truck Matching, Load Offers API and Shipment related APIs.

Impersonating a carrier

Your token, by itself, does not have a lot of scopes associated with it.

In order to do more in the platform, you need to impersonate a carrier.

The basic workflow for this is the following:

1. Search Carrier (in order to find his primary key on Loadsmart);

2. Request Integration with a Carrier;

3. Check Integration request to see if it was accepted by the carrier;

4. Do requests on behalf of this carrier

The workflow is simple, however there are exceptions scenarios of several endpoints, that we will try to cover as clear as possible.

There are different steps you need to take in order to be have a fully configured carrier in out platform, depending on it’s initial state.

The following starting states are possible for a carrier in Loadsmart:

1. NEW

2. PENDING

3. READY

For carriers that are NEW in Loadsmart, you will need to provide data for the first user and the documents associated with that carrier (W9, Insurance, Authority).

For carriers that are PENDING or READY, you will need to wait for the carrier owner acceptance.

Once the integration is accepted and the carrier still PENDING, it means that one or more documents are missing (check on Check Integration) or an approval is needed on Loadsmart side.

You can poll the Check Integration endpoint to see if the integration got accepted.

The basic steps you need to take are:

Step	Initial Carrier State = PENDING/READY	Initial Carrier State = NEW
1	Search Carrier (GET)	Search Carrier (GET)
2	Carrier status = PENDING/READY	Carrier Status = NEW
3	Request Integration (POST)	Request Integration with Owner (POST)
4	Poll Check Integration (GET)	Integration Auto Accepted
5	Proceed with Usr-JWT calls	Proceed with Usr-JWT calls

Carrier Compliance and “Load Offers” feature

While the process for onboarding a new carrier on our platform is simple, there are specific checks we make in order to make sure the carriers we are allowing to take in freight, are compliant with our customers.

Each customer has a threshold for insurance and safety checks, so, while you might see freight available, not all freight will be available for any carrier. The carrier must be compliant with what each of our customers specify.

Right now, there is no API to find out these constraints and they are handled internally and will be reflected in the acceptance endpoints if the carrier does not meet the shipper requirements.

However, if you aim to use the Truck Matching and/or Load Offers API in order to book loads for carriers, you need to send a set of documents using our API so our operations team can validate them and authorize this impersonated carrier to source loads.

The Document Upload endpoint allows you to send a PDF or a image for the type of document you are sending. There are three types that are required in order for the carrier to source loads.

1. W9

2. insurance

3. authority

Since, for now, this check is a semi-automated process, it can take some time from the upload to the validation of each piece of document.

You can poll the Check Integration endpoint to check the status for each document.

A carrier is fully “onboarded” and allowed to take freight when the response of this endpoint is the following:

{
    "id": "fe17b7e7-6453-4520-b99d-2d2b44972468",
    "account_id": "bc32c4d4-5732-7845-aa32-132cdab5467b",
    "carrier": {
        "id": "9f87d040-f843-42e7-887a-45bea55e76f3",
        "mc": "12345",
        "dot": "54321",
        "name": "John Doe Freights",
        "status": "ready",
        "eligible": true
    },
    "status": "ACCEPTED",
    "documents": [
        {
        "type": "w9",
        "status": "accepted"
        },
        {
        "type": "insurance",
        "status": "accepted"
        },
        {
        "type": "authority",
        "status": "accepted"
        }
    ]
}

Validating on Sandbox

In order to make sure that all steps are been correctly followed, there are a test-case to execute in sandbox environment. Here follows the sequence of actions to be executed:

1. Generate an Application-JWT token;

2. Search Carrier with MC# 9999 or DOT 1667640;

3. Request Integration for this Carrier;

4. Check Integration and verify the status field, it must be ACCEPTED;

Case the integration supports document exchange, it is recommended to test the documents upload;

5. Generate an User-JWT token, use the account_id value retrieved on step 3 (also on step 4) to build the token and impersonate the carrier;

6. Document Upload the W9, insurance and authority documents and then reach the document_url of each response in order to verify if the file was correctly uploaded.

The following diagram represents the flow of requesting integration to a carrier and be able to use Load Offers API.

Notes: each box on the diagram above represents a request, the following image describes which token signature must be used on each request.