Data Format

Treezor API follows the standards below regarding the formats of data it returns and accepts. Exceptions are detailed in the documentation when relevant.

Requests

Apart from parameters that are explicitly expected in the URL (mostly IDs), Treezor expects all parameters in a JSON object.

Example

CURL

curl -X PUT {baseUrl}/endpoint \
	--header 'Content-Type: application/json' \
	-d '{
		"idStatus":"active",
		"firstname":"John",
		"lastname":"Smith"
	}'

Important – Correct number of parameters

Note that each endpoint expects a precise (n) number of parameters.

Providing n-x or n+x parameters can result in an error.

Amounts

Amounts are expected as number with two decimals. They do not include the currency name.

Example

• 180.99 for an amount of 180,99
• 1285.00 for an amount of 1285

Currencies

Currencies follow the ISO 4217 standard, a 3-character code. While this code is usually in the 3 capitalized letters format, you may encounter the numerical version on some endpoints (e.g., EUR or 978 for Euro).

Countries

Countries follow the ISO 3166-1 alpha-2 standard, a 2 capitalized letter code (e.g., FR for France).

Examples

• FR for France
• DE for Germany
• CH for Switzerland

Dates

Dates follow the RFC3339 standard.

They are provided and expected in Paris time, which is

• UTC+2 Central European DST (Daylight Saving Time)
• UTC+1 Central European otherwise.

Examples

PHP

date('Y-m-d\TH:i:sP');
// 2020-08-25T07:06:13+02:00

2020-08-25T07:06:13-07:00

You can read about UTC here and check UTC timezones by country there.

Phones

Phones numbers are expected with the country code prefix (e.g., +33), without leading zero.

Examples

• The French number 06 05 04 03 02 is expected as +33605040302
• The German number 013 456 7899 is expected as +491234567899

Files

Files (such as documents and templates) are expected in base64 encoded format in a JSON object attribute. They are also returned as base64.

Example

PHP

// composer require php-curl-class/php-curl-class
$request = new Curl\Curl;
$request->setHeader('Authorization', 'Bearer <JWT>'); // Don't forget to replace with your token
$request->setHeader('Content-Type', 'application/json');
$request->post(
		'https://<company-name>.sandbox.treezor.co/v1/documents/', [
			// [...] this example doesn't show all the mandatory parameters
			'userId'			=>'<USER_ID>',
			'documentTypeId'	=>'<DOCUMENT_TYPE_ID>',
			'name'				=>'19-Extrait-Kbis.pdf',
			'fileContentBase64'	=>base64_encode(
				file_get_contents(
					'/home/johnsmith/Downloads/19-Extrait-Kbis.pdf'
				)
			)
		]
	);

CURL

# encode the file into base64
base64 /home/johnsmith/Downloads/19-Extrait-Kbis.pdf > /home/johnsmith/Downloads/19-Extrait-Kbis.base64
# show the content of the encoded file
cat /home/johnsmith/Downloads/19-Extrait-Kbis.base64 # ZHVtbXkg[...]dGVzdAo=
# post the encoded file
curl -X POST {baseUrl}/v1/documents/ \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{
		"userId":"{userId}",
		"documentTypeId":"[documentTypeId}",
		"name":"19-Extrait KBis.pdf",
		"fileContentBase64":"ZHVtbXkg[...]dGVzdAo=",
	}'
	# [...]
	# This example doesn't show all the mandatory parameters

IDs

• Numerical identifiers such as userId, should be provided as integer.
• Textual identifiers such as client_id, should be provided as string.

Ids are progressively migrated to UUIDv4.

You should anticipate this API-wide migration by typing all IDs as 36-character strings in your databases.

Numerical example

JSON

{
	"userId":18742 					// No quotes (legacy ID)
}

Textual example

JSON

{
	"client_id":"<client_id_here>" 	// with quotes
}

UUIDv4 example

JSON

{
	"webhook_id":"45a10236-4e55-41b5-8cbd-00acea4cb553"
}

Texts, metas, tags

Strings are expected in Unicode (UTF-8).

Addresses

Address lines (address{1-3} attributes) for User addresses allow for 150 characters, but you may limit them to 56 characters following the AFNOR XP Z 10-011 standard of May 1997.

If you're issuing Cards, the Card object applies further restrictions and we recommend even shorter strings due to mail carrier limitations. Below the maximum number of characters per field.

Field	User object	Card object	Mail carrier recommendation
address1	150	50	~38
address2	150	50	~38
address3	150	35	35

Important – Mail carrier limitations

The table above provides a rough estimation for mail carrier maximum amount of printed characters, as those limitations may change depending on the selected font for instance.