Skip to main content
API docs by Redocly

Creative Testing API (1.0.0-beta)

Download OpenAPI specification:Download

API reference for the Creative Testing API, including creatives, prediction jobs management, prediction and webhook endpoints.

Creatives

Creatives provides a complete set of API endpoints for handling creative assets across their entire lifecycle.

Get all creatives

Returns all registered creative assets and their metadata for easy tracking and management.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a creative by given a downloadable URL

Registers a new creative by providing a downloadable URL, enabling quick onboarding with optional targeting details for prediction jobs.

Request Body schema: application/json
downloadable_url
string

A public URL where the creative file can be accessed and downloaded. This link must be reachable over the internet to allow the system to fetch and process the creative asset. The ad length must follow the guidence: . The file format must be .mp4 or .mov.The file FPS should not exceed 60 and file size must <=3GB.

webhook_url
string

The callback URL provided by the API caller to receive asynchronous updates on the prediction job’status, such as completion or errors.

Array of objects or null (creatives_platformFormats)

A list of platform and format configurations applied to this prediction job, detailing which media the creative is evaluated on (platform, format, skippable settings).
If no argument is given, all viable platform formats will be assessed according to the creative aspect ratio. Aspect ratio for each format reference

genders
Array of strings or null
Enum: "male" "female"

Specifies the target genders for which the creative should be evaluated on(optional). If no argument is given, the data across all available genders will be returned. If multiple genders are provided, data will be aggregated across all selected genders.

countries
Array of strings or null
Enum: "AU" "UK" "US" "DE" "SA" "AE" "NZ" "PL" "CA" "FR" "BE"

A list of country codes specifying the geographic regions targeted for evaluation(optional). If no argument is given, the data across all available countries will be returned. If multiple country codes are provided, data will be aggregated across all selected regions.

age_groups
Array of strings or null
Enum: "18-24" "25-34" "35-44" "45-54" "55+"

Defines the age groups the creative should be assessed against(optional).If no argument is given, the data across all available countries will be returned. If multiple age_groups s are provided, data will be aggregated across all selected age_groups.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "file_name": "my_creative_video.mp4",
  • "downloadable_url": "https://www.amplified.co/creatives/my_creative_video.mp4",
  • "file_source": "external_downloadable_link",
  • "file_size": 10000,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "status": "uploaded",
  • "prediction_jobs": [
    ]
}

Find creative by ID

Retrieves metadata for a specific creative using its creativeId.

path Parameters
creativeId
required
string
Example: 550e8400-e29b-41d4-a716-446655445555

The unique identifier (UUID) of the creative you want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "file_name": "my_creative_video.mp4",
  • "downloadable_url": "https://www.amplified.co/creatives/my_creative_video.mp4",
  • "file_source": "external_downloadable_link",
  • "file_size": 10000,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "status": "uploaded",
  • "prediction_jobs": [
    ]
}

Delete a creative file

Removes the file associated with a specific creative, identified by creativeId.

path Parameters
creativeId
required
string
Example: 550e8400-e29b-41d4-a716-446655445555

The unique identifier (UUID) of the creative whose file should be deleted.

Responses

Create a creative by uploading a file

Creates a new creative by uploading a video file directly (mp4 or mov, ≤5MB) with optional targeting details for prediction jobs.

Request Body schema:
webhook_url
string

The callback URL provided by the API caller to receive asynchronous updates on the prediction job’status, such as completion or errors.

Array of objects or null (creatives_platformFormats)

A list of platform and format configurations applied to this prediction job, detailing which media the creative is evaluated on (e.g., platform type, ad format, skippable settings).
If no argument is given, all viable platform formats will be assessed according to the creative aspect ratio.Aspect ratio for each format reference

genders
Array of strings or null
Enum: "male" "female"

Specifies the target genders for which the creative should be evaluated on(optional). If no argument is given, the data across all available genders will be returned. If multiple genders are provided, data will be aggregated across all selected genders.

