API Reference

Data

Is there a JSON Schema?

We allow additional JSON pairs (NVPs) to be added in a request (though we don't recommend this) and we may return back additional JSON pairs (NVPs) in a response (optional JSON pairs (NVPs) that you may not be using but another client may be using). We also allow JSON pairs (NVPs) to be sent in a request in any order and we may return back JSON pairs (NVPs) in a response in any order.
Be sure you can handle "freeform" JSON responses.

What is the type of a Data Value? Is it a String, an Integer, an Amount, a Boolean, or what?

We treat all Data Values initially as Strings. We then apply a Value Restriction to the String. So for example:

  • an Integer, we look for a string with only digits
  • an Amount, for currency number 840, USD, we look for a string with only digits and a single decimal point with two decimal digits but no commas nor currency sign
  • a Boolean, we look for a string with the value of either true or false
    Therefore, we should be able to parse almost all JSON Requests without having to just return a generic error (parse error).

How to specify an Amount Value?

In order to handle international currencies, an Amount is a String. International currencies:
use either a point or a comma as their decimal mark and
might have a maximum of 0, 1, 2, 3, or 4 decimal places.
So for example, for those using currency number 840, USD, an Amount must have a decimal point (.) with 2 decimal digits and no commas (,) nor currency sign ($). Examples:
1000.20 --> Valid
1.20 --> Valid
0.20 --> Valid
.20 --> Valid

.4 --> Invalid, 2 decimal digits are required
1.4 --> Invalid, 2 decimal digits are required
1,000.2 --> 1Invalid, comma not needed
$10.21 --> Invalid, dollar sign not needed

Is there a size limitation to String Values?

Unless specified in the Value column, String Values can be of any reasonable size. However there is a limitation to the total number of bytes in your request. And remember, some Unicode characters, especially international characters, are more than one byte.

Are null Values valid?

JSON Values that are null are accepted, according to the JSON Specifications, but it is preferred that you just leave out the pair (NVP):
Works:

{
  "NameA": "Test",
  "NameB": null,
  "NameC": "Test"
}

Preferred:

{
  "NameA": "Test",
  "NameC": "Test"
}

What valid characters can be used for fields such as Reference IDs, Memo, Names (first and last), etc...?

The API can accept any UTF-8 character; however, to be safe for other processes that may be using this data, we recommend the use of only the Base64 URL-Safe Character Set. We will also explicitly restrict the use of these characters:

  • , Comma (used in csv files)
  • " Double Quotes (used in csv files)
  • ~. Tilde
  • ^. Caret
    We do recommend the use of only the Base64 URL-Safe Character Set.

Base64 Encoding

Binary Data and some Strings, that are beyond Alphanumeric, should be encoded in Base64 with no padding and using the URL-Safe Character Set:

  • A-Z. Uppercase alphabetic characters
  • a-z. Lowercase alphabetic characters
  • 0-9. Digits
    • Minus Sign
  • _. Underscore

Format of the JSON Request and Response Data?

We required that all whitespaces are removed from the JSON Request (pack your JSON Request). We will also return a JSON Response in a packed format where all whitespaces are removed.

Nice for human:

{
  "NameA": "Test",
  "NameB": 1
}

But not so much for our Application and also it clutters our logs, so preferably:

{"NameA":"Test","NameB":1}