# Routable API Documentation ## Guides - [Obtaining Accounting Software Object IDs](https://developers.routable.com/docs/accounting-software-objects.md): Models categories like accounts, classes, locations and tax codes in your accounting software. - [Configured and Custom Fields](https://developers.routable.com/docs/configured-and-custom-fields-in-ledgers.md) - [Oracle NetSuite](https://developers.routable.com/docs/netsuite.md) - [NetSuite Sandbox Setup](https://developers.routable.com/docs/netsuite-sandbox-setup.md) - [Payables and Receivables in NetSuite](https://developers.routable.com/docs/payables-in-netsuite.md) - [QuickBooks Online](https://developers.routable.com/docs/quickbooks-online.md): This section covers connecting your QBO account to your Routable account as well as setting up a QBO sandbox for testing purposes! - [QBO Sandbox Configuration](https://developers.routable.com/docs/quickbooks-online-sandbox-configuration.md) - [QBO Sandbox Setup](https://developers.routable.com/docs/quickbooks-online-sandbox.md) - [Sync Bank Accounts with QBO](https://developers.routable.com/docs/set-up-bank-accounts.md) - [Sage Intacct](https://developers.routable.com/docs/sage-intacct.md) - [Payables and Receivables in Sage Intacct](https://developers.routable.com/docs/payables-in-sage-intacct.md) - [Xero](https://developers.routable.com/docs/xero.md) - [Xero Sandbox Setup](https://developers.routable.com/docs/xero-sandbox.md) - [Approval Rules](https://developers.routable.com/docs/approval-rules.md) - [Data Formats](https://developers.routable.com/docs/data-formats.md): How we expect to send and receive various types of data in the Routable API - [Errors and Status Codes](https://developers.routable.com/docs/errors-and-status-codes.md) - [File Attachments](https://developers.routable.com/docs/file-attachments.md) - [HTML Messages](https://developers.routable.com/docs/html-messages.md): Routable supports a limited subset of HTML tags in messages. - [Pagination and Sorting](https://developers.routable.com/docs/pagination-and-sorting.md) - [Payment Statuses](https://developers.routable.com/docs/payment-statuses.md): The lifecycle of a Payable or Receivable - [Using AI/LLMs with the API](https://developers.routable.com/docs/mcp.md) - [Your Routable Sandbox](https://developers.routable.com/docs/our-sandbox.md): Ready to test Routable? We're ready to support your team along the way. - [Where to Get Help](https://developers.routable.com/docs/where-to-get-help.md): Routable isn't just a platform - it's a team of people committed to your success. If you need a hand, we've got you covered. - [Your API Token](https://developers.routable.com/docs/your-api-token.md): Keep it secret. Keep it safe. - [AccountingSoftwareObject](https://developers.routable.com/docs/accountingsoftwareobject.md) - [Account](https://developers.routable.com/docs/accounts.md): Accounts are funding sources for your Payables. - [Company](https://developers.routable.com/docs/company.md): A Company is someone you pay, or someone who pays you. Or, why not both? - [Country](https://developers.routable.com/docs/country.md): Describes Routable's capabilities when dealing with Companies in any Country or Territory. - [Payable](https://developers.routable.com/docs/payables-1.md): A resource describing a payment that needs to be made to a Company. - [PurposeCode](https://developers.routable.com/docs/purpose-codes.md): Some countries require payments to specify their purpose. - [Resource Overview](https://developers.routable.com/docs/resource-overview-1.md) - [TeamMember](https://developers.routable.com/docs/team-members.md): An individual human that works for/with your company and can perform tasks in your Routable account - [WebhookEvent](https://developers.routable.com/docs/webhookevent.md) - [Adding Check Stub Details](https://developers.routable.com/docs/check-stub-details.md): Sending a paper check through Routable? Here's how to make a nifty check stub to include. - [Estimating Fees and Exchange Rates for Payments](https://developers.routable.com/docs/estimating-fees-and-exchange-rates-for-payments.md) - [International Payments](https://developers.routable.com/docs/cross-border-payments.md) - [Supported Countries and Territories](https://developers.routable.com/docs/supported-countries-and-territories.md) - [Handling Failed Payments](https://developers.routable.com/docs/handling-failed-payments.md) - [Instant Payments](https://developers.routable.com/docs/instant-payments.md) - [Vendor Compliance Checks](https://developers.routable.com/docs/vendor-compliance-checks.md) - [Migrating from Bill.com](https://developers.routable.com/docs/migrating-from-billcom.md) - [Developing Webhooks](https://developers.routable.com/docs/webhooks.md) - [Collecting Payment and Tax Information](https://developers.routable.com/docs/collecting-payment-information.md) - [Verifying Bank Account Information (via Routable)](https://developers.routable.com/docs/verifying-bank-account-information-via-routable.md) - [Verifying Bank Account Information (via Plaid)](https://developers.routable.com/docs/verifying-bank-account-information.md) - [Before You Begin...](https://developers.routable.com/docs/embedding-within-your-app.md) - [Your First Payable](https://developers.routable.com/docs/your-first-payable.md): It's time to move some money! ## API Reference - [400 Validation Error](https://developers.routable.com/reference/400-validation-error.md) - [402 Payment Required](https://developers.routable.com/reference/402-payment-required.md) - [405 Method Not Supported](https://developers.routable.com/reference/405-method-not-supported.md) - [409 Conflict](https://developers.routable.com/reference/409-conflict.md) - [500 Internal Server Error](https://developers.routable.com/reference/internal-server-error-500.md) - [List Accounting Software Objects](https://developers.routable.com/reference/list-accounting-software-objects.md): Retrieve `AccountingSoftwareObjects` of a given type. Use the optional `search` parameter to filter results. - [Deposit Funds into Routable Balance](https://developers.routable.com/reference/deposit-into-balance.md): Moves funds from the specified `bank` `Account` into your Routable balance. - [List Accounts](https://developers.routable.com/reference/list-accounts.md): Returns a list of previously created Accounts. - [Retrieve an Account](https://developers.routable.com/reference/retrieve-account.md): Retrieve an existing Account. - [Retrieve Routable Balance Account](https://developers.routable.com/reference/retrieve-balance.md): Retrieves the `Account` for your Routable balance. Returns the same response as `GET /v1/settings/accounts/{id}` where the `id` references your `balance` `Account`. - [Archive a Company](https://developers.routable.com/reference/archive-company.md): Archives a `Company`. Archived Companies will not appear in List Company calls, and cannot be updated. They cannot receive `Payables` or `Receivables`. `Compliance Reports` will not be run on archived Companies, and `TaxForms` and `PaymentMethods` may not be added. This action cannot be performed when the `Company` has `Payables` or `Receivables` in non-final states. - [Create a Company](https://developers.routable.com/reference/create-company.md): ### Business or Personal? When creating a company, take note that there are two different types of companies: `business` and `personal`. - You would create a company as `business` when they are acting as a sole proprietorship, LLC, or corporation. - You would create a company as `personal` when they are acting as a contractor or a freelancer. Also, take note that the parameters available to configure the company are slightly different between the two types of companies. We've documented these differences in the request schema. #### What's in a name? When creating a company, we allow you to set different names based on the type of company. > ⚠ > > If the `business_name` for your company is incorrect, it can cause issues for payments. | | `name` | `business_name` | |------------|-----------------------|-------------------------------------------------| | `business` | Set from `business_name` | ✅ | | `personal` | ✅ | Set from contact's `first_name`
and `last_name` | When working with many `personal` companies, it's common to run into naming collisions. We recommend including some sort of unique ID in the name such as `Jane Doe [bHvRzbRA]`. Your finance team might have preferences here - Check with them 💪. ### Contacts Companies have Contacts that are the recipient of messages pertaining to the Company. These resources are created when you create a Company. A Company can have Contacts added, archived and updated at a later time via the Contacts APIs. - [Invite a Company](https://developers.routable.com/reference/invite-company.md): After creating a company, you may invite the company to use Routable's vendor onboarding flow to add additional contact information and payment method details to their vendor profile. This can be done in two ways: via email and/or via an embedded link. To send the invitation via email, set the `send_invite_email` parameter to `true`. The recipients of the email will be based on the `Company's` `Contacts` and their `default_contact_for_company_management` value: - When `actionable`, the contact will receive an email with a clickable link that allows them to submit information. - When `read_only`, the contact will only be notified of the invitation. - When `none`, the contact will not receive an email notification. To use the embedded link flow, use the `get_links` parameter with a value of `true`. You may also specify a `confirmation_redirect_url` to route the user to after completion of the Routable onboarding flow. After inviting a company, their `status` will change to `invited`. After the contact enters their information, the company's `status` will change to `accepted`. Attempting to send an invitation to a Company that is already `accepted` will generate a `400 Bad Request` error. For more information, see our [help docs](https://docs.routable.com/en/articles/3482971-what-does-a-vendor-invite-look-like). - [List Companies](https://developers.routable.com/reference/list-companies.md): Returns a list of previously created Companies. - [Retrieve a Company](https://developers.routable.com/reference/retrieve-company.md): Retrieve a previously created Company. - [Unarchive a Company](https://developers.routable.com/reference/unarchive-company.md): Restores a `Company` that has been archived. - [Update a Company](https://developers.routable.com/reference/update-company.md): Update a previously created Company. - [Re-Invite a Company](https://developers.routable.com/reference/update-invite-company.md): After inviting a company for the first time, you may send a new invite to update information: - Updating the payment method on file - Updating tax information This can be done in one of two ways: via email or via an embedded link. To send the invitation via email, set the `send_invite_email` parameter to `true`. Note that if both `request_payment_method` and `request_tax_form` are selected, the company will receive one email for each request. The recipients of the email will be based on the `Company's` `Contacts` and their `default_contact_for_company_management` value: - When `actionable`, the contact will receive an email with a clickable link that allows them to submit information. - When `read_only`, the contact will only be notified of the invitation. - When `none`, the contact will not receive an email notification. To use the embedded link flow, use the `get_links` parameter with a value of `true`. Note that when using `get_links: true`, each contact will have their own invitation URL, for each of the requests selected. You may also specify a `confirmation_redirect_url` to route the user to after completion of the Routable onboarding flow. - [Dismiss Compliance Check](https://developers.routable.com/reference/dismiss-compliance-check.md): Indicate that you have manually verified a vendor with compliance issues and wish to send them Payables. - [Retrieve Compliance Report](https://developers.routable.com/reference/retrieve-compliance-report.md): View details about the most recent set of compliance checks performed on a vendor, and details of any issues that were discovered. - [Create a Contact](https://developers.routable.com/reference/create-contact.md): Create a new Contact. Additional Contacts may only be added to Companies of type `business`. - [List Contacts](https://developers.routable.com/reference/list-contacts.md): Returns a list of previously created Contacts. - [Retrieve a Contact](https://developers.routable.com/reference/retrieve-contact.md): Retrieve an existing Contact object - [Update a Contact](https://developers.routable.com/reference/update-contact.md): Update an existing Contact. - [List Countries](https://developers.routable.com/reference/list-countries.md): Returns a list of Countries (and territories) around the world. - [List Purpose Codes](https://developers.routable.com/reference/list-country-purpose-codes.md): Get list of `PurposeCodes` for a specific `Country`. - [Retrieve a Country](https://developers.routable.com/reference/retrieve-country.md): Returns details about a specific `Country` (or territory). This includes static data to help you with building a user interface, such as country names and telephone code requirements, as well as information about the payment options Routable provides in this `Country` and the data required to use them. - [Estimate Currency Conversions and Fees](https://developers.routable.com/reference/estimate-fees-and-convert.md): Given a currency, amount and delivery method, this endpoint calculates the estimated Routable fees to send the hypothetical payment, as well as the current conversion rate between the sender's and receiver's currencies. - [Cancel a Payable](https://developers.routable.com/reference/cancel-payable.md): Cancel an existing Payable. For full details on when you can cancel payables, see our [help docs](https://docs.routable.com/hc/en-us/articles/21512880766349-Cancel-a-payment). - [Create a Payable](https://developers.routable.com/reference/create-payable.md): ### Types of Payables Routable supports creating six different types of `Payables`: **Bank Transfer** (`type=ach`) - Create this `Payable` type when you explicitly want to pay your vendor via bank transfer. - Your vendor must have an existing `PaymentMethod` where `type=bank`. - This `Payable` type is also used for `real_time_payments` like FedNow and RTP. See [Real-Time Payments](https://developers.routable.com/v1/docs/real-time-payments) for more information. **Check** (`type=check`) - Create this `Payable` type when you explicitly want to pay your vendor via check. - Your vendor must have an existing `PaymentMethod` where `type=address`. **External** (`type=external`) - Create this `Payable` type when you want to track a payment that was already made outside of Routable. **International** (`type=international`) - Create this `Payable` type when paying international vendors via local bank transfer or SWIFT. - Your vendor must have an existing `PaymentMethod` where `type=international`. They can create this in the Invite a Company or Accept Payment flows. - See the `delivery_methods` array in the vendor's `PaymentMethod` to determine what delivery methods are supported. - You must have an existing `PaymentMethod` where `type=bank` to process an international transaction. - See [International Payments](https://developers.routable.com/v1/docs/cross-border-payments) for details. **PayPal** (`type=paypal`) - 🚧 **PayPal support is currently in limited availability. Please contact Routable to see if your Workspace qualifies for PayPal integration.** - Create this `Payable` type when making PayPal direct payments. - Your vendor must have an existing `PaymentMethod` where `type=paypal`. **Vendor Choice** (`type=vendor_choice`) - Create this `Payable` type when you want your vendor to be able to choose their preferred payment method. - You may use this when your vendor has no existing payment methods and they will be prompted to submit a payment method via our onboarding flow. ### Rate Limiting 🏁 This endpoint's rate limit is 100 calls per minute. ### Idempotency Key We highly recommend you supply an [idempotency key](http://developers.routable.com/docs/idempotency-keys#/) when creating `Payables` to prevent duplicate requests. These keys are **stored for a period of 24 hours**. If a request fails due to a network error, you can safely retry the same request with the same key and guarantee that your request had exactly one effect. When a request is sent with an idempotency key for an already created resource, the response object for the existing resource will be returned. All requests with the same key will be considered attempts for the same request. It is therefore important that you use unique keys. We suggest using random values, such as UUIDs. ### Status Codes Please note that it is possible for this endpoint to return a `202` response, which indicates that we are still processing the request. To ensure that the payment has been created, you may attempt to retrieve it using the returned ID or `self` link. ### Scheduling Payables Routable supports 3 different ways of scheduling your `Payables` based on the value supplied for `send_on`. **Sending a Payable Today** - To send a `Payable` today, set it to today's date **in Pacific time**. - Use this when you want to send a `Payable` ASAP. **Sending a Payable in the Future** - To send a `Payable` in the future, set `send_on` to a future date **in Pacific time**. - Use this when you want to send a `Payable` in the future. **Sending a Payable with no defined date** - To create a `Payable` with no specified date, set `send_on` to `null`. - Use this when you want to prepare a `Payable` to be sent. This can be useful when testing out your integration. ### Default Contacts When sending `Payables` via our API, we will notify all contacts associated with the company based on the values specified for their `default_contact_for_payable_and_receivable` field. ### Default Approvals When sending `Payables` via our API and a payable requires approvals [per your approval settings](https://docs.routable.com/hc/en-us/articles/21509130402701-Configuring-and-customizing-your-approval-settings) we will automatically fill in the appropriate team members. We do this by finding all applicable levels of approval and requesting approvals from all `TeamMembers`. For example, you can set up your account so that: - Any `Payable` over $1,000 requires a first level approval from either Angela or Oscar. - Any `Payable` over $2,000 requires a second level approval from both Michael and Andy. When creating a `Payable` for $1,100 the API would request approval from both Angela and Oscar. When creating a `Payable` for $2,100 the API would request approval from both Michael and Andy for the second level as well as Angela and Oscar on the first level. - [Estimate Fees for a Payable](https://developers.routable.com/reference/estimate-payable.md): Given a valid `Payable` payload, return an estimate of the currency conversion (if applicable), as well as the Routable and transfer fees associated with making the payable. - [List Payables](https://developers.routable.com/reference/list-payables.md): Returns a list of Payables that were previously created. - [Send a Payable Reminder](https://developers.routable.com/reference/remind-payable.md): Send an email reminding a vendor to take action on an existing Payable. - [Download Confirmation PDF](https://developers.routable.com/reference/retrieve-payable-confirmation.md): If the Payable has been successfully processed, this endpoint returns the PDF confirmation of the successful payment. - [Retrieve a Payable](https://developers.routable.com/reference/retrieve-payable.md): Retrieve an existing Payable object - [Update a Payable](https://developers.routable.com/reference/update-payable.md): Update an existing Payable. 🏁 This endpoint's rate limit is 100 calls per minute. - [Archive a Payment Method](https://developers.routable.com/reference/archive-payment-method.md): Archives a `PaymentMethod`. Archived `PaymentMethods` cannot be used for transactions. This action cannot be performed while the `PaymentMethod` has `Payables` in non-final states. - [Create a Payment Method](https://developers.routable.com/reference/create-payment-method.md): Create a new `PaymentMethod` attached to a `Company`. Please note that there are **four** different types of `PaymentMethods`: `address`, `bank`, `international`, and `paypal`. Companies may have up to six `bank` `PaymentMethods` attached to them. This limit does not apply to other `types` of `PaymentMethods`. - [List Payment Methods](https://developers.routable.com/reference/list-payment-methods.md): Returns a list of `PaymentMethods` that were previously created. - [Retrieve a Payment Method](https://developers.routable.com/reference/retrieve-payment-method.md): Retrieve an existing `PaymentMethod` object. - [Unarchive a Payment Method](https://developers.routable.com/reference/unarchive-payment-method.md): Unarchives a `PaymentMethod`. Only `PaymentMethods` with `archived_by`=`team_member` can be unarchived. - [Update a Payment Method](https://developers.routable.com/reference/update-payment-method.md): Update an existing `PaymentMethod` object. - [Validate a Payment Method](https://developers.routable.com/reference/validate-payment-method.md): Validate a new `PaymentMethod` before attaching it to a `Company`. Please note that only `bank` `PaymentMethods` can be validated at this time. When testing in [the Routable Sandbox](https://developers.routable.com/docs/our-sandbox), you can deterministically control the results you wish to receive for each `check` based on the values of the last two digits of the `account_number`: ![The last digit is the desired `verification` result, second to last is the desired `ownership` result.](https://files.readme.io/d1c74fa053fd75781cc151341bb6cef734235c6b117ebd1d420956956c8eba48-bank_account_validation_test_data.png "Test Account Numbers") Pass the following number in a check's digit to get the result you want: 1: `match` 2: `mismatch` 3: `no_data` 4: `unable_to_verify` 5-9 and 0: result undefined - [Cancel a Receivable](https://developers.routable.com/reference/cancel-receivable.md): Cancel an Receivable. For full details on when you can cancel Receivables, see our [help docs](https://docs.routable.com/en/articles/4798143-canceling-a-payable-or-receivable). - [Create a Receivable](https://developers.routable.com/reference/create-receivable.md): Create a Receivable to be paid by one of your Customers. - [List Receivables](https://developers.routable.com/reference/list-receivables.md): Returns a list of Receivables that were previously created. - [Send a Receivable Reminder](https://developers.routable.com/reference/remind-receivable.md): Send an email reminding a vendor to take action on an existing Receivable. - [Retrieve a Receivable](https://developers.routable.com/reference/retrieve-receivable.md): Retrieve an existing Receivable object - [Update a Receivable](https://developers.routable.com/reference/update-receivable.md): Update an existing Receivable. 🏁 This endpoint's rate limit is 100 calls per minute. - [List Team Members](https://developers.routable.com/reference/list-team-members.md): Returns a list of existing `TeamMembers`. - [Retrieve a TeamMember](https://developers.routable.com/reference/retrieve-team-member.md): Retrieve a `TeamMember` - [Retrieve Workspace Settings](https://developers.routable.com/reference/retrieve-workspace-settings.md): Retrieves some top-level settings for your Routable `Workspace`. - [Create Company Tax Form](https://developers.routable.com/reference/create-tax-form.md): Create a new `TaxForm` for the specified `Company`. - [List Tax Forms (Completed)](https://developers.routable.com/reference/list-tax-forms.md): Retrieves the active TaxForms for this Company that are in a `completed` status. This will currently return just one TaxForm. - [List Webhook Events](https://developers.routable.com/reference/list-webhook-events.md): Returns a list of existing Webhook Events. - [Retrieve a Webhook Event](https://developers.routable.com/reference/retrieve-webhook-event.md): Retrieve an existing Webhook Event. - [Retry Webhook Events](https://developers.routable.com/reference/retry-webhook-events.md): Retry Webhook Events. ## Changelog - [New webhooks and powered-up PaymentMethod controls](https://developers.routable.com/changelog/new-webhooks-increased-paymentmethod-control-and-more.md) - [Qapla'! Routable's stellar payments API goes even further!](https://developers.routable.com/changelog/qapla-routables-stellar-payments-api-goes-even-further.md) - [Spring cleaning with new Payable and Receivable filters!](https://developers.routable.com/changelog/spring-cleaning-continues-with-new-payable-and-receivable-filters.md) - ["Check" out these new improvements!](https://developers.routable.com/changelog/check-out-these-new-improvements.md) - [Santa needs reliable deliveries. So do you. We got you.](https://developers.routable.com/changelog/santa-needs-reliable-deliveries-so-do-you-we-got-you.md)