Falvey Insurance

Add incidental cargo insurance to Loads with the Falvey integration. This integration provides the ability to complete the following tasks.

• Obtain pricing for cargo insurance

• Apply insurance premiums to quotes

• Authorize insurance

• Void insurance for Loads

The Falvey insurance API is accessible by internal users in the TMS on the Insurance Lightning Web Component (LWC) and also to Customer Portal users when creating Loads. Falvey provides the option to purchase additional cargo insurance for transporting Loads. The Insurance LWC is below the Customer and Carrier Quote sections of the Insurance LWC. See the Insurance article linked above for instructions to show or hide the LWC.

Setup

Enter Credentials

Enable the Falvey integration by completing the following steps.

1. Navigate to TMS Admin.

2. Select Credentials.

3. Choose the Global Services tab.

4. Find Falvey in the list and open the record.

5. Check the Enabled box and

6. Enter the User ID, Password 1, and Password 2 into the text fields.

7. Click the Save button when finished.

From TMS Admin → Configuration, confirm that the Use Platform Events For Insurance box is Checked.

Remote Site Settings

If upgrading from a previous release of the TMS, check that the Remote Site Settings for the Falvey integration URL are current.

1. Click the Setup gear icon in the top Right corner.

2. From the drop-down, click Setup.

3. In the Quick Find Toolbar type Remote Site Settings and click the link.

4. From the list of remote sites find Falvey and click the Edit link.

5.  Update the Remote Site URL to match the Service URL below: 

Service URL: https://shipassured.falveyshippers.com/

Test Service URL: https://sandbox.falveycargo.com/(Falvey_Test remote site)

API Insurance

To generate an insurance quote or authorize a policy from Falvey, the Cargo Value field must be set on the Load. It is recommended that the Cargo Value field be set as required when using the Falvey integration. Add the Cargo Value field to the Load TMS1 field set to include the field when creating Loads. The Save & Rate feature requires the Cargo Value field to retrieve an insurance rate from Falvey.

If a Cargo Value is not present on the Load, requesting a premium generates an error.

Falvey only accepts Load currencies in USD or CAD. Attempting to request insurance for other currencies generates an error. 

Falvey calculates insurance premium and fee exchange rates. Contact Falvey for additional exchange rate information. In multi-currency organizations, the Cargo Value currency field is controlled by the Default Load Currency under TMS Admin, Configuration in Multi-Currency Settings.

After creating a Load, the Insurance component allows for adding supplementary cargo insurance to a Load. Six buttons provide additional actions for adding cargo insurance to a Load.

The Insurance LWC links to "View Excluded Commodities," a modal listing any restricted commodities or countries. 

Warning:

It is crucial that the Cargo Insurance Excluded Commodities and Cargo Insurance Authorization fields are configured properly so users are aware of the restrictions.

The TMS does not enforce these item or country exclusions. Contact Falvey for a list of commodities not covered by their cargo insurance.

Navigate to TMS Admin, Configuration to the Customer Portal Configuration section. Click the pencil on the right to open the Rich Text Editor for the Cargo Insurance Excluded Commodities field. 

Information entered in the Cargo Insurance Excluded Commodities field displays on the Insurance LWC and the Customer Portal.

Sample Excluded Commodities:

Get Premium

1. Calls the Falvey API to request an insurance quote for the selected Load.

2. Returns insurance quote information and display it on the Insurance LWC.

3. Sets the Insurance Policy Status field to Pending.

4. Sets the Insurance Policy Status as of field to the current date/time.

The Load Cargo Value field must have a value in order to request an insurance quote from Falvey.

Falvey supports cargo insurance policies:

• Up to $500,000 USD for LTL Loads.

• Up to $1,000,000 USD for FTL Loads.

• Attempting to get a premium or authorize cargo insurance greater than these values generates an error.

• Contact Falvey for insuring Loads with cargo values greater than these limits.

