API Reference Documentation: https://staging.denim.com/api/v1/documentation#/Jobs

About Jobs

A job is a collection of payables, receivables, and fees (obligations) associated with an invoice or purchase order. Jobs also include the documents needed for Denim to process the job’s obligations. This documentation is updated to include details on version 2 of our Jobs endpoint.

Jobs API V1 and V2

In Version 1 of our create jobs endpoint, your application needs to provide Client-Debtor and Client-Payee relationships (see 4. Mapping and Syncing Companies). This requires your application to also build UI to handle searching for Denim company records and mapping them to your own companies, and creating Client-Debtor and Client-Payee relationships. This can be a lot of UX to build within your application.

Version 2 enables your application to instead provide external_company_id values (your company IDs), and then our shared clients can handle the mapping within Denim’s web app. Once the client maps these external_company_ids to Denim records and creates the relationships, whenever those external_company_ids are provided in future imports, the mapping is automatically applied.

Version 2 also supports everything Version 1 supports! Therefore if you chose to still handle mapping companies within your application, you can pass relationship_id along with your payables and receivables.

Additionally, when creating obligations (see below) on a job, in v1 they are provided in a list of obligations with the appropriate types and subtypes. With v2, payable obligations (e.g. obligations to Carriers) are provided in a list of payables, receivable obligations (e.g. obligations of shippers) in a list of receivables.

Creating Jobs

API Reference Documentation

Jobs are created by a POST request to /api/v2/jobs. As described above, jobs created with the v2 endpoint, client-payee and client-debtor relationships can be included if known (through the relationship_id attribute), or your application can pass external_company_id attributes and our shared clients can define relationships in the Denim web app in the Import Review page.

For jobs created via v1, client-payee relationships are required for jobs with payable obligations and client-debtor relationships are required for jobs with receivable obligations. This requires that integrators provide a user interface for users to search for debtors and payees within Denim’s system and create debtors and payees for companies not yet included in Denim’s system, using api/v1/debtor-relationships and api/v1/payee-relationships.

Jobs can be either factored or non-factored. Factored jobs will have funds advanced to the Payee by Denim, and Denim will then take possession of the invoice for future collection. Factored jobs require a receivable obligation. 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.

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 client's contractors.	Ensure that `is_factored` is `true`. V1: In the `obligations` array, include only obligations of type `receivable`. V2: Include the obligation details in the `receivables` list only.
Factored job with debtors and payees.	A factored job where Denim is responsible for handling collections from a client's customer and pays the client's contractors.	Ensure that `is_factored` is `true`. V1: In the `obligations` array, include obligations of types `receivable` and `payable`. V2: Include the obligation details in both the `receivables` list and the `payables` list.
Non-factored job with debtors only.	A non-factored job where Denim is responsible for handling collections from a client's customer but does not pay the client's contractors.	Ensure that `is_factored` is `false`. V1: In the `obligations` array, include only obligations of type `receivable`. V2: Include the obligation details in the `receivables` list only.
Non-factored job with debtors and payees.	A non-factored job where Denim is responsible for handling collections from a client's customer and pays the client's contractors.	Ensure that `is_factored` is `false`. V1: In the `obligations` array, include obligations of types `receivable` and `payable`. V2: Include the obligation details in both the `receivables` list and the `payables` list.
Non-factored job with payees only.	This is a job type where clients advance funds to Denim for paying their contractors.	Ensure that `is_factored` is `false`. V1: In the `obligations` array, include only obligations of type `payable`. V2: Include the obligation details in the `payables` list only.

Obligations

Obligations are the financial transactions that are part of the job. Factored jobs typically include obligations describing a payable corresponding to the Client-Payee relationship and a receivable corresponding to the Client-Debtor relationship, so that Denim can advance payment to the broker and the payee and collect payment from the debtor. Non-factored jobs often include either both obligation types or only a payable. Refer to the table above for details.

Job Documents

In general, Denim needs to receive billing paperwork and supporting paperwork. Documents of type billing_paperwork are sent to debtors and supporting_paperwork allows Denim to pay the payable obligation (document types are explained below). For jobs created via v1, designate type of billing_paperwork or supporting_paperwork. For jobs created via v2, documents included in the payable are treated as supporting_paperwork and documents included in the receivable are treated as billing_paperwork.

Supported formats are PDF, JPEG, and PNG. Documents must be under 10 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 and our system will download the document and securely store it in GCP via Google Storage service.

a. V1: using the documents attribute.

b. V2: using the documents attribute within the corresponding payables or receivables obligations attributes.
If the documents need to be uploaded separately, documents can be uploaded directly to the relevant Denim API endpoint after the job has 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.

a. V1: /api/v1/jobs/{job_id}/documents
b. V2: /api/v2/jobs/{job_id}/documents

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 to ensure that the customer/shipper agreed to the prices and work.
Proof of Delivery	billing_paperwork	proof_of_work	Can be a Proof of Delivery document or a signed Bill of Lading
Carrier Invoice	supporting_paperwork	invoice	Not needed when there are no contractor payable obligations.

Document Types

The table below provides an exhaustive list of all the document types associated with the Denim API.

For jobs created via v1, designate type of billing_paperwork or supporting_paperwork. For jobs created via v2, documents included in the payable are treated as supporting_paperwork and documents included in the receivable are treated as billing_paperwork.

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 (/api/v1/jobs/quote) 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

Jobs created with /api/v1/jobs default to pending, but can be created with a submit_type of draft if you do not want to submit the job for immediate review/approval by Denim.

Jobs created with /api/v2/jobs do not require a submit_type at this time. Jobs are initially created and pushed to our Import Review page. This offers our shared client the opportunity to complete company mapping steps and review the job data for any validation issues prior to submitting for draft. These jobs will have a status of client_review.

Client Review

Jobs submitted through V2 initially have a status of client_review. This offers our shared client the opportunity to complete company mapping steps and review the job data for any validation issues prior to submitting for draft through the Import Review page.

Draft

Jobs in draft status have not yet been submitted for Denim's review and approval.

Pending

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. A job in a pending state is undergoing this review.

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. At this time, jobs in client_review status can only be deleted by our shared client within the Import Review page in the Denim web app.