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

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: bytes

},

{

id: 'file-id',

type: 'web-static',

name: 'https://www.ziflow.com},

size: null

},

{

id: 'file-id',

type: 'web-interactive',

name: 'https://www.ziflow.com},

size: null

},

{

id: 'file-id',

type: 'file',

name: 'sample_proof.mp4',

size: bytes

}

]

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

[

{stage1_object},

{stage2_object}

]

List of stage objects - see table below for detailed description

 

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)

suppress_all_emails

true / false

Default: false

 

If trueZiflow will not send any emails regarding this proof.

The only emails that can be triggered are the emails that are sent when using the "Remind" function within the web application.

 

workflow_template

{

"id": template id,

"name": template name

}

Default: null

Applied workflow template object

 

Detailed description of Stage object:

Field Description  Read-only
 id stage ID  
name

Stage name

Default: "Stage 1"

 
deadline

Deadline date and time calculated when stage starts

i.e. '2012-02-22T02:00:00.000Z'

Default: null

  
only_one_decision

true / false

Default: false

 
status see 'decision_status' field of proof for allowed values  
custom_email_subject

"Some subject"

Default: null

 
custom_email_message

"Some subject"

Default: null

 
members

[

{member1_object},

{member2_object}

]

 

List of members/reviewers - see detailed member object description in table below

 
lock

See detailed description in table below

 
stage_trigger

See detailed description in table below

 

Detailed description of Member object:

Field Description  Read-only
id reviewer's id  
contact  Contact object  
email reviewer's email  
view 

true

Always true

  
comment

true / false

Default: true

 
decision

true / false

Default: false

 
manage

true / false

Default: false except proof owner

 
notification

‘all_activity’ / 'replies_to_my_comments’ / ‘decisions’ / ‘final_decision’ / ‘hourly_digest’ / ‘daily_digest’ / ‘disabled’

Default: 'all_activity'

 
progress

{

notified = true / false,

opened = true / false,

commented = true / false,

completed = true / false

}

proof_url

'https://subdomain.ziflow.io/proof/1234'

visible only for proof owner or admin

decision_status see 'decision_status' field of proof for allowed values
comments 5
replies 3

Detailed description of Lock object:

Below fields can be edited only on Enterprise edition.

In case lock type - next_stage_starts, parent stage can be defined only:

- by unique stage_name during proof creation

- by stage_id during proof update

Field  Description  Read-only
 type

allowed values:

'manual' / 'on_completion' / 'all_dependent_stages_started' / 'next_stage_starts'

Default: null

 

next_stage_name

Has value only if type is 'next_stage_starts'

Default: null

 
next_stage_id

Has value only if type is 'next_stage_starts'

Default: null

 

Stage trigger object details:

Content of stage_trigger object, except Deadline object, can be edited only on Enterprise edition.

 

Field Description Read-only
trigger_id Tirgger id  
trigger Trigger object described in table below  
deadline Deadline object described in table below  

Trigger object details:

Parent stage can be defined only

- by unique stage_name during proof creation

- by stage_id during proof update

Field Description Read-only
type

allowed values:

'immediately' / 'manual' / 'on_completion' / 'on_approved' / 'on_approved_or_approvedwithchanges' / 'deadline_reached'

Default: 'immediately'

 
parent_stage_id

Has value for all types except 'immediately' and 'manual'

Default: null

 
parent_stage_name

Has value for all types except 'immediately' and 'manual'

Default: null

 

 Deadline object can be used to set stage deadline:

Field Description Read-only
days

number of business days to calculate deadline once stage starts (0=today)

Default: null   

 
time

Time in UTC i.e. "09:00:00.000Z"

Time is required only if days=0 and has to be at least 1 hour ahead from stage start

Default: null

 

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
Sample GET response body

