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 Payees 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 payee is your contractor or carrier. They are the entity that needs to be paid for services. Payees are a type of Company in our ecosystem and are associated to our shared client through Client-Payee Relationships.
  externalDocs:
    description: 'Guides: Companies'
    url: https://help.denim.com/hc/en-us/articles/9403899854107-4-Mapping-and-Syncing-Companies
  name: Payees
paths:
  /api/v1/payee-relationships:
    get:
      callbacks: {}
      description: This retrieves the payees 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.ClientPayeeRelationshipController.index (2)
      parameters:
      - description: Search string for payee company name or MC Number.
        example: Best Carrier LLC
        in: query
        name: query
        required: false
        schema:
          type: string
      - description: "Payee Relationship Filters.\n\n- status\n- days to pay offset\n- quick pay rate\n    - Note: `quick_pay_rate` is in basis points (ex: 100 bps == %1.00)\",\n"
        example:
          days_to_pay_offset: 5
          quick_pay_rate: 100
          status: pending
        in: query
        name: filters
        required: false
        schema:
          description: Available filters for fetching Payees
          example:
            status: pending
          properties:
            days_to_pay_offset:
              description: Payee relationship days to pay offset
              type: integer
            has_elected_payment_terms:
              description: Filter by whether the payee has elected payment terms
              type: boolean
            quick_pay_rate:
              description: 'Payee relationship quick pay rate, stored in basis points (ex: 100 bps == %1.00)'
              type: integer
            status:
              description: Payee relationship status
              enum:
              - pending
              - approved
              - rejected
              type: string
          title: Payee Relationship Filters
          type: object
      - description: Filter for payee payment setting types
        in: query
        name: payment_types_filter
        required: false
        schema:
          items:
            enum:
            - ach
            - check
            - missing
            type: string
          type: array
      - 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/Payee Index Response'
          description: Payee relationship response
      security:
      - api_key: []
      summary: List Client-Payee Relationships
      tags:
      - Payees
    post:
      callbacks: {}
      description: 'Creates a Client-Payee Relationship. Read the guide below for details. There are several different ways to create payees, whether it includes a factor assignment, etc. Important note: all factor assignments or updates create ''Requests'' in our Request Center and these are all reviewed and approved by our operations team before becoming effective. This review is to ensure the proper payees receive payments and don''t impact other payee setups.

        '
      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.ClientPayeeRelationshipController.create (2)
      parameters: []
      requestBody:
        content:
          application/json:
            examples:
              add_new_payee_example_without_factor:
                description: Invite a new payee (without a factor)
                summary: Add a new payee without a factor
                value:
                  client_payee_relationship:
                    contact_email: tom@tomslogistics.com
                    contact_first_name: Tom
                    contact_last_name: Brogan
                    contact_phone_number: 1 123 123 3434
                    days_to_pay_offset: 4
                  company:
                    city: New York
                    company_name: New Carrier LLC
                    country: USA
                    ein: '123456789'
                    mc_number: '12345678'
                    state: NY
                    website: www.newcompany.com
              add_new_payee_with_factor_example:
                description: Invite a new payee with a factor
                summary: Add a new payee with a pre-existing factor
                value:
                  company:
                    city: New York
                    company_name: New Carrrier LLC
                    country: USA
                    ein: '123456789'
                    mc_number: '12345678'
                    state: NY
                    website: www.newcompany.com
                  payee:
                    days_to_pay_offset: 3
                    factor_company_id: 34
              add_new_payee_with_new_factor_example:
                description: Invite a new payee with a new factor not in the system
                summary: Add a new payee with a new factor
                value:
                  company:
                    city: New York
                    company_name: New Carrrier LLC
                    country: USA
                    ein: '123456789'
                    mc_number: '12345678'
                    state: NY
                    website: www.newcompany.com
                  payee:
                    days_to_pay_offset: 3
                    factor_company_id: 0
              existing_payee_example_without_factor:
                description: Add a relationship with an existing payee direct (without a factor)
                summary: Link existing payee without a factor
                value:
                  client_payee_relationship:
                    contact_email: tom@tomslogistics.com
                    contact_first_name: Tom
                    contact_last_name: Brogan
                    contact_phone_number: 1 123 123 3434
                    days_to_pay_offset: 4
                  company_id: 123
              existing_payee_with_factor_example:
                description: Add a relationship with an existing payee with factoring relationship already setup
                summary: Link existing payee with a pre-existing factor relationship
                value:
                  company_id: 123
              existing_payee_with_new_factor_example:
                description: Add a relationship with an existing payee and set a new factor not in the system. New factor requests are reviewed by our operations team.
                summary: Link existing payee and set a new factor
                value:
                  company_id: 123
                  payee:
                    days_to_pay_offset: 4
                    factor_company_id: 0
            schema:
              $ref: '#/components/schemas/Payee Create'
        description: Creating a payee relationship params
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payee Create Response'
          description: Payee relationship created response
      security:
      - api_key: []
      summary: Create a Client-Payee Relationship
      tags:
      - Payees
  /api/v1/payee-relationships/{client_payee_relationship_id}/update-assign-factor:
    post:
      callbacks: {}
      description: Creates a request to change the factor assigned to the payee. These changes are reviewed by our operations team and the original factor will still be referenced until this request is reviewed and approved.
      operationId: AxlePayWeb.Api.V1.ClientPayeeRelationshipController.update_assign_factor (2)
      parameters:
      - description: client_payee_relationship_id
        example: 543
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            examples:
              update_with_existing_factor_example:
                description: Assign an existing factor to an existing payee relationship
                summary: Update with existing assigned factor
                value:
                  payee:
                    factor_company_id: 34
              update_with_new_factor_example:
                description: Assign a new factor to an existing payee relationship
                summary: Update with new assigned factor
                value:
                  payee:
                    factor_company_id: 0
            schema:
              $ref: '#/components/schemas/Update or set assigned factor on an existing payee relationship'
        description: Update or set the assigned factor on an existing payee relationship
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payee Create Response'
          description: Update payee relationship assigned factor
      security:
      - api_key: []
      summary: Update a payee's assigned factor
      tags:
      - Payees
