Data Types

String

Fields with the data type String are containing regular UTF-8 text spanning the whole unicode range, therefore it is possible for them to contain emojis. Additionally they might specify a specific size with a appendix, e.g. String(32) denotes a String which can have a length of up to 32 characters. If no specific length is specified the field can contain a String of a length of up to 16MB, thus we encourage you to account for this when specifying fields in databases or building UI.

Increasing the length of a request field of type String is considered a breaking change and therefore will be announcend beforehand. Decreasing the length of a request field of type String is not considered a breaking change and thus will not be announced.

The API will reject requests that contain fields with data outside of the documented boundary with an appropriate error message.

Decreasing the length of a response field of type String is considered a breaking change and therefore will be announcend beforehand. Increasing the length of a response field of type String is not considered a breaking change and thus will not be announced.

Integer

Fields with the data type Integer are containing numbers in the range from -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807.

If a field specifies a different upper bound the specific definition takes precedence.

Floating point numbers or numbers outside of this range that are sent to the API in fields defined as Integer will be rejected with an appropriate error message.

Double

Fields with the data type Double are equal to JSON numbers and can be either integers or floating point numbers, mostly used as floating point numbers.

Enum

Enum hold a value out of a documented amount of possible String values.

Adding new values to Enum, which are part of our API responses, are not considered breaking and should be handled by the client gracefully.

Changes on Enum values that are part of our process logic like flow or session state will be announced beforehand.

Removing values from existing request fields of type Enum is considered a breaking change and will be announced beforehand.

Note that the error handling enum is considered a special case and we expect customers to fallback to the top-level categories for newly added error categories.

Date

Dates in our API always follow the ISO-8601 - Standard in the form of YYYY-MM-DD. All dates shall be provided in the UTC timezone.

DateTime

Dates with time in our API always follow the ISO-8601 - Standard with a UTC offset, in the form of YYYY-MM-DDThh:mm:ss.sssZ. Example: 2007-12-03T10:15:30.152Z.

URI/URL

Uniform Resource Identifiers follow the official defined scheme and will be validated against it.

URI = scheme ":" ["//" authority] path ["?" query] ["#" fragment]