{

"id": "7c7f0b55-0a34-4fc7-a009-798051a22b61",
"name": "Sample proof",
"owner": {
"id": "ec2b4aee-42b6-42f8-92cd-264d1c9d4d0c",
"type": "user",
"first_name": "Kyle",
"last_name": "Logan",
"email": "user.name@domain.com",
"roles": [
"admin",
"billing",
"user",
"manager"
],
"phone": "+4407400142385",
"company": "QAtesting",
"tenant": {
"tenant_id": "f05ad1cc-a73c-4aa0-a03d-7f041b87bd51",
"subdomain": "qatesting",
"company_name": "QAtesting"
},
"verified": true,
"blocked": false,
"timezone": "Europe/London"
},
"created_by": {
"id": "ec2b4aee-42b6-42f8-92cd-264d1c9d4d0c",
"type": "user",
"first_name": "Kyle",
"last_name": "Logan",
"email": "user.name@domain.com",
"roles": [
"admin",
"billing",
"user",
"manager"
],
"phone": "+4407400142385",
"company": "QAtesting",
"tenant": {
"tenant_id": "f05ad1cc-a73c-4aa0-a03d-7f041b87bd51",
"subdomain": "qatesting",
"company_name": "QAtesting"
},
"verified": true,
"blocked": false,
"timezone": "Europe/London"
},
"created_at": "2018-05-02T13:22:09.270Z",
"version": 1,
"versions": [
{
"version": 1,
"version_id": "7c7f0b55-0a34-4fc7-a009-798051a22b61"
}
],
"source_files": [
{
"id": "e6e35bd8-f746-459e-9ccb-c00832e76303",
"type": "file",
"name": "allgroups.PNG",
"size": 50662
}
],
"status": "in_progress",
"locked": false,
"decision_status": null,
"public_link": "https://qatesting.com/proof/c69q0ebom0sockr3vrl1k2t709",
"stages": [
{
"id": "42ae3500-115b-41b0-b148-b19b2fdedd99",
"name": "Stage 1",
"deadline": "2018-10-02T08:00:00.000Z",
"only_one_decision": false,
"status": null,
"members": [
{
"id": "32c30222-6c64-4c0e-8d62-378063216bcf",
"contact": {
"id": "ec2b4aee-42b6-42f8-92cd-264d1c9d4d0c",
"type": "user",
"first_name": "Kyle",
"last_name": "Logan",
"email": "user.name@domain.com",
"roles": [
"admin",
"billing",
"user",
"manager"
],
"phone": "+4407400142385",
"company": "QAtesting",
"tenant": {
"tenant_id": "f05ad1cc-a73c-4aa0-a03d-7f041b87bd51",
"subdomain": "qatesting",
"company_name": "QAtesting"
},
"verified": true,
"blocked": false,
"timezone": "Europe/London"
},
"email": "user.name@domain.com",
"view": true,
"comment": true,
"decision": true,
"manage": true,
"notification": "all_activity",
"progress": {
"notified": true,
"opened": true,
"commented": true,
"completed": false
},
"proof_url": "https://qatesting.com/proof/r65ajt5vteqee8dbc34j4u467l",
"decision_status": null,
"comments": 2,
"replies": 3
},
{
"id": "32c30222-6c64-4c0e-8d62-378063216bcf",
"contact": {
"id": "ec2b4aee-42b6-42f8-92cd-264d1c9d4d0c",
"type": "user",
"first_name": "Adam",
"last_name": "Thomson",
"email": "manager.name@domain.com",
"roles": [
"user",
"manager"
],
"phone": "+4407400142565",
"company": "QAtesting",
"tenant": {
"tenant_id": "f05ad1cc-a73c-4aa0-a03d-7f041b87bd51",
"subdomain": "qatesting",
"company_name": "QAtesting"
},
"verified": true,
"blocked": false,
"timezone": "Europe/London"
},
"email": "manager.name@domain.com",
"view": true,
"comment": true,
"decision": true,
"manage": true,
"notification": "all_activity",
"progress": {
"notified": true,
"opened": true,
"commented": true,
"completed": true
},
"proof_url": "https://qatesting.com/proof/r65ajt5vteqee8dbc34j4u467l",
"decision_status": "approved",
"comments": 2,
"replies": 4
}
],
"custom_email_subject": "Important proof to review",
"custom_email_message": "Hi, there is very important proof to review",
"lock": {
"type": null,
"next_stage_name": null,
"next_stage_id": null
},
"stage_trigger": {
"trigger_id": "aac17fdb-b922-4194-b7c4-9dbcd627ee4b",
"trigger": {
"type": "immediately",
"parent_stage_id": null,
"parent_stage_name": null
},
"deadline": {
"days": 5,
"time": "08:00:00.000Z"
}
}
},
{
"id": "b8db7773-5b96-45e2-88bb-2faa0b46f530",
"name": "Stage 2",
"deadline": "2018-10-09T13:30:45.134Z",
"only_one_decision": false,
"status": null,
"members": [
{
"id": "624bdf28-79ab-443d-b2ef-d4ec68b17ee2",
"contact": {
"id": "6f103cd2-0791-4405-b003-7f6cf9cc11cf",
"type": "user",
"first_name": "Admin",
"last_name": "User",
"email": "admin.name@domain.com",
"roles": [
"admin"
],
"phone": null,
"company": "QAtesting",
"tenant": {
"tenant_id": "f05ad1cc-a73c-4aa0-a03d-7f041b87bd51",
"subdomain": "qatesting",
"company_name": "QAtesting"
},
"verified": true,
"blocked": false,
"timezone": "Europe/London"
},
"email": "admin.name@domain.com",
"view": true,
"comment": true,
"decision": false,
"manage": true,
"notification": "all_activity",
"progress": {
"notified": true,
"opened": false,
"commented": false,
"completed": true
},
"proof_url": "https://qatesting.com/proof/hfp0439049v3ohqkrgq4ke6im4",
"decision_status": null,
"comments": 0,
"replies": 0
}
],
"custom_email_subject": null,
"custom_email_message": null,
"lock": {
"type": null,
"next_stage_name": null,
"next_stage_id": null
},
"stage_trigger": {
"trigger_id": "aef17fdb-b942-4194-b7c4-9dbcd627rg6t",
"trigger": {
"type": "immediately",
"parent_stage_id": null,
"parent_stage_name": null
},
"deadline": {
"days": 10,
"time": null
}
}
}
],
"lock_on_decisions": true,
"allow_source_download": false,
"secure_proofing": false,
"require_sign_in": false,
"download_link": null,
"suppress_all_emails": false,
"workflow_template": null

}

