Proofs

Overview

Proofs are one of the fundamental building blocks of Ziflow.

It is important to note the distinction between how proofs are represented within the application vs the API:

  • Application: only the latest version of a proof visible to a logged in the user is displayed - if a proof has 4 versions, the user would see v4 with v1 to v3 sitting “behind” this latest version.
  • API: each version is its own proof object and versions are linked by use of a parent ID, thereby creating a linked list of proof objects.

Proofs have the following fields:

Field

Description

Read-only

id

Unique ID of a Proof

name

Given name of a proof.

Default: first source’s name

 

owner

Contact object: {contact: {...}}

 

created_by

Contact object: {contact: {...}}

created_at

Date and time the proof was created: '2012-02-22T02:06:58.147Z'

version

The version number of this proof

version_previous_id

The parent proof version’s proof ID

versions

[{version: '1', version-id: '5551'},

{version: '2', version-id: '5552'},

{version: '3', version-id: '5553'}]

source_files

[{id: 'file-id', type: 'file', name: 'sample_proof.pdf', size: byes},

{id: 'file-id', type: 'web', name: 'https://www.ziflow.com}, ...]

[{id: 'file-id', type: 'video', name: 'sample_proof.mp4', size: byes}]

status

The overall status of the proof:

‘uploading’ / ‘in_progress’ / ‘completed’ / ‘failed’

locked

true / false

Default: false

 

decision_status

The overall proof status calculated from all the stages:

null / ‘changes_required’ / ‘approved_with_changes’ /

‘approved’ / ‘not_relevant’

Default: null

public_link

Either null or 'https://ziflow.ziflow.io/proof/84n0ntlb1aapkdmchjgkcn9b8j'

stages

[{
 id: stage-id (*READ ONLY*),
 name: 'Project Managers',
 deadline: '2012-02-22T02:06:58.147Z',
 only_one_decision: true (*Default: false*),
 status: {see 'decision_status' field of proof for values} (*READ ONLY*),
 custom_email_subject: "Some subject" (Default: null),
 custom_email_message: "Some HTML message here<br/>And more text<br/>" (Default: "" )
 members: [{
   id: reviewer_id (*READ ONLY*),
   contact: {...} (READ ONLY),
   view: true (*Always true*),
   comment: false/true (*Default: false*):
   decision: false/true (*Default: false*):
   manage: false/true (*Default: false except if owner it's always true*),
   notification: ‘all_activity’ / ‘replies_to_my_comments’ / ‘decisions’ /
           ‘final_decision’ / ‘hourly_digest’ /
           ‘daily_digest’ / ‘disabled’ (*Default:all_activity*),
   progress: {notified='false/true', opened='false/true',
           commented='false/true', completed='false/true'
          (*READ ONLY*),
   decision_status: {see 'decision_status' field of proof for values} (*READ ONLY*),
   comments: 5 (*READ ONLY*),
   replies: 3 (*READ ONLY*)
 }, ...
}, ...]



 

lock_on_decisions

true / false

Default: false

allow_source_download

true / false

Default: false

secure_proofing

true / false

Default: false

require_sign_in

true / false

Default: false

download_link

Either null or URL to download the source file(s)

Get a proof

Method Details
HTTP methods GET
Response format json
Requires authentication Yes
Rate limited Yes

GET /v1/proofs/{id}

Returns information about a single proof version.

Required parameters How to use Description
API Token apikey=[key] query parameter Used to authenticate the request
Proof ID Used in the request URL (see above) Unique identifier of a specific proof version

Create a proof

Method Details
HTTP methods POST
Response format json
Requires authentication Yes
Rate limited Yes

POST /v1/proofs

Creates a new proof, version or batch of proofs in Ziflow with a simple HTTP POST.

The POST body must include:

  • At least one URL(s) to a file or a website page. We currently support downloading files using HTTP/HTTPS and S3. You may also specify a URL for web capturing by including the type: 'web' parameter.
  • At least one stage
  • At least one member that must be the owner of the proof

The proof will be created immediately and start processing. Once processed reviewers will be notified.

Required parameters How to use Description
apitoken apikey=[key] query parameter Used to authenticate the request
input

[{source: 's3://ziflowtesting/test.mov', type: 'file'},

{source: 'http://www.awesomeant.com/test.mov', type: 'file'},

{source: 'https://www.ziflow.com', type: 'web'}]

One or more input files or web pages.
stages

Provide at least one stage for the proof. See the GetProof JSON structure

 
members

Provide at least the owner of the proof as a member (reviewer) of the proof within the stage

 
Optional parameters How to use Description
combine

true/false

Default: false or forced to false for  the Starter edition

If true the input sources are combined into one proof in the order passed through.

The parameter is only available for the Business edition.

name Used in the request body

If provided and a single proof is being created, the name will be used for the proof name.

If a batch of proofs are being created, the system will ignore this field and use the input source’s name

version_previous_id Used in the request body If provided and the user has rights to create a new version, this proof will become the new version of the proof.
Any other proof property that is not Read-Only    

Update a proof

Method Details
HTTP methods PUT
Response format json
Requires authentication Yes
Rate limited Yes

PUT /v1/proofs/{id}

A specific, existing proof can be updated by making a PUT request on the URL for that proof. Only the fields provided in the data block will be updated; any unspecified fields will remain unchanged.

Helpful tips:

  • It is best to specify only those fields you wish to change.
  • When working with Stages and Members you are able to pass in only the id, which means we'll leave that object unchanged. This is useful when adding or deleting Stages or Members on the proof.

Returns the complete updated proof record.

Required parameters How to use Description
API Token apikey=[key] query parameter Used to authenticate the request
Proof ID Used in the request URL (see above) Unique identifier of a specific proof version
Proof JSON Used in the request body The proof JSON object that can be obtained from the GET method

Delete a proof

Method Details
HTTP methods DELETE
Response format json
Requires authentication Yes
Rate limited Yes

DELETE /v1/proofs/{id}

A specific, existing proof can be deleted by making a DELETE request on the URL for that proof.

Returns an empty data record.

Required parameters How to use Description
API Token apikey=[key] query parameter Used to authenticate the request
Proof ID Used in the request URL (see above) Unique identifier of a specific proof version