countries
Array of strings or null
Enum: "AU" "UK" "US" "DE" "SA" "AE" "NZ" "PL" "CA" "FR" "BE"

A list of country codes specifying the geographic regions targeted for evaluation(optional). If no argument is given, the data across all available countries will be returned. If multiple country codes are provided, data will be aggregated across all selected regions.

age_groups
Array of strings or null
Enum: "18-24" "25-34" "35-44" "45-54" "55+"

Defines the age groups the creative should be assessed against(optional).If no argument is given, the data across all available countries will be returned. If multiple age_groups s are provided, data will be aggregated across all selected age_groups.

Responses

Request samples

Content type
{
  • "webhook_url": "https://www.company.com/webhook_url",
  • "platform_formats": [
    ],
  • "genders": [
    ],
  • "countries": [
    ],
  • "age_groups": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "file_name": "my_creative_video.mp4",
  • "downloadable_url": "https://www.amplified.co/creatives/my_creative_video.mp4",
  • "file_source": "external_downloadable_link",
  • "file_size": 10000,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "status": "uploaded",
  • "prediction_jobs": [
    ]
}

Prediction_jobs

Prediction Jobs provides a complete set of API endpoints for managing the entire lifecycle of prediction tasks.

Get all prediction jobs

Retrieves a list of all prediction jobs created in the system, including their details, statuses, and associated creatives. This endpoint gives developers a full overview of active, completed, and historical prediction tasks for better tracking and management.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a prediection job

Creates a new prediction job for a specified creative, allowing you to analyze attention performance across selected demographics, platforms, and formats.

Request Body schema: application/json
creative_id
string

The unique identifier of the creative you want to run a prediction on.

webhook_url
string

The callback URL provided by the API caller to receive asynchronous updates on the prediction job’status.

Array of objects or null (creatives_platformFormats)

A list of platform and format configurations applied to this prediction job, detailing which media the creative is evaluated on (e.g., platform type, ad format, skippable settings).
If no argument is given, all viable platform formats will be assessed according to the creative aspect ratio. Aspect ratio for each format reference

genders
Array of strings or null
Enum: "male" "female"

Specifies the target genders for which the creative should be evaluated on(optional). If no argument is given, the data across all available genders will be returned. If multiple genders are provided, data will be aggregated across all selected genders.

countries
Array of strings or null
Enum: "AU" "UK" "US" "DE" "SA" "AE" "NZ" "PL" "CA" "FR" "BE"

A list of country codes specifying the geographic regions targeted for evaluation(optional). If no argument is given, the data across all available countries will be returned. If multiple country codes are provided, data will be aggregated across all selected regions.

age_groups
Array of strings or null
Enum: "18-24" "25-34" "35-44" "45-54" "55+"

Defines the age groups the creative should be assessed against(optional).If no argument is given, the data across all available countries will be returned. If multiple age_groups s are provided, data will be aggregated across all selected age_groups.

Responses

Request samples

Content type
application/json
{
  • "creative_id": "550e8400-e29b-41d4-a716-446655445555",
  • "webhook_url": "https://www.company.com/webhook_url",
  • "platform_formats": [
    ],
  • "genders": [
    ],
  • "countries": [
    ],
  • "age_groups": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655441111",
  • "creative_id": "550e8400-e29b-41d4-a716-446655440000",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "webhook_url": "https://www.company.com/webhook_url",
  • "status": "in-progress",
  • "platform_formats": [
    ],
  • "genders": [
    ],
  • "countries": [
    ],
  • "age_groups": [
    ],
  • "creative": {
    }
}

Find prediction job by ID

Retrieves detailed metadata and status for a specific prediction job using its predictionJobId.

path Parameters
predictionJobId
required
string
Example: 550e8400-e29b-41d4-a716-446655446666

The unique identifier (UUID) of the prediction job you want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655441111",
  • "creative_id": "550e8400-e29b-41d4-a716-446655440000",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "webhook_url": "https://www.company.com/webhook_url",
  • "status": "in-progress",
  • "platform_formats": [
    ],
  • "genders": [
    ],
  • "countries": [
    ],
  • "age_groups": [
    ],
  • "creative": {
    }
}

