We publish everything related to our API on github at this location: https://github.com/eZmaxinc. You'll find git repos for the specification, documentation, SDKs and samples.

Documentation, SDKs and samples are provided in english only for easier maintenance, but we also have french speaking integrators that can help you out.

Most of our SDKs provide language specific documentation, but you'll find more details on this page about the general use of the API. Both the SDK's specific document (if you choose to use a SDK) and this documentation can be used in complementarity.

If you find any mistake or omission in the documentation, please notify us. We'll quickly fix the issue.

We highly recommend to schedule an online meeting with your technical team and an eZmax integrator. During this meeting, we go through requirements, business logic, configuration, api key generation, and we go through the list of functions you might need to implement to achieve your goals. Make sure you take this opportunity to speed up your integration project.

If you need help understanding how to use this API, don't waste too much time searching in it. Contact support-api@ezmax.ca, we're here to help. We are developpers so we know programmers don't like to waste time in documentation. If you don't find what you need in the documentation, let us know, we'll improve it and put you rapidly up on track.

We highly believe in open standards and open source. We have adopted the Open API vision where all of the functionnalities of our applications are accessible with open source definition files. We use our own public API's to build our interfaces so you can do pretty much everything we can do. Open API has a rich toolset from editor, generators, mock servers, validators, etc. Learn more at OpenAPI Initiative

If you need our Open API Spec file to use in your toolset, here is a direct link to it: ezmax.v1.0.json

We provide SDKs for customers. They are generated using OpenAPI Generator, we encourage customers to use them as we also provide samples for them. You can choose to build your own implementation manually or can use any compatible OpenAPI 3.0 generator like OpenAPI Generator, Swagger Codegen or any commercial generators.

We try to make it as easy as possible for you to use our SDKs so we publish packages on NPM and Composer. If you don't find your favorite language supported or it we could make your like easier by automating package distribution, let us know !

When you send your API requests, you'll need to send them in the proper region and proper environment where your customer data are stored. Based on your requirements (proximity and legislation), we will create your environment in one of our supported region's.

The general format of the URL where to send requests is: https://{sInfrastructureenvironmenttypeDescription}.api.appcluster01.sInfrastructureregionCode}.ezmax.com/rest/

Where "{sInfrastructureenvironmenttypeDescription}" and "{sInfrastructureregionCode}" need to be replaced with one of the values in the table below.

Our SDKs have a default value of "prod" and "ca-central-1". You will need to call "setHost" to change the default value if needed.

Note: You should always use "prod" for the environment unless otherwise instructed by eZmax's support.

sInfrastructureenvironmenttypeDescription	Description
prod	Production
stg	Staging
qa	Quality Assurance
dev	Development

sInfrastructureregionCode	Description
af-south-1	Africa (Cape Town)
ap-east-1	Asia Pacific (Hong Kong)
ap-northeast-1	Asia Pacific (Tokyo)
ap-northeast-2	Asia Pacific (Seoul)
ap-northeast-3	Asia Pacific (Osaka-Local)
ap-south-1	Asia Pacific (Mumbai)
ap-southeast-1	Asia Pacific (Singapore)
ap-southeast-2	Asia Pacific (Sydney)
ca-central-1	Canada (Central)
eu-central-1	Europe (Frankfurt)
eu-north-1	Europe (Stockholm)
eu-south-1	Europe (Milan)
eu-west-1	Europe (Ireland)
eu-west-2	Europe (London)
eu-west-3	Europe (Paris)
sa-east-1	South America (São Paulo)
us-east-1	US East (N. Virginia)
us-east-2	US East (Ohio)
us-west-1	US West (N. California)
us-west-2	US West (Oregon)

Some of the functions needs to be called on the global infrastructure instead of the regional servers. These functions are all located in the Global section of the documentation.

The general format of the URL where to send requests is: https://{sInfrastructureenvironmenttypeDescription}.api.global.ezmax.com/

Where "{sInfrastructureenvironmenttypeDescription}" needs to be replaced with one of the values in the table below.

