Basic Denim integrations enable the integrated system to send Denim the info needed to create jobs in Denim, which may include mapping to and creating payee and debtor companies in Denim. More advanced integrations include consuming Denim data for display in the integrated system.
Denim's API supports multiple approaches for consuming Denim data - including job data (ie. job status), transactions data (ie. payment dates), and documents (ie. proofs of delivery) uploaded to Denim.
Detailed documentation of Denim’s API is available at https://app.denim.com/api/v1/documentation
Jobs, Payments, and Obligations
Job Data is available from GET calls to the /api/v1/jobs and /api/v2/jobs endpoints. Denim recommends using whichever jobs endpoint you currently use to POST to Denim. Learn more about the differences between the v1 and v2 jobs endpoint here: https://help.denim.com/hc/en-us/articles/9403903798811
These endpoints provide paginated responses and accept queries of company names, amount, job number, and job statuses.
Some commonly consumed job data are:
- Job Status
- Available values :
- “draft”
- “pending”
- “approved”
- “rejected”
- “completed”
- “client_review” (jobs v2 endpoints only)
- Available values :
- Payment data (within the “obligations” object)
- “amount_due”
- Amount paid or amount received as “applied_amount”
- Payment date as "latest_entry": {"inserted_at"}
- Job payee as “client_payee_relationship_id”
- Job debtor as "client_debtor_relationship_id"
- Obligation UUID as “uuid” to be used with Transactions endpoint (see section below)
Human-understandable obligation types and subtypes:
| Denim Obligation Type | Denim Obligation Subtype | Human-readable Description | Note |
| receivable | primary | Receivable | |
| payable | primary | Contractor Payable | |
| payable | advance | Advance Payable | This could be paid to the client or contractor. If the job company_id matches the obligation company_id, then it is a client advance. Otherwise a contractor advance |
| payable | rebate | Client Rebate | AKA "reserve" |
| earnings | factoring_fee | Factoring Fee | |
| earnings | servicing_fee | Servicing Fee | |
| receivable | prefunding | Client-provided Funding | This is an obligation from a client to pay a contractor |
Documents
Denim jobs include documents that have been uploaded through the Denim web app or have been sent through Denim’s API.
Documents are available from URL provided from the jobs endpoints, as a “documents” object:
Transactions
Beyond the payment data available at the jobs endpoint (see above), more detailed payment data is available from the /api/v1/transactions endpoint. This endpoint returns all transactions, paginated, by default, so Denim recommends querying by obligation uuid, which is available from the jobs endpoint (see above). The transaction endpoint is slower and more expensive than Denim’s other endpoint
Some of the most commonly consumed transactions data are:
- Applied Transactions data “applied_transactions”
- “amount_due”
- “applied _amount”
- “payment_status”
- “total_amount”
- “type”
- Transactions date as “transaction_date”
- Payment method as “method”
Polling
Denim recommends daily polling of jobs endpoints and transaction endpoints. If near-real-time data is desired by your users, hourly polling of the jobs endpoints is acceptable. Due to costs and throttling, we do NOT recommend polling the transactions endpoint more than once per day.