Download OpenAPI specification:Download
This API expose all the functionnalities for the eZmax and eZsign applications.
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.
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.
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.
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.
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.
To apply a signature to your request you will need to send 3 additional HTTP Headers to the request:
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:
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 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
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.
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 |
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 |
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 |
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.
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.
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.
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 |
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