Our SDKs have a default value of "prod". You will need to call "setHost" to change the default value if needed.

Note: You should always use "prod" for the environment unless otherwise instructed by eZmax's support.

sInfrastructureenvironmenttypeDescription	Description
prod	Production
stg	Staging
qa	Quality Assurance
dev	Development

Except for a few functions that do not require authorization, most of the functions require an API key that is sent in the request headers. The header name is "Authorization".

There are 4 types of API Key that can be used to make requests to the API.

1. API type key which is static and not session based. It can be generated from the admin console. This is the most common type of authentication for "server to server" kind of integration. Never use this in a web based (client) application as the key could be leaked. This type of key begins with the letter A.

2. Delegated type key which has an expiration time. It is commonly used in mobile or web application where you cannot use an API type key that could be leaked. The application would query a server part that will generate a Delegated type key using an API type key. The Delegated type key could now be used by the mobile or web page application without leaking the API type key. This type of key begins with the letter D.

3. User type key which are session based and can be retrieved after a successful authentication. This type of key is reserved to specific situations where the other types of key are not desirable. This type of key begins with the letter U.

4. Special type key which are for special cases where other types of keys cannot be used. This type of key is reserved to specific situations. This type of key begins with the letter S.

Each API key can be restricted to specific IP addresse(s). This is an optional but recommended security feature you should put in place if all your requests will be coming from a specific range. You can configure the allowed ranges from the eZmax administration console.

Each API Key can be configured to have specific permission(s) so we highly recommend to use the "Least privileges" principle. For example, instead of allowing all permissions to an API Key, you should perhaps create an API Keys each for each of your application having just the specific permissions needed. You can configure the API Key's permission in eZmax's administration console.

Request Signing is a process of signing the request with a Secret that is not transmitted over the Wire. The signing process improves security in case your API Key is leaked or during a MITM attack (Man in the Middle). It will also prevent request manipulation or replay attack. Since all requests must use https these kinds of attacks are hard to conduct but sometimes customers might not be aware their underlying library does not verify SSL Certs validity or that their application can disclose their API key if it's not well secured. It takes a bit of effort to sign requests but it's highly recommended to do so.

Mandatory requirements of signing varies by used key type. For API type keys (most common type), you can configure if signing is mandatory or not in eZmax's administration console. Delegated, User and Special type keys must sign requests otherwise requests will fail.

How to sign a request

To apply a signature to your request you will need to send 3 additional HTTP Headers to the request:

• Ezmax-Date
• Ezmax-Fingerprint
• Ezmax-Signature

Ezmax-Date

Ezmax-Date Is the date/time when you send the request. It needs to be a ISO 8601 formatted date/time. It's a format that supports timezones so you can either use your local timezone of GMT. Be aware certain implementation adds milliseconds to the formatted date which won't be accepted by the API (ex: Javascript's toISOString function).

There is a tolerance of ±5 minutes clock skew between the date/time you specify and the server's time so make sure your time is correct. Usage of a NTP server is recommended. Compute the date/time as close as possible to the actual sending of the request. For example, don't set the current time at the beginning of a long running script that sends 50 requests to the server with the same time/date as you might receive errors related to clock skew.

Examples:

• 2000-12-31T23:59:59Z
• 2000-12-31T23:59:59-05:00

Ezmax-Fingerprint

Ezmax-Fingerprint Is a fingerprint (aka hash) representing the request you are sending. Any alteration in any part of the request would produce a different fingerprint. The hash is computed using SHA256. Most programming languages offer an implementation of SHA256. To make sure your implementation is producing expected values, try to hash the value "foo", it should produce the value "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae".

To compute the Fingerprint, you'll need to concatenate the Method, the URL, the Body, the API Key and the Date. All these values will need to be separated by a line Feed caracter (\n). Make sure your Method is Uppercase (Shoud be "GET", not "Get" or "get"). Make sure your URL Scheme and Host or the URL are lowercase (Should be "https://www.example.com", not "HTTPS://WWW.EXAMPLE.COM"). Also make sure the the URI part of the URL is properly URL encoded (Should be "/Path%20with%20Spaces/?Key=Value%20with%20Spaces", not "/Path with Spaces/?Key=Value with Spaces". If the Body is empty (ex: GET request don't have a body), use an empty string.

