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.

Best Practices

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 for 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.


Securing Proofs

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 an email address that will be the account owner going forward.

Once registered, send an email to partners@ziflow.com 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.

Adding Users

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 true.

To ensure you remain compliant with SOC2 or similar, ensure that users are required to 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.

Require password change for auto-verified users setting in Ziflow

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

Proof Processing

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.

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 HTTP / HTTPS and 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 src.

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

In the Settings section of an account, you can brand the Ziflow Viewer and emails (if you choose to use ours) and also switch on/off numerous buttons/features within the Ziflow Viewer.


7. Displaying a List of Proofs

Our /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.

Did this answer your question?