openapi: 3.0.1
info:
  title: Routable API
  description: >-
    Specification of the Routable v1 REST API for B2B payments, accounts payable
    and receivable automation, and mass payouts. Manage vendor and customer
    companies, contacts, payment methods, funding accounts, payables,
    receivables, and webhook events. All requests are JSON over HTTPS and
    authenticated with a Bearer API token.
  termsOfService: https://www.routable.com/terms-of-service/
  contact:
    name: Routable Support
    url: https://developers.routable.com/docs
  version: '1.0'
servers:
  - url: https://api.routable.com/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Companies
    description: Vendor and customer companies.
  - name: Contacts
    description: Contacts associated with companies.
  - name: Payment Methods
    description: Bank, international, and check payment methods.
  - name: Funding Sources
    description: Funding accounts and the Routable Balance.
  - name: Payables
    description: Bills owed to vendors.
  - name: Receivables
    description: Amounts owed to you by customers.
  - name: Webhooks
    description: Webhook events.
paths:
  /companies:
    get:
      operationId: listCompanies
      tags:
        - Companies
      summary: List companies
      description: Returns a paginated list of vendor and customer companies.
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A list of companies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyList'
    post:
      operationId: createCompany
      tags:
        - Companies
      summary: Create a company
      description: Creates a new vendor or customer company.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyCreate'
      responses:
        '201':
          description: The created company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
  /companies/{id}:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    get:
      operationId: retrieveCompany
      tags:
        - Companies
      summary: Retrieve a company
      responses:
        '200':
          description: The requested company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
    patch:
      operationId: updateCompany
      tags:
        - Companies
      summary: Update a company
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyUpdate'
      responses:
        '200':
          description: The updated company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
  /companies/{id}/archive:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    post:
      operationId: archiveCompany
      tags:
        - Companies
      summary: Archive a company
      responses:
        '200':
          description: The archived company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
  /companies/{id}/unarchive:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    post:
      operationId: unarchiveCompany
      tags:
        - Companies
      summary: Unarchive a company
      responses:
        '200':
          description: The unarchived company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
  /companies/{id}/invite:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    post:
      operationId: inviteCompany
      tags:
        - Companies
      summary: Invite a company
      description: Sends or re-sends an invitation for the company to provide payment information.
      responses:
        '200':
          description: The invited company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
  /contacts:
    get:
      operationId: listContacts
      tags:
        - Contacts
      summary: List contacts
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A list of contacts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
    post:
      operationId: createContact
      tags:
        - Contacts
      summary: Create a contact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCreate'
      responses:
        '201':
          description: The created contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
  /contacts/{id}:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    get:
      operationId: retrieveContact
      tags:
        - Contacts
      summary: Retrieve a contact
      responses:
        '200':
          description: The requested contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
    patch:
      operationId: updateContact
      tags:
        - Contacts
      summary: Update a contact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCreate'
      responses:
        '200':
          description: The updated contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
  /payment_methods:
    get:
      operationId: listPaymentMethods
      tags:
        - Payment Methods
      summary: List payment methods
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A list of payment methods.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethodList'
    post:
      operationId: createPaymentMethod
      tags:
        - Payment Methods
      summary: Create a payment method
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentMethodCreate'
      responses:
        '201':
          description: The created payment method.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethod'
  /payment_methods/{id}:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    get:
      operationId: retrievePaymentMethod
      tags:
        - Payment Methods
      summary: Retrieve a payment method
      responses:
        '200':
          description: The requested payment method.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethod'
    patch:
      operationId: updatePaymentMethod
      tags:
        - Payment Methods
      summary: Update a payment method
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentMethodCreate'
      responses:
        '200':
          description: The updated payment method.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethod'
  /payment_methods/validate:
    post:
      operationId: validatePaymentMethod
      tags:
        - Payment Methods
      summary: Validate a payment method
      description: Validates bank or international payment details before creating a payment method.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentMethodCreate'
      responses:
        '200':
          description: Validation result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
  /settings/accounts:
    get:
      operationId: listAccounts
      tags:
        - Funding Sources
      summary: List funding accounts
      responses:
        '200':
          description: A list of funding accounts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundingAccountList'
  /settings/accounts/{id}:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    get:
      operationId: retrieveAccount
      tags:
        - Funding Sources
      summary: Retrieve a funding account
      responses:
        '200':
          description: The requested funding account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundingAccount'
  /settings/accounts/balance:
    get:
      operationId: retrieveBalanceAccount
      tags:
        - Funding Sources
      summary: Retrieve the Routable Balance account
      responses:
        '200':
          description: The Routable Balance account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundingAccount'
  /settings/accounts/{id}/deposit:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    post:
      operationId: depositFunds
      tags:
        - Funding Sources
      summary: Deposit funds into Routable Balance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
              properties:
                amount:
                  type: string
                  description: Amount to deposit, as a decimal string.
      responses:
        '200':
          description: The updated funding account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundingAccount'
  /payables:
    get:
      operationId: listPayables
      tags:
        - Payables
      summary: List payables
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A list of payables.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayableList'
    post:
      operationId: createPayable
      tags:
        - Payables
      summary: Create a payable
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayableCreate'
      responses:
        '201':
          description: The created payable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payable'
  /payables/{id}:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    get:
      operationId: retrievePayable
      tags:
        - Payables
      summary: Retrieve a payable
      responses:
        '200':
          description: The requested payable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payable'
    patch:
      operationId: updatePayable
      tags:
        - Payables
      summary: Update a payable
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayableCreate'
      responses:
        '200':
          description: The updated payable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payable'
  /payables/{id}/cancel:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    post:
      operationId: cancelPayable
      tags:
        - Payables
      summary: Cancel a payable
      responses:
        '200':
          description: The cancelled payable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payable'
  /payables/{id}/remind:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    post:
      operationId: remindPayable
      tags:
        - Payables
      summary: Send a payable reminder
      responses:
        '200':
          description: Reminder sent.
  /payables/{id}/estimate:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    post:
      operationId: estimatePayableFees
      tags:
        - Payables
      summary: Estimate fees for a payable
      responses:
        '200':
          description: Fee estimate.
          content:
            application/json:
              schema:
                type: object
                properties:
                  fee:
                    type: string
                  total:
                    type: string
                  currency:
                    type: string
  /payables/{id}/confirmation:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    get:
      operationId: downloadPayableConfirmation
      tags:
        - Payables
      summary: Download confirmation PDF
      responses:
        '200':
          description: Confirmation PDF.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
  /receivables:
    get:
      operationId: listReceivables
      tags:
        - Receivables
      summary: List receivables
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A list of receivables.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceivableList'
    post:
      operationId: createReceivable
      tags:
        - Receivables
      summary: Create a receivable
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceivableCreate'
      responses:
        '201':
          description: The created receivable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receivable'
  /receivables/{id}:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    get:
      operationId: retrieveReceivable
      tags:
        - Receivables
      summary: Retrieve a receivable
      responses:
        '200':
          description: The requested receivable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receivable'
    patch:
      operationId: updateReceivable
      tags:
        - Receivables
      summary: Update a receivable
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceivableCreate'
      responses:
        '200':
          description: The updated receivable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receivable'
  /receivables/{id}/cancel:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    post:
      operationId: cancelReceivable
      tags:
        - Receivables
      summary: Cancel a receivable
      responses:
        '200':
          description: The cancelled receivable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receivable'
  /receivables/{id}/remind:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    post:
      operationId: remindReceivable
      tags:
        - Receivables
      summary: Send a receivable reminder
      responses:
        '200':
          description: Reminder sent.
  /webhook_events:
    get:
      operationId: listWebhookEvents
      tags:
        - Webhooks
      summary: List webhook events
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A list of webhook events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEventList'
  /webhook_events/{id}:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    get:
      operationId: retrieveWebhookEvent
      tags:
        - Webhooks
      summary: Retrieve a webhook event
      responses:
        '200':
          description: The requested webhook event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEvent'
  /webhook_events/{id}/retry:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    post:
      operationId: retryWebhookEvent
      tags:
        - Webhooks
      summary: Retry a webhook event
      responses:
        '200':
          description: The retried webhook event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEvent'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API token presented as `Authorization: Bearer {your_token}`. Generate
        tokens in the Routable dashboard. A sandbox environment is available for
        testing without moving real money.
  parameters:
    IdPath:
      name: id
      in: path
      required: true
      description: The unique identifier of the resource.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum number of records to return per page.
      schema:
        type: integer
        default: 25
    StartingAfter:
      name: starting_after
      in: query
      required: false
      description: Cursor for pagination; the id of the last record on the previous page.
      schema:
        type: string
  schemas:
    Pagination:
      type: object
      properties:
        count:
          type: integer
        next:
          type: string
          nullable: true
        previous:
          type: string
          nullable: true
    Company:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          description: Whether the company is a vendor, customer, or both.
          enum:
            - vendor
            - customer
            - both
        status:
          type: string
          description: Onboarding status of the company.
          enum:
            - pending
            - invited
            - accepted
            - archived
        email:
          type: string
          format: email
        is_archived:
          type: boolean
        date_created:
          type: string
          format: date-time
        date_modified:
          type: string
          format: date-time
    CompanyCreate:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
        type:
          type: string
          enum:
            - vendor
            - customer
            - both
        email:
          type: string
          format: email
    CompanyUpdate:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
    CompanyList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Company'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Contact:
      type: object
      properties:
        id:
          type: string
        company:
          type: string
          description: The id of the company this contact belongs to.
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        date_created:
          type: string
          format: date-time
    ContactCreate:
      type: object
      required:
        - company
        - email
      properties:
        company:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
    ContactList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        pagination:
          $ref: '#/components/schemas/Pagination'
    PaymentMethod:
      type: object
      properties:
        id:
          type: string
        company:
          type: string
        type:
          type: string
          description: The kind of payment method.
          enum:
            - bank
            - international
            - check
            - address
        status:
          type: string
        is_archived:
          type: boolean
        date_created:
          type: string
          format: date-time
    PaymentMethodCreate:
      type: object
      required:
        - company
        - type
      properties:
        company:
          type: string
        type:
          type: string
          enum:
            - bank
            - international
            - check
            - address
        account_number:
          type: string
        routing_number:
          type: string
        account_type:
          type: string
          enum:
            - checking
            - savings
    PaymentMethodList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethod'
        pagination:
          $ref: '#/components/schemas/Pagination'
    FundingAccount:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          description: The kind of funding account (e.g., bank or balance).
        balance:
          type: string
          description: Available balance as a decimal string, when applicable.
        currency:
          type: string
        date_created:
          type: string
          format: date-time
    FundingAccountList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FundingAccount'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Payable:
      type: object
      properties:
        id:
          type: string
        company:
          type: string
          description: The vendor company being paid.
        status:
          type: string
          enum:
            - new
            - scheduled
            - processing
            - completed
            - cancelled
            - failed
        amount:
          type: string
        currency:
          type: string
        reference_code:
          type: string
        due_date:
          type: string
          format: date
        date_created:
          type: string
          format: date-time
    PayableCreate:
      type: object
      required:
        - company
        - amount
      properties:
        company:
          type: string
        amount:
          type: string
        currency:
          type: string
          default: USD
        reference_code:
          type: string
        due_date:
          type: string
          format: date
        funding_account:
          type: string
          description: The funding account id used to source the payment.
    PayableList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Payable'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Receivable:
      type: object
      properties:
        id:
          type: string
        company:
          type: string
          description: The customer company being billed.
        status:
          type: string
          enum:
            - new
            - sent
            - processing
            - completed
            - cancelled
            - failed
        amount:
          type: string
        currency:
          type: string
        reference_code:
          type: string
        due_date:
          type: string
          format: date
        date_created:
          type: string
          format: date-time
    ReceivableCreate:
      type: object
      required:
        - company
        - amount
      properties:
        company:
          type: string
        amount:
          type: string
        currency:
          type: string
          default: USD
        reference_code:
          type: string
        due_date:
          type: string
          format: date
    ReceivableList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Receivable'
        pagination:
          $ref: '#/components/schemas/Pagination'
    WebhookEvent:
      type: object
      properties:
        id:
          type: string
        event_type:
          type: string
          description: The type of event, e.g. payable.completed or company.accepted.
        status:
          type: string
          enum:
            - pending
            - delivered
            - failed
        payload:
          type: object
          additionalProperties: true
        date_created:
          type: string
          format: date-time
    WebhookEventList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEvent'
        pagination:
          $ref: '#/components/schemas/Pagination'