Create and process a bulk Payable

The Wingspan Bulk Invoice Creation API allows you to create multiple invoices at once, enabling seamless bulk payments to payees, such as a contractor. The process requires a CSV file containing all the necessary payment details, and depending on the specified processing strategy, the system generates either individual invoices for each payee or consolidate multiple line items into a single invoice.

Before you begin

Determine which processing strategy is right for your project:

  • Single Processing Strategy: Creates individual invoices for each row in the CSV file, ensuring distinct payables with only one line item per invoice, without any consolidation.
  • Merge Processing Strategy: Consolidates multiple payable line items with matching attributes (like due date, status, and merge key) into one invoice, ideal for cases with items sharing similar characteristics, such as paying a firm for multiple contractors' work.

Ensure that your CSV file has all of the required parameters for each row. Keep in mind that each row represents a Payable. You can download an example CSV file here or in the application.

EmailRequiredDefined by youThe email address of the payee.
Collaborator IDRequired for existing payeesAlphanumeric IDUnique identifier representing the collaborator (contractor).
AmountRequiredNumber and currency.
The monetary amount that is to be paid.
Line Item TitleRequiredDefined by youA descriptive title for the line item.
Due DateRequiredISO date formatThe date that the payment is due.
ReimbursableRequiredYes | NoThis field indicated whether the payment is reimbursable.
StatusRequiredDraft or OpenThe status of the payable. Set this to Draft if the Payable needs to be Approved before being sent to general payroll. Set this to Open to Approve immediately.
Line Item DescriptionOptionalDefined by youUse this field to add more descriptive information to your Line Items.
Invoice NotesOptionalDefined by youDifferent from Line Item Description, this field is used to include notes to the Payable as a whole.
Attachment IDRequired for attachmentsAlphanumeric IDIf you need to attach a file to your Payable, such as a receipt, you can do so by indicating the file's Attachment ID in this field.

To create the bulk Payable invoice

  1. Create the Payable by calling POST




    • Content-Type: text/csv: This header indicates that the request body contains a CSV file.
    • Accept: application/json: This header signals that the API response should be in JSON format.
    • Authorization: Bearer <Your_Access_Token>: This header is required for authentication. Replace <Your_Access_Token> with your actual access token.

    Request Body

    • processingStrategy: This can be either Single or Merge.
      • Single: An invoice will be created for each contractor.
      • Merge: Multiple line items are consolidated into a single invoice.


    The API requires a CSV file containing payment details for contractors. The CSV file should be attached to the request using the --data-binary option.


    --data-binary '@path/to/your/file.csv'

    Replace @path/to/your/file.csv with the path to your CSV file.

    Curl Command Example

    curl --location --request POST '' \
    --header 'Content-Type: text/csv' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer YOUR_FULL_ACCESS_TOKEN' \
    --data-binary '@path/to/your/file.csv'
      "processingStrategy": "Single"


    The API returns a JSON response indicating the success or failure of the bulk payable creation process. If successful, it will provide details of the created invoices. If successful, the status of the invoice should be Draft or Open, depending on your payroll settings. For more information about the Payable statuses, see .

  2. Troubleshooting

    Make sure that:

    • The CSV file is correctly formatted and contains all necessary information.
    • The Content-Type and Accept headers are set as described above.
    • The Authorization header contains a valid token.
    • The processing strategy is correctly set to either Single or Merge.
    • For further assistance or queries, reach out to the Wingspan API support team.
  3. If you have configured your payroll settings to require a single or multi-step Approval process, then the Payable must be Approved by a representative from your organization before it is entered into the pool for your next payroll run.

    You must use the tools in the application to approve payables. To approve Payables in the Wingspan application, go to Payables and select the To approve tab. Otherwise, if you set the status to Open, the Payables are pre-approved.

  4. After all necessary Payables are approved, you can initiate a payroll run immediately or allow the approved Payables to run during your regularly scheduled runs. For more information on payroll settings, see .

  5. To run payroll immediately, call POST https://


    POST https://


    • accept: application/json: Specifies the format of the response data.
    • content-type: application/json: Indicates the media type of the resource/data.
    • Authorization: Bearer <Your_Access_Token>: This header is required for authentication. Replace <Your_Access_Token> with your actual access token.

    Request Body Parameters:

    There are no body parameters for this call.


    A successful request will return an appropriate success status code (e.g., 201 Created or 200 OK) along with a JSON response containing details of the Payroll Run.

    Your payroll run is now complete and funds are transferred from your payroll funding account to your payees. You can review your payment history on the Payments page in the Wingspan application.