Get Details of a Creative

Component Creatives API (1.0)

The terms creative components and native components may be used interchangeably. The front part of the endpoint is:

QA API Base: https://t1qa1.mediamath.com/component_creatives/v1.0/ (or whichever QA server is being used)

Prod API Base: https://t1.mediamath.com/component_creatives/v1.0

Component Creatives are uploaded in the "Creatives Tab" within the Creatives Module, and is where creatives for native campaigns are uploaded.

Download OpenAPI description

component-creatives.json

component-creatives.yaml

Overview

URL https://www.mediamath.com/contact-us/

API Support developers@mediamath.com

License Apache 2.0

Servers

https://t1.mediamath.com/

Component Creatives

Operations

List Creatives

Request

List creatives

Query

statusinteger[ 0 .. 1 ]

status

sort_bystring

sort_by

Enum"atomic_creative_id""advertiser_id""advertiser_name""concept_name""start_date""end_date""concept_id""creative_name""last_modified""external_identifier"

page_limitinteger[ 1 .. 100 ]

page_limit

Default 20

page_offsetinteger

page_offset

Default 0

advertiser_idinteger

advertiser_id

curl -i -X GET \
  'https://t1.mediamath.com/component_creatives/v1.0/creatives?advertiser_id=0&page_limit=20&page_offset=0&sort_by=atomic_creative_id&status=1'

Responses

Bodyapplication/json

Response

application/json

{
  "data": [
    { … },
    { … }
  ],
  "meta": {
    "code": 200,
    "count": 2,
    "next_page": "http://component-creative-api.prod.cbe.mediamath.com/v1.0/creatives?page_offset=2&page_limit=2",
    "offset": 0,
    "status": "success",
    "total_count": 864,
    "type": "creatives"
  }
}

Create a New Creative

Request

Create a new creative

Bodyapplication/json

See below

any

curl -i -X POST \
  https://t1.mediamath.com/component_creatives/v1.0/creatives \
  -H 'Content-Type: application/json'

Responses

Remember, assets have different schema depending on asset type.

Header: Cookie: adama_session={adama_session}

Headers

new1579011858564string

Bodyapplication/json

Response

application/json

{
  "data": {
    "advertiser_id": 100178,
    "advertiser_name": "Brooklyn Bubblegum Co.",
    "assets": [ … ],
    "atomic_creative_id": 3200795,
    "created_at": "2016-11-17T17:29:39.607Z",
    "creative_id": 261,
    "creative_name": "test creative",
    "end_date": "2016-11-30T00:00:00",
    "external_identifier": "NA",
    "last_modified": "2016-11-17T17:30:55",
    "last_published": "2016-11-17T17:29:39.607Z",
    "start_date": "2016-09-30T00:00:00",
    "status": "1",
    "unpublished": false,
    "updated_at": "2016-11-17T17:29:39.607Z"
  },
  "meta": {
    "code": 201,
    "status": "created",
    "type": "creative"
  }
}

Get Group Version Info

Request

Get group version info

curl -i -X GET \
  https://t1.mediamath.com/component_creatives/v1.0/version

Responses

Bodyapplication/json

Response

application/json

{
  "version": "cfb1074-20190419202430"
}

List Creative Approvals

Request

List Creative Approvals

Query

atomic_creative_idsstringrequired

Actually, an integer or comma-delimited list not to exceed 50 items

curl -i -X GET \
  'https://t1.mediamath.com/component_creatives/v1.0/approvals?atomic_creative_ids=string'

Responses

See below

Bodyapplication/json

Response

application/json

{
  "data": [
    { … },
    { … },
    { … }
  ],
  "meta": {
    "code": 200,
    "status": "success",
    "type": "approvals"
  }
}

Post an Image or Subtitle Asset

Request

Note about image assets:

Base64 encoded image assets can be uploaded via this endpoint. This new image asset is represented in the assets param as an object containing an encoded_image_file and image_name properties. Example assets: "[{"encoded_image_file": base64_data_here, "image_filename":"logo.png"}]"

Note about subtitle assets:

Base64 encoded subtitle assets can be uploaded via this endpoint. This new subtitle asset is represented in the assets param as an object containing an encoded_subtitle_file and subtitle_filename properties. Example assets: "[{"encoded_subtitle_file": base64_data_here, "subtitle_filename":"test.srt"}]"

Header should be of format: Cookie: adama_session={adama_session}

Headers

adama_sessionstring

See below

Bodyapplication/json

See below

any

curl -i -X POST \
  https://t1.mediamath.com/component_creatives/v1.0/approvals \
  -H 'Content-Type: application/json' \
  -H 'adama_session: string'

Responses

All assets have asset_id, asset_type, component_id, and component_human_name. asset_type=text also have asset_value. asset_type=image have the 5 parameters that start with "image_"

Bodyapplication/json

Response

application/json

{
  "data": {
    "advertiser_id": 100178,
    "advertiser_name": "Brooklyn Bubblegum Co.",
    "assets": [ … ],
    "atomic_creative_id": 3200795,
    "created_at": "2016-11-17T17:29:39.607Z",
    "creative_id": 261,
    "creative_name": "test creative",
    "end_date": "2016-11-30T00:00:00",
    "external_identifier": "NA",
    "fb_status": "UNKNOWN",
    "last_modified": "2016-11-17T17:30:55",
    "start_date": "2016-09-30T00:00:00",
    "status": "1",
    "updated_at": "2016-11-17T17:29:39.607Z"
  },
  "meta": {
    "code": 201,
    "status": "created",
    "type": "creative"
  }
}

Get Creative's Eligibility Details

Request

Get creative's eligibility details

Path

atomic_creative_idstringrequired

See below

curl -i -X GET \
  'https://t1.mediamath.com/component_creatives/v1.0/creatives/{atomic_creative_id}/eligibility'

Responses

Bodyapplication/json

Response

application/json

{
  "data": [
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … }
  ],
  "meta": {
    "code": 200,
    "status": "success",
    "type": "creative_eligibility"
  }
}

Get Details of a Creative

Request

Get details of a creative

Path

atomic_creative_idintegerrequired

See below

curl -i -X GET \
  'https://t1.mediamath.com/component_creatives/v1.0/creatives/{atomic_creative_id}'

Responses

start_date and end_date are not required fields, but they either both exist or don't exist per creative.

If the asset_type is text, asset_value is defined, otherwise, the 5 parameters that begin "image_" are defined.

Bodyapplication/json

Response

application/json

{
  "data": {
    "advertiser_id": 166476,
    "advertiser_name": "000Adam Test Advertiser",
    "assets": [ … ],
    "atomic_creative_id": 4813554,
    "concept_id": "1432620",
    "concept_name": "LVR_US_IN_New Collection_Female_23June2017",
    "created_at": "2017-09-25T19:22:41.788Z",
    "creative_id": 1205,
    "creative_name": "LVR_US_IN_NewCollection_612x612_28June_06",
    "external_identifier": "NA",
    "last_modified": "2017-09-25T19:22:00",
    "last_published": "2018-03-06T16:00:27.624Z",
    "status": "1",
    "unpublished": false,
    "updated_at": "2018-03-06T16:00:27.624Z"
  },
  "meta": {
    "code": 200,
    "status": "success",
    "type": "creative"
  }
}

Update Creatives Details

Request

Update creatives details

Caution

If the the parameter assets is defined, then all previous assets belonging to this creative are replaced with this new array of assets. You can avoid deleting assets by adding the asset by id to the assets param like so [{"asset_id":34223}] :::

Note about image assets:

Base64 encoded image assets can be uploaded via this endpoint. This new image asset is represented in the assets param as an object containing an encoded_image_file and image_filename properties. Example assets: "[{"encoded_image_file": base64_data_here, "image_filename":"logo.png"}]"

Note about subtitle assets:

Path

atomic_creative_idstringrequired

atomic_creative_id

Headers

adama_sessionstring

See below

Bodyapplication/json

See below

any

curl -i -X POST \
  'https://t1.mediamath.com/component_creatives/v1.0/creatives/{atomic_creative_id}' \
  -H 'Content-Type: application/json' \
  -H 'adama_session: string'

Responses

Different asset types use different parameters

Bodyapplication/json

Response

application/json