Once the SHA256 hash is computed, prefix it with "v1=" which is future proofing version identifier.

Here is an example implementation in PHP:

public static function getFingerprintV1 ($sAuthorization, $dtDate, $sMethod, $sURL, $sBody = '') {
    $sContentToHash = "$sMethod\n$sURL\n$sBody\n$sAuthorization\n$dtDate";
    return 'v1='.hash('sha256', $sContentToHash);
}

Here are two examples of what a GET and POST requests Fingerprints could look like. You can validate if your algorithm work by using these sample values and comparing them to the expected values. In the example below the litteral "\n" should be replaced with a linefeed character.

GET\n
https://prod.api.appcluster01.ca-central-1.ezmax.com/rest/1/object/activesession/getCurrent\n
\n
ThisIsMyAuthorizationKey\n
2000-12-31T23:59:59Z

Expected result for Ezmax-Fingerprint (GET): v1=8f6f3ed75edb6e2cbe777b4fda5cab1a6adaebadc758780eb82c3d49934f354a

POST\n
https://prod.api.global.ezmax.com/1/module/sspr/sendUsernames\n
{"pksCustomerCode": "demo","fkiLanguageID": "2","eUserTypeSSPR": "Native","sEmailAddress": "example@domain.com"}\n
ThisIsMyAuthorizationKey\n
2000-12-31T23:59:59Z

Expected result for Ezmax-Fingerprint (POST): v1=6dbdbc26437f1216f9cd0068a4fc35c272a062b1f638c7557d497ebbf3702ded

Ezmax-Signature

Ezmax-Signature Is the actual signature proving the request was generated by the key owner using its secret. The signature is computed using HMAC and SHA512/256. Don't confuse SHA256, SHA512 and SHA512/256, these are 3 distinct algorithms. Most programming languages offer an implementation of HMAC with SHA512/256. To make sure your implementation is producing expected values, try to hash the value "foo" with the key "bar", it should produce the value "12af52e7e555f0813a143f49462423b0c37da6734ab1acb091c6069f010ce814".

To compute the Signature, you'll need to concatenate the Ezmax-Fingerprint, the API Key and the Ezmax-Date. The 3 values are concatenated WITHOUT separators. Then calculate the HMAC using SHA512/256 using your Secret as the key.

Once the HMAC-SHA512/256 hash is computed, prefix it with "v1=" which is future proofing version identifier.

Here is an example implementation in PHP:

public static function getSignatureV1 ($sAuthorization, $dtDate, $sFingerprint, $sSecret) {
    $sContentToSign = "$sFingerprint$sAuthorization$dtDate";
    return 'v1='.hash_hmac('sha512/256', $sContentToSign, $sSecret);
}

Here are two examples of what the GET and POST requests Signature would be. You can validate if your algorithm work by using these sample values and comparing them to the expected values. For the below examples, we have used the same API Key, Fingerprint and Date as in the Fingerprint section above. The only new variable is the Secret which is "ThisIsTheSecretAssociatedToTheAuthorizationKey" for this example.

v1=8f6f3ed75edb6e2cbe777b4fda5cab1a6adaebadc758780eb82c3d49934f354aThisIsMyAuthorizationKey2000-12-31T23:59:59Z

Expected result for Ezmax-Signature (GET): v1=3909792a7c950e8d2977fa389166c5cbd67807dada50a583cf83040894e717a4

v1=6dbdbc26437f1216f9cd0068a4fc35c272a062b1f638c7557d497ebbf3702dedThisIsMyAuthorizationKey2000-12-31T23:59:59Z

Expected result for Ezmax-Signature (POST): v1=62219af85fb56038bdd24666a775a88e05bfcd44ff59ac5d3f25d39e4d63b9ac