If the Cargo Value field is greater than these policy limits, no insurance policy is returned from Falvey. The Load is NOT insured.

Get Price Operation

Two values are sent to Falvey in the Get Price Operation call. The value of the cargo and a description of that cargo. When received, Falvey calculates the Insurance Premium amount. A search for any excluded item words is also completed. The insurance premium amount is returned along with any excluded items in a list.

The customer Account SFID is sent in the Get Price operation to return customer-specific pricing. The first time a customer is sent to Falvey to create the customer in the Falvey system, the standard pricing is returned. After the first Load, Falvey returns the customer-specific pricing negotiated with the customer.

Sample Get Price Operation XML Request Payload

<FalveyFreight>
 <Authorization>
      <AuthorizationUserName>[UserName]</AuthorizationUserName>
      <AuthorizationPassword>[Password]</AuthorizationPassword>
      <AuthorizationKey>[Key]</AuthorizationKey>
      <AuthorizationCompany>[CompanyName]</AuthorizationCompany>
  </Authorization>
 <ProcessInformation>
      <Process>BSU</Process>
  </ProcessInformation>
 <ShipmentInformation>
      <SI_ShipmentTypeID>1002</SI_ShipmentTypeID>
      <SI_InsuredAmount>20000.00</SI_InsuredAmount>
      <SI_Currency>USD</SI_Currency>
      <ShippingMerchandiseDescription>fishing pole</ShippingMerchandiseDescription>
      <CompanyUUID>123456789101112</CompanyUUID>
  </ShipmentInformation>
</FalveyFreight>

Sample Get Price Operation XML Response Payload

<FalveyFreight>
  <Response>
       <Result>Successful</Result>
       <ResultMessage>None</ResultMessage>
       <InsurancePremium>1,000.00</InsurancePremium>
       <ProviderFee>0.00</ProviderFee>
       <ServiceFee>0.00</ServiceFee>
       <ExcludedItemMatch>fish</ExcludedItemMatch>
       <ExcludedItemIDMatch>195</ExcludedItemIDMatch>
       <VerifyInputData>
            <SI_ShipmentTypeID>1002</SI_ShipmentTypeID>
            <SI_InsuredAmount>20000.00</SI_InsuredAmount>
            <SI_Currency>USD</SI_Currency>
            <ShippingMerchandiseDescription>fishing pole</ShippingMerchandiseDescription>
       </VerifyInputData>
  </Response>
</FalveyFreight>

TMS Field Updates

Apply

The Apply button provides the option to Add Premium to customer quote or Deduct premium from carrier quote.

• Select Add Premium to customer quote to add an accessorial to the customer quote.

  • The Total Insurance Premium amount is added to the customer quote.

  • The Insurance Policy Status field changes to Offered.

• Select Deduct premium from carrier quote to add an accessorial to the carrier quote.

  • The Total Insurance Premium amount is subtracted from the Carrier Quote.

  • When multiple Loads are available in the Insurance LWC (for example, a combined Carrier Load in a Freight Plan) only Deduct premium from carrier quote is available. There is no Customer Quote with the combined Carrier Load.

Authorize

After receiving the premium quote, clicking the Authorize button calls the Falvey API to complete the following actions.

1. Accept the insurance quote.

2. Apply the insurance to the Load.

3. Set the Insurance Policy Status field to Authorized.

4. Set the Insurance Policy Status as of field to the date/time of authorization.

5. Return the Insurance Certificate Number from Falvey and displays on the Insurance LWC.

6. Return the Insurance Certificate PDF Link from Falvey and stored on the Load record.

   1. On a default lightning record page layout, the link is found on the Insurance/Claims tab.

A banner displays a success message or any errors.

The Get Premium action does not need to be separate from or occur before the Authorize action. Click Authorize to both Get Premium and Authorize in one action.

Warning:

If the Cargo Value on the Load changes, perform the following actions.