{
  "data": {
    "advertiser_id": 100178,
    "assets": [ … ],
    "atomic_creative_id": 3200795,
    "created_at": "2016-11-17T17:29:39.607Z",
    "creative_id": 261,
    "creative_name": "The updated name of the creative",
    "end_date": "2016-10-17T00:00:00",
    "external_identifier": "NA",
    "last_modified": "2016-11-17T17:47:43",
    "last_published": "2016-11-17T17:29:39.607Z",
    "start_date": "2016-10-15T00:00:00",
    "status": "1",
    "unpublished": false,
    "updated_at": "2016-11-17T17:29:39.607Z"
  },
  "meta": {
    "code": 200,
    "status": "updated",
    "type": "creative"
  }
}

Get Atomic Creative with Preview Info

Request

Get an atomic creative with preview info.

".QUERY." should be replaced by a question mark for actual execution

Path

atomic_creative_idintegerrequired

See below

Headers

cookiestring

Cookie: adama_session={adama_session}

curl -i -X GET \
  'https://t1.mediamath.com/component_creatives/v1.0/creatives/{atomic_creative_id}.QUERY.include=previews' \
  -H 'cookie: string' \
  -b string

Responses

In the previews array, the types are not limited to just NATIVE_MOBILE_0 and NATIVE_MOBILE_1 and NATIVE_DESKTOP_0 and NATIVE_DESKTOP_1 (note: NATIVE_MOBILE_ and NATIVE_DESKTOP_ will only be followed by 0 or 1). Other options (with no underscore-number) include: MOBILE_BANNER AUDIENCE_NETWORK_OUTSTREAM_VIDEO MOBILE_INTERSTITIAL MOBILE_NATIVE INSTREAM_VIDEO_DESKTOP INSTREAM_VIDEO_MOBILE INSTANT_ARTICLE_STANDARD MESSENGER_MOBILE_INBOX_MEDIA DESKTOP_FEED_STANDARD MOBILE_FEED_STANDARD RIGHT_COLUMN_STANDARD SUGGESTED_VIDEO_DESKTOP SUGGESTED_VIDEO_MOBILE INSTAGRAM_STANDARD

GET /component_creatives/v1.0/creatives/{atomic_creative_id}/eligibility will list out all of these external id's, and should not vary when the atomic_creative_id changes.

Bodyapplication/json

Response

application/json

{
  "data": {
    "advertiser_id": 123710,
    "advertiser_name": "Donkey Test Advertiser",
    "assets": [ … ],
    "atomic_creative_id": 9534525,
    "concept_id": "123508",
    "concept_name": "NDAR - Native Creative",
    "created_at": "2019-06-19T17:56:55.431Z",
    "creative_id": 17941,
    "creative_name": "NDAR - Native Creative",
    "external_identifier": "NA",
    "last_modified": "2019-06-19T17:56:22",
    "last_published": "2019-06-19T17:57:29.300Z",
    "previews": { … },
    "status": "1",
    "unpublished": false,
    "updated_at": "2019-06-19T17:57:29.300Z"
  },
  "meta": {
    "code": 200,
    "status": "success",
    "type": "creative"
  }
}

Get a Text Asset

Request

Get a text asset

Headers

Cookie: adama_session={adama_session}

Path

asset_idintegerrequired

See below

curl -i -X GET \
  'https://t1.mediamath.com/component_creatives/v1.0/assets/{asset_id}'

Responses

Depending on the asset type, you'll either get an asset_value (text) or the 5 parameters that start with "image" (image). Everything else comes with either type. It may be associated with either an advertise_id or a creative_id.

Bodyapplication/json

Response

application/json

{
  "data": {
    "advertiser_id": 100178,
    "asset_id": 1537,
    "asset_name": null,
    "component_human_name": "Image",
    "component_id": 2,
    "created_at": "2016-11-17T17:29:32.340Z",
    "image_file_size": null,
    "image_filename": "mediamathlogo.png",
    "image_height": 100,
    "image_url": "https://s3.amazonaws.com/mm-component-creative/1479403772247_227082bd4ced0f888aa0066f06ea1402_mediamathlogo.png",
    "image_width": 160,
    "updated_at": "2016-11-17T17:29:32.340Z"
  },
  "meta": {
    "code": 200,
    "status": "success",
    "type": "asset"
  }
}

