Denim Jobs V2 API

openapi: 3.2.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:
    Job:
      description: A job and it's documents and obligations.
      properties:
        actionable_doc_audit_issue_count:
          default: 0
          description: Count of document-audit issues in action_required status for this job.
          minimum: 0
          type: integer
        client_id:
          description: Client ID
          type: integer
        company_id:
          description: Company ID
          type: integer
        documents:
          items:
            $ref: '#/components/schemas/Job_Document'
          type: array
        is_approved:
          description: Status of job approval
          type: boolean
        is_rejected:
          description: Status of job rejection
          type: boolean
        is_validated:
          description: Status of job validation
          type: boolean
        is_verified:
          description: Status of job verification
          type: boolean
        manual_needs_attention:
          default: false
          description: Boolean indicating only manual/admin needs-attention signals (excludes document-audit issue signals).
          type: boolean
        needs_attention:
          description: 'Composite filter flag: true when manual_needs_attention is true OR actionable_doc_audit_issue_count > 0.'
          type: boolean
        notes:
          description: Notes for our team
          type:
          - string
          - 'null'
        obligations:
          items:
            $ref: '#/components/schemas/Job_Obligation'
          type: array
        reference_number:
          description: Job reference number
          type: string
        status:
          description: Job statuses
          enum:
          - draft
          - pending
          - approved
          - rejected
          - completed
          type: string
        status_message:
          description: Message from our team
          type:
          - string
          - 'null'
        uuid:
          description: Unique identifier for the job in UUID4 format
          type: string
      title: Job
      type: object
    Receivable_Obligation:
      description: V2 Job receivable obligation representing payments to be collected by Denim.
      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
        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: invoice
            url: https://www.publicurl.com/billing_paperwork.pdf
          - subtype: invoice
            url: https://www.publicurl.com/billing_paperwork.pdf
          items:
            description: Documents associated with an obligation.
            properties:
              subtype:
                description: Paperwork subtype
                enum:
                - carrier_misc
                - invoice
                - other
                - proof_of_work
                - purchase_order
                type:
                - string
                - 'null'
              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
                type:
                - string
                - 'null'
              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_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
        line_items:
          description: "  Line Items associated with the obligation. Two requirements:\n  1. base_amount line item must be provided, the rest should be accessorial_fee\n  1. The sum of all line item amounts must add up to the total_amount of the receivable obligation\n"
          example:
          - amount: 89000
            description: Invoice Price
            type: base_amount
          - amount: 9000
            description: Lumper Fee
            type: accessorial_fee
          - amount: 2000
            description: Fuel Surcharge
            type: accessorial_fee
          items:
            description: 'Line Item associated with the obligation. '
            properties:
              amount:
                description: Amount of the obligation in cents
                example: 6500
                type: integer
              description:
                description: Describe the line item
                example: Lumper Fee
                type: string
              type:
                description: Type of the line item
                enum:
                - accessorial_fee
                - base_amount
                - express_factoring_fee
                - non_factoring_fee
                - job_processing_fee
                - servicing_fee
                example: accessorial_fee
                type: string
            title: Obligation Line Item
            type: object
          type: array
        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
        shipment:
          $ref: '#/components/schemas/Shipment_details'
        total_amount:
          description: Total amount of the obligation in cents
          example: 100000
          type: integer
      title: Receivable Obligation
      type: object
    Job_Obligation:
      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:
              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
        amount_due:
          description: Amount due on the obligation in cents
          type: integer
        applied_amount:
          description: Amount of transactions that have been applied to the obligation in cents
          type:
          - integer
          - 'null'
        company_id:
          description: Company ID for the obligation
          type: integer
        company_name:
          description: Company name of the obligation
          type: string
        discounted_days:
          description: Number of days factoring was delayed for a discount
          type: integer
        due_date:
          description: Date obligation is due in ISO format. The due_date should be within -60 and +120 days of the current datetime.
          type: string
        line_items:
          description: "  Line Items associated with the obligation. Two requirements:\n  1. base_amount line item must be provided, the rest should be accessorial_fee\n  1. The sum of all line item amounts must add up to the total_amount of the receivable obligation\n"
          example:
          - amount: 89000
            description: Invoice Price
            type: base_amount
          - amount: 9000
            description: Lumper Fee
            type: accessorial_fee
          - amount: 2000
            description: Fuel Surcharge
            type: accessorial_fee
          items:
            description: 'Line Item associated with the obligation. '
            properties:
              amount:
                description: Amount of the obligation in cents
                example: 6500
                type: integer
              description:
                description: Describe the line item
                example: Lumper Fee
                type: string
              type:
                description: Type of the line item
                enum:
                - accessorial_fee
                - base_amount
                - express_factoring_fee
                - non_factoring_fee
                - job_processing_fee
                - servicing_fee
                example: accessorial_fee
                type: string
            title: Obligation Line Item
            type: object
          type: array
        payment_details:
          description: Payment details for the obligation
          properties:
            account_name:
              description: Name of account used for payment
              required: false
              type: string
            account_number:
              description: Last four digits of the account used for payment
              example: X7890
              required: false
              type: string
            account_type:
              description: Type of account used for payment
              enum:
              - checking
              - savings
              - check_address
              required: false
              type: string
            check_number:
              description: Number of check used for payment
              required: false
              type: string
          type: object
        payment_status:
          description: Payment status of the obligation
          enum:
          - pending
          - fully_paid
          - overpaid
          - underpaid
          - expected
          - scheduled
          type:
          - string
          - 'null'
        subtype:
          description: Subtype of the obligation
          enum:
          - primary
          - client
          - advance
          - rebate
          - factoring_fee
          - servicing_fee
          type: string
        total_amount:
          description: Total amount of the obligation in cents
          type: integer
        type:
          description: Type of the obligation
          enum:
          - receivable
          - payable
          - earnings
          type: string
        uuid:
          description: Unique identifier for the obligation in UUID4 format.
          type: string
      title: Job Obligation
      type: object
    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
                type:
                - string
                - 'null'
              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
                type:
                - string
                - 'null'
              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
    Obligation_Document:
      description: Documents associated with an obligation.
      properties:
        subtype:
          description: Paperwork subtype
          enum:
          - carrier_misc
          - invoice
          - other
          - proof_of_work
          - purchase_order
          type:
          - string
          - 'null'
        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
          type:
          - string
          - 'null'
        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
    Shipment_details:
      description: Shipment associated with the obligation
      properties:
        destination:
          properties:
            location:
              $ref: '#/components/schemas/Location'
            name:
              description: Location Name
              example: Warehouse
              type: string
          title: Destination location of the shipment
          type: object
        dropoff_date:
          properties:
            actual_date:
              description: Actual date of the action.
              example: '2023-03-21T16:00:00Z'
              format: date-time
              type: string
            target_end_date:
              description: Target end DateTime in ISO Format.
              example: '2023-03-22T16:00:00Z'
              format: date-time
              type: string
            target_start_date:
              description: Target start DateTime in ISO Format.
              example: '2023-03-20T16:00:00Z'
              format: date-time
              type: string
          title: DateTime of the actions
          type: object
        external_resource_id:
          description: Idenifier within an externa

# --- 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