Denim Jobs V2 API
Version 2. A job is a collection of obligations (payables, receivables, and fees) associated with an invoice or purchase order.
OpenAPI Specification
openapi: 3.0.0
info:
contact:
email: engineering@denim.com
name: Denim Engineering Team
url: https://www.denim.com
description: The Denim Public API can be used by 3rd parties to sync companies, debtor relationships, payee relationships, and create invoices within Denim's payment platform. This enables streamlined operations and job invoice data between transportation management systems and Denim.
title: Denim Public API Reference Documentation Companies Jobs V2 API
version: 1.0.0
x-logo:
altText: Denim
backgroundColor: '#f5f5f5'
url: https://app.denim.com/images/branding/denim-logo-color.png
servers:
- description: Staging Environment
url: https://staging.denim.com
variables: {}
security:
- api_key: []
tags:
- description: Version 2. A job is a collection of obligations (payables, receivables, and fees) associated with an invoice or purchase order.
externalDocs:
description: 'Guides: Adding Jobs'
url: https://help.denim.com/hc/en-us/articles/9403903798811-5-Adding-Jobs
name: Jobs V2
paths:
/api/v2/jobs:
get:
callbacks: {}
description: A job is a collection of payables, receivables, and fees (obligations) associated with an invoice or purchase order.
externalDocs:
description: 'API Integration Guides: Adding Jobs'
url: https://help.denim.com/hc/en-us/articles/9403903798811-5-Adding-Jobs
operationId: AxlePayWeb.Api.V2.JobController.index
parameters:
- description: Search by company name, amount, or job number
example: $1,000.00
in: query
name: query
required: false
schema:
type: string
- description: Job statuses
example: approved
in: query
name: status
required: false
schema:
description: Job statuses
enum:
- draft
- pending
- approved
- rejected
- completed
- all_active
- all_inactive
example: approved
title: Job Status
type: string
- description: 'When true, return only jobs that need attention: manual/admin flag OR actionable document-audit issue.'
in: query
name: needs_attention
required: false
schema:
type: boolean
- description: The page of results to query.
example: 1
in: query
name: page
required: false
schema:
type: integer
- description: The number of entities per page of results.
example: 10
in: query
name: per_page
required: false
schema:
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Job Index Response'
description: Jobs index response
security:
- api_key: []
summary: List Jobs
tags:
- Jobs V2
post:
callbacks: {}
description: Create a new Job using our V2 API. Jobs created with this API can have certain Denim relationship IDs ommitted in favor of external IDs. Clients will then be able to utilitze the Denim Dashboard to review these Jobs and complete any mappings as necessary. Once a mapping between an external ID and a Denim ID has been completed, it will not need to be mapped for future Jobs.
externalDocs:
description: 'API Integration Guides: Adding Jobs'
url: https://help.denim.com/hc/en-us/articles/9403903798811-5-Adding-Jobs
operationId: AxlePayWeb.Api.V2.JobController.create
parameters: []
requestBody:
content:
application/json:
examples:
1_factored_payable_and_receivable_job:
summary: Create a factored job with both payable and receivable
2_factored_receivable_only_job:
summary: Create a factored job with receivable only
value:
is_factored: true
job_reference_number: shipment-70001
notes: Notes for the Denim operations team.
receivables:
- documents:
- subtype: invoice
url: https://www.publicurl.com/billing_paperwork.pdf
due_date: '2024-03-01T00:00:00Z'
external_company_id: '1394783'
obligation_date: '2024-01-01T00:00:00Z'
reference_number: '70001'
total_amount: 50000
3_non_factored_payable_and_receivable_job:
summary: Create a non-factored job with both payable and receivable
value:
is_factored: false
job_reference_number: shipment-70001
notes: Notes for the Denim operations team.
payables:
- documents:
- subtype: invoice
url: https://www.publicurl.com/billing_paperwork.pdf
due_date: '2024-03-01T00:00:00Z'
external_company_id: '1394783'
obligation_date: '2024-01-01T00:00:00Z'
reference_number: G21
total_amount: 26000
receivables:
- documents:
- subtype: invoice
url: https://www.publicurl.com/billing_paperwork.pdf
due_date: '2024-03-01T00:00:00Z'
external_company_id: '1394783'
obligation_date: '2024-01-01T00:00:00Z'
reference_number: '70001'
total_amount: 50000
4_non_factored_receivable_only_job:
summary: Create a non-factored job with receivable only
value:
is_factored: false
job_reference_number: shipment-70001
notes: Notes for the Denim operations team.
receivables:
- documents:
- subtype: invoice
url: https://www.publicurl.com/billing_paperwork.pdf
due_date: '2024-03-01T00:00:00Z'
external_company_id: '1394783'
obligation_date: '2024-01-01T00:00:00Z'
reference_number: '70001'
total_amount: 50000
5_non_factored_payable_only_job:
summary: Create a non-factored job with payable only
value:
is_factored: false
job_reference_number: shipment-70001
notes: Notes for the Denim operations team.
payables:
- documents:
- subtype: invoice
url: https://www.publicurl.com/billing_paperwork.pdf
due_date: '2024-03-01T00:00:00Z'
external_company_id: '1394783'
obligation_date: '2024-01-01T00:00:00Z'
reference_number: G21
total_amount: 26000
6_receivable_only_ltl_job:
summary: Create a receivable-only LTL job that references one or more payable-only jobs
value:
is_factored: true
job_reference_number: shipment-70001
notes: Notes for the Denim operations team.
receivables:
- allocated_payables:
- allocated_cost: 8000
allocated_revenue: 10000
payable_reference_number: G21
- allocated_cost: 11000
allocated_revenue: 15000
payable_reference_number: L22
- allocated_cost: 15000
allocated_revenue: 20000
payable_reference_number: 99A
- allocated_cost: 5000
allocated_revenue: 5000
payable_reference_number: '999'
documents:
- subtype: invoice
url: https://www.publicurl.com/billing_paperwork.pdf
due_date: '2024-03-01T00:00:00Z'
external_company_id: '1394783'
obligation_date: '2024-01-01T00:00:00Z'
reference_number: '70001'
total_amount: 50000
7_payable_only_ltl_job:
summary: Create a payable-only LTL job that references one or more receivable-only jobs
value:
is_factored: false
job_reference_number: route-G21
notes: Notes for the Denim operations team.
payables:
- allocated_receivables:
- allocated_cost: 8000
allocated_revenue: 10000
receivable_reference_number: '70001'
- allocated_cost: 12000
allocated_revenue: 15000
receivable_reference_number: '80001'
- allocated_cost: 6000
allocated_revenue: 12000
receivable_reference_number: '90001'
documents:
- subtype: invoice
url: https://www.publicurl.com/billing_paperwork.pdf
due_date: '2024-03-01T00:00:00Z'
external_company_id: '1394783'
obligation_date: '2024-01-01T00:00:00Z'
reference_number: G21
total_amount: 26000
schema:
$ref: '#/components/schemas/V2 Job Create Request'
description: Job create request
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Job Create Response'
description: New Job
security:
- api_key: []
summary: Create a Job
tags:
- Jobs V2
/api/v2/jobs/{job_id}:
get:
callbacks: {}
description: Returns a Job by UUID. This can return either a Job or a Job in Import Review. If the Job has been created, it will return a Job. If the Job has not yet been sumitted as a draft job and is under client_review, this will return a slimmer Job schema.
externalDocs:
description: 'API Integration Guides: Adding Jobs'
url: https://help.denim.com/hc/en-us/articles/9403903798811-5-Adding-Jobs
operationId: AxlePayWeb.Api.V2.JobController.show
parameters:
- description: Job UUID
example: 06f9eccc-e5df-44ce-ba68-d4ccbdbc33e6
in: path
name: id
required: true
schema:
type: string
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Job Show Response'
description: Job Record
security:
- api_key: []
summary: Show a Job by ID
tags:
- Jobs V2
/api/v2/jobs/{job_id}/document:
post:
callbacks: {}
description: 'This endpoint enables adding documents to existing jobs. This can accept either a json body with a publicly accessible `url`, `type` and `subtype`, or a multi-part form body including a `file` as the binary and `type` and `subtype`. In either case, the document will be uploaded and stored to our secure Google Cloud Platform storage.
'
externalDocs:
description: 'API Integration Guides: Adding Jobs'
url: https://help.denim.com/hc/en-us/articles/9403903798811-5-Adding-Jobs
operationId: AxlePayWeb.Api.V2.JobController.create_document
parameters:
- description: Job UUID
example: 06f9eccc-e5df-44ce-ba68-d4ccbdbc33e6
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Obligation Document'
multipart/form-data:
schema:
$ref: '#/components/schemas/Upload a document to a job'
description: Upload document request body
required: true
responses:
'204':
description: No Content
security:
- api_key: []
summary: Create a Job Document
tags:
- Jobs V2
components:
schemas:
Payable Obligation:
description: V2 Job payable obligation representing the payments to be made to carriers or contractors.
properties:
allocated_receivables:
description: '[Not yet implemented] For payable-only jobs, tracks the receivables associated to the payable. In particular for LTL shipments, this enables a payable-only job to be associated with a future receivable obligation.'
example: []
items:
properties:
allocated_cost:
description: Allocated cost in cents.
type: number
allocated_revenue:
description: Allocated revenue in cents
type: number
receivable_reference_number:
description: Receivable reference number
required: true
type: string
type: object
type: array
documents:
description: Documents associated with this obligation. Document type can be omitted as the type will be inferred by its presence with a receivable obligation.
example:
- subtype: proof_of_work
url: https://www.publicurl.com/supporting_paperwork.pdf
- subtype: invoice
url: https://www.publicurl.com/supporting_paperwork.pdf
items:
description: Documents associated with an obligation.
properties:
subtype:
description: Paperwork subtype
enum:
- carrier_misc
- invoice
- other
- proof_of_work
- purchase_order
nullable: true
type: string
type:
description: Optional. Type will be set or overridden when included with a receivable (billing_paperwork) or payable (supporting_paperwork).
enum:
- billing_paperwork
- supporting_paperwork
nullable: true
type: string
url:
description: 'Full remote URL of document file to be uploaded. Content-Type header is required in response. Allowed Content-Type values: application/pdf, image/png and image/jpeg.'
example: https://www.publicurl.com/paperwork.pdf
required: true
type: string
title: Obligation Document
type: object
type: array
due_date:
description: Date obligation is due in ISO format. The due_date should be within -60 and +120 days of the current datetime.
example: '2023-03-23T16:00:00Z'
format: date-time
type: string
external_company_id:
description: A unique identifier within the integrator's database (external to Denim). External company IDs will be able to go through a mapping experience within the Denim Dashboard to map external companies with Denim companies. Either an `external_company_id` OR `relationship_id` must be provided.
example: '1394783'
type: string
external_company_mc_number:
description: A unique universal identifier.
example: '123456'
type: string
external_company_name:
description: Name of the company associated with the `external_company_id`. This will show on the Import Review page to make it easier to map the external company to a Denim company.
example: Homer Trucking
type: string
load:
$ref: '#/components/schemas/Load details'
obligation_date:
description: Invoice date of the obligation.
example: '2023-03-23T16:00:00Z'
format: date-time
type: string
reference_number:
description: Obligation Reference Number.
example: PO-3395-098
type: string
relationship_id:
description: A relationship_id within Denim. This should be either a ClientDebtor Relationship ID (receivable) or a ClientPayee Relationship ID (payable). Either an `external_company_id` OR `relationship_id` must be provided.
example: 378
type: integer
total_amount:
description: Total amount of the obligation in cents
example: 100000
type: integer
title: Payable Obligation
type: object
Job Index Response:
description: Response schema for fetching jobs
example:
data:
- actionable_doc_audit_issue_count: 0
client_id: 2
company_id: 3
documents:
- file_name: 1582558423630_a5993a13c2_embedded_jpeg_pdf.pdf
inserted_at: '2020-02-24T15:33:46'
type: billing_paperwork
url: https://link-to-gcp-file.gcp.com
uuid: 3227bb84-6735-48c1-b8ea-4e7d09d1e07d
is_approved: true
is_rejected: false
is_validated: true
is_verified: true
manual_needs_attention: false
needs_attention: false
notes: There was a lumper fee
obligations:
- amount_due: 10000
applied_amount: 0
client_debtor_relationship_id: null
client_payee_relationship_days_to_pay_offset: null
client_payee_relationship_id: null
company_id: 2
company_name: Denim Logistics
discounted_days: 0
due_date: '2020-02-26T15:34:22Z'
latest_entry: null
payment_status: scheduled
reference_number: ''
status: approved
subtype: advance
total_amount: 10000
type: payable
- amount_due: 80000
applied_amount: 0
client_debtor_relationship_id: null
client_payee_relationship_days_to_pay_offset: 3
client_payee_relationship_id: 21
company_id: 45
company_name: Carrier LLC
discounted_days: 0
due_date: '2020-02-26T15:34:22Z'
latest_entry: null
payment_status: scheduled
reference_number: ''
status: approved
subtype: advance
total_amount: 80000
type: payable
uuid: a5558b9f-21d1-44b3-ad35-d642c9dc9b4d
- amount_due: 2000
applied_amount: 0
client_debtor_relationship_id: null
client_payee_relationship_days_to_pay_offset: null
client_payee_relationship_id: null
company_id: 2
company_name: Denim Logistics
discounted_days: 0
due_date: '2020-03-26T04:00:00Z'
latest_entry: null
payment_status: expected
reference_number: ''
status: approved
subtype: factoring_fee
total_amount: 3000
type: earnings
uuid: 580a94ca-0920-4fd3-aac7-aad144b57995
- amount_due: 7000
applied_amount: 0
client_debtor_relationship_id: null
client_payee_relationship_days_to_pay_offset: null
client_payee_relationship_id: null
company_id: 2
company_name: Denim Logistics
discounted_days: 0
due_date: '2020-03-26T04:00:00Z'
latest_entry:
inserted_at: '2020-03-24T04:00:00Z'
type: rebate_auto_giveback
uuid: 0a212a02-1623-4ea8-811c-db3da8e90f12
payment_status: expected
reference_number: ''
status: approved
subtype: rebate
total_amount: 7000
type: payable
uuid: 740ecc52-77f5-461d-b7dd-a30266dbc8d0
- amount_due: 100000
applied_amount: 0
client_debtor_relationship_id: 30
client_payee_relationship_days_to_pay_offset: null
client_payee_relationship_id: null
company_id: 116
company_name: New Debtor
discounted_days: 0
due_date: '2020-03-26T04:00:00Z'
latest_entry:
inserted_at: '2020-03-24T04:00:00Z'
type: payment_applied_to_obligation
uuid: 0a212a02-1623-4ea8-811c-db3da8e90f12
line_items:
- amount: 89000
description: Invoice Price
type: base_amount
- amount: 9000
description: Lumper Fee
type: accessorial_fee
- amount: 2000
description: Fuel Surcharge
type: accessorial_fee
payment_status: expected
reference_number: ''
status: approved
subtype: primary
total_amount: 100000
type: receivable
uuid: a5c3a55e-a58a-40a0-9408-6cfbc89f7441
reference_number: test-123
status: approved
status_message: This job is approved
uuid: 06f9eccc-e5df-44ce-ba68-d4ccbdbc33e6
page: 1
per_page: 2
total_pages: 3
total_result: 1
properties:
data:
items:
$ref: '#/components/schemas/Job'
type: array
page:
description: Current page of results
type: integer
per_page:
description: Entities per page
type: integer
total_pages:
description: Total number of pages
type: integer
total_result:
description: Total number of results
type: integer
title: Job Index Response
type: object
Job Document:
description: Associated documents for the job. Optional
properties:
subtype:
description: Billing or supporting paperwork subtype. Optional
enum:
- purchase_order
- proof_of_work
- invoice
nullable: true
type: string
type:
description: Billing paperwork gets sent to debtor. Supporting paperwork allows us to pay the carrier.
enum:
- billing_paperwork
- supporting_paperwork
type: string
url:
description: 'Full remote URL of document file to be uploaded. Content-Type header is required in response. Allowed Content-Type values: application/pdf, image/png and image/jpeg.'
type: string
title: Job Document
type: object
Obligation Document:
description: Documents associated with an obligation.
properties:
subtype:
description: Paperwork subtype
enum:
- carrier_misc
- invoice
- other
- proof_of_work
- purchase_order
nullable: true
type: string
type:
description: Optional. Type will be set or overridden when included with a receivable (billing_paperwork) or payable (supporting_paperwork).
enum:
- billing_paperwork
- supporting_paperwork
nullable: true
type: string
url:
description: 'Full remote URL of document file to be uploaded. Content-Type header is required in response. Allowed Content-Type values: application/pdf, image/png and image/jpeg.'
example: https://www.publicurl.com/paperwork.pdf
required: true
type: string
title: Obligation Document
type: object
Job Show Response:
description: Response schema for fetching jobs
example:
data:
actionable_doc_audit_issue_count: 0
client_id: 2
company_id: 3
documents:
- file_name: 1582558423630_a5993a13c2_embedded_jpeg_pdf.pdf
inserted_at: '2020-02-24T15:33:46'
type: billing_paperwork
url: https://link-to-gcp-file.gcp.com
uuid: 3227bb84-6735-48c1-b8ea-4e7d09d1e07d
is_approved: true
is_rejected: false
is_validated: true
is_verified: true
manual_needs_attention: false
needs_attention: false
notes: There was a lumper fee
obligations:
- amount_due: 10000
applied_amount: 0
client_debtor_relationship_id: null
client_payee_relationship_id: null
company_id: 2
company_name: Denim Logistics
discounted_days: 0
due_date: '2020-02-26T15:34:22Z'
payment_details: {}
payment_status: scheduled
reference_number: ''
status: approved
subtype: advance
total_amount: 10000
type: payable
- amount_due: 80000
applied_amount: 0
client_debtor_relationship_id: null
client_payee_relationship_id: 21
company_id: 45
company_name: Carrier LLC
discounted_days: 0
due_date: '2020-02-26T15:34:22Z'
payment_details: {}
payment_status: scheduled
reference_number: ''
status: approved
subtype: advance
total_amount: 80000
type: payable
uuid: a5558b9f-21d1-44b3-ad35-d642c9dc9b4d
- amount_due: 2000
applied_amount: 0
client_debtor_relationship_id: null
client_payee_relationship_id: null
company_id: 2
company_name: Denim Logistics
discounted_days: 0
due_date: '2020-03-26T04:00:00Z'
payment_details: {}
payment_status: expected
reference_number: ''
status: approved
subtype: factoring_fee
total_amount: 3000
type: earnings
uuid: 580a94ca-0920-4fd3-aac7-aad144b57995
- amount_due: 7000
applied_amount: 0
client_debtor_relationship_id: null
client_payee_relationship_id: null
company_id: 2
company_name: Denim Logistics
discounted_days: 0
due_date: '2020-03-26T04:00:00Z'
payment_details: {}
payment_status: expected
reference_number: ''
status: approved
subtype: rebate
total_amount: 7000
type: payable
uuid: 740ecc52-77f5-461d-b7dd-a30266dbc8d0
- amount_due: 100000
applied_amount: 0
client_debtor_relationship_id: 30
client_payee_relationship_id: null
company_id: 116
company_name: New Debtor
discounted_days: 0
due_date: '2020-03-26T04:00:00Z'
line_items:
- amount: 89000
description: Invoice Price
type: base_amount
- amount: 9000
description: Lumper Fee
type: accessorial_fee
- amount: 2000
description: Fuel Surcharge
type: accessorial_fee
payment_details:
account_name: Bank Account Name
account_number: X7890
account_type: checking
payment_status: fully_paid
reference_number: ''
status: approved
subtype: primary
total_amount: 100000
type: receivable
uuid: a5c3a55e-a58a-40a0-9408-6cfbc89f7441
reference_number: test-123
status: approved
status_message: This job is approved
uuid: 06f9eccc-e5df-44ce-ba68-d4ccbdbc33e6
properties:
data:
$ref: '#/components/schemas/Job'
title: Job Show Response
type: object
Upload a document to a job:
description: Upload a PDF, PNG, or JPEG documents associated with a job. Files will be uploaded to our secure file storage.
properties:
file:
description: Multi-part file upload of document.
format: binary
type: string
subtype:
description: Billing or supporting paperwork subtype. Optional
enum:
- purchase_order
- proof_of_work
- invoice
nullable: true
type: string
type:
description: Billing paperwork gets sent to debtor. Supporting paperwork allows us to pay the carrier.
enum:
- billing_paperwork
- supporting_paperwork
type: string
title: Upload a document to a job
type: object
Job Create Response:
description: Response for creating a job
example:
data:
company_id: 784
documents:
- subtype: proof_of_work
type: billing_paperwork
url: https://example.com/samples/sample_files/sample_document.pdf
- subtype: invoice
type: supporting_paperwork
url: https://example.com/samples/sample_files/sample_document.pdf
is_factored: true
obligations:
- client_debtor_relationship_id: null
client_payee_relationship_id: 21
company_id: 45
discounted_days: 0
due_date: '2020-02-26T15:34:22Z'
obligation_date: '2020-01-26T15:34:22Z'
reference_number: ''
subtype: primary
total_amount: 80000
type: payable
- client_debtor_relationship_id: 30
client_payee_relationship_id: null
company_id: 116
discounted_days: 0
due_date: '2020-03-26T04:00:00Z'
line_items:
- amount: 89000
description: Invoice Price
type: base_amount
- amount: 9000
description: Lumper Fee
type: accessorial_fee
- amount: 2000
description: Fuel Surcharge
type: accessorial_fee
obligation_date: '2020-02-26T04:00:00Z'
reference_number: ''
subtype: primary
total_amount: 100000
type: receivable
reference_number: test-123
status: pending
status_message: null
uuid: 3227bb84-6735-48c1-b8ea-4e7d09d1e07d
properties:
data:
properties:
company_id:
description: Company ID
type: integer
documents:
items:
$ref: '#/components/schemas/Job Document'
type: array
is_factored:
description: Whether job should be factored or not.
type: boolean
obligations:
items:
description: Payables, Receivables, and Denim's Fees for a job
properties:
allocated_payables:
description: '[Not yet implemented] For receivable-only jobs, tracks the payables associated to the receivable. In particular for LTL shipments, this enables a receivable-only job to be associated with previous payable obligations.'
example: []
items:
properties:
allocated_cost:
description: Allocated cost in cents.
type: number
allocated_revenue:
description: Allocated revenue in cents
type: number
payable_reference_number:
description: Payable reference number
required: true
type: string
type: object
type: array
allocated_receivables:
description: '[Not yet implemented] For payable-only jobs, tracks the receivables associated to the payable. In particular for LTL shipments, this enables a payable-only job to be associated with a future receivable obligation.'
example: []
items:
properties:
# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/denim/refs/heads/main/openapi/denim-jobs-v2-api-openapi.yml