Request Update Image Asset

Request

Request update image asset

Text asset is in the request sample below.

Image asset request sample: ------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="asset_value"; filename="" Content-Type:

------WebKitFormBoundary7MA4YWxkTrZu0gW--

Path

asset_idstringrequired

asset_id

Headers

adama_sessionstring

See below

curl -i -X POST \
  'https://t1.mediamath.com/component_creatives/v1.0/assets/{asset_id}' \
  -H 'adama_session: string'

Responses

The data section will either have asset_value (text asset) or the 5 image parameters (image asset). It may be associated with either an advertise_id or a creative_id.

Request update image asset (multipart/form-data)

Headers

Cookie: adama_session={adama_session}

Body

------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="asset_value"; filename="" Content-Type:

------WebKitFormBoundary7MA4YWxkTrZu0gW--

------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="asset_value"; filename="" Content-Type:

------WebKitFormBoundary7MA4YWxkTrZu0gW--

Body

Response

{
  "data": {
    "advertiser_id": 100178,
    "asset_id": 1537,
    "asset_name": null,
    "component_human_name": "Image",
    "component_id": 2,
    "created_at": "2016-11-17T17:29:32.340Z",
    "image_file_size": null,
    "image_filename": "mediamathlogo.png",
    "image_height": 100,
    "image_url": "https://s3.amazonaws.com/mm-component-creative/1479403772247_227082bd4ced0f888aa0066f06ea1402_mediamathlogo.png",
    "image_width": 160,
    "updated_at": "2016-11-17T17:29:32.340Z"
  },
  "meta": {
    "code": 201,
    "status": "created",
    "type": "asset"
  }
}

List Components

Request

List components

curl -i -X GET \
  https://t1.mediamath.com/component_creatives/v1.0/components

Responses

Bodyapplication/json

Response

application/json

{
  "data": [
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … }
  ],
  "meta": {
    "code": 200,
    "status": "success",
    "total_count": 9,
    "type": "component"
  }
}

Create a Component

Request

Access is restricted to certain T1 user IDs stored in the database, disallowed users will receive a 401 eeror message.

The ID of the created component will be in the response.

Headers

adama_sessionstring

See below

Bodyapplication/json

{ "component_human_name": "Right Image", "component_name": "right_image", "value_type_name": "IMAGE" }

any

curl -i -X POST \
  https://t1.mediamath.com/component_creatives/v1.0/components \
  -H 'Content-Type: application/json' \
  -H 'adama_session: string'

Responses

Bodyapplication/json

Response

application/json

{
  "data": {
    "char_limit": null,
    "component_human_name": "Right Image",
    "component_id": 11,
    "created_at": "2016-11-17T19:58:06.894Z",
    "is_enabled": true,
    "updated_at": "2016-11-17T19:58:06.894Z",
    "value_type_name": "IMAGE"
  },
  "meta": {
    "code": 201,
    "status": "created",
    "type": "component"
  }
}

Get a Single Component Creative

Request

Get a single component creative

Path

component_idintegerrequired

See below

curl -i -X GET \
  'https://t1.mediamath.com/component_creatives/v1.0/components/{component_id}'

Responses

Bodyapplication/json

Response

application/json

{
  "data": {
    "char_limit": null,
    "component_human_name": "Destination URL",
    "component_id": 4,
    "created_at": "2016-12-01T03:56:44.085Z",
    "is_enabled": true,
    "updated_at": "2016-12-01T03:56:44.085Z",
    "value_type_name": "TEXT"
  },
  "meta": {
    "code": 200,
    "status": "success",
    "type": "component"
  }
}

Update a Single component creative

Request

Update a Single component creative

Path

component_idintegerrequired

See below

Bodyapplication/json

See below

any

curl -i -X POST \
  'https://t1.mediamath.com/component_creatives/v1.0/components/{component_id}' \
  -H 'Content-Type: application/json'

Responses

Bodyapplication/json

Response

application/json

