Creative Force External Post Gateway API allows you to connect your productions directly to a vendor via API, as opposed to an FTP server. For tech-forward vendors, this can be a great alternative option– allowing further flexibility in how your assets are sent and received.

Article Overview

This article will walk through the steps of setting up the API connection, both as a Creative Force user and as the external vendor.

Creative Force Setup

As a studio user, to set up the connection for your external vendors using the Gateway API, there are two steps that you need to follow.

Add New Vendor

To get started, we will need to add a new vendor. Head to Studio Settings → External Post-Production → select Add → then set the Connection Type to 'Gateway API.'

Under Connection Settings, you will need to add a Webhook URL– The webhook URL is provided by the vendor, and is effectively the URL that images are delivered to.

⚠️ Important: The Webhook Payload URL for External Post API cannot be the same as the Webhook URL you set up in the Webhook section of Gamma.

Once you have added the URL, click 'Save.' Creative Force will automatically generate a Secret Key in the field that populates below the Webhook field.

Copy the Secret Key and share it with the vendor so that they may proceed with verifying the Webhook URL. After completing the connection settings configuration, save and exit the vendor setup menu for now.

Register New App

For the next step, we will need to register a new application in Creative Force. This will generate a token for the vendor to be able to connect to the Gateway API, and allow them to make the necessary API calls to Creative Force to complete the post-production process.

Head to Studio Settings → Registered Apps → 'Register App'

Configuration Field	Function
Allowed Grant Type	You will have the option to register the app using one of two authorization grant types. Authorization Code Client Credentials
Application Name	Name the application.
Application Description	Describe the application to help identify it.
On Behalf User	Set an internal user that the application will take actions on behalf of.

⚠️ Important: The assigned user needs to have adequate permissions. For more information, see our Recommended API User article here.

If using 'OAuth Code Grant Flow, ' you can share the generated tokens with your vendor for them to access the Creative Force Gateway API. Please note that the tokens are only valid for 1 hour.

External Vendor Setup

This section of the article is intended for the External Vendors. In the following sections, we will run through the flow of how the tasks are being managed, processed, and the webhook callback details.

For more details regarding API call examples, you can refer to our Developer Documentation by visiting the link below.

Developer Documentation

List Tasks & Webhook Flow

Once a task is ready or rejected, Creative Force will call back to your webhook. To facilitate this, you will need to provide the Webhook URL to your client for them to add it to the CF system.

After successfully adding your Webhook URL to the system, your client will give you a Secret Key, and you will need to verify it.

In case of a missing webhook, you can use the listing API as a fallback method:

GET /v1/expost/tasks?postProductionVendorId=

Tasks Process Flow

Input

taskId
contentCreationTypeId (ecom/editorial)

Ecom Flow

Get task detail
- Task info
- Input assets and their expected output assets
- GET /v1/extpost/tasks/{taskId}
Get task annotations/markings
- Get all annotations from the external post, including both instruction & rejection notes.
- GET /v1/extpost/tasks/{taskId}/annotation
Download input & spec
- POST /v1/assets/bulk-get-assets
- POST /v1/files/bulk-get-files
- POST /v1/specs/bulk-get-specs

Get Product & Job information (optional)
- GET v1/jobs/{jobId}
- GET v1/products/{productId}

Start task
- PUT /v1/extpost/tasks/{tasksId}/start
- Only when you call this API will the task status be changed to 'In Progress'; otherwise, it will stay in 'To Do' until you return assets to Creative Force.
Retouching
- Based on 'expected outputs.'
Upload all output files to CF storage (AmazonS3)
- POST v1/assets/get-presigned-url
- PUT https://s3bucket.amazonaws/t/a.jpg?signature....example
Submit asset output mapping
- POST /v1/export/tasks/{taskId}/submit-assets
- Submit assets for external post tasks. All expected assets need to be submitted at once. For rejection cases, only correction assets are required.

Editorial Flow

Get task detail
- Task info
- Input assets and their expected output assets
- GET /v1/editorial/extpost/tasks/{taskId}
Get task annotations
- Get all annotations from external post, including both instruction & rejection notes.
- GET /v1/editorial/extpost/tasks/{taskId}/annotation
Download input & spec
- POST /v1/assets/bulk-get-assets
- POST /v1/files/bulk-get-files
- POST /v1/editorial/specs/bulk-get-specs

Get Project & Deliverable information (optional)
- GET v1/editorial/projects/{projectId}
- GET v1/editorial/deliverables/{deliverabletId}

Start task
- PUT /v1/editorial/extpost/tasks/{tasksId}/start
- Only when you call this API will the task status be changed to 'In Progress'; otherwise, it will stay in 'To Do' until you return assets to Creative Force.
Retouching
- Based on 'expected outputs.'
Upload all output files to CF storage (AmazonS3)
- POST v1/assets/get-presigned-url
- PUT https://s3bucket.amazonaws/t/a.jpg?signature....example
Submit asset output mapping
- POST /v1/editorial/export/tasks/{taskId}/submit-assets
- Submit assets for external post tasks. All expected assets need to be submitted at once. For rejection cases, only corrected assets are required.

New/Rejected Tasks

Headers are the same as shown in our Webhook article here.

Key	Type	Description
Action	string	The action that was performed. Can be one of the following: ExternalPostTaskReadyToWork ExternalPostTaskRejected
PayloadId	string	ID of the payload (GUID)
EventGroupName	string	The event group triggered. Value: ExternalPostTask
EventDatetimeUtc	long	Unix Timestamp (milliseconds) - the number of milliseconds since the Unix Epoch
TaskId	string	ID of the task (GUID)
ClientId	string	ID of the client (GUID)
JobId	string	ID of the job (GUID)
ProductId	string	ID of the product (GUID)
StepId	int	ID of the step
StepStatusId	int	ID of the Step Status
ProductionTypeId	int	Production Type ID
ContentCreationTypeId	int	Content Creation Type ID (Ecom or Editorial)
EditorialProjectId	string	Editorial Project ID (GUID)
EditorialDeliverableId	Array of string	List of ID of Editorial Deliverable (List of GUID)