Divvy Network API

openapi: 3.2.0
info:
  title: BILL v3 Network API
  description: BILL is a cloud-based financial operations platform for an organization's accounts payable (AP), accounts receivable (AR), and spend & expense (S&E) automation.
  version: '1'
servers:
- url: https://gateway.stage.bill.com/connect
  description: sandbox
tags:
- name: Network
paths:
  /v3/network:
    get:
      tags:
      - Network
      summary: Search for an organization in the BILL Network
      description: 'Search for a customer, vendor, or verified national vendor organization. You can search in the BILL Network and verified national vendor (`RPPS`) network.


        When you search in the BILL Network, there are two `name` requirements for getting search results.

        * Your search term must have a minimum of three characters.

        * Your search term must be a complete word. You will not get search results when your search term is a partial word.


        When you search in the verified national vendor (`RPPS`) network, search results are based on both a complete and partial match on `name` and `zipOrPostalCode`. You can further filter your search by the billing statement `accountNumber` with the vendor. For example, your Verizon internet bill account number.


        See BILL Network in the Guides section for more information, sample requests, and responses.'
      operationId: search
      parameters:
      - name: sessionId
        in: header
        schema:
          type:
          - string
          - 'null'
          description: API session ID generated with `/v3/login`
          example: '{{session_id}}'
      - name: devKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Developer key generated with your BILL developer account
          example: '{{developer_key}}'
      - name: name
        in: query
        required: true
        schema:
          minLength: 1
          type: string
          description: Organization name
          example: '{{network_vendor_name}}'
      - name: scope
        in: query
        schema:
          allOf:
          - $ref: '#/components/schemas/ScopeType'
          - description: 'Network name. You can search in one or both networks.

              * Select `BILL` for BILL Network

              * Select `RPPS` for verified national vendor network

              * Select `ALL` for both networks'
            example: BILL
      - name: zipOrPostalCode
        in: query
        schema:
          type:
          - string
          - 'null'
          description: Organization zip or postal code. When you set this field, BILL searches with `zipOrPostalCode` for all organizations.
      - name: accountNumber
        in: query
        schema:
          type:
          - string
          - 'null'
          description: Your billing statement account number with the verified national vendor (`RPPS`) organization
      responses:
        '200':
          description: Search for an organization in the BILL Network response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkSearchResponseDto'
        4XX:
          description: List of errors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BdcError'
        5XX:
          description: List of errors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BdcError'
  /v3/network/invitation/accept:
    post:
      tags:
      - Network
      summary: Accept connection request
      description: 'Accept a connection request sent by a vendor or customer.


        The organization receiving the connection request must have auto-connections disabled. If auto-connections are not disabled, BILL automatically connects the organizations in the BILL Network.


        When the invitation is accepted, BILL connects the two organizations in the BILL Network.


        See BILL Network in the Guides section for more information, sample requests, and responses.'
      operationId: acceptInvitation
      parameters:
      - name: sessionId
        in: header
        schema:
          type:
          - string
          - 'null'
          description: API session ID generated with `/v3/login`
          example: '{{session_id}}'
      - name: devKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Developer key generated with your BILL developer account
          example: '{{developer_key}}'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptInvitationRequestDto'
        required: true
      responses:
        '200':
          description: Accept connection request response
        4XX:
          description: List of errors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BdcError'
        5XX:
          description: List of errors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BdcError'
  /v3/network/invitation/customer/{customerId}:
    get:
      tags:
      - Network
      summary: Get customer connection request status
      description: 'Get the status of an existing connection request sent with `POST /v3/network/invitation/customer/{customerId}`.


        When you send a connection request to a customer organization that has auto-connections enabled, BILL automatically connects you with the organization. If the organization has auto-connections disabled, the connection request status changes when the customer accepts the request.


        **Note**: If the customer does not respond to the connection request for 60 days, the request expires.


        See BILL Network in the Guides section for more information, sample requests, and responses.'
      operationId: getCustomerInvitation
      parameters:
      - name: sessionId
        in: header
        schema:
          type:
          - string
          - 'null'
          description: API session ID generated with `/v3/login`
          example: '{{session_id}}'
      - name: devKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Developer key generated with your BILL developer account
          example: '{{developer_key}}'
      - name: customerId
        in: path
        required: true
        schema:
          minLength: 1
          type: string
          description: BILL-generated ID of the customer record in your organization. The value begins with `0cu`.
          example: '{{customer_id}}'
      responses:
        '200':
          description: Get customer connection request status response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetInvitationResponseDto'
        4XX:
          description: List of errors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BdcError'
        5XX:
          description: List of errors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BdcError'
    post:
      tags:
      - Network
      summary: Send connection request to a customer
      description: 'Send a connection request to a customer organization in the BILL Network. BILL automatically connects the customer organization with the customer record in your BILL organization.


        If the customer organization has auto-connections disabled, BILL sends an invitation email to the customer email address. When the customer accepts the invitation, BILL connects the customer organization with the customer record in your BILL organization.


        If the customer does not respond, you can delete the connection request (with `DELETE /v3/network/invitation/customer/{customerId}`) before sending a new connection request.


        **Note**: If the customer does not respond to a connection request for 60 days, the request expires.


        See BILL Network in the Guides section for more information, sample requests, and responses.'
      operationId: createCustomerInvitation
      parameters:
      - name: sessionId
        in: header
        schema:
          type:
          - string
          - 'null'
          description: API session ID generated with `/v3/login`
          example: '{{session_id}}'
      - name: devKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Developer key generated with your BILL developer account
          example: '{{developer_key}}'
      - name: customerId
        in: path
        required: true
        schema:
          minLength: 1
          type: string
          description: BILL-generated ID of the customer record in your organization. The value begins with `0cu`.
          example: '{{customer_id}}'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInvitationRequestDto'
        required: true
      responses:
        '200':
          description: Send connection request to a customer response
        4XX:
          description: List of errors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BdcError'
        5XX:
          description: List of errors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BdcError'
    delete:
      tags:
      - Network
      summary: Delete customer connection
      description: 'Delete an existing Network connection with a customer organization. Delete customer connection follows a set of rules.

        * **No scheduled payments**: There should be no scheduled payments. All scheduled payments must be canceled before you can disconnect.

        * **No in-process payments**: There should be no in-progress payments. All in-progress payments must clear before you can disconnect.


        You can use this endpoint to cancel a pending connection request sent to a customer that has auto-connections disabled. You can send a new connection request after an existing connection or connection request is canceled.


        **Note**: If the customer does not respond to a connection request for 60 days, the request expires.


        See BILL Network in the Guides section for more information, sample requests, and responses.'
      operationId: deleteCustomerInvitation
      parameters:
      - name: sessionId
        in: header
        schema:
          type:
          - string
          - 'null'
          description: API session ID generated with `/v3/login`
          example: '{{session_id}}'
      - name: devKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Developer key generated with your BILL developer account
          example: '{{developer_key}}'
      - name: customerId
        in: path
        required: true
        schema:
          minLength: 1
          type: string
          description: BILL-generated ID of the customer record in your organization. The value begins with `0cu`.
          example: '{{customer_id}}'
      responses:
        '200':
          description: Delete customer connection response
        4XX:
          description: List of errors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BdcError'
        5XX:
          description: List of errors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BdcError'
  /v3/network/invitation/vendor/{vendorId}:
    get:
      tags:
      - Network
      summary: Get vendor connection request status
      description: 'Get the status of an existing connection request sent with `POST /v3/network/invitation/vendor/{vendorId}`.


        When you send a connection request to a vendor organization that has auto-connections enabled, BILL automatically connects you with the organization. If the organization has auto-connections disabled, the connection request status changes when the vendor accepts the request.


        **Note**: If the vendor does not respond to the connection request for 60 days, the request expires.


        See BILL Network in the Guides section for more information, sample requests, and responses.'
      operationId: getVendorInvitation
      parameters:
      - name: sessionId
        in: header
        schema:
          type:
          - string
          - 'null'
          description: API session ID generated with `/v3/login`
          example: '{{session_id}}'
      - name: devKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Developer key generated with your BILL developer account
          example: '{{developer_key}}'
      - name: vendorId
        in: path
        required: true
        schema:
          minLength: 1
          type: string
          description: BILL-generated ID of the vendor record in your organization. The value begins with `009`.
          example: '{{vendor_id}}'
      responses:
        '200':
          description: Get vendor connection request status response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetInvitationResponseDto'
        4XX:
          description: List of errors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BdcError'
        5XX:
          description: List of errors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BdcError'
    post:
      tags:
      - Network
      summary: Send connection request to a vendor
      description: 'Send a connection request to a vendor organization in the BILL Network. BILL automatically connects the vendor organization with the vendor record in your BILL organization.


        If the vendor organization has auto-connections disabled, BILL sends an invitation email to the vendor email address. When the vendor accepts the invitation, BILL connects the vendor organization with the vendor record in your BILL organization.


        If the vendor does not respond, you can delete the connection request (with `DELETE /v3/network/invitation/vendor/{vendorId}`) before sending a new connection request.


        **Note**: If the vendor does not respond to the connection request for 60 days, the request expires.


        See BILL Network in the Guides section for more information, sample requests, and responses.'
      operationId: createVendorInvitation
      parameters:
      - name: sessionId
        in: header
        schema:
          type:
          - string
          - 'null'
          description: API session ID generated with `/v3/login`
          example: '{{session_id}}'
      - name: devKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Developer key generated with your BILL developer account
          example: '{{developer_key}}'
      - name: vendorId
        in: path
        required: true
        schema:
          minLength: 1
          type: string
          description: BILL-generated ID of the vendor record in your organization. The value begins with `009`.
          example: '{{vendor_id}}'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInvitationRequestDto'
        required: true
      responses:
        '200':
          description: Send connection request to a vendor response
        4XX:
          description: List of errors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BdcError'
        5XX:
          description: List of errors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BdcError'
    delete:
      tags:
      - Network
      summary: Delete vendor connection
      description: 'Delete an existing Network connection with a vendor organization. Delete vendor connection follows a set of rules.

        * **No scheduled payments**: There should be no scheduled payments. All scheduled payments must be canceled before you can disconnect.

        * **No in-process payments**: There should be no in-progress payments. All in-progress payments must clear before you can disconnect.


        You can use this endpoint to cancel a pending connection request sent to a vendor that has auto-connections disabled. You can send a new connection request after an existing connection or connection request is canceled.


        **Note**: If the vendor does not respond to a connection request for 60 days, the request expires.


        See BILL Network in the Guides section for more information, sample requests, and responses.'
      operationId: deleteVendorInvitation
      parameters:
      - name: sessionId
        in: header
        schema:
          type:
          - string
          - 'null'
          description: API session ID generated with `/v3/login`
          example: '{{session_id}}'
      - name: devKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Developer key generated with your BILL developer account
          example: '{{developer_key}}'
      - name: vendorId
        in: path
        required: true
        schema:
          minLength: 1
          type: string
          description: BILL-generated ID of the vendor record in your organization. The value begins with `009`.
          example: '{{vendor_id}}'
      responses:
        '200':
          description: Delete vendor connection response
        4XX:
          description: List of errors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BdcError'
        5XX:
          description: List of errors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BdcError'
  /v3/network/invitation/vendor/{vendorId}/email:
    post:
      tags:
      - Network
      summary: Send connection request to a vendor not in the BILL Network
      description: 'Send a connection request to a vendor not in the BILL Network.


        BILL sends an invitation email to the provided vendor email address. When the vendor accepts the invitation and sets up a BILL account, BILL connects the vendor organization with the vendor record in your BILL organization.


        **Note**:

        * The vendor organization must exist before BILL can send an invitation email.

        * If the vendor does not respond to a connection request for 60 days, the request expires.


        See BILL Network in the Guides section for more information, sample requests, and responses.'
      operationId: inviteVendorNotInBillNetwork
      parameters:
      - name: sessionId
        in: header
        schema:
          type:
          - string
          - 'null'
          description: API session ID generated with `/v3/login`
          example: '{{session_id}}'
      - name: devKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Developer key generated with your BILL developer account
          example: '{{developer_key}}'
      - name: vendorId
        in: path
        required: true
        schema:
          minLength: 1
          type: string
          description: BILL-generated ID of the vendor record in your organization. The value begins with `009`.
          example: '{{vendor_id}}'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InviteVendorNotInBillNetworkRequestDto'
        required: true
      responses:
        '200':
          description: Send connection request to a vendor not in the BILL Network response
        4XX:
          description: List of errors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BdcError'
        5XX:
          description: List of errors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BdcError'