{
  "data": {
    "char_limit": null,
    "component_human_name": "Destination URL",
    "component_id": 4,
    "created_at": "2016-12-01T03:56:44.085Z",
    "is_enabled": true,
    "updated_at": "2016-12-01T03:56:44.085Z",
    "value_type_name": "TEXT"
  },
  "meta": {
    "code": 200,
    "status": "success",
    "type": "component"
  }
}

Create a New Asset Collection

Request

Create an asset and optionally associate it with a creative. Either an advertiser_id or creative_ids must be provided. All creatives in creative_ids must belong to the same advertiser.

The ID of the created asset will be in the response.

Request text asset (application/json)

Attributes (NewTextAsset)

Headers

Cookie: adama_session={adama_session}

The body shown below is for a text asset.

An image asset body might be in the form of: ------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="component_id"

2 ------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="asset_value"; filename="" Content-Type:

------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="creative_ids"

[3200795] ------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="advertiser_id"

100178 ------WebKitFormBoundary7MA4YWxkTrZu0gW--

Headers

adama_sessionstring

adama_session

Bodyapplication/json

See below

any

curl -i -X POST \
  https://t1.mediamath.com/component_creatives/v1.0/assets \
  -H 'Content-Type: application/json' \
  -H 'adama_session: string'

Responses

Body

Response

{
  "data": {
    "advertiser_id": 100178,
    "asset_id": 1546,
    "asset_name": null,
    "component_human_name": "Image",
    "component_id": 2,
    "created_at": "2016-11-18T16:38:45.375Z",
    "image_file_size": 5052,
    "image_filename": "logo.png",
    "image_height": 100,
    "image_url": "https://s3.amazonaws.com/mm-component-creative/1479487125286_227082bd4ced0f888aa0066f06ea1402_logo.png",
    "image_width": 160,
    "updated_at": "2016-11-18T16:38:45.375Z"
  },
  "meta": {
    "code": 201,
    "status": "created",
    "type": "asset"
  }
}

Get video asset upload S3 URL

Request

Get a pre-signed S3 URL to be used for uploading video assets. Once an object is put in the S3 bucket, this S3 url without it's query parameters can be used as an asset_value for video assets.

Path

filenamestringrequired

Cannot include any of the following characters: {}^/`[]~<>|#%'"

Headers

cookiestring

Cookie: adama_session={adama_session};

curl -i -X GET \
  'https://t1.mediamath.com/component_creatives/v1.0/upload/{filename}' \
  -H 'cookie: string' \
  -b string

Responses

Bodyapplication/json

Response

application/json

{
  "meta": {
    "code": 200,
    "status": "success",
    "type": "upload"
  },
  "data": "https://mm-component-creative-prod-dev.s3.amazonaws.com/1506608929527_cb764213f2b67169dacc809f077e4e7f_hello.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJ2DETCTFEHT7BQOA%2F20170928%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20170928T142849Z&X-Amz-Expires=60&X-Amz-Signature=536f9681d6de47f121616673b7a14cb9524d48944cb8d689f83e6f173da2f301&X-Amz-SignedHeaders=host"
}

Component Creatives API (1.0)

Component Creatives

List Creatives

Request

Responses

Was this helpful?

Create a New Creative

Request

Responses

Was this helpful?

Get Group Version Info

Request

Responses

Was this helpful?

List Creative Approvals

Request

Responses

Was this helpful?

Post an Image or Subtitle Asset

Request

Responses

Was this helpful?

Get Creative's Eligibility Details

Request

Responses

Was this helpful?

Get Details of a Creative

Request

Responses

Was this helpful?

Update Creatives Details

Request

Update creatives details

Caution

Note about subtitle assets:

Responses

Was this helpful?

Get Atomic Creative with Preview Info

Request

".QUERY." should be replaced by a question mark for actual execution

Responses

Was this helpful?

Get a Text Asset

Request

Responses

Was this helpful?

Request Update Image Asset

Request

Responses

Was this helpful?

List Components

Request

Responses

Was this helpful?

Create a Component

Request

Responses

Was this helpful?

Get a Single Component Creative

Request

Responses

Was this helpful?

Update a Single component creative

Request

Responses

Was this helpful?

Create a New Asset Collection

Request

Responses

Was this helpful?

Get video asset upload S3 URL

Request

Responses

Was this helpful?