Data Formats

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

Date and Times

For our API, we use the ISO 8601. ISO 8601 is a standard for representing dates and times in a machine-readable format. It specifies a set of representations for dates, times, and intervals, including standard formats for representing dates and times with or without a time zone.

The format consists of a series of fields separated by punctuation, with the most significant fields appearing first. The basic format for representing a date and time is:

YYYY-MM-DDTHH:MM:SSZ

Where:

• YYYY is the year, represented as four digits
• MM is the month, represented as two digits (01-12)
• DD is the day of the month, represented as two digits (01-31)
• T is a separator indicating the start of the time portion of the date-time value
• HH is the hour, represented as two digits (00-23)
• MM is the minute, represented as two digits (00-59)
• SS is the second, represented as two digits (00-59)
• Z is the timezone

For example, the date and time "2022-12-29T12:34:56Z" would represent December 29, 2022 at 12:34:56 (12:34 PM).

The API uses UTC, or Coordinated Universal Time, for the date/time field. UTC is a standardized time reference that is the same everywhere in the world. It is the primary time standard by which the world regulates clocks and time. UTC is based on atomic clocks, which are highly accurate clocks that measure the vibrations of atoms to determine the passage of time. Because UTC is based on atomic clocks, it is extremely stable and accurate.

Monetary values

For our API, every monetary must be in a ISO 4217, that is an international standard for representing currencies. It specifies a three-letter code for each currency, as well as the currency's minor unit of currency. For example, the code for US dollars is "USD".

Also, the amount field for money is represented in cents rather than the base unit of the currency. This allows for more precise representation of the amount, as well as easier computation and storage of monetary values. For example, if you want to represent $10.50 in an API, you would store the amount as 1050 (rather than 10.50).

This would be represented like:

{
    "amount": 10000,
    "currency": "COP"
}

This represents an amount of 10000 cents, or 100 Colombian pesos. The currency is specified using the ISO 4217 currency code for Colombian pesos, which is "COP".

Telephone Numbers

Both domestic and international telephone numbers are represented with the E.164.

E.164 is a standard for the formatting of telephone numbers. It specifies a standardized format for telephone numbers that includes a country code, a national destination code, and a local subscriber number. The format is as follows:

+[country code][national destination code][local subscriber number]

For example, a telephone number in Colombia might be formatted as +57 300 555 0000, where the +57 is the country code for Colombia, the "300" is the national destination code, and the "555 0000" is the local subscriber number.