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. |
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.
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-assetsPOST /v1/files/bulk-get-filesPOST /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}/startOnly 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
Submit asset output mapping
POST /v1/export/tasks/{taskId}/submit-assetsSubmit 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-assetsPOST /v1/files/bulk-get-filesPOST /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}/startOnly 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
Submit asset output mapping
POST /v1/editorial/export/tasks/{taskId}/submit-assetsSubmit 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:
|
PayloadId | string | ID of the payload (GUID) |
EventGroupName | string | The event group triggered.
|
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) |