Get latest version of proofs

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

GET /v1/proofs

Returns a paginated list of proofs with a maximum of 100 proofs. It returns the latest version the user making the API call can see. A list is sorted from the newest to the oldest proofs.

 Required parameters  How to use  Description
 API Token  apikey=[key] query parameter  Used to authenticate the request.
 Required parameters  How to use  Description
 count    Specifies number of records to return with max=100
 page    Used for pagination, starting at 1
Response structure

{

"proofs": [

{ proof object },

{ proof object }

],

"count": 50,

"page": 1,

"has_more": true

}

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 also with parametrized URL.  You may also specify a URL for live website or web capturing by including the type: 'web-interactive' or 'web-static'.
  • 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.

Returns proof_id in response body

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

Used in the request body

[

{

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

},

{

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

},

{

source: 'https://www.ziflow.com',

type: 'web-static'

},

{

source: 'https://ziflow.io',

type: 'web-interactive'

}

]

One or more input files or web pages.
stages

Used in the request body

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

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

 
Optional parameters How to use Description
combine

true/false

Default: false or forced to false for  the Starter edition and for audio, video and web-interactive proofs as well.

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

The parameter is only available for the Business and Enterprise 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 is being created, the system will ignore this field and use the input source file'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.
owner_email Used in the request body

If the field is not provided, the owner of the proof will be the user performing the API call. Another email address can be supplied and we'll make this user the owner.

 

The email address needs to be an active user in the same account and reviewer in any proof stage.

Any other proof property that is not Read-Only    
Sample POST proof request body

{

"version_previous_id": "e174185d-a95e-4f57-a12c-ceae6c77dc39",

"name": "Sample proof",

"combine": true,
"input": [
{
"source": "https://yourpage.com/somefile.pdf?foo=bar",
"type": "file"
},
{
"source": "https://yourpage.com/someotherfile.pdf",
"type": "file"
}
],
"stages": [
{
"name": "Stage 1",
"deadline": "2018-10-02T13:30:00.000Z",
"only_one_decision": false,
"members": [
{
"email": "user.name@domain.com",
"view": true,
"comment": true,
"decision": true,
"manage": true,
"notification": "all_activity"
},
{
"email": "manager.name@domain.com",
"view": true,
"comment": true,
"decision": true,
"manage": true,
"notification": "all_activity",
}
],
"custom_email_subject": "Important proof to review",
"custom_email_message": "Hi, there is very important proof to review"
},
{
"name": "Stage 2",
"deadline": "null",
"only_one_decision": false,
"members": [
{
"email": "admin.name@domain.com",
"view": true,
"comment": true,
"decision": false,
"manage": true,
"notification": "all_activity",
}
],
"custom_email_subject": null,
"custom_email_message": null
}
],
"lock_on_decisions": true,
"allow_source_download": true,
"secure_proofing": false,
"require_sign_in": false,
"suppress_all_emails": false,
"owner_email": "manager.name@domain.com"

}

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
 Optional parameters  How to use  Description
 owner_email  Used in the request body  