components:
  schemas:
    Severity:
      type: string
      enum:
      - ERROR
      - WARNING
      - INFORMATION
    Network:
      type: object
      properties:
        id:
          type: string
          description: Payment Network ID (PNI) of the organization. BILL uses the PNI to send and receive electronic payments.
        name:
          type: string
          description: Organization name
        type:
          allOf:
          - $ref: '#/components/schemas/NetworkAccountType'
          - description: Account type.
        addresses:
          type: array
          description: Organization address
          items:
            $ref: '#/components/schemas/AddressDto'
        managedBy:
          allOf:
          - $ref: '#/components/schemas/NetworkManagedBy'
          - description: Search result metadata information
      description: An organization in the BILL network or verified national vendor network.
    NetworkManagedBy:
      type: object
      properties:
        name:
          type: string
          description: Network managed by name
        email:
          type: string
          description: Network managed by email address
        emailDomain:
          type: string
          description: Verified email address domain
      description: Metadata about who manages the network for the organization.
    BdcError:
      required:
      - category
      - code
      - severity
      - timestamp
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        code:
          type: string
        severity:
          $ref: '#/components/schemas/Severity'
        category:
          $ref: '#/components/schemas/Category'
        message:
          type: string
        params:
          type: array
          items:
            $ref: '#/components/schemas/Param'
        detail:
          type: string
        help:
          type: string
    GetInvitationResponseDto:
      type: object
      properties:
        id:
          type: string
          description: BILL-generated ID of the customer or vendor record in your organization
        status:
          allOf:
          - $ref: '#/components/schemas/NetworkInvitationStatus'
          - description: Network invitation status.
        networkId:
          type: string
          description: Payment Network ID (PNI). BILL uses the PNI to send and receive electronic payments.
      description: Invitation status response.
    Param:
      required:
      - name
      - value
      type: object
      properties:
        additional:
          type: object
          additionalProperties:
            type: string
        name:
          minLength: 1
          type: string
        value:
          minLength: 1
          type: string
    AcceptInvitationRequestDto:
      required:
      - networkId
      - type
      type: object
      properties:
        networkId:
          minLength: 1
          type: string
          description: Payment Network ID (PNI) of the customer or vendor that sent the invitation. BILL uses the PNI to send and receive electronic payments.
        type:
          allOf:
          - $ref: '#/components/schemas/AcceptInviteType'
          - description: 'Type of organization that sent the invitation.

              * Select `VENDOR` to accept a connection request from a vendor

              * Select `CUSTOMER` to accept a connection request from a customer'
        id:
          type:
          - string
          - 'null'
          description: 'BILL-generated ID of the existing vendor or customer record in your organization that you want to connect with. The value begins with `009` (vendor) or `0cu` (customer).


            When you set this field, you cannot set `name` in your request.'
        name:
          type:
          - string
          - 'null'
          description: 'Name of the new vendor or customer record that you want to add in your organization. BILL creates a new record with this name.


            When you set this field, you cannot set `id` in your request.'
      description: Accept network invitation
      example: "{\n  \"networkId\": \"{{network_id}}\",\n  \"type\": \"CUSTOMER\",\n  \"id\": {{customer_id}}\n}"
    AcceptInviteType:
      type: string
      description: Enum for different types of organizations in BILL network.
      enum:
      - VENDOR
      - CUSTOMER
    InviteVendorNotInBillNetworkRequestDto:
      required:
      - email
      type: object
      properties:
        email:
          minLength: 1
          type: string
          description: Vendor email address
      description: Invite a vendor not in BILL network
      example:
        email: '{{vendor_email}}'
    AddressDto:
      type: object
      properties:
        line1:
          type: string
          description: Address line 1
        line2:
          type: string
          description: Address line 2
        city:
          type: string
          description: City
        stateOrProvince:
          type: string
          description: State or province
        zipOrPostalCode:
          type: string
          description: Zip or postal code
        country:
          type: string
          description: Country
      description: Address information.
    NetworkAccountType:
      type: string
      description: Enum for different types of accounts in BILL network.
      enum:
      - ADVANCED
      - BUSINESS
      - RPPS
      - CONTRACTOR
      - EMPLOYEE_OR_INDIVIDUAL
      - UNDEFINED
    NetworkInvitationStatus:
      type: string
      description: Status of the invitation from customer/vendor to an organization.
      enum:
      - NOT_CONNECTED
      - PENDING
      - CONNECTED
      - CONNECTED_RPPS
    NetworkSearchResponseDto:
      type: object
      properties:
        results:
          type: array
          description: Results that match the search criteria
          items:
            $ref: '#/components/schemas/Network'
      description: Network search response.
    Category:
      type: string
      enum:
      - REQUEST
      - APPLICATION
      - SERVER
      - DOWNSTREAM
    ScopeType:
      type: string
      description: 'Network name. You can search in one or both networks.

        * Select `BILL` for BILL Network

        * Select `RPPS` for verified national vendor network

        * Select `ALL` for both networks'
      example: BILL
      enum:
      - BILL
      - RPPS
      - ALL
    CreateInvitationRequestDto:
      required:
      - networkId
      - networkType
      type: object
      properties:
        networkId:
          minLength: 1
          type: string
          description: 'Payment Network ID (PNI) of the organization you want to connect with. For a verified national vendor, the value begins with `0rv`. BILL uses the PNI to send and receive electronic payments.


            You can retrieve `networkId` from your `GET /v3/network` search result.'
        networkType:
          allOf:
          - $ref: '#/components/schemas/NetworkType'
          - description: 'Network type.

              * Select `BILL` for BILL Network

              * Select `RPPS` for verified national vendor network'
        rppsInformation:
          allOf:
          - $ref: '#/components/schemas/RppsInformation'
          - description: Additional information required if `networkType` is `RPPS`
      description: Create an organization in the BILL network
      example:
        networkId: '{{network_id}}'
        networkType: BILL
    NetworkType:
      type: string
      description: Enum for different types of network.
      enum:
      - BILL
      - RPPS
    RppsInformation:
      required:
      - accountNumber
      type: object
      properties:
        accountNumber:
          minLength: 1
          type: string
          description: 'Your billing statement account number with the verified national vendor organization.


            This value must match the vendor `accountNumber` set while creating or updating a vendor.'
        addressId:
          type: string
          description: BILL-generated ID of the billing address for the verified national vendor organization. The value begins with `0ra`. Each address is identified by a unique ID.
      description: Dto for additional information needed when sending invite to organization in Rpps network.