Delete predction job by ID

Deletes a specific prediction job identified by predictionJobId.

path Parameters
predictionJobId
required
string
Example: 550e8400-e29b-41d4-a716-446655446666

The unique identifier (UUID) of the prediction job you want to delete.

Responses

Predictions

The Prediction endpoints provide access to detailed analysis results for completed prediction jobs. They allow you to retrieve attention metrics and tailored platform recommendations to help optimize creative performance across different audiences and channels.

Get attention data

Retrieves second-by-second attention predictions for a specific prediction job, detailing how active, passive, and no-attention levels shift over time.

Attention score: overall attention score of the creative on the given platform_formats. It measures how well an ad holds audience attention over time, while giving more emphasis on attention captured early where people are most engaged.

Benchmark: score of the given platform_formats for comparison.

Go signal:
Fix indicates that your creative performs below the benchmark for the specified platform formats.

Good indicates that your creative meets or exceeds performance expectations for the specified platform formats.

Excellent indicates that your creative ranks within the top 20% of the specified platform formats.

Attention seconds and decay:
Example of a visualised attention seconds prediction and attention decay returned via the endpoint:Creative Testing Integration Flow

path Parameters
predictionJobId
required
string
Example: 550e8400-e29b-41d4-a716-446655445555

The unique identifier (UUID) of the prediction job you want to query.

Responses

Response samples

Content type
application/json
{
  • "predicted_at": "2019-08-24T14:15:22Z",
  • "creative": {
    },
  • "attentions": [
    ]
}

Get recommendations

Retrieves media recommendations and creative recommendations for a specific prediction job, helping guide media placement and creative optimization.These recommendations are based on the predicted attention performance of the creative across different configurations. If only one viable platform exists, only the recommended_platform is given. If two viable platforms exist, both recommended_platform and reconsider_platform are given.

path Parameters
predictionJobId
required
string
Example: 550e8400-e29b-41d4-a716-446655445555

The unique identifier (UUID) of the prediction job you want recommendations for.

query Parameters
brand_size
required
string
Enum: "category_leader" "challenger" "small"

The size of the brand or advertiser for contextualizing recommendations.

first_brand_moment
required
number

The timestamp (in seconds) when the brand first appears in the creative.

campaign_objective
required
string
Enum: "upper_funnel" "mid_funnel" "lower_funnel"

The main goal or objective of the campaign. You can choose from upper_funnel (Awareness and brand building), mid_funnel (Reinforcement and consideration), or lower_funnel (Performance and conversion).

Responses

Response samples

Content type
application/json
{
  • "predicted_at": "2019-08-24T14:15:22Z",
  • "creative": {
    },
  • "recommended_platform": {
    },
  • "supplementary_platform": {
    },
  • "reconsider_platform": {
    },
  • "creative_recommendations": {
    }
}

Webhook

The Webhook endpoints allow developers to set up automated notifications from the Amplified system, delivering real-time updates on prediction job status changes directly to a specified callback URL provided by the caller.

Webhook

Request Body schema: application/json
prediction_job_id
string

The unique ID of the prediction job that triggered the webhook update.

creative_id
string

The unique ID of the creative associated with the prediction job.

webhook_url
string

The callback URL (provided by the API caller) where the update notification is sent.

timestamp
string <date-time>

The exact time when the event or status update occurred.

event
string

The type of event triggering the webhook

status
string

The status of the prediction job

message
string

Messages about the update

error
string

Error message when something goes wrong

Responses

Request samples

Content type
application/json
{
  • "prediction_job_id": "550e8400-e29b-41d4-a716-446655446666",
  • "creative_id": "550e8400-e29b-41d4-a716-446655445555",
  • "webhook_url": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "event": "prediction_job_status_update",
  • "status": "prediction_result_ready",
  • "message": "string",
  • "error": "string"
}