Carrier Management APIs
=======================

The Carrier Management APIs allow you to programatically
search, onboard and effectively enable a carrier to work
with Loadsmart.

The main goal behind this API is to provide to Loadsmart
the necessary information required for a carrier to move
loads within our network.

Using this API you are able to:

Features:

1. Manage Carriers
2. Manage Drivers
3. Upload Documents

Manage Carriers
***************

Using this set of endpoints, you are able to search an existing carrier
in our database, and if necessary onboard this carrier.

**NOTE:** For these endpoints to work you need an :code:`Application-JWT` token.

First, check the carrier information in our database using the 
`search a carrier endpoint`_:

Request::

    curl --request GET \
    --url 'https://api.sandbox.loadsmart.com/api/v2/carrier/search?mc=87654321' \
    --header 'Authorization: JWT <Application-JWT token>'

In this request's response you'll see the carrier details:

Response::
    
    {
        "data": 
            {
                "id": "6e8nc0ac-e830-476d-980b-74d9bedfc824",
                "dot": "12345678",
                "mc": "87654321",
                "status": "Pending",
                "eligible": true,
                "name": "CARRIER NAME"
            }
    }

Then, you can request an integration with this carrier using the 
`request carrier integration endpoint`_:

Request::

    curl --request POST \
    --url https://api.sandbox.loadsmart.com/api/v2/carrier/integration-request \
    --header 'Authorization: JWT <Application-JWT token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "carrier_id": "6e8nc0ac-e830-476d-980b-74d9bedfc824",
        "owner": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@email.com",
            "phone_number": "+14075156874",
            "phone_number_extension": "123"
        }
    }'

Response::

    {
        "data": {
            "id": "2c95f6c1-be65-44c2-872c-764b3d46ee37",
            "account_id": "dbba5c17-8b94-4147-b506-86d3e04eb56c", <-- Account ID to be used in Usr-JWT requests
            "status": "ACCEPTED",
            "carrier": {
                "id": "6e8nc0ac-e830-476d-980b-74d9bedfc824",
                "dot": "12345678",
                "mc": "87654321",
                "status": "Pending",
                "eligible": true,
                "name": "CARRIER NAME"
            },
            "documents": [
                {
                    "type": "w9",
                    "status": "accepted"
                },
                {
                    "type": "insurance",
                    "status": "missing"
                },
                {
                    "type": "authority",
                    "status": "missing"
                }
            ]
        }
    }

Notice the **data.status** value. If it's **ACCEPTED** 
you will be able to impersonate the carrier via API and
use other endpoints such as Book.

If you need to check this integration request data afterwards
you can do it by using the `get integration request endpoint`_:

Request::

    curl --request GET \
    --url https://api.sandbox.loadsmart.com/api/v2/carrier/integration-request/2c95f6c1-be65-44c2-872c-764b3d46ee37 \
    --header 'Authorization: JWT <Application-JWT token>'


Onboard a carrier
*****************

Loadsmart uses RMIS to monitor the carrier compliance status. If you are
onboarding a carrier that is not in our network, the carrier is requested 
to provide a set of information.

Please, forward the carrier user to `Loadsmart's RMIS page`_ in order to
complete the carrier onbaording process. After the carrier 
data submission, our operations team will review the carrier's data.
Considering that the carrier is compliant with prerequisites, the carrier status will be changed to **Ready**.

When the carrier status changes, your service will receive a webhook
event:

Webhook::
    
    {
        "type": "carrier:status:changed",
        "created_at": "2022-08-30T10:45:00.000Z",
        "details": {
            "id": "6e8nc0ac-e830-476d-980b-74d9bedfc824",
            "dot": "12345678",
            "mc": "87654321",
            "status": "Ready",
            "previous_status": "Pending",
            "eligible": true,
            "name": "CARRIER NAME"
        }
    }

Manage Drivers
**************

This set of endpoints allows you to control the drivers for each
carrier. For each moved load, you will be asked to assign a driver
(if you are able to do so) for that load.

In order for you to assign drivers to a load, you need to manage them.

These endpoints will allow you to create, edit and remove drivers
for each carrier.

For these endpoints to work, you need a :code:`Usr-JWT` token, because
you are impersonating a specific carrier.

.. _search a carrier endpoint: https://developer.loadsmart.com/api/index.html#tag/Carrier/paths/~1api~1v2~1carrier~1search/get
.. _request carrier integration endpoint: https://developer.loadsmart.com/api/index.html#tag/Carrier/paths/~1api~1v2~1carrier~1integration-request/post
.. _get integration request endpoint: https://developer.loadsmart.com/api/index.html#tag/Carrier/paths/~1api~1v2~1carrier~1integration-request~1%7Bid%7D/get
.. _Loadsmart's RMIS page: https://loadsmartcarriers.rmissecure.com/_s/reg/GeneralRequirementsV2.aspx