LIS-FIF API v2 Documentation

Overview

The LIS-FIF API uses authenticated web requests to perform quote and certification transactions without a graphical user interface.

Note: This is version 2.0 of the API. For v1.0, use this documentation.

API Endpoint: https://quote.freightinsurancefast.com/api/v2/

Authentication

The account that's used for signing in the FIF website is a user account. Each User Account is part of a synthetic Company Account. Multiple users can be linked to the same company account.

In both the Quote and Certification view a dropdown list of users may be visible if multiple user accounts are associated with the company account.

A FIF API account is linked to a company-level account; it is accessed with an account id and a secret key.

The secret key is a shared secret between the FIF server and the requesting client. It is never directly transmitted. Instead, the key is used to compute a validation token that further authenticates each web request.

Each request contains an action. The authentication token is an SHA1 digest of the account id, the secret key, action and an hourly timestamp.

A timestamp uses the YYYY-MM-DD-HH format, where HH is the 24-hour representation of the hour. The time components are not zero-padded. For example, March 5, 2019 at 7:20pm is written as 2019-3-5-19. The logical timezone is Pacific Time with applicable daylight saving. i.e. PST and PDT.

Each part of the token calculation is separated by a hyphan ("-"). For example, an API account 123 with an API key of "abc" computes the token on March 5, 2019 at 7:20pm:

token = SHA1 (123-abc-quotes-2019-3-5-19) = f2be53c1003e4832a9f070c28f77a5b5b623a435

Request Format

Requests are sent in GET via HTTPS. The following fields must always be included:
accountid
action
token

Requests with additional payloads are sent in POST.

Response Format

A JSON encoded object will be returned in plain text.

echo

This is a diagnostic action for testing connectivity, authentication and character encoding.

Field	Description	Type	Required
phrase	phrase to be echo'ed back	String	Yes

Object Flow

The LIS-FIF API is a collection of data dictionary lookups and record creation methods. The output of some API calls flows into another. The following diagram shows the most critical path for preparing, creating, and purchasing a Quote. The quote purchase results in an insurance Certificate.

commodities

List of Commodity IDs.
In v1.0, the commodity list contains a list of terms and conditions that are attached to each commodity. In reality, the list of terms one must agree to is a combination of many factors. It is not suitable to display the conditions for individual commodities until more user input is collected.

Request Fields:

Field	Description	Type	Required
term	optional search filter	String	No

Response Fields in a list of objects:

Field	Description
commodityid	commodity identifier to pass to other API calls
name	display name of the commodity
keywords	informational, used to diagnose the request search filter
new_or_used	0-UI allows free New/Used selection; 1-lock UI to New; 2-lock UI to Used
requires_reefer	0-UI unlocks Reefer checkbox; 1-UI locks Reefer checkbox and sets to "checked"

Sample Response:

[
    {
        "commodityid": 4,
        "keywords": "",
        "name": "Air conditioning equipment parts",
        "new_or_used": 0,
        "requires_reefer": 0
    },
    {
        "commodityid": 112,
        "keywords": "",
        "name": "Fish or seafood FTL only",
        "new_or_used": 0,
        "requires_reefer": 1
    },
    {
        "commodityid": 389,
        "keywords": "furniture",
        "name": "Furniture-New: metal",
        "new_or_used": 1,
        "requires_reefer": 0
    },
    {
        "commodityid": 402,
        "keywords": "",
        "name": "Rock Crushers (USED)",
        "new_or_used": 2,
        "requires_reefer": 0
    }
]

countries

List of countries

Field	Description	Type	Required
ecozoneid	ECO Zone Filter	Numeric	No

equipments

List of equipments

transmodes

Get a list of transport mode IDs, given the source and destination countries.

Field	Description	Type	Required
from	Source Country ID	numeric	Yes
to	Destination Country ID	numeric	Yes

deductibles

List of candidate deductible amounts. Use these values to drive the UI, so that the user will not enter an unacceptable amount.

Field	Description	Type	Required
from	Source Country ID	numeric	Yes
to	Destination Country ID	numeric	Yes
transmodeid	Transport Mode; use transmodes to obtain valid options	numeric	Yes
commodityid	Commodity ID	numeric	Yes
loadtype	Load Type: Full, or Partial Truck Load	ftl or ltl - required if Transport is "Truck"	No
overweight	Whether the load is overweight 0-No; 1-Yes	numeric	No
oversized	Whether the load is oversized 0-No; 1-Yes	numeric	No
reefer	Whether refrigerated equipment will be used. 0-No; 1-Yes	numeric	No
instotal	Insured Total	numeric	No

quote_prepare

To prepare a quote, a JSON-encoded request object must be sent via POST. The accountid, action and token are still sent as GET parameters.

The quote_prepare function splits the original quote creation method into two stages. This is a major departure from the version 1.0 behavior.

By collecting all the information about a quote first, it is possible to determine the most suitable back-end carrier, or "provider".