components:
  schemas:
    Update or set assigned factor on an existing payee relationship:
      description: Allows setting or changing the assigned factor on an existing payee relationship.
      example:
        payee:
          factor_company_id: 34
      properties:
        payee:
          $ref: '#/components/schemas/Payee Factor Company'
      required:
      - payee
      title: Update or set assigned factor on an existing payee relationship
      type: object
    Payee Index Response:
      description: Response schema for fetching payee relationships
      example:
        data:
        - client_payee_relationship:
            contact_email: tsmith@gmail.com
            contact_first_name: Thomas
            contact_last_name: Smith
            contact_phone_number: +1 (234) 234 - 5344
            id: 74
            payment_setting:
              account_name: Joe's Factoring LLC
              account_number: X8508
              address_line_1: null
              address_line_2: null
              city: null
              country: null
              method: ach
              state: null
              to_factor: true
              zip_code: null
            status: pending
          company:
            city: Atlanta
            company_name: Best Trucking Company
            ein: '123456789'
            id: 35
            mc_number: '12345678'
            state: GA
            status: active
            website: www.besttrucking.com
          payee:
            factor_company_name: Joe's Factoring LLC
            id: 25
        - client_payee_relationship:
            contact_email: boydj@gmail.com
            contact_first_name: Boyd
            contact_last_name: Johnson
            contact_phone_number: +1 (675) 544 - 8526
            id: 544
            payment_setting:
              account_name: Boyds Logistics
              account_number: X8534
              address_line_1: null
              address_line_2: null
              city: null
              country: null
              method: ach
              state: null
              to_factor: false
              zip_code: null
            status: pending
          company:
            city: Chicago
            company_name: Boyds Logistics
            ein: '123456789'
            id: 35
            mc_number: '12345678'
            state: IL
            status: active
            website: null
          payee:
            factor_company_name: ''
            id: 99
        page: 1
        per_page: 2
        total_pages: 3
        total_results: 2
      properties:
        data:
          items:
            properties:
              client_payee_relationship:
                $ref: '#/components/schemas/Client-Payee Relationship'
              company:
                $ref: '#/components/schemas/Payee Company'
              payee:
                $ref: '#/components/schemas/Payee'
            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: Payee Index Response
      type: object
    Payee Create Response:
      description: Response schema for creating a new payee relationship
      example:
        data:
          client_payee_relationship:
            contact_email: boydj@gmail.com
            contact_first_name: Boyd
            contact_last_name: Johnson
            contact_phone_number: +1 (675) 544 - 8526
            id: 544
            payment_setting: null
            status: pending
          company:
            city: New York
            company_name: Best Trucking Company
            ein: '123456789'
            id: 74
            mc_number: '12345678'
            progress: initial
            state: NY
            status: under_review
            website: www.besttrucking.com
          payee:
            factor_company_name: ''
            id: 25
      properties:
        data:
          properties:
            client_payee_relationship:
              $ref: '#/components/schemas/Client-Payee Relationship'
            company:
              $ref: '#/components/schemas/Payee Company'
            payee:
              $ref: '#/components/schemas/Payee'
          type: object
      title: Payee Create Response
      type: object
    Client-Payee Relationship:
      description: Included only if there is an existing non-deleted Client-Payee Relationship for the requesting client.
      properties:
        contact_email:
          description: Contact email at the payee company.
          type: string
        days_to_pay_offset:
          description: Per-relationship offset (in days) added to the payee's standard pay terms.
          nullable: true
          type: integer
        id:
          description: usable as `client_payee_relationship_id`
          type: integer
      title: Client-Payee Relationship
      type: object
    Payee:
      description: Payee Company Information
      properties:
        factor_company_name:
          description: Name of the payee's factoring company, if they have one
          type: string
        id:
          description: Payee ID
          type: integer
      title: Payee
      type: object
    Payee Create:
      description: Use the company search API to find an existing company or send the `company` parameters to create a new company. Either 'payee' (when the payee has factor) or 'client_payee_relationship' (no factor) required when creating payee relationship.
      example:
        client_payee_relationship:
          contact_email: tom@tomslogistics.com
          contact_first_name: Tom
          contact_last_name: Brogan
          contact_phone_number: '11231233434'
          payment_setting:
            account_name: New Customer LLC
            account_number: X8508
            address_line_1: null
            address_line_2: null
            city: null
            country: null
            method: ach
            state: null
            to_factor: false
            zip_code: null
        company:
          city: New York
          company_name: New Customer LLC
          ein: '123456789'
          mc_number: null
          state: NY
          website: www.newcompany.com
      properties:
        client_payee_relationship:
          $ref: '#/components/schemas/Client-Payee Relationship'
        company:
          $ref: '#/components/schemas/Payee Company'
        company_id:
          description: Company ID. Either 'company_id' (existing company) or 'company' (new company) required when creating payee relationship.
          type: integer
        payee:
          $ref: '#/components/schemas/Payee Factor Company'
      title: Payee Create
      type: object
    Payee Factor Company:
      description: Set the assigned factor for the payee.
      properties:
        factor_company_id:
          description: Factor company ID. Can be found using the Search Companies endpoint or use '0' for new a factor.
          type: integer
      title: Payee Factor Company
      type: object
    Payee Company:
      description: A payee company
      properties:
        city:
          description: City
          type: string
        company_name:
          description: Payee company name
          type: string
        country:
          default: USA
          description: Country (3 Character Abbreviation)
          enum:
          - USA
          - CAN
          type: string
        ein:
          description: Federal EIN / Tax ID (9 digits)
          nullable: true
          type: string
        id:
          description: Company ID
          type: integer
        mc_number:
          description: FMCSA Motor Carrier Number (6-8 digits)
          nullable: true
          type: string
        progess:
          description: Payee setup progress
          enum:
          - initial
          - setup_started
          - onboarding_started
          - done
          type: string
        state:
          description: State (2 Character Abbreviation)
          type: string
        status:
          description: Payee status
          enum:
          - under_review
          - active
          type: string
      required:
      - company_name
      title: Payee 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