Activating the Integration
Step 1: Create an API Profile in Turvo
The first step is to create an API Profile in Turvo, which allows your account to send job data over their API to Denim. Only Super Admins can create and manage Turvo API profiles.
Create an API User
Before you can create an API profile, it is recommended that you create a special Super Admin-level user that will be associated with the Denim API Profile.
- To create a user, go to Turvo's Admin Console, then select Users, then Add user.
- The user name can be "Denim API" or similar.
- The email address should be an email address you control.
- After creating, check the email associated with the new user and create a password.
Add API Profile
- Go to your Turvo Admin Console
- Select API & Webhooks
- Click Add an API Profile
- Set your Profile Name (It can be anything - we suggest using "Denim" or something similar).
- For Profile User Name, use the name of the Super Admin-level user that you created to use with the API Profile.
- Once a profile is created, add an API key in the upper right of the screen.
- For more information on Turvo API Profiles, visit the Turvo help article here.
Step 2: Link your account in the Denim app
Login to the Denim webapp, navigate to your Settings menu, and then select the TMS Integrations tab.
On the integrations page, enter the Turvo login credentials to establish a connection between Denim and Turvo. Use the credentials for the Turvo user associated with the API Profile you created earlier - the TMS Username and TMS Password are the Turvo email and password for the API user account created earlier. The API key is available from Turvo: Admin Console > API & Webhooks.
Preparing Turvo Shipments for Import to Denim
How Denim Selects Jobs for Import
Denim imports details from Shipment objects in Turvo and converts them to Denim jobs. When you initiate an import, our app will search your Turvo account for Shipments in the Ready for Billing status. In order for jobs to qualify, the following documents must be uploaded to, or generated within, the Shipment in Turvo:
- Customer Rate Confirmation - documentation generally needed by Denim
- Proof of Delivery - documentation generally needed by Denim
- Carrier Invoice - documentation generally needed by Denim
- Also used to import the following fields:
- Invoice # imported as Denim job's Contractor Invoice Number
- Invoice Amount imported as Denim job's Payable Amount
- Invoice Due Date imported as Denim job's Payable Due Date
- Also used to import the following fields:
- Customer Invoice from Turvo - does not need to be sent to the customer, but create this document in Turvo so that Denim can import the following fields:
- Invoice Amount as Denim's Receivable Amount
- Invoice Due Date imported as Denim's Receivable Due Date
If provided, a Customer Purchase Order # will be imported as the Denim job's Customer PO#.
Once your shipments are ready in Turvo, follow the steps below for more details on completed the Denim import.
Suggested Turvo Settings
These optional settings will help with your workflow and ensure that jobs imported to Denim contain all required information and documents, and can be efficiently reviewed and submitted for funding.
Access your settings via the Admin console and select the Payments card:
Once you've clicked on the Payments card, find "Billing document rules."
Add POD, carrier invoice, and customer rate confirmation as required documents. This will give you an alert that these docs are missing when you put the job into Ready for Billing status.
The Import Process
STEP 1 | Import Jobs from Turvo
To start the Import process, select the Import Jobs button. The Import Jobs button can be found on the Dashboard, Jobs Board and Import Review pages. Once you've opened the import modal, select the TMS Bulk Import option. If you completed the authentication steps above, you will see that Turvo is already selected as your linked TMS, and you will have the option to set a date range for imports.
Set the date range you'd like to import. From here, Denim will import any shipments in Ready for Billing status with a delivery date within the date range you entered. You will receive a confirmation prompt if the import is successful, including the number of jobs imported. If no qualifying Shipments are found, you will have the option to adjust your date range.
Successful imports will be created in an interim status for final review and are not yet saved into your Jobs Board.
Click the Go to Import Review button to visit the Import Review page to finalize the import process and save jobs as drafts.
STEP 2 | Resolve Company Mapping
If this is your first time using a customer or contractor with this integration, we will ask you to map them to debtor or payee companies in Denim's database. You will only need to do this once per shipper or contractor you work with. Once a company as been identified in Denim and the mapping is saved, we'll automatically select the company for you on subsequent imports.
Map companies by searching the company name in the field in the Denim Equivalent column. A green checkmark next to the company name indicates and existing relationship to your account, and a plus sign is a company that exists in the Denim system but doesn't have a relationship to your account. You can click that company to add a relationship, or click Add New Company to create one from scratch.
STEP 3 | Review Interim Jobs on the Import Review Page
The last step allows you to review the imported job details before converting the interim jobs to draft status or submitting. Click the Save Jobs as Draft button if the jobs need further attention, or Submit for Funding if the jobs and paperwork are ready for Denim's review.
- Jobs with a green checkmark are free of errors and ready to save or submit.
- Jobs that are not ready will be marked with a red triangle and populated at the top of the list. The specific error(s) in that row are indicated by red text or outlined with a red input field.
- If the Save Jobs as Drafts and Submit For Funding buttons are disabled, that means none of the listed jobs are ready to submit. Common errors that may need to be fixed include:
- A Company has not been defined/mapped. This is resolved by completing step 2.
- An input is not formatting correctly
- Information is missing
- The job or reference number is duplicated
When you click to save the jobs, you'll see a success message at the top of the page indicating how many jobs were saved as drafts. The saved jobs will now be viewable on the Jobs Board page.
If an error can not be corrected, the best solution is to delete it and try to import again. If this approach still does not fix the issues, adding it as a job through the Add Jobs workflow in your webapp dashboard may be necessary.
Payment Updates from Denim to Turvo
Denim automatically updates Turvo shipments with the details of customer and contractor payments as they occur. Navigate to the Details tab on your Turvo shipment to see the payment amount and method.
Notes:
- Charged back invoices (due to partial or full nonpayment) will not be synced back to Turvo
- Partial payments that are not charged back will update into Turvo, but Turvo's API does not accept overpayments.
Have any additional questions? Reach out to your account manager, or check out Turvo's help center.