API Reference Documentation: https://staging.denim.com/api/v1/documentation
A Note about Jobs API V1 and V2
In Version 1 of our create jobs endpoint (see 5. Adding and Managing Jobs), your application needs to map companies across systems - to provide Client-Debtor and Client-Payee relationships (see below sections). 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 of our create jobs endpoint (see 5. Adding and Managing Jobs) 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.
The below is only relevant if you plan to build a company mapping UX in your application. If you choose to use the V2 of our create jobs endpoint, proceed to 5. Adding and Managing Jobs.
Company Mapping
The content below explains Denim's endpoints needed to map companies from external platforms with company records within Denim. Debtors and Payees are types of companies within Denim's database. The goal of this section is to learn how to map your companies to our companies when it comes time to create jobs, and ensure invoices are collected from the correct Client-Debtor companies and payments sent to the correct Client-Payee company.
NOTE! Mapping companies is not an automatic process. Integrators will need to make these connections using Denim's API to either discover and map existing records, or create new company records within Denim's platform. At this time there is no bulk syncing operation available; this will need to be done on the individual company level.
This step is important as it helps to prevent duplicate company records within Denim, and serves to ensure everyone is paid on time and without delays.
Searching for Companies
Related API Reference: https://app.denim.com/api/v1/documentation#/Companies
To find existing companies within Denim, there are two endpoints to explain: factoring companies and other types of companies. We'll explain factoring companies first, then explain searching for other types of companies.
UX Suggestion! Searching for companies (particularly by name) could return multiple similar results, so we recommend providing some UI in your application to enable users to see the results and pick the best match. As mentioned, creating duplicate company records could slow the payment process.
Factoring Companies
This endpoint simply provides a list of all factoring companies established within Denim's ecosystem. You might need these companies when setting up Payees as they could also be using a factor. There are no query parameters for searching these companies. All factoring companies will be returned in a single page, regardless of the number of results, so you will not need to handle multiple pages.
Searching for Companies
Searching for companies returns a paginated list of results. If leveraging company name search, we recommend adding some type of user interaction where users can choose the correct company from the results, as there can be multiple companies with similar names. If you're searching for carriers or brokers, it is preferred to use MC numbers for search where possible (these should be used without an MC- prefix). The following parameters are available:
query
The query term is a string and searches against company name or MC number. MC numbers should be used without any MC- prefix or leading zeros.
type
If you know the type of company you're searching for, this can help sort results. Note that this is not a filter, but is used for sorting the results. For example, if you search using "type": "debtor" , the companies we have marked as debtors will appear first in the returned results. Type can be one of debtor , payee , or factor . If you're searching for factors, we recommend using the List Factoring Companies endpoint instead, as it will return only those companies.
page
Which page of the search results to return. Default is 1.
per_page
How many results to return per page of the results. Default is 25.
Client-Debtor and Client-Payee Relationships
If a company in the search results already has a Client-Debtor or Client-Payee relationship, that information will be included in the return data for that company record in the result. There are more details explaining these relationships below, and examples of these returns in the API Reference Documentation.
Client-Debtor Relationships
Debtors, as defined previously in the Terminology guide, are the shippers or companies actually paying the invoices.
Debtors and Credit Limits
Debtors will have a global credit limit set by Denim's operations team that applies across all Client-Debtor relationships. In the case of factored jobs, Denim is advancing funds and these jobs will count towards that global limit.
When adding a new debtor company that does not already exist in Denim's ecosystem, you are also able to include a credit limit request. These credit limit requests are verified by our operations team. Credit limit request are not included when mapping an existing Debtor to your client when creating Client-Debtor Relationships as they will already have an established credit limit.
After a debtor is established in Denim, credit limits can only be updated later by our shared client via the Denim Dashboard, not the API. These credit limit requests will be reviewed by our operations team.
Link Existing Debtor
If a company you are linking to the client already exists in the Denim ecosystem (e.g. found through the Company search above), you can create a Client-Debtor relationship simply by providing the company_id of the company record.
Add a New Debtor
If you are not able to find a company record to use for a Client-Debtor Relationship, you can create a company with basic details. This will create a company record within Denim and also create the Client-Debtor Relationship in the same request. Additionally, if needed, a credit request can be included.
Client-Payee Relationships
Payees, as explained previously in the terminology guide, are those companies that are being paid as part of a Job.
Factors and Payees
It is possible for Payees (carriers) to themselves use a Factoring company to help with cash flow and to pay their own drivers or contractors. In those cases, Denim needs to know if they are using a factor so that we can send funds to their factor and not the carrier directly.
Existing Factors
Denim has an API endpoint that returns a list of factoring companies we've worked with before. In many cases, the Factor you need to add will be available through those results and you'll only need to supply the company_id of that factor.
New Factors
If the Factor is not available through that endpoint, you can add a new Factor by passing a company id of 0 . This will create a request for a new factor and alert our operations team to verify the contact information for this new factoring company.
Link Existing Payee
If a company you are adding as a payee to this client already exists in Denim's database (e.g. through a company search above), you can create a Client-Payee relationship simply by providing the company_id for the payee.
If needed, you can pass a factor with a company as described above. This is useful if the existing payee record does not have a factor assigned or the factor assigned is incorrect. As described previously, this will create a request to change the Factor associated with the company and will be reviewed by our operations team.
Add a New Payee
If you are not able to find a company record to use in creating a Client-Payee Relationship, you can create a company by providing basic details. This will create a new company record within Denim and create the Client-Payee Relationship in the same request. Additionally, if needed, you can pass a factor with the company as described above.
Updating Payee Factor
If the Payee has added a factor or changed factoring companies, the factor can be updated through this endpoint. As explained above, if the factor being updated to does not yet exist in Denim, pass a company id of 0 to create a new one.