You can embed Ziflow’s review and approval workflow directly into your applications using Ziflow API.

This article walks you through how to:

• Set up and configure Ziflow accounts for development and production
• Decide how to authenticate API calls and manage users
• Secure proofs and viewer access
• Handle webhook notifications
• Embed and brand the proof viewer

You’ll see Decision prompts to help you choose the best architectural approach for your implementation.

If you’re looking to connect Ziflow with third-party tools such as Slack, Adobe, or Asana, see Integrations.

This guide is for:

• Partners integrating Ziflow as a white-label or embedded component
• Developers building a custom product workflow powered by the Ziflow API
• Platform engineers who need to manage multiple customer accounts or tenants

What you’ll need

• A developer account 
• Familiarity with RESTful APIs and authentication
• The ability to handle webhooks and embed iFrames

Best practices

Here are some best practices to consider before and during the integration:

• Use multiple development accounts for integration development and testing. Notify Ziflow which ones you'll use.
• Create separate Ziflow accounts for each customer to avoid accidental data sharing.
• Use webhooks instead of polling the Ziflow API for updates.
• When processing webhook events, reply immediately and handle the work on your end asynchronously.

Manage customer accounts

Use separate accounts for each customer, or even for individual business units.

• Avoid storing multiple customers’ data in a single account. It has no commercial benefit, and it reduces the risk of accidental data exposure.
• Each user (email) can belong to multiple accounts, making switching and managing these accounts simple.
• Accounts can be linked using trust relationships, automatically sharing contacts between them. This is useful when using multiple accounts for a single customer.

Manage users and API access

Contact types

• Users: Licensed users who can log in, create, and manage proofs (paid)
• Guests: Reviewers automatically added when invited to a proof. They can’t log in but can access proofs via secure token URLs (free)
  
  Note: Enterprise edition can also have Lite Users, which are out of scope.

Decision: API user approach

Choose how API calls are made:

• Generic API user (recommended): One user handles all API calls. Proofs can still be assigned to named users. 
• Per-user API calls: Calls are made on behalf of individual users.

Secure proof access

• Each reviewer receives a unique tokenized URL for each proof.
• URLs are one-time or expire within 24 hours, mitigating accidental sharing.
• Avoid relying on Ziflow authentication. Authenticate reviewers against your own system instead.

Decision: secure access if URL is shared

Relying on reviewers authenticating when accessing proofs can be challenging.  These reviewers should authenticate against your application, not Ziflow.

Ziflow recommends using one-time URLs which expire URLs once used or within a maximum of 24 hours. For more information, see the Ziflow API documentation.

Set up a developer account

To set up a Ziflow account or multiple developer accounts.

1. Register here. Do not use the generic API user to sign up. Use an email address that will be the account owner going forward. We recommend an address that is associated with a role and not a person to avoid losing access if a person leaves your organization.
2. 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.

Create the API user

As recommended, you can use a generic API user for each Ziflow account to make all the API calls.

1. Once your account is set up, log in and go to the People tab to add this user to the account.
2. Log in as this API user in a new browser session and get their API key.

Add 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. For most integrations, this is not required, but if you do, you can follow these steps.

Add named users (optional)

Add verified named users if you want them to appear as proof owners. These users will not receive an email to verify their accounts. 

POST https://api.ziflow.io/v1/users
{
"email": "user@example.com",
"verified": true
}

Go to Settings > API Settings > General in your account and enable Ask user to change their password when they sign in for SOC2 compliance. This prompts the user to change their passwords on the first login to Ziflow.

Allow iframe embedding

Use the Allow embedding the Ziflow application setting to control which parts of the app (if any) are allowed to be embedded. See Configure general security settings.

Subscribe to webhooks

Before creating a proof, subscribe to proof-related events so Ziflow can notify you when they occur.
At a minimum, subscribe to the “processed” event webhook so your app knows when proofs are ready.

Subscriptions can be made through the API or the UI.

Create proofs

Ziflow processes source files (static, video, rich media) into optimized formats for review, regardless of their type.

Decision: Add reviewers now or later?

• Add at creation: If you know reviewers in advance
• Add later dynamically: If reviewers join as needed, you can use the endpoint to add a reviewer when needed

Processing considerations

Processing is an integral part of the solution, allowing proofs to load quickly in the Proof Viewer instead of users having to download potentially large source files.

• Static files: Processing time depends on number of pages and dimensions. Multi-page docs are processed in parallel.
• Video files: Processing time depends on duration of the video.

Source file requirements

When creating a proof using the Ziflow API, you need to consider that the files are not uploaded to Ziflow, but instead downloaded by our systems.

• Provide accessible file URLs; Ziflow downloads them directly
• Supported sources: HTTP/HTTPS and S3 
• Recommended: Use HTTPS whenever possible, and for S3 use presigned URLs

Proof creation steps

Creating a proof requires a single API call. 

1. Ensure files are available.
2. Confirm subscription to the processed webhook.
3. POST to:

https://api.ziflow.io/v1/proofs

Ziflow processes asynchronously. When the proof is processed, Ziflow makes a POST request to the endpoint registered for this event, and the proof is ready for review.

Embed the Proof Viewer

Use an <iframe> with the reviewer’s one-time URL as the src.

• The Proof Viewer adapts to the content type and frame size.
• To add a reviewer before embedding, call the endpoint to add a reviewer and then call to obtain their one-time URL.

Brand the Proof Viewer

In the Settings section of your Ziflow account, you can:

• Brand the Proof Viewer and emails
• Enable or disable buttons and features in the Proof Viewer

Display a list of proofs

• Use the/proofs/search API endpoint to list proofs.
• Apply filters just like the Ziflow UI.
• The endpoint allows you to limit the data returned by passing in the fields to improve performance.