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

We support file attachments via Data URLs and typically recommend a library to help facilitate the process of creating these URLs. Here's a few snippets to get you started:

from datauri import DataURI
const attachment_for_routable_api = { 
   # => data:application/pdf;base64,JVBERi0xLjMNJeLjz9 (truncated)
   "data_uri": str(DataURI.from_file('test.pdf')) 
   "name": "test.pdf"
const Datauri = require('datauri/sync');

const attachment_for_routable_api = { 
   //  data:application/pdf;base64,JVBE Ri0xLjMNJ (truncated)
   "data_uri": Datauri('test.pdf').content,  
   "name": "test.pdf"
$filename = 'test.pdf';
$mime_type = mime_content_type($filename)
$data = file_get_contents($filename);
$attachment_for_routable_api = { 
   // data:application/pdf;base64,JVBE Ri0xLjMNJ (truncated)
   "data_uri": 'data:' . $mime_type . ';base64,' . base64_encode($data),
   "name": $filename

We currently support attaching the following file types:

  • CSV
  • DOCX
  • JPG
  • PDF
  • PNG
  • TXT
  • XLSX


Be extra careful with file attachments uploaded from users!

Certain file formats such as DOCX and PDF can carry hidden malware. If your application is allowing file uploads from end users, you should absolutely perform rigorous validation against those files to ensure they are safe to be processed before allowing them to be processed by your system or by Routable. Techniques for doing this in various programming languages are outside the scope of this document.

Banking Information

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

Did this page help you?