x-provenance:
  method: searched
  source: https://developer.bill.com/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://developer.bill.com/reference/acceptinvitation.md
  - https://developer.bill.com/reference/addreimbursementreceipt.md
  - https://developer.bill.com/reference/addtransactionreceipt.md
  - https://developer.bill.com/reference/approveordenyreimbursement.md
  - https://developer.bill.com/reference/archivebankaccount.md
  - https://developer.bill.com/reference/archivebankaccountuser.md
  - https://developer.bill.com/reference/archivebill.md
  - https://developer.bill.com/reference/archiveclassificationaccountingclass.md
  - https://developer.bill.com/reference/archiveclassificationchartofaccounts.md
  - https://developer.bill.com/reference/archiveclassificationdepartment.md
  - https://developer.bill.com/reference/archiveclassificationemployee.md
  - https://developer.bill.com/reference/archiveclassificationitem.md
  - https://developer.bill.com/reference/archiveclassificationjob.md
  - https://developer.bill.com/reference/archiveclassificationlocation.md
  - https://developer.bill.com/reference/archivecreditmemo.md
  - https://developer.bill.com/reference/archivecustomer.md
  - https://developer.bill.com/reference/archivecustomerbankaccount.md
  - https://developer.bill.com/reference/archivecustomercontact.md
  - https://developer.bill.com/reference/archiveinvoice.md
  - https://developer.bill.com/reference/archiveorganizationuser.md
  - https://developer.bill.com/reference/archivepartneruser.md
  - https://developer.bill.com/reference/archiverecurringbill.md
  - https://developer.bill.com/reference/archiverecurringinvoice.md
  - https://developer.bill.com/reference/archivevendor.md
  - https://developer.bill.com/reference/archivevendorcredit.md
  - https://developer.bill.com/reference/authorizetochargecustomer.md
  - https://developer.bill.com/reference/billapprovedenyactions.md
  - https://developer.bill.com/reference/bulkarchiveclassificationaccountingclass.md
  - https://developer.bill.com/reference/bulkarchiveclassificationchartofaccounts.md
  - https://developer.bill.com/reference/bulkarchiveclassificationdepartment.md
  - https://developer.bill.com/reference/bulkarchiveclassificationemployee.md
  - https://developer.bill.com/reference/bulkarchiveclassificationitem.md


# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/divvy/refs/heads/main/openapi/divvy-network-api-openapi.yml