Skip to main content
API docs by Redocly

Amplified Intelligence PROVE API (v1)

Download OpenAPI specification:Download

This API provides functionality to generate tags and access report metrics.

Tag API

Generate JS Tag

This API is used to generate JS tags using the provided configuration.

Authorizations:
auth0
Request Body schema: application/json
campaign
required
string (Campaign) [ 0 .. 100 ] characters ^[\w-]*$

A unique identifier for the campaign - this should match the campaign used when querying session data via the report API.

insertionOrder
required
string (InsertionOrder) [ 0 .. 100 ] characters ^[\w-]*$

A unique identifier for the insertion order - this should match the insertion order used when querying session data via the report API.

lineItem
required
string (LineItem) [ 0 .. 100 ] characters ^[\w-]*$

A unique identifier for the line item - this should match the line item used when querying session data via the report API.

adFormat
required
string (SupportedJsAdFormats)
Enum: "dis.std.billboard" "dis.std.half-page" "dis.std.interstitial" "dis.std.leaderboard" "dis.std.mobile-banner" "dis.std.mrec" "dis.std.portrait" "dis.std.skyscraper" "dis.celtra.interscroller" "dis.teads.drag-and-drop" "dis.teads.flow" "dis.teads.spin-card"

Ad formats that are supported by the JS tag.

sessionIdMacro
string (SessionIdMacro)

This will ensure all PROVE data uses the provided macro value to identify sessions.

tcf
required
boolean (Tcf)

Indicates whether generated tags should include TCF macros for handling user consent.

object (TagAttributes)

Providing tag attributes that can be used to enhance the session and enable additional custom queries via the report API. Please note; if no publisher ID has been specified, our tag will attempt to dynamically resolve this.

Responses

Request samples

Content type
application/json
{
  • "campaign": "campaign-id1",
  • "insertionOrder": "insertion-order-id1",
  • "lineItem": "line-item-1",
  • "adFormat": "dis.std.mobile-banner",
  • "tcf": true
}

Response samples

Content type
application/json
{
  • "js": "<script type=\"text/javascript\" src=\"https://pixel.amplified.co/v1/js/display/org1/cmp1/prove/io1/line-item-1\"></script>",
  • "vastLinearWrapper": null,
  • "vastLinearEvents": null
}

Generate VAST Linear Wrapper Tag

This API is used to generate VAST Linear Wrapper tags using the provided configuration.

Please note; for online video ad formats we require OMID support, these include; vid.std.instream, vid.std.outstream and vid.teads.header.

Authorizations:
auth0
Request Body schema: application/json
campaign
required
string (Campaign) [ 0 .. 100 ] characters ^[\w-]*$

A unique identifier for the campaign - this should match the campaign used when querying session data via the report API.

insertionOrder
required
string (InsertionOrder) [ 0 .. 100 ] characters ^[\w-]*$

A unique identifier for the insertion order - this should match the insertion order used when querying session data via the report API.

lineItem
required
string (LineItem) [ 0 .. 100 ] characters ^[\w-]*$

A unique identifier for the line item - this should match the line item used when querying session data via the report API.

adFormat
required
string (SupportedVastLinearWrapperAdFormats)
Enum: "vid.std.instream" "vid.std.outstream" "vid.teads.header" "vid.vod.6s" "vid.vod.10s" "vid.vod.15s" "vid.vod.20s" "vid.vod.30s" "vid.vod.40s" "vid.vod.60s"

Ad formats that are supported by the VAST linear wrapper tag.

sessionIdMacro
string (SessionIdMacro)

This will ensure all PROVE data uses the provided macro value to identify sessions.

tcf
required
boolean (Tcf)

Indicates whether generated tags should include TCF macros for handling user consent.

object (TagAttributes)

Providing tag attributes that can be used to enhance the session and enable additional custom queries via the report API. Please note; if no publisher ID has been specified, our tag will attempt to dynamically resolve this.

required
object

Details of the original VAST URL that needs to be wrapped.

vastVersion
required
string (SupportedVastVersions)
Enum: "3.0" "4.0" "4.1" "4.2"

Support VAST versions - select the latest version supported by the player.

Responses

Request samples

Content type
application/json
{
  • "campaign": "campaign-id1",
  • "insertionOrder": "insertion-order-id1",
  • "lineItem": "line-item-1",
  • "adFormat": "vid.vod.30s",
  • "tcf": true,
  • "originalVast": {},
  • "vastVersion": "3.0"
}