• For Loads where the Get Price call has returned a premium amount: Press the Get Premium button to receive another quote from Falvey.

• For Loads where the Authorize call has returned an insurance certificate: Press the Void button to remove the current policy. Press the Get Premium button to receive a new quote from Falvey.

Commit Insurance Operation

The following information is sent during the Commit Insurance Operation request.

1. Company and Contact information.

2. Shipment information including origin and destination.

3. Carrier ID and Carrier Name.

4. Insured Amount.

Sample Commit Insurance Operation XML Request Payload

<FalveyFreight>
  <Authorization>
       <AuthorizationUserName>[UserName]</AuthorizationUserName>
       <AuthorizationPassword>[Password]</AuthorizationPassword>
       <AuthorizationKey>[Key]</AuthorizationKey>
       <AuthorizationCompany>[CompanyName]</AuthorizationCompany>
  </Authorization>
  <ProcessInformation>
       <Process>BSU</Process>
  </ProcessInformation>
  <CompanyInformation>
       <CompanyUUID>123456789101112</CompanyUUID>
       <CompanyName>Testing Company 001</CompanyName>
       <CompanyStreet1>789 Business Lane</CompanyStreet1>
       <CompanyStreet2>Suite 202</CompanyStreet2>
       <CompanyCity>Wakefield</CompanyCity>
       <CompanyState>Rhode Island</CompanyState>
       <CompanyZip>02879</CompanyZip>
       <CompanyCountry>United States</CompanyCountry>
       <CompanyEmail>email@companyName.com</CompanyEmail>
       <CompanyExistingFalveyID>9876</CompanyExistingFalveyID>
  </CompanyInformation>
  <CompanyContactInformation>
       <CompanyContactUUID>002</CompanyContactUUID>
       <CompanyContactFirstName>Tester_FirstName</CompanyContactFirstName>
       <CompanyContactLastName>Tester_LastName</CompanyContactLastName>
       <CompanyContactStreet1>789 Business Lane</CompanyContactStreet1>
       <CompanyContactStreet2>Suite 202</CompanyContactStreet2>
       <CompanyContactCity>Wakefield</CompanyContactCity>
       <CompanyContactState>Rhode Island</CompanyContactState>
       <CompanyContactZip>02879</CompanyContactZip>
       <CompanyContactCountry>United States</CompanyContactCountry>
       <CompanyContactEmail>tester_email@companyName.com</CompanyContactEmail>
  </CompanyContactInformation>
  <ShippingInformation>
       <ShippingUUID>003</ShippingUUID>
       <ShippingTrackingNumber>Testing_003</ShippingTrackingNumber>
       <ShippingTypeID>1001</ShippingTypeID>
       <ShippingDate>04/17/2008</ShippingDate>
       <ShippingMarksAndNumbers>Testing</ShippingMarksAndNumbers>
       <ShippingSumInsured>50000</ShippingSumInsured>
       <ShippingMerchandiseDescription>Testing</ShippingMerchandiseDescription>
       <ShippingCurrency>CAD</ShippingCurrency>
       <ShippingCommodityTypeID>9016</ShippingCommodityTypeID>
       <ExclusionConfirmation>1/4/2016</ExclusionConfirmation>
       <ExcludedItemID>263,268,267</ExcludedItemID>
       <ShippingOrigin>
            <OriginStreet1>123 Any Street</OriginStreet1>
            <OriginStreet2>Suite 101</OriginStreet2>
            <OriginCity>Providence</OriginCity>
            <OriginState>Rhode Island</OriginState>
            <OriginZip>02913</OriginZip>
            <OriginCountry>United States</OriginCountry>
       </ShippingOrigin>
       <ShippingDestination>
            <DestinationStreet1>456 Anywhere Road</DestinationStreet1>
            <DestinationStreet2></DestinationStreet2>
            <DestinationCity>Boston</DestinationCity>
            <DestinationState>Massachusetts</DestinationState>
            <DestinationZip>02101</DestinationZip>
            <DestinationCountry>United States</DestinationCountry>
       </ShippingDestination>
  </ShippingInformation>
  <CarrierInformation>
       <CarrierUUID>Testing_004</CarrierUUID>
       <CarrierName>Testing_004</CarrierName>
  </CarrierInformation>
