Denim Debtors API
A debtor is your customer or shipper. They are the entity that will be paying the invoices. Debtors are a type of Company in our ecosystem and are associated to our shared client through Client-Debtor Relationships.
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 Debtors 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: A debtor is your customer or shipper. They are the entity that will be paying the invoices. Debtors are a type of Company in our ecosystem and are associated to our shared client through Client-Debtor Relationships.
externalDocs:
description: 'Guides: Companies'
url: https://help.denim.com/hc/en-us/articles/9403899854107-4-Mapping-and-Syncing-Companies
name: Debtors
paths:
/api/v1/debtor-relationships:
get:
callbacks: {}
description: This retrieves the debtors that your company has a relationship with.
externalDocs:
description: 'API Integration Guides: Mapping and Syncing Companies'
url: https://help.denim.com/hc/en-us/articles/9403899854107-4-Mapping-and-Syncing-Companies
operationId: AxlePayWeb.Api.V1.ClientDebtorRelationshipController.index (2)
parameters:
- description: Search string for debtor company name or MC Number.
example: ABC Shipping Company
in: query
name: query
required: false
schema:
type: string
- description: Debtor Relationship Filters
example:
average_dbt_from: 0
average_dbt_to: 90
average_dso_from: 0
average_dso_to: 90
credit_usage_from: 0
credit_usage_to: 100
funding_type: factored
net_terms: 30
open_aging_from: 0
open_aging_to: 10000
open_chargebacks_from: 0
open_chargebacks_to: 10000
overall_status:
- verified
- under_review
- no_buy
- declined
- noa_pending_delivery
in: query
name: filters
required: false
schema:
description: Available filters for fetching Debtors
example:
average_dbt_from: 5
average_dbt_to: 12
average_dso_from: 25
average_dso_to: 45
credit_usage_from: 50
credit_usage_to: 75
funding_type: factored
net_terms: 15
open_aging_from: 0
open_aging_to: 10000
open_chargebacks_from: 0
open_chargebacks_to: 10000
overall_status:
- verified
- noa_pending_delivery
sort_col: credit_usage_percentage
sort_dir: desc
properties:
average_dbt_from:
description: Average Days Beyond Terms lower bound
type: integer
average_dbt_to:
description: Average Days Beyond Terms upper bound
type: integer
average_dso_from:
description: Average Days Sales Outstanding lower bound
type: integer
average_dso_to:
description: Average Days Sales Outstanding upper bound
type: integer
credit_usage_from:
description: Credit usage percentage lower bound (0-100)
type: integer
credit_usage_to:
description: Credit usage percentage upper bound (0-100)
type: integer
funding_type:
description: Type of funding
enum:
- factored
- non_factored
type: enum
net_terms:
description: Net terms (payment days)
type: integer
open_aging_from:
description: Open Aging lower bound (in dollars)
type: integer
open_aging_to:
description: Open Aging upper bound (in dollars)
type: integer
open_chargebacks_from:
description: Open Chargebacks lower bound (in dollars)
type: integer
open_chargebacks_to:
description: Open Chargebacks upper bound (in dollars)
type: integer
overall_status:
description: Debtor relationship overall status
items:
enum:
- verified
- under_review
- no_buy
- declined
- noa_pending_delivery
type: enum
type: array
sort_col:
description: Column to sort by
enum:
- status
- credit_usage_percentage
- net_terms
- average_dso
- average_dbt
- open_aging
- open_chargebacks
type: string
sort_dir:
description: Sort direction
enum:
- asc
- desc
type: string
title: Debtor Relationship Filters
type: object
- 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/Debtor Index Response'
description: Debtor relationship response
security:
- api_key: []
summary: List Client-Debtor Relationships
tags:
- Debtors
post:
callbacks: {}
description: You can create a debtor relationship by linking to an existing approved company in our system (preferred) by passing the company_id found using the GET/companies endpoint. Alternatively, you can create a new company and client-debtor relationship simultaneously by sending the company attributes. Note that all credit requests are reviewed by our operations team for approval.
externalDocs:
description: 'API Integration Guides: Mapping and Syncing Companies'
url: https://help.denim.com/hc/en-us/articles/9403899854107-4-Mapping-and-Syncing-Companies
operationId: AxlePayWeb.Api.V1.ClientDebtorRelationshipController.create (2)
parameters: []
requestBody:
content:
application/json:
examples:
existing_company_example:
description: Creates a Client-Debtor Relationship using an existing company_id record.
summary: Create Client-Debtor Relationship with Existing Company
value:
company_id: 123
new_company_with_credit_example:
description: Add new company and client-debtor relationship with credit request. Note that credit requests are reviewed by our operations team.
summary: Create a new company and Client-Debtor Relationship
value:
company:
address_line_1: 1 Fifth Avenue
address_line_2: 'PH #9'
city: New York
company_name: New Customer LLC
country: USA
dot_number: null
ein: '123456789'
freight_forwarder_number: '123456'
mc_number: null
state: NY
website: www.newcompany.com
credit_request:
credit_amount: 500000
invoicing_email: invoicing@newcompany.com
phone_number: '12025348399'
schema:
$ref: '#/components/schemas/Debtor Create'
description: Creating Client-Debtor Relationship params
required: false
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Debtor Create Response'
description: Debtor relationship created response
security:
- api_key: []
summary: Create new Client-Debtor Relationship
tags:
- Debtors
components:
schemas:
Debtor:
description: Debtor attributes shared across all clients (as opposed to per-relationship attributes, which live on `client_debtor_relationship`).
properties:
credit_limit:
description: Shared credit limit for this debtor (in cents). In the company search response this is the debtor's `shared_credit_limit`. When a per-relationship limit is required, use `client_debtor_relationship.credit_limit`.
nullable: true
type: integer
credit_used:
description: Shared credit used by this debtor (in cents). Not populated by the company search endpoint; use `client_debtor_relationship.credit_used` for the per-relationship amount.
nullable: true
type: integer
net_terms:
description: Default net terms (payment days) for the debtor. The per-relationship value on `client_debtor_relationship.net_terms` takes precedence when set.
nullable: true
type: integer
title: Debtor
type: object
Debtor Create:
description: Use the company search API to link to an existing approved debtor or send the `company` parameters to create a new debtor.
example:
company:
address_line_1: 1 Fifth Avenue
address_line_2: 'PH #9'
city: New York
company_name: New Customer LLC
country: USA
dot_number: null
ein: '123456789'
freight_forwarder_number: '123456'
mc_number: null
state: NY
website: www.newcompany.com
zip_code: '11111'
credit_request:
credit_amount: 500000
invoicing_email: invoicing@newcompany.com
phone_number: '12025348399'
properties:
company:
$ref: '#/components/schemas/Debtor Company'
company_id:
description: Company ID
type: integer
credit_request:
$ref: '#/components/schemas/Debtor Company Credit Request'
required:
- name
- email
title: Debtor Create
type: object
Debtor Index Response:
description: Response schema for fetching debtor relationships
example:
data:
- client_debtor_relationship:
average_dbt_past_60_days: 5.0
average_dso_past_60_days: 25.5
credit_limit: 500000
credit_used: 200000
default_job_is_factored: true
id: 3
net_terms: 30
no_buy_status: false
noa_status: pending_delivery
open_aging: 0
open_chargebacks: 0
overall_status: noa_pending_delivery
status: pending
company:
address_line_1: 1 Fifth Avenue
address_line_2: 'PH #9'
city: New York
company_name: ABC Shipping Company
dot_number: '1234567'
ein: '123456789'
freight_forwarder_number: '123456'
id: 74
mc_number: '12345678'
state: NY
website: www.abcshipping.com
zip_code: '11111'
debtor:
credit_limit: null
credit_used: null
- client_debtor_relationship:
average_dbt_past_60_days: 12.3
average_dso_past_60_days: 32.7
credit_limit: 500000
credit_used: 200000
default_job_is_factored: false
id: 43
net_terms: 45
no_buy_status: false
noa_status: pending_delivery
open_aging: 500000
open_chargebacks: 100000
overall_status: under_review
status: pending
company:
address_line_1: 123 Royals Blvd.
address_line_2: 'attn: John Smith'
city: Kansas City
company_name: Best Customer LLC
ein: '123456789'
freight_forwarder_number: '123456'
id: 43
mc_number: '12345678'
state: MO
website: www.bestco.com
zip_code: '11111'
debtor:
credit_limit: null
credit_used: null
page: 1
per_page: 2
total_pages: 3
properties:
data:
items:
properties:
client_debtor_relationship:
$ref: '#/components/schemas/Client-Debtor Relationship'
company:
$ref: '#/components/schemas/Debtor Company'
debtor:
$ref: '#/components/schemas/Debtor'
type: object
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_results:
description: Total number of results
type: integer
title: Debtor Index Response
type: object
Debtor Create Response:
description: Response schema for creating a new debtor relationship
example:
data:
client_debtor_relationship:
average_dbt_past_60_days: null
average_dso_past_60_days: null
credit_limit: 500000
credit_used: 200000
default_job_is_factored: true
id: 3
net_terms: 30
no_buy_status: false
noa_status: pending_delivery
open_aging: 0
open_chargebacks: 0
overall_status: noa_pending_delivery
status: pending
company:
address_line_1: 1 Fifth Ave.
address_line_2: 'PH #9'
city: New York
company_name: ABC Shipping Company
country: USA
dot_number: '1234567'
ein: '123456789'
freight_forwarder_number: '123456'
id: 74
mc_number: '12345678'
state: NY
website: www.abcshipping.com
zip_code: '11111'
debtor:
credit_limit: null
credit_used: null
properties:
data:
properties:
client_debtor_relationship:
$ref: '#/components/schemas/Client-Debtor Relationship'
company:
$ref: '#/components/schemas/Debtor Company'
debtor:
$ref: '#/components/schemas/Debtor'
type: object
title: Debtor Create Response
type: object
Debtor Company Credit Request:
description: Credit request for a new debtor company
properties:
credit_amount:
description: Request amount in cents
type: integer
invoicing_email:
description: Invoicing email
type: string
phone_number:
description: Invoicing phone number
type: string
title: Debtor Company Credit Request
type: object
Client-Debtor Relationship:
description: Included only when a non-deleted Client-Debtor Relationship exists between the requesting client and the company. The `id` is usable as `client_debtor_relationship_id` in other API requests.
properties:
average_dbt_past_60_days:
description: Average Days Beyond Terms
nullable: true
type: number
average_dso_past_60_days:
description: Average Days Sales Outstanding (DSO) in the past 60 days
nullable: true
type: number
default_job_is_factored:
description: Whether new jobs for this debtor default to factored funding.
nullable: true
type: boolean
id:
description: usable as `client_debtor_relationship_id`
type: integer
net_terms:
description: Net terms (payment days) for this relationship. Overrides `debtor.net_terms` when set.
nullable: true
type: integer
noa_status:
description: Notice-of-Assignment status for the relationship.
enum:
- pending_delivery
- delivered
- viewed
- confirmed
type: string
status:
description: Per-client approval status for this debtor relationship. `approved` relationships are ready for use. The system enforces at most one `approved` relationship per (client, debtor) — any prior duplicates are marked `rejected`. When the `best_match` sort returns multiple results for the same company, the highest-credit-amount row wins (see operation description).
enum:
- pending
- approved
- rejected
type: string
title: Client-Debtor Relationship
type: object
Debtor Company:
description: A debtor company
properties:
address_line_1:
description: Address Line 1
type: string
address_line_2:
description: Address Line 2
type: string
city:
description: City
type: string
company_name:
description: Debtor company name
type: string
country:
default: USA
description: Country (3 character abbreviation)
enum:
- USA
- CAN
type: string
dot_number:
description: DOT Number (Department of Transportation Number)
nullable: true
type: string
ein:
description: Federal EIN / Tax ID (9 digits)
nullable: true
type: string
freight_forwarder_number:
description: Freight Forwarder Number
nullable: true
type: string
id:
description: Company ID
type: integer
mc_number:
description: FMCSA Motor Carrier Number (6-8 digits)
nullable: true
type: string
state:
description: State (2 Character Abbreviation)
type: string
website:
description: Website URL
nullable: true
type: string
zip_code:
description: Zip Code
type: string
required:
- company_name
title: Debtor Company
type: object
securitySchemes:
api_key:
in: header
name: x-api-key
type: apiKey
externalDocs:
description: API Integration Guides
url: https://help.denim.com/hc/en-us/sections/9403805442843-API-Integration-Guides