Wrapping up the examples

The whole process was detailed above but here is summary of what your http headers should look like to sign these example requests considering the following common variables:

Variable	Example value
Date	2000-12-31T23:59:59Z
Authorization	ThisIsMyAuthorizationKey
Secret	ThisIsTheSecretAssociatedToTheAuthorizationKey

For a GET request to https://prod.api.appcluster01.ca-central-1.ezmax.com/rest/1/object/activesession/getCurrent:

Authorization: ThisIsMyAuthorizationKey
Ezmax-Date: 2000-12-31T23:59:59Z
Ezmax-Fingerprint: v1=8f6f3ed75edb6e2cbe777b4fda5cab1a6adaebadc758780eb82c3d49934f354a
Ezmax-Signature: v1=3909792a7c950e8d2977fa389166c5cbd67807dada50a583cf83040894e717a4

For a POST request to https://prod.api.global.ezmax.com/1/module/sspr/sendUsernames with this body content = '{"pksCustomerCode": "demo","fkiLanguageID": "2","eUserTypeSSPR": "Native","sEmailAddress": "example@domain.com"}' :

Authorization: ThisIsMyAuthorizationKey
Ezmax-Date: 2000-12-31T23:59:59Z
Ezmax-Fingerprint: v1=6dbdbc26437f1216f9cd0068a4fc35c272a062b1f638c7557d497ebbf3702ded
Ezmax-Signature: v1=62219af85fb56038bdd24666a775a88e05bfcd44ff59ac5d3f25d39e4d63b9ac

We use standard HTTP Status Codes to return details about completed function calls.

You should always validate the HTTP response's status code before trying to read the content of the body. Our SDKs do this automatically. In each of the documented function, we document only the function's specific return code to facilitate the reading of the documentation. Even if a generic return code is not documented at the function's level, it could be returned by the API.

