Introduction

Good2Go provides an HTTP-based API for integrating with your existing backend. Many functionalities of Good2Go are accessible through these REST APIs. You can use any scripting language to call these APIs. These APIs virtually allow Good2Go to be driven by external systems like an MIS solution, or drive downstream applications such as workflow automation solutions.

This documentation aims to provide necessary information you need to work with our API.

Preface

In Good2Go, everything centers around jobs, their properties, and associated actions. A job can either be a file or a folder.

The first step for an API consumer is to understand four fundamental actions:

• Creating a job, especially a file;
• Retrieving a list of available jobs;
• Obtaining intrinsic properties of a job; and
• Creating a task associated with a job.

The two most frequently used APIs are: (1) retrieving a list of available jobs, and (2) obtaining intrinsic properties of a job. To get the list of jobs, simply use the API endpoint: api/v1/jobs. This will return a list of jobs already available on Good2Go for the given user.

If the GUID of the job is known then intrinsic properties of job can be retrieve using API: api/v1/jobs/{job_guid}. Where in {job_guid} need to be replaced with GUID of the job. Various properties returned by this API are documented in the respective section.

There are APIs to upload and download the document associated with a job.

There are APIs to add task to a job and send reminders, or update existing task.

There are also few APIs to retrieve past history of the job, get list of reminders, get the customer associated with the job, etc.

Job and actions

Each job is associated with several properties. Some properties are fundamental properties of job. Through API, these properties can be read and updated. There are also optional properties which are available (readonly) only when certain condition is meet. The following fundamental properties are worth to mention here:

• File or folder name.
• Alternative text for reference.
• Job is a file or folder.
• Current status of the job.
• To whom the job being assigned for a given task.
• The end customer of the job (especially print buyer).
• The size of the file.
• The mime type of the file.
• The current file version.
• Some more information about given job type (pdf, image etc.).
• Due date.

Also several actions can be performed on jobs, such as sending a review request to customer, or sending email for quote approval etc. They are defined in Job notifications section.

Job status

There are eight predefined job statuses:

• approved,
• change-requested,
• done,
• expired,
• new,
• pending,
• processing, and
• rejected.

Expired, pending, and processing are internal job statuses, and they can't be set by any API method call.

Expired

Job status is set to expired when job is idle for a predefined time period. A job once expired can be reverted to previous status by simply modifying any properties of the job.

Pending

When a task is initiated, job status is automatically set to pending. For example, when a job is sent for review, its status is set to pending.

Processing

When a print buyer or reviewer opens the task-related page, e.g., the review page, the job status is automatically set to processing.

Alternative text

Every job has an alternative text (alt_text) field. The alternative text field can be used to save a description or information about a job, e.g., MIS order number.

Webhook

Good2Go service internally can notify about a precise event on job. This is a great way to received an event rather than continuously polling the job data from Good2Go to identify changes. Webhook are efficient way to receive events. Webhooks can be used as alerts to keep your workflow or your applications in sync with jobs inside Good2Go. Good2Go webhook can send events to any publicly accessible server.

Authentication and Security

You can include HTTP Basic Authentication to the endpoint URL to verify the request is coming from Good2Go servers.

The webhook endpoint are always called from following IP address:

• 54.144.219.59
• 3.93.121.127

You can configure endpoint to refuse other IP addresses.

Retry

Good2Go will attempt to send this notification to the specified endpoint(s). The endpoint must respond with a 2XX status code in timely manner. If failed to receive correct status, Good2Go will try three (3) more times after 30 seconds, 5 minutes and 15 minutes respectively.

Payload

It sent only JSON data. The common structure of the event payload is as follows:

• data: Data specific to the event, if any.
• event_type: Event type in dotted event type notation.
• job: Good2Go job structure.
• job_guid: The GUID of the job for which the event is sent.

For the structure of job parameter refer to Get job information. The data parameter is specific to the event.

Event Type

• jobs.anonymous.reminder
• jobs.created
• jobs.label.changed
• jobs.preflighted
• jobs.review.approval
• jobs.review.message
• jobs.review.notify
• jobs.status.changed
• jobs.task.completed
• jobs.task.created
• jobs.task.email.reply
• jobs.version.changed

Method

Endpoint is always called with HTTP POST request.

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

The authentication key can be retrieved after logging to Good2Go Review application. Visit to integration page, go to API Keys section, register an application name and click Create API token.