Response samples

Content type
application/json
{}

Generate VAST Linear Events

This API is used to generate VAST linear events using the provided configuration.

Please note; when using VAST linear events, the ad server is required to check for TCF user consent using our vendor ID (1195), and only include these events if user consent is given.

Authorizations:
auth0
Request Body schema: application/json
campaign
required
string (Campaign) [ 0 .. 100 ] characters ^[\w-]*$

A unique identifier for the campaign - this should match the campaign used when querying session data via the report API.

insertionOrder
required
string (InsertionOrder) [ 0 .. 100 ] characters ^[\w-]*$

A unique identifier for the insertion order - this should match the insertion order used when querying session data via the report API.

lineItem
required
string (LineItem) [ 0 .. 100 ] characters ^[\w-]*$

A unique identifier for the line item - this should match the line item used when querying session data via the report API.

adFormat
required
string (SupportedVastLinearEventsAdFormats)
Enum: "vid.vod.6s" "vid.vod.10s" "vid.vod.15s" "vid.vod.20s" "vid.vod.30s" "vid.vod.40s" "vid.vod.60s"

Ad formats that are supported by VAST linear events.

sessionIdMacro
required
string (SessionIdMacro)

This will ensure all PROVE data uses the provided macro value to identify sessions.

object (TagAttributes)

Providing tag attributes that can be used to enhance the session and enable additional custom queries via the report API. Please note; if no publisher ID has been specified, our tag will attempt to dynamically resolve this.

vastVersion
required
string (SupportedVastVersions)
Enum: "3.0" "4.0" "4.1" "4.2"

Support VAST versions - select the latest version supported by the player.

Responses

Request samples

Content type
application/json
{
  • "campaign": "campaign-id1",
  • "insertionOrder": "insertion-order-id1",
  • "lineItem": "line-item-1",
  • "adFormat": "vid.vod.30s",
  • "sessionIdMacro": "${IMPRESSION_ID}",
  • "vastVersion": "3.0"
}

Response samples

Content type
application/json
{}

Report API

Retrieve report metrics

This API is used to retrieve report metrics.

Authorizations:
auth0
query Parameters
campaign
required
string
insertionOrder
required
string
lineItems
required
Array of strings unique
Examples:
  • lineItems=lineItem1 - Single line item.
  • lineItems=lineItem1,lineItem2 - Multiple line items
metrics
required
string
Enum: "impressions" "avgActiveAttention" "avgPassiveAttention" "impressionsActive1s" "impressionsActive2s" "impressionsActive3s" "impressionsActive4s" "impressionsActive5s"
Examples:
  • metrics=impressions - Single report metric.
  • metrics=impressions,avgActiveAttention,avgPassiveAttention - Multiple report metrics.
breakdown
string
Enum: "lineItem" "publisherId" "adFormat" "deviceType" "mediaType" "timeOfDay" "countryName" "custom.<name>"
Examples:
  • breakdown=publisherId - Single report breakdown with default size.
  • breakdown=publisherId,deviceType - Multiple report breakdown with default sizes.
  • breakdown=publisherId:20 - Report breakdown with specific size.
  • breakdown=custom.channel - Custom report breakdown.

When supplying a breakdown value, by default we will respond with a limited number of records depending on the type. However, it is possible to override this value by adding ":" - e.g. publisherId:50 would return the top 50 publishers.

NOTE: the maximum specified size for any breakdown is 100.

NOTE: when specifying a line item breakdown, by default we will adjust the size according to the number of line items specified.

It is also possible to specify multiple breakdown query string parameters, in this instance we will take into account all entries when performing the report query and the same order will be preserved in the response - see request/response examples.

start
required
string <date>
Examples:
  • start=2023-01-15T01:02:03Z - UTC
  • start=2023-01-15T01:02:03+05:00 - Offset

The start date/time for your query in ISO-8601 format - the supplied time must include the offset, or end with "Z" if working with UTC.

end
required
string <date>
Examples:
  • end=2023-01-15T01:02:03Z - UTC
  • end=2023-01-15T01:02:03+05:00 - Offset

The end date/time for your query in ISO-8601 format - the supplied time must include the offset, or end with "Z" if working with UTC.

Responses

Response samples

Content type
application/json
Example

metrics=impressions,avgActiveAttention,avgPassiveAttention

{
  • "metrics": {
    }
}