Field	Description	Type	Required
from	Source Country ID	numeric	Yes
to	Destination Country ID	numeric	Yes
transmodeid	Transport Mode; use transmodes to obtain valid options	numeric	Yes
loadtype	Load Type: Full, or Partial Truck Load	ftl or ltl	No
instotal	Insured Total	numeric	Yes
insded	Deductibles	numeric	Yes
commodityid	Commodity ID; use commodities to obtain valid options	numeric	Yes
commoditynotes	Description of Commodity	string	Yes
condition	New or Used	string	No
overweight	Whether the load is overweight 0-No; 1-Yes	numeric	No
oversized	Whether the load is oversized 0-No; 1-Yes	numeric	No
reefer	Whether refrigerated equipment will be used. 0-No; 1-Yes	numeric	No
cif	Whether to add 10% CIF 0-No; 1-Yes	numeric	No

Sample Response:

{
    "providerid": 3,
    "netrate": "0.05500",
    "warrate": 0,
    "finalrate": "0.06500",
    "discounted": 12,
    "fee": 210.82,
    "lisrate": "0.055",
    "channelrate": "0.06500",
    "channelfee": "78",
    "conditions_to_agree": [
        "Condition 1",
        "Condition 2"
    ]
}

quote_create

To create a quote, a JSON-encoded request object must be sent via POST. The accountid, action and token are still sent as GET parameters.
The request parameters to quote_create should be consistent to the first-pass call to quote_prepare. The quote_prepare call returns a designated provider, and a list of terms/conditions to agree. These fields must be looped back to the quote_create call.

Field	Description	Type	Required
agreed_conditions	A list of all the agreed terms/conditions; returned by quote_prepare	array	Yes
providerid	Designated Provider ID; returned by quote_prepare	numeric	Yes
from	Source Country ID	numeric	Yes
to	Destination Country ID	numeric	Yes
transmodeid	Transport Mode; use transmodes to obtain valid options	numeric	Yes
loadtype	Load Type: Full, or Partial Truck Load	ftl or ltl	No
instotal	Insured Total	numeric	Yes
insded	Deductibles	numeric	Yes
commodityid	Commodity ID; use commodities to obtain valid options	numeric	Yes
commoditynotes	Description of Commodity	string	Yes
condition	New or Used	string	No
overweight	Whether the load is overweight 0-No; 1-Yes	numeric	No
oversized	Whether the load is oversized 0-No; 1-Yes	numeric	No
reefer	Whether refrigerated equipment will be used. 0-No; 1-Yes	numeric	No
cif	Whether to add 10% CIF 0-No; 1-Yes	numeric	No

Sample Request:

{
    "from": 199,
    "to": 199,
    "transmodeid": 1,
    "additionalnotes": "a long enough descriptive field",
    "instotal": 500000,
    "insded": 1000,
    "agreed_conditions": [
        "Condition text 1",
        "Condition text 2"
    ],
    "commodityid": 1,
    "loadtype": "ltl",
    "commoditynotes": "commodity description",
    "condition": "Used"
}

quote_purchase

To purchase a quote, a JSON-encoded request object must be sent via POST. The accountid, action and token are still sent as GET parameters.

Field	Description	Type	Required
quoteid		numeric	Yes
owner	Owner's Name	string	Yes
owneraddr	Owner's Street Address (required for QBE)	string	Yes
ownercity	Owner's City (required for QBE)	string	Yes
ownerprov	Owner's State or Province (required for QBE)	string	Yes
ownerzip	Owner's ZIP	string	Yes
ownercountry	Owner's Country (required for QBE)	string	Yes
consignee		string	No
reference		string	No
broker		string	No
carrier		string	Yes
docket		string	No
equipmentid	call equipments for options	numeric	Yes
pieces		numeric	Yes
weight	weight in lbs when unit unspecified	numeric or string	Yes
shipdate	Shipment Date	YYYY-MM-DD	Yes
fromcity	Originating City	string	Yes
fromstate	Originating State	string	Yes
tocity	Destination City	string	Yes
tostate	Destination State	string	Yes

Sample Request:

{
    "quoteid": 49622,
    "owner": "Bob",
    "consignee": "Joe",
    "reference": "aaa-123",
    "broker": "broker-one",
    "carrier": "Some other carrier",
    "docket": "ddd",
    "equipmentid": 5,
    "pieces": 1,
    "weight": "500 lb",
    "shipdate": "2020-6-12",
    "fromcity": "San Jose",
    "fromstate": "CA",
    "tocity": "Houston",
    "tostate": "TX"
}

certs

list all the purchased certificates.

cert_download

download the printable (PDF) version of a certificate, identified by the Certificate ID (certid) in the URL query parameter (GET).

cert_void

Field	Description	Type	Required
certid	Certificate ID	numeric	Yes
reason	Reason for voiding	string	No

Sample Request:

{
    "certid": 1234,
    "reason": "test reason"
}