Generic return codes (Documented at the function's level)

HTTP Status Code	Meaning	Detail
200	OK	The request completed successfully and valid data was returned in the body
201	Created	The request completed successfully. Some elements were created and details about the created items was returned in the body
204	No Content	The request completed successfully. There was no need to return any data in the body
403	Forbidden	The request is not allowed to be executed. Look for detail about the error in the body
404	Not Found	The request failed. The element on which you were trying to work does not exists. Look for detail about the error in the body
422	Unprocessable entity	The request was syntactically valid but failed because of an interdependance condition. Look for detail about the error in the body

Generic return codes (Undocumented at the function's level)

HTTP Status Code	Meaning	Detail
400	Bad Request	The request does not meet specifications. For example: an invalid type for a variable, a value that does not pass validation or a protocol violation. Look for details about the error in the response's body
401	Unauthorized	The API Key is either not present, expired, invalid or inactive. It could also mean you are calling the API from an unauthorized IP address
403	Forbidden	The Provided API Key is valid, but it is not allowed to execute the request. Verify the Key's permissions
404	Not Found	Your request was sent to a URL that does not exist. Make sure you are calling the proper version number of the function and look for typos in the URL
405	Method Not Allowed	The URL is valid, but the Method is not allowed. For example, have you call a GET while the function expects a POST ?
429	Too Many Requests	Too many requests were received from your API Key/IP address. Make sure to optimize your requests or ask for a limit increase. For example, make a single request to create 100 objects instead of calling 100 requests each creating a single objet
500	Internal Server Error	This should never happen. There is either a temporary problem that should resolve quickly or an error you should report to technical support.
503	Service Unavailable	This should never happen. There is either a temporary problem that should resolve quickly or an error you should report to technical support

Custom return codes (Undocumented at the function's level)

These codes can only be generated for User type API Key. The API, Delegated and Special types keys will never return such codes. (See Authorization section for more information). Most users should not be concerned with these status codes.

HTTP Status Code	Meaning	Detail
351	Phone Validation required	(2FA) User needs to complete a Voice Call or SMS challenge
352	Question Validation required	(2FA) User needs to complete a question/answer challenge
353	Clause Acceptance required	User need to accept electronic signature terms and conditions
354	Computer Validation required	User's computer is not authorized
355	Password Change required	User must change it's password
356	Native Application Version Check	The user is not running the latest version of the native application

Webhook delivery successful code

These codes will be considered as a succesful delivery when they are returned by your webpage during a Webhook delivery.

HTTP Status Code	Meaning	Detail
202	Accepted	The request has been received but not yet acted upon. It is intended for cases where another process or server handles the request, or for batch processing.
204	No Content	The request completed successfully. There was no need to return any data in the body

A Webhook (also called a web callback or HTTP push API) is a way for your application to be notified of an event in real time.

For example, if you send a contract for signing and need to be notified as soon as it get signed.

You could program a loop to query the document status every 5 minutes for many days until you receive a response saying the document is signed. This is a bad approach as it will waste a lot of resources everytime you make a call to the API for no reason.

A better approach would be to configure a webhook in the eZmax's administration console to watch for a specific event. In this exemple, the event to monitor is "DocumentCompleted" from the module "Ezsign". This way, as soon as the document gets signed, a request will be made to YOUR server to let you know about the event that just happened.

When you configure eZmax to notify you of events, you must provide your server's URL and a fallback email address. The URL provided must use HTTPS for security reasons.

Types of Webhook:

Look for purple indicators with the word "EVENT" throughout the documentation to see currently available Webhooks events you can subscribe to. If you have a need for an event that is not available, please send a feature request to technical support.

Important:

• The event will be delivered using a POST request.
• Your server will need to reply with a HTTP Status Code 202 or 204 to let eZmax know you've accepted the message and we shall not try to deliver the message again. If the server does not respond with a 202 or 204 Code, the message will be sent over and over until all tries are exhausted.
• The 202 or 204 response must be returned in less than 30 seconds otherwise a timeout will occur and the event will be retried following the retry schedule.
• Make sure to secure your Webhook receiving URL to make sure someone does not send forged messages to your application. You can do this by providing a secure token in your URL, for example "?token=mysecuretoken1234", or by validating the webhook message's signature.

Testing

In eZmax's administration module, you'll find a "Test" button that you can use as many time as you need to test your server code easily with a sample event.

eZmax will attempt to deliver the event to your server instantly but will retry many times if your server does not respond successfully for some reason (see schedule below). After all attempts are exhausted, the event will be forwarded to the configured fallback email in the same format as the webhook. The email body will contain the JSON request in the same format as the webhook. This way, you'll be able to send the request to your server using Postman, Curl or similar tool.

Retry Delivery schedule

This is the approximate retry schedule. Since there is a 30 seconds timeout on each try, there could be a cumulative overhead up to 3½ minutes.

Minutes after previous step	Minutes after event	Method
N/A	0	HTTPS
1	1	HTTPS
5	6	HTTPS
15	21	HTTPS
15	36	HTTPS
15	51	HTTPS
15	66	HTTPS
0	66	Email

Failed attempt reporting

If you don't receive the event on the first attempt, there will be debugging information about each previous attempt in the body of the event. You'll be able to see the timestamp of each previous attempt and the return code returned by your server or a timeout indication if your server hasn't replied.

All notable changes to this project will be documented in this section.

Version numbers are using MAJOR.MINOR.PATCH numbering format for example 1.2.23

MAJOR will be incremented only if there is an incompatible breaking change. New distinct documentation and specification files will be published.

MINOR will be incremented only if a function becomes deprecated or deleted (after being deprecated in a previous version)

PATCH will be incremented everytime changes and additions are released.

You can always safely update to newer PATCH version if you stay in the same MAJOR.MINOR prefix.

You can safely update to a newer MINOR version as long as you don't jump more than a version at a time. For example, let say there is a function named "foo" in version 1.0.23. We might deprecate this function in version 1.1.1 but you can continue using it. We might decide to remove it in version 1.2.1 so then you would have a breaking ch