If the field is not provided, the owner of the proof will be the user performing the API call. Another email address can be supplied and we'll make this user the owner.

 

The email address needs to be an active user in the same account and reviewer in any proof stage.

Sample PUT proof body
Example with update proof name, add reviewer to stage, add new stage and change proof owner

{

"name": "Update proof name",

 "stages": [

{

"id": "42ae3500-115b-41b0-b148-b19b2fdedd99",

"only_one_decision": true,

"members": [

{

"id": "32c30222-6c64-4c0e-8d62-378063216bcf",

},

{

"id": "32c30222-6c64-4c0e-8d62-378063216bcf",

 }, 

{

"email": "reviewer.update@domain.com",

"decision": true

]

},

{

"id": "b8db7773-5b96-45e2-88bb-2faa0b46f530"

},

{

"name": "New stage",

"members":[

{

"email": "new.owner@domain.com",

}

]

}

],

"allow_source_download": true,

"owner_email": "new.owner@domain.com"

}

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

Delete all proof versions

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

DELETE /v1/proofs/{proof_id}/allVersions

Deletes all versions of given proof.

Returns 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

Update a reviewer's decision

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

POST v1/proofs/{proof-id}/reviewers/status

or

PUT v1/proofs/{proof-id}/reviewers/status

Both requests work exactly the same way: send/update reviewer's status - make decision or complete review.

Returns a reviewer/member object.

Sample POST reviewer's decision body

{

"reviewer_id": "e4d55eb7-ebe1-450f-bfb5-78f1fe66c00a",

"decision": "approved_with_changes"

}

Sample POST reviewer's status body

{

"reviewer_id": "e4d55eb7-ebe1-450f-bfb5-78f1fe66c00a",

"completed": true

}

 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
decision 'pending' / 'changes_required' / 'approved_with_changes' / 'approved' / 'not_relevant'  Reviewers decision on the proof.
completed  true/false  Status for non-decision reviewers.
 Optional parameters  How to use  Description
 reviewer_id  Used in the request URL ID of the reviewer performing the action 

Create a proof from a Workflow Template

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

POST /v1/proofs

 

Available only on Enterprise edition.

Allows creating proofs based on Workflow templates.

Request body requires the same parameters as standard proof creation.

Stages property in JSON body is required as placeholder (see code example below) - it will be ignored and replaced by stages defined in Workflow template. Workflow template can be used only when it's active.

 Required parameters  How to use  Description
 API Token  apikey=[key] query parameter Used to authenticate the request 
 workflow_template

"workflow_template":

{

"id": template id

}

 Proof will be created based on this Workflow Template.
Sample POST request body
Sample JSON creating proof from workflow template

{

"name": "Proof from workflow template",

"input": [
{
"source": "https://yourpage.com/somefile.pdf?foo=bar",
"type": "file"
}
 
],
"stages": [
{
"name": "Stage 1",
"members": [
{
"email": "user.name@domain.com",
]
}
],
"lock_on_decisions": true,
"allow_source_download": true,
"secure_proofing": true,
"require_sign_in": false,
"suppress_all_emails": false,
"workflow_template":{
"id": "218422ef-8b96-4cc2-9a30-d0a91da2082b"
}

}

Response structure
Response contains workflow template object with id and name and proof id.

[

{
"workflow_template": {
"id": "d6f3793c-81c6-4afd-8aa2-06c22e43e002",
"name": "Proof template"
},
"id": "ed8e2b95-4ef3-4912-a896-015dd626fd83"
}

]

Get all Workflow Templates

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

GET /v1/workflowtemplates

 

Available only on Enterprise edition.

API method that returns all workflow templates in the account. Only users with admin rights can access this data.

Response contains array with workflow template objects. 

 Required parameters  How to use  Description
 API Token apikey=[key] query parameter Used to authenticate the request.
Sample response

[

{

"id": "14f19fba-6fea-4df6-b0d4-59d4827a4ac5",

"name": "New Template 2",

"owner": { Contact object },

"created_by": { Contact object },

"created_at": "2018-06-11T14:03:15.000Z",

"stages": [

{ Stage objects with placeholder for proof owner:

"members": [

{

"id": "caed8ff2-644d-4b00-a333-7c8bc690f320",

"contact": null,

"email": "",

"view": true,

"comment": true,

"decision": true,

"manage": true,

"notification": "all_activity",

"progress": null,

"proof_url": null,

"decision_status": null,

"comments": 0,

"replies": 0

}

]

}

],

"active": true

}

]