Data Formats

How we expect to send and receive various types of data in the Routable API

Dates and Times

The names of date fields in the Routable API will always be postfixed with _on (e.g. due_on, issued_on). Dates are recorded in the ISO 8601 format: YYYY-MM-DD.

The names of timestamp fields will always be postfixed with _at (e.g. created_at, approved_at). Timestamps are recorded in the longest-form ISO 8601 format. Timestamps in API responses will be normalized to UTC, and timestamps in requests must include timezone designators. The format used is YYYY-MM-DDThh:mm:ss.sTZD, for example, 2019-07-09T15:03:36.1234+00:00.

In these format strings:
YYYY = four-digit year
MM = two-digit month (01=January, etc.)
DD = two-digit day of month (01 through 31)
hh = two digits of hour (00 through 23) (am/pm NOT allowed)
mm = two digits of minute (00 through 59)
ss = two digits of second (00 through 59)
s = between one and six digits representing a decimal fraction of a second
TZD = time zone designator (+hh:mm or -hh:mm)

Country and Currency Codes

Whenever a country is referenced in the API, it will be rendered in the two-letter ISO 3166-1-alpha2 format, for example, US for the United States and CA for Canada.

Currency codes will be represented in the three-letter ISO 4217 standard, for example, USD and EUR.

Only countries and currencies currently supported by Routable's Cross-border Payments system will be accepted. See the Supported Countries and Territories Explorer to find valid country codes and currency codes.

Telephone Numbers

Both domestic and international telephone numbers are transmitted in the E.164 format: +11234567890.

Google's libphonenumber library does an excellent job with formatting for the various rules that govern E.164. The library was originally released for C++, Java and JavaScript and has been ported to other languages as well:

Message Fields

When performing actions that trigger transactional emails to your customers and vendors, such as Invite a Company and Create a Payable, you have the ability to include a custom `message in the request. This message field will be added in the email that is sent to the vendor.

Custom messages support the following limited formatting options:

Plain Text Processing

When sending as plain text, your message will go through the following steps:

  • Any <br> tags will be converted to newlines
  • All remaining HTML will be stripped
  • The resulting text will be rendered into the email

File Attachments

See File Attachments.

Banking Information

A list of test banking data that will pass validation can be found in the Plaid documentation.


What’s Next