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.

Parmeter	Use	Value	Description
`Email`	Required	Defined by you	The email address of the payee.
`Collaborator ID`	Required for existing payees	Alphanumeric ID	Unique identifier representing the collaborator (contractor).
`Amount`	Required	Number and currency. E.g. USD CAD	The monetary amount that is to be paid.
Line Item Title	Required	Defined by you	A descriptive title for the line item.
Due Date	Required	ISO date format	The date that the payment is due.
Reimbursable	Required	Yes \| No	This field indicated whether the payment is reimbursable.
Status	Required	Draft or Open	The 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 Description	Optional	Defined by you	Use this field to add more descriptive information to your Line Items.
Invoice Notes	Optional	Defined by you	Different from Line Item Description, this field is used to include notes to the Payable as a whole.
Attachment ID	Required for attachments	Alphanumeric ID	If 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

Create the Payable by calling POST https://api.wingspan.app/payments/bulk/payable/batch.

Endpoint

POST https://api.wingspan.app/payments/bulk/payable/batch

Headers
- 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.
Payload

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.

Example:
```
--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 'https://api.wingspan.app/payments/bulk/payable/batch' \
--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"
}
```
Response

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 .
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.
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.
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 .
To run payroll immediately, call POST https:// api.wingspan.app/payments/pay-approved.

Endpoint

POST https:// api.wingspan.app/payments/pay-approved

Headers:
- 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.

Response:

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.