Skip to main content
External Post API Guide
Ha Ngan Nguyen avatar
Written by Ha Ngan Nguyen
Updated over 7 months ago

Creative Force External Post Gateway API allows you to connect your CF instance directly to your vendor via an API as opposed to FTP or Box.com. For Tech-focused vendors, this can oftentimes be a great option to have a direct link between CF and themselves as opposed to relying on an intermediary data point like an FTP

This article will guide you through the steps of setting this up both as a CF customer and the external vendors.

Creative Force Customer Set Up

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

Step 1: Add the vendor to your external-post production vendors list

  • Studio Settings -> Post-production -> External Post -> Add

  • Add the Webhook URL from your vendor here. When a task is ready for the External Post step, CF will callback to the webhook of the vendor. We will talk in detail about this later in the article.

  • Once you added the Webhook URL, click ‘Save’. Creative Force will automatically generate a secret key. You will then need to give the secret key to your vendor for them to verify the Webhook URL.

After adding the vendor here, you can assign this vendor to your workflows and style guides.

Note: the Webhook payload URL for external post API cannot be the same as the webhook URL you set up in the Webhook section in Gamma.

Step 2: Generate a token for the vendor to be able to connect to CF Gateway API

  • Register the application with Creative Force. Go to Studio Settings -> Integrations -> Registered apps.

Then, click ‘Register App’. You will have the option to register an app using Authorization Code Grant Flow or Client Credentials Flow.

Click here to learn more about using Authorization Code Grant Flow.

Click here to learn more about using Client Credentials Flow.

Once you have the tokens, you can share them with your vendor for them to access CF Gateway API. Please note that the tokens are valid for 1 hour.

External vendors

For the external vendors, this part of the article will run through the flow of how the tasks are being managed and processed and the Webhook callback detail.

For more details regarding the API call examples, you can refer to our API document here.

List of tasks or Webhook flow

Once a task is ready or rejected, CF will callback to your webhook so you will need to provide your Webhook URL to your client, for them to add it to the CF system. After 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 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 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, the task status will be changed to In Progress, otherwise, it will stay in To Do until you return the images back to CF.

  • 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, the task status will be changed to In Progress, otherwise, it will stay in To Do until you return the images back to CF.

  • 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 correction assets are required.

Webhook on new/rejected task

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

Did this answer your question?