Onboarding Your Vendors

Creating Companies in the Routable ecosystem is a prerequisite to paying them

Collecting Vendor Information

To onboard vendors to Routable, you’ll start by creating a Company. You can do this using the Create a Company endpoint. Companies can be defined as either a business (which requires a legal entity like an LLC or C Corporation) or an individual (for freelancers).

📘

Reminder

Companies can be Vendors (you pay them), Customers (they pay you), or both. For this example, we'll focus on creating Vendors.

When working with individuals (e.g. contractors or freelancers), creating a company can be as simple as collecting their first name, last name and email address. We call these personal Companies. When working with businesses (e.g. LLCs or C Corporations), we'll be collecting this information for at least one contact at the company as well, but you will also need to collect their legal business name. Our system refers to these vendors as business companies.

Because of this difference in data collection requirements, we recommend building a screen like the following into your user interface and asking your end users to help you fill in some of this data rather than guessing.

2560

A simple company collection form

Where this lives in your user’s journey is totally up to you! We’ve seen some partners integrate this directly into their application’s sign up flow and others integrate it deeper into their user’s journey as part of collecting their first payout.

The choice is yours!

Creating the Company in Routable

Now that we have our company information, we're ready to set them up in Routable. Use the Create a Company endpoint to create the company.

📘

Reminder: Active Team Member

To create a Company, and to perform many other actions in the Routable API, we'll need to define an Active Team Member as the "person" making these requests. You can look up the IDs for your Team Members on the Routable Dashboard. We recommend saving a default Team Member ID as part of your Routable configuration, alongside your API token. See Team Members for more details.

We'll go ahead and build the API call here. In this example, we're building a "business" Company, so we include the business_name field.

If you stored this Company in your system as well, you can use the external_id field to record the ID of the record in your system to provide an easy link between Routable and your application. We recommend storing the ID of the Routable Company record in your Company object as well.

{
      "acting_team_member": teamMemberId,
      "business_name": form_data.companyName,
      "type": "business",
      "is_vendor": true,
      "is_customer": false,
      "external_id": "{{id from your system}}",
      "contacts": [
        {
          "first_name": form_data.contactFirstName,
          "last_name": form_data.contactLastName,
          "email": form_data.contactEmail,
          "default_contact_for_company_management": "actionable",
          "default_contact_for_payable_and_receivable": "actionable"
        }
      ]
}

Submitting this request to the Create a Company endpoint will return a response like this:

{
  "object":"Company",
  "id":"1be13eba-1668-459f-8f75-ba5de664fd0f",
  "type":"business",
  "contacts":{
    "object":"List",
    "results":[
      {
        "object":"Contact",
        "id":"460c77a5-320b-4a85-b860-9626e737a2ec",
        "default_contact_for_company_management":"actionable",
        "default_contact_for_payable_and_receivable":"actionable",
        "email":"[email protected]",
        "first_name":"Bob",
        "is_archived":false,
        "last_name":"Vance",
        "phone_number":"+14155552671",
        "phone_number_country":"US",
        "links":{
          "self":"https://api.sandbox.routable.com/v1/companies/1be13eba-1668-459f-8f75-ba5de664fd0f/contacts/460c77a5-320b-4a85-b860-9626e737a2ec",
          "company":"https://api.sandbox.routable.com/v1/companies/1be13eba-1668-459f-8f75-ba5de664fd0f"
        }
      }
    ],
    "links":{
      "self":"https://api.sandbox.routable.com/v1/companies/1be13eba-1668-459f-8f75-ba5de664fd0f/contacts"
    }
  },
  "created_at":"2021-05-25T16:26:21.155263+00:00",
  "external_id":"518a25a0-34e6-4a18-870b-0a617d5fbf49",
  "is_customer":false,
  "is_vendor":true,
  "ledger":{
    "customer_id":"None",
    "vendor_id":"None"
  },
  "business_name":"Vance Refrigeration",
  "display_name":"Bob Vance",
  "status":"added",
  "links":{
    "self":"https://api.sandbox.routable.com/v1/companies/1be13eba-1668-459f-8f75-ba5de664fd0f",
    "contacts":"https://api.sandbox.routable.com/v1/companies/1be13eba-1668-459f-8f75-ba5de664fd0f/contacts",
    "payment_methods":"https://api.sandbox.routable.com/v1/companies/1be13eba-1668-459f-8f75-ba5de664fd0f/payment-methods",
    "payables":"https://api.sandbox.routable.com/v1/payables?company=1be13eba-1668-459f-8f75-ba5de664fd0f"
  }
}

You'll want to grab the id field from this request and store it alongside the Company's data in your application.

Note that we didn't provide any banking or payment information. How are we going to pay our vendor? Let's find out in our next step: Collecting Payment Information.