Invite and Pay a Contractor with Wingspan

Welcome to the Wingspan API guide on how to create and pay a contractor. This guide walks you through the steps to invite a contractor to Wingspan and create your first payable. To successfully complete this process, you'll need to:

1. Create a collaborator to represent your contractor in the API
2. Create a payable for that collaborator

Before we begin, let's clarify some key terminology used throughout this guide:

• Collaborator: A collaborator refers to a contractor who can send and/or receive payments.
• Client: The client represents the payer on an invoice and can reference a collaboratorId if the collaborator is the payer.
• Member: The member represents the payee, the person to whom money is to be paid, and can also reference a collaboratorId if the collaborator is the payee.

Before you begin

Before you can create a collaborator payment, ensure that you have completed the following prerequisites:

1. Configured your payroll settings.
2. Set up a payment method.

1. Create a collaborator

In Wingspan, a collaborator represents the relationship between you (the payer or client) and your contractor (the member). To create a collaborator, you only need their email address and to call the /payments/collaborator endpoint. Once you create a collaborator, an invitation will be sent to them to join Wingspan.

API Request:

const options = {
  url: 'https://api.wingspan.app/payments/collaborator',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': `Bearer <Token>`
  },
  params: { 
    'api_token': <token>
  },
  body: {
    'memberEmail': <contractor email>,
    'memberCompany': <optional, company name of contractor>,
    'memberName': <optional>,
    'clientId': <userId of your account>
  }
}

return z.request(options)
  .then((response) => {
    response.throwForStatus();
    const results = response.json;
    return results;
  });

The response will include a Collaborator record. Make sure to persist the collaboratorId in your database as a reference for creating payables for this new collaborator.

{
  "memberId": "Rdyd3jHZHqeCkWyRiHRAM0",
  "clientId": "nQkN_xPGFnHcMw7v4SNW8V",
  "status": "Pending",
  "taxStatus": "Incomplete",
  "collaboratorId": "nwDrUhv_FWTHISr3pTtog0"
}

2. Create a payable to the collaborator

To create a draft payable for the collaborator, make a POST request to the /payments/payable endpoint.

API Request:

const options = {
  url: 'https://api.wingspan.app/payments/payable',
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'accept': 'application/json, text/plain, */*',
    'authorization': `Bearer <token>`
  },
  body: {
    'collaboratorId': <>,
    'dueDate': <ISO 8601 date>,
    'lineItems': [
        {
        "description": "Line Item Title",
        "totalCost": 20.00,
        "reimbursableExpense": false
        }
		],
    'status': 'Draft',
    "creditFeeHandling": { // If the invoice is paid via a credit card, client pays fee.
      "clientPays": 100,
      "memberPays": 0
   },
   "currency": "USD"
  }
}


return z.request(options)
  .then((response) => {
    response.throwForStatus();
    const results = response.json;
    return results;
  });

The API will return a Payable object. Be sure to persist the payableId to track the status of this payable in the future.