This guide will take you through the integration steps and key points to consider at each point. When you see Decision, this will prompt you to make a choice in your integration.
Here are some best practices to consider before and during the integration:
● You can use multiple development accounts for integration development and testing; simply let us know which these are;
● Create separate Ziflow accounts for each customer. This ensures different customer data won’t be inadvertently shared;
● Use webhooks instead of polling the Ziflow API for updates;
● When processing webhook events, reply immediately and handle the work on your end asynchronously.
Understanding Ziflow Accounts
We highly recommend using separate Ziflow accounts for each of your customers. You could even utilize a separate account for smaller business units. There is no commercial benefit to storing multiple customers’ proofs and data in one Ziflow account, and this avoids data being seen by the wrong user in your product if, for example, you have a bug that pulls the incorrect data from Ziflow.
By using separate accounts, you have an additional layer of security provided by Ziflow. Our platform allows the same user (email address) to be added to multiple Ziflow accounts, which makes switching and managing these accounts quite simple.
Furthermore, accounts can be linked using trust relationships, which then automatically share contacts between these accounts. It is especially useful when using multiple accounts for a single customer.
Understanding Ziflow Users
Ziflow has two types of contacts relevant to integration:
1. Users: these people can log in to Ziflow and create & manage proofs.
a. Users are paid licenses.
2. Guests: these are reviewers of proofs and are automatically added to your people list as they are added to proofs. They can not log in to Ziflow but can obtain secure tokens to access proofs.
a. Guests are free.
There is a third type called Lite Users, but this is out of scope when embedding review and approval in your application.
Decision: An important decision to make before starting development is whether you will:
A. use a generic API Admin user to make all API calls; or
B. make calls on behalf of users.
We recommend using a generic API user to make all the API calls. You will still be able to assign the ownership of proofs to other named users in the account, which is generally the biggest concern.
When sharing a proof with a user or guest, a unique tokenized URL is generated that identifies this reviewer on that particular proof. These URLs are not shared between reviewers or between a reviewer’s proofs.
Decision: The next question then facing developers is how to secure access to proofs if this unique URL was somehow shared. Relying on reviewers authenticating when accessing proofs can be challenging as you would generally want these reviewers to authenticate against your application, not Ziflow.
Instead of authentication, we recommend utilizing one-time URLs, which provide a mechanism of expiring proof URLs once used or a maximum of 24 hours. By using this method, you can secure access to proofs very easily.
1. Set up a Developer Account
First, you need a Ziflow account or multiple developer accounts. Register here. Do not use the generic API user here to sign up, but instead use an email address that will be the account owner going forward.
Once registered, send an email to firstname.lastname@example.org with the email address(es) used for your development account(s), and we will upgrade the account(s) to the Enterprise edition.
We will also arrange a call with you to discuss signing up for one of our partner programs.
2. User Management
Create the API User
As recommended, you can use a generic API user per Ziflow account to make all the API calls. Once your account is set up, log in and go to the People tab to add this user to the account.
Now login as this API user in a new browser session and grab their API key.
If the API user owns the proofs, you can skip this step. You only need to add named users if you need them to show up as the owners of a proof within the proof viewer. For most integrations, this is not required, but if you do, you can follow these steps.
Our API allows you to add verified users to the account, so these users will not receive an email to verify their accounts. You can do this by making a POST call to https://api.ziflow.io/v1/users and setting the field verified to
To ensure you remain compliant with SOC2 or similar, ensure that users must change their passwords on the first login to Ziflow by going to API Settings in your account and toggling “Require password change for auto-verified users” to enable it.
3. Subscribe to Webhooks
Before creating a proof, it’s important to subscribe to the required proof events so that we can notify you of when these occur. You can subscribe to webhooks either through the API or through the UI.
NOTE: You should, at a minimum, subscribe to the “processed” event webhook and be able to handle this. More on processing proofs in the next section.
4. Creating Proofs
When creating a proof in Ziflow, we process the original source files or links regardless of their type (static, video, rich media, or websites) to a standard, optimized format for review and approval.
Decision: if you know who the reviewers are at proof creation time, you can add them here. If reviewers need to be added as and when they access the proof, you can use the endpoint to add a reviewer as and when needed.
The processing time primarily depends on the following factors:
● Static files: number of pages and page dimensions;
○ Multi-page static documents are processed in parallel to ensure your proof is ready as quickly as possible;
● A/V files: length of the video.
This processing forms an integral part of the solution, allowing proofs to load fast when reviewing in our Ziflow Viewer instead of users having to download potentially large source files.
When creating a proof using the Ziflow API, you need to consider the following: files are not uploaded to Ziflow but rather downloaded by our systems.
● When calling the API to create a proof, you will provide a location to your file(s) that we can access and download.
● We currently support
S3 input locations.
● Our recommendation is to use HTTPS, and if using
S3 - utilize presigned URLs.
Proof Creation Steps
Creating a proof is quite simple and requires only a single API call. Please review our help documentation to understand how automated workflow and other proof settings can be utilized.
Steps to create a proof:
1. Ensure the files for the proof are available;
2. Ensure you have subscribed to the processed webhook as discussed above;
3. Make a POST request to
https://api.ziflow.io/v1/proofs with the required body;
a. Ziflow will start creating the proof asynchronously;
4. When the proof has been processed, we make a
POST request to the endpoint registered to handle this event;
a. At this point, the proof is now ready for review.
5. Embedding the Proof Viewer
Embedding the Ziflow Proof Viewer is as simple as using an iFrame and providing a reviewer’s one-time URL as the
The same Ziflow Viewer will adapt based on the content being reviewed and is also responsive in design which means the viewer interface will adjust based on the dimensions you provide it.
If you need to add a reviewer before displaying the proof, you can call the endpoint to add a reviewer and then call to obtain their one-time URL.
6. Branding the Proof Viewer
7. Displaying a List of Proofs
/proofs/search API endpoint can be used to return the proofs you want to list in your application. You can filter these proofs just as you would inside our UI.
NOTE: The endpoint furthermore allows you to limit the data returned by passing in the
fields you require since passing back all the data can take additional time.