</FalveyFreight>

Sample Commit Insurance Operation XML Response Payload

<FalveyFreight>
  <Response>
       <Result>Successful</Result>
       <ResultMessage> </ResultMessage>
       <BOL>Testing_003</BOL>
       <FalveyShipmentID>1014</FalveyShipmentID>
       <ShipmentDate>04/17/2008</ShipmentDate>
       <ShippingSumInsured>50000</ShippingSumInsured>
       <ShippingSumInsuredWords>Fifty Thousand Dollars and Zero Cents</ShippingSumInsuredWords>
       <ShippingCurrency>USD</ShippingCurrency>
       <Premium>2,020.50</Premium>
       <ProviderFee>0.00</ProviderFee>
       <ServiceFee>0.00</ServiceFee>
       <CertificateNumber>…</CertificateNumber>
       <PolicyNumber>123456</PolicyNumber>
       <CertificatePDFLink>(URL to download certificate)</CertificatePDFLink>
       <CertificatePDFQRCode>(base64 QR Code to download certificate)</CertificatePDFQRCode>
       <WaybillAdditional>123456</WaybillAdditional>
       <Rate>5.00</Rate>
       <InvoiceNum>111000101</InvoiceNum>
  </Response>
</FalveyFreight> 

TMS Field Updates

Void

The Void button calls the Falvey API to void the authorized policy commitment. A banner displays success or any errors.

When the policy is successfully voided the following occurs.

1. Insurance Policy Status changes to Voided.

2. Insurance Certificate Number is removed.

3. Insurance Service Fee and Insurance Provider Fee fields are set to 0.

4. Any Customer Quote application or Carrier Quote deduction for the policy is removed.

If a Load is cancelled and the Insurance Policy Status is set to Authorized, the Void call is made automatically. Use the Refresh button on the Insurance LWC to update field information displayed.

When a Load has a Load Status of In Transit, Delivered, or Completed, the cargo insurance cannot be voided.

Void Insurance Operation

The shipment information is sent to Falvey in the Void Insurance Operation call. A response is returned with a confirmation of the shipment information.

Warning:

Falvey prevents voiding any authorized insurance policies of the previous month on the 1st day of the new month. To void an authorized policy at the beginning of the month, contact Falvey support. The following error banner displays:

Sample Void Insurance Operation XML Request Payload

<FalveyFreight>
  <Authorization>
       <AuthorizationUserName>[UserName]</AuthorizationUserName>
       <AuthorizationPassword>[Password]</AuthorizationPassword>
       <AuthorizationKey>[Key]</AuthorizationKey>
       <AuthorizationCompany>[CompanyName]</AuthorizationCompany>
  </Authorization>
  <ProcessInformation>
       <Process>BSU</Process>
  </ProcessInformation>
  <ShipmentInformation>
       <SI_FalveyShipmentID>14168</SI_FalveyShipmentID>
       <SI_BOL>Testing_003</SI_BOL>
       <SI_ShipmentUUID>201720201701</SI_ShipmentUUID>
       <SI_CertificateNumber>5C62C474-EEED-4520-A44F-6D5D51901747</SI_CertificateNumber>
       <CompanyUUID>123456789101112</CompanyUUID>
  </ShipmentInformation>
</FalveyFreight> 

Sample Void Insurance Operation XML Response Payload

<FalveyFreight>
  <Response>
       <Result>Successful</Result>
       <ResultMessage>None</ResultMessage>
  </Response>
  <VerifyInputData>
       <SI_FalveyShipmentID>14168</SI_FalveyShipmentID>
       <SI_BOL>Testing_003</SI_BOL>
       <SI_ShipmentUUID>201720201701</SI_ShipmentUUID>
       <SI_CertificateNumber>5C62C474-EEED-4520-A44F-6D5D51901747</SI_CertificateNumber>
  </VerifyInputData>
</FalveyFreight>

TMS Field Updates

Errors generated from a missing Cargo Value field or an invalid currency are sent to the Customer Sales Rep. on the Load by email. If there is no Customer Sales Rep. associated with the Load, the user that edited the customer quote is sent the email. If no internal user edited the customer quote, the owner of the Load is sent the email.

Correct any errors and manually request or authorize insurance on the Insurance LWC. Adding cargo insurance to Loads may be automated. See the section regarding automation for more information. Errors that occur during the automation process (including invalid credentials) are also sent via email.

Emails are sent via the Queued Transactions job.

API Insurance in the Customer/Community Portal

When the Falvey API Insurance integration is enabled, Customer Portal users can request and authorize additional cargo insurance on the Quote Wizard LWC.

Portal Text Configuration

There are four settings under TMS Admin → Configuration that each provide additional text to Customer Portal users.

1. Cargo Insurance Overview: Text displayed when the "Learn More" link on the Quote Wizard LWC Load entry page is clicked.

2. View excluded Commodities: Text displayed when the "View Excluded Commodities" link on the Quote Wizard LWC Load entry page and on the Quote Wizard LWC tender page.

3. Cargo Insurance Opt Out: Text displayed when Show Cargo Insurance Options is not Checked on the Quote Wizard LWC Load entry page of the Customer Portal.

4. Cargo Insurance Authorization: Text displayed on the Quote Wizard LWC tender page of the Customer Portal.

Restricted Cargo

Some insurance APIs (including Falvey) have restricted cargo that is not covered. This is NOT enforced by the TMS. It is crucial that the Cargo Insurance Excluded Commodities and Cargo Insurance Authorization fields are configured properly so users are aware of any restrictions.

Configure the following Customer Transportation Profile record settings to control insurance in the Customer Portal.

• Hide: The cargo insurance option section does not appear in the portal.

• Opt In: Show Cargo Insurance Options is Checked by default.

• Opt Out: Show Cargo Insurance Options is not Checked, but available in the portal.

By default, the cargo insurance displays below the Load Accessorials section of the Quote Wizard LWC. The Transportation Profile record of each customer contains settings for more control of Portal users purchasing cargo insurance.

When a Portal user chooses the insurance, an additional panel is displayed on the Quote Wizard LWC Tender page with a check box that must be Checked before tendering the Load.

When a user creates a Load and Checks the Show Cargo Insurance Options the following occurs.

1. The Cargo Value field is required before getting quotes or saving the Load.

2. The Cargo Insurance Offered field on the Load is Checked.

3. When receiving quotes, the price of the insurance is listed on the quote.

When insurance is authorized and a Load is successfully tendered, the following occurs.

• The Cargo Insurance Authorized field on the Load is Checked.

• An accessorial for the price of the insurance is added to the customer quote. The accessorial is the Cargo Insurance Accessorial field under TMS Admin → Configuration.

• An insurance certificate link is generated and returned from Falvey and added to the Load.

If the insurance authorization fails, an email with the error is sent to the designated email and the Cargo Insurance Authorized field remains Checked. 

The insurance authorization can still proceed even if tendering to the Carrier fails.

When the Load is tendered, an accessorial for the price of the insurance is added to the customer quote. This accessorial is determined by the Cargo Insurance Accessorial field in TMS Admin.

API Field Mapping Table

The table below contains the request and response fields that are included in the Falvey API integration.

*Fields with an asterisk are required.

Sample Insurance Certificate

Insurance coverage policies vary by company. Check the Insurance Certificate PDF Link field for specific policy information.

For more information on Falvey insurance, see the Falvey Support Page.