API Reference Documentation:
A job is a collection of payables, receivables, and fees (obligations) associated with an invoice or purchase order.
Creating Jobs
Jobs can be either factored or non-factored. Factored jobs will have funds advanced to the Client-Payee relationship by Denim, and Denim will then take possession of the invoice for future collection. For non-factored jobs, Denim does not advance any funds, but will still handle aspects of invoicing, collections, and contractor payments. More details on the types or combinations of job obligations are explained below.
Jobs have a few pieces of information attached: obligations and documents. Jobs can be created with a submit_type
of draft
if you do not want to submit the job for review/approval by Denim. By default, jobs will be submitted for review when created.
Types of Jobs
For factored and non-factored jobs, there are several supported job types that are configured based on the absence or presence of payable
and receivable
obligations. The table below summarizes the various job types and how to configure the payload to support them.
Job Type |
Description |
Configuration |
Factored job with debtors only. |
A factored job where Denim is responsible for handling collections from the Client-Debtor Relationship but does not pay the customer's contractors. |
In the |
Factored job with debtors and payees. |
A factored job where Denim is responsible for handling collections from a customer's customer and pays the customer's contractors. |
In the |
Non-factored job with debtors only. |
A non-factored job where Denim is responsible for handling collections from a customer's customer but does not pay the customer's contractors. |
In the |
Non-factored job with debtors and payees. |
A non-factored job where Denim is responsible for handling collections from a customer's customer and pays the customer's contractors. |
In the |
Non-factored job with payees only. |
This is a job type where clients advance funds to Denim for paying their contractors. |
In the |
Obligations
Obligations are all the financial transactions that are part of the job. In the case of factored jobs, there will need to be obligation definitions for both the payable to the Client-Payee relationship (the company being advanced funds) and a receivable to the Client-Debtor relationship. In the case of non-factored jobs, only a payable to the Client-Payee relationship needs to be defined.
Job Documents
In general, Denim ultimately needs to receive billing paperwork and supporting paperwork. The billing_paperwork
is sent to debtors and supporting_paperwork
allows Denim to pay the payable obligation (document types are explained below). Supported formats are PDF, JPEG, and PNG. Documents must be under 5 MB. Documents are not initially required when creating a job and can be added later.
Adding Documents
There are two ways to attach documents:
-
If the document is available at a publicly accessible URL, the URL can be included at the time the job is created using the
documents
attribute and our system will download the document and securely store it in GCP via Google Storage service. -
If the documents need to be uploaded separately, documents can be uploaded directly to the Denim API endpoint
/api/v1/jobs/{job_id}/documents
associated with the job after the job has initially been created. Note that this endpoint is a multi-part form which accepts a file upload. When files are uploaded in this manner, they are securely stored in GCP via the Google Storage service. This is the preferred method for ensuring that files are safely uploaded and stored, as there could be issues downloading documents from URLs in the first scenario above.
Expected Documents
TMS integrators are expected to provide, at a minimum, the following documents when submitting jobs for funding.
Document |
Type |
Subtype |
Notes |
Shipper Rate Confirmation |
billing_paperwork |
purchase_order |
Typically required. |
Proof of Delivery |
billing_paperwork |
proof_of_work |
|
Carrier Invoice |
supporting_paperwork |
purchase_order |
Not needed when there are no contractor payables. |
Document Types
The table below provides an exhaustive list of all the document types associated with the Denim API.
Type |
Description |
supporting_paperwork |
Supporting Paperwork - These are usually carrier docs (such as the carrier rate confirmation and carrier invoice) and they DO NOT get sent to the debtor. |
billing_paperwork |
Billing Paperwork - This includes POD, shipper rate con. They DO get sent to the debtor as a part of the invoice |
Document Subtypes
The table below provides an exhaustive list of all the document subtypes associated with the Denim API.
Subtype |
Description |
purchase_order |
Rate confirmation, i.e proof that someone agreed to the prices and work. |
invoice |
Invoice from the carrier or to the shipper (depending on billing or supporting) |
proof_of_work |
Usually proof of delivery, signed BOL, Lumper receipts, etc. |
Get a Factoring Quote
The quotation endpoint allows you to determine the factoring cost of a job using the same list of obligations that is used to create a job without actually creating a draft or submitted job.
Job Statuses
Pending
Generally, jobs are initially submitted in the pending
status. All jobs submitted to Denim go through a review process to ensure all the expected documents are available and other attributes about the job are verified by our team.
Draft
It is possible to submit a job initially as a draft using "submit_type": "draft"
, meaning it does not go into Denim's queue for review after creation. This can be useful if your flow requires documents to be added later. Jobs in pending
status can also be reverted to a draft using the revert-to-draft
endpoint.
Approved/Rejected
After Denim reviews the job, it will either be approved or rejected. In the case of rejected, we might be in conversation with our shared client to resolve any issues with the job as submitted.
Completed
Jobs are completed when all payables have been paid, and receivables have been collected by Denim.
Deleting Jobs
Jobs in a pending
or draft
state can be deleted. However once a job progresses further in any status, it cannot be deleted.