Formats dictate the precise formatting of values atop the basic JSON data types (string, numeric, boolean, array, object), aligning with the properties mandated by our API.
This document section delineates the recurrent formats through contextual examples, serving as a reference for the API specifications highlighted for each request/response transactions.
Int
In JSON, there is no distinct separation between integers and floating-point numbers. This format is employed to indicate that the numeric value must be without any decimal places.
Example
{
"integer": 111
}
Enum
Enums are a collection of pre-defined string values, written in fully capitalized form, with multiple words separated by underscores "_".
Example
{
"enums": ["BAZ", "FOO_BAR"]
}
Datetime
All datetimes/timestamps will be expressed as RFC3339 strings, consistently in UTC format. Whenever a property necessitates a datetime representation, it will be indicated using this format.
Example
{
"created_at": "2023-07-20T15:15:37+00:00"
}
Date
Date is a string formatted as YYYY-MM-DD, it represents a date without its time part. Used for things such as date of birth, documents expiry dates etc.
Example
{
"date_of_birth": "1912-06-23"
}
Monetary amount
All monetary values will be represented as decimals wrapped within strings. This approach is adopted to prevent any possible misinterpretation caused by floating-point rounding. Many JSON unmarshallers (e.g. javascript) will unmarshal JSON numbers to IEEE 754 double-precision floating point numbers, potentially leading to a silent loss of precision.
Example
{
"amount": "99.99"
}
Currency
Currencies are represented as ISO 4217 enums.
Example
{
"currencies": ["GBP", "USD", "KES"]
}
Country
Countries are represented as ISO 3166-1 alpha-2 enums.
Example
{
"countries": ["GB", "US", "KE"]
}
Phone number
Phone numbers are strings represented as E.164
Example
{
"uk_number": "+442071838750"
}