MediaMath Component Creatives API

openapi: 3.0.0
info:
  title: Component Creatives API
  description: 'The terms creative components and native components may be used interchangeably.

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


    ## Component Creatives API v3.0 (current)


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


    Prod API Base: `https://api.mediamath.com/component_creatives/v3.0/`


    v3.0 endpoints use Bearer (JWT) authentication via the `Authorization` header.


    ## Component Creatives API v1.0 (deprecated)


    > **Deprecated:** The v1.0 endpoints are deprecated. Please migrate to v3.0.


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


    Prod API Base: `https://api.mediamath.com/component_creatives/v1.0`'
  contact:
    name: API Support
    url: https://support.infillion.com/
  license:
    url: http://www.apache.org/licenses/LICENSE-2.0.html
    name: Apache 2.0
  version: '3.0'
tags:
- name: Component Creatives
  description: "{% admonition type=\"danger\" name=\"This API is deprecated and will be removed soon\"\
    \ %}\n  Please migrate to the **Component Creatives API v3.0** documented above.\n{% /admonition %}\n\
    \n{% admonition type=\"warning\" name=\"Notice about authentication with cookie adama_session\" %}\n\
    \  The use of cookie adama_session for authentication has been discontinued and it's not supported\
    \ in Component Creatives API v3.0.\n  We ask all of our clients who have not yet migrated to **Bearer\
    \ (JWT) Authentication** to do so as soon as possible.\n{% /admonition %}"
- name: Creatives - Native
  description: v3.0 component (native) creative endpoints.
- name: Components
  description: v3.0 component definition endpoints.
- name: Approvals
  description: v3.0 creative approval status endpoints.
x-tagGroups:
- name: Component Creatives API v3.0
  tags:
  - Creatives - Native
  - Components
  - Approvals
- name: Component Creatives API v1.0 (Deprecated)
  tags:
  - Component Creatives
paths:
  /component_creatives/v1.0/creatives:
    get:
      tags:
      - Component Creatives
      security: []
      summary: List Creatives
      description: '**⚠️ Deprecated** — Use `GET /v3.0/creatives` instead.


        List creatives'
      operationId: List-creatives
      parameters:
      - name: status
        in: query
        description: status
        schema:
          type: integer
          minimum: 0
          maximum: 1
      - name: sort_by
        in: query
        description: sort_by
        schema:
          type: string
          enum:
          - atomic_creative_id
          - advertiser_id
          - advertiser_name
          - concept_name
          - start_date
          - end_date
          - concept_id
          - creative_name
          - last_modified
          - external_identifier
          - status
      - name: page_limit
        in: query
        description: page_limit
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: page_offset
        in: query
        description: page_offset
        schema:
          type: integer
          default: 0
      - name: advertiser_id
        in: query
        description: advertiser_id
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              examples:
                response:
                  value:
                    data:
                    - advertiser_id: 122631
                      advertiser_name: ACME
                      assets:
                      - asset_id: 159377
                        asset_type: text
                        asset_value: 'Puppeteer Component Creative #2'
                        component_human_name: Title
                        component_id: 7
                      - asset_id: 159378
                        asset_type: text
                        asset_value: 'DO NOT MODIFY: Puppeteer Test Creative used for automated testing.'
                        component_human_name: Description
                        component_id: 10
                      - asset_id: 159379
                        asset_type: text
                        asset_value: https://t1.mediamath.com/
                        component_human_name: Destination URL
                        component_id: 4
                      atomic_creative_id: 6897203
                      concept_id: '2219854'
                      concept_name: 'Puppeteer Component Creative #2'
                      created_at: '2019-05-29T17:04:53.082Z'
                      creative_id: 16160
                      creative_name: 'Puppeteer Component Creative #2'
                      end_date: '2019-01-01T00:00:00'
                      external_identifier: NA
                      last_modified: '2019-05-29T17:04:32'
                      last_published: '2019-05-29T17:04:58.589Z'
                      start_date: '2019-01-01T00:00:00'
                      status: '1'
                      unpublished: false
                      updated_at: '2019-05-29T17:04:58.589Z'
                    - advertiser_id: 225607
                      advertiser_name: IBM - Outbrain
                      assets:
                      - asset_id: 155128
                        asset_type: image
                        component_human_name: Image
                        component_id: 2
                        image_file_size: 117931
                        image_filename: LinuxONE_Native_Banking_1200x1200.jpg
                        image_height: 1200
                        image_url: https://s3.amazonaws.com/mm-component-creative-api/1558639899084_c6df48cfa3d27180af814331f73553b7_LinuxONE_Native_Banking_1200x1200.jpg
                        image_width: 1200
                      - asset_id: 155129
                        asset_type: text
                        asset_value: https://www.ibm.com/account/reg/us-en/signup?formid=urx-36770
                        component_human_name: Destination URL
                        component_id: 4
                      - asset_id: 155130
                        asset_type: text
                        asset_value: IBM
                        component_human_name: Brand Name(sponsored by)
                        component_id: 13
                      - asset_id: 155131
                        asset_type: text
                        asset_value: https://bs.serving-sys.com/Serving/adServer.bs?cn=trd&pli=1074647816&adid=1077380410&ord=[RANDOM_NUMBER]
                        component_human_name: 3PAS Click Tracking URL
                        component_id: 14
                      - asset_id: 155132
                        asset_type: text
                        asset_value: "Maintaining Trust for Financial Services \r\n\r\n"
                        component_human_name: Title
                        component_id: 7
                      - asset_id: 155133
                        asset_type: text
                        asset_value: Protect your customers' data and prevent breaches with the right
                          IT infrastructure. Read how
                        component_human_name: Description
                        component_id: 10
                      - asset_id: 155134
                        asset_type: text
                        asset_value: https://bs.serving-sys.com/Serving/adServer.bs?cn=display&c=19&pli=1074647816&adid=1077380410&ord=[RANDOM_NUMBER]
                        component_human_name: 3PAS Impression Tracking URL
                        component_id: 16
                      - asset_id: 155135
                        asset_type: image
                        component_human_name: Logo
                        component_id: 21
                        image_file_size: 2770
                        image_filename: ibm.png
                        image_height: 200
                        image_url: https://s3.amazonaws.com/mm-component-creative-api/1558639899093_d5e4e3a232b3456e309c242d687a126c_ibm.png
                        image_width: 200
                      atomic_creative_id: 6884010
                      concept_id: '2213973'
                      concept_name: ibm_outbrain
                      created_at: '2019-05-23T19:31:39.059Z'
                      creative_id: 15550
                      creative_name: outbrain4
                      external_identifier: NA
                      last_modified: '2019-05-23T19:31:23'
                      last_published: '2019-05-23T19:31:51.910Z'
                      status: '1'
                      unpublished: false
                      updated_at: '2019-05-23T19:31:51.910Z'
                    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
        '400':
          description: "Here are 2 examples of error sections (meta sections are identical):\n\n     \
            \ \"location\": \"query\",\n      \"param\": \"page_limit\",\n      \"msg\": \"must be an\
            \ Integer between 1 and 100\",\n      \"value\": \"0\"\n\nand \n\n      \"location\": \"query\"\
            ,\n      \"param\": \"atomic_creative_ids\",\n      \"msg\": \"Must provide comma separated\
            \ ids and number of ids should not exceed 50\",\n      \"value\": \"\""
          content:
            application/json:
              examples:
                response:
                  value:
                    meta:
                      code: 400
                      status: error
                      message: Validation Error
                    errors:
                    - location: query
                      param: atomic_creative_ids
                      msg: Must provide comma separated ids and number of ids should not exceed 50
                      value: ''
        '401':
          description: ''
          content:
            application/json:
              examples:
                response:
                  value:
                    meta:
                      code: 401
                      status: error
                      type: error
                      message: Authorization required.
    post:
      tags:
      - Component Creatives
      security: []
      summary: Create a New Creative
      description: '**⚠️ Deprecated** — Use `POST /v3.0/creatives` instead.


        Create a new creative'
      operationId: Create-a-new-creative
      requestBody:
        $ref: '#/components/requestBodies/Create-a-new-creativeBody'
      responses:
        '201':
          description: 'Remember, assets have different schema depending on asset type.


            Header: Cookie: adama_session={adama_session}'
          headers:
            new1579011858564:
              schema:
                type: string
          content:
            application/json:
              examples:
                response:
                  value:
                    data:
                      advertiser_id: 100178
                      advertiser_name: Brooklyn Bubblegum Co.
                      assets:
                      - asset_id: 1538
                        asset_type: text
                        asset_value: new body
                        component: body
                      - asset_id: 1539
                        asset_type: image
                        component: image
                        image_file_size: null
                        image_filename: mediamathlogo.png
                        image_height: 100
                        image_url: https://s3.amazonaws.com/mm-component-creative/1479403779621_227082bd4ced0f888aa0066f06ea1402_mediamathlogo.png
                        image_width: 160
                      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
        '400':
          description: ''
          content:
            application/json:
              examples:
                response:
                  value:
                    meta:
                      code: 400
                      status: error
                      message: Validation Error
                    errors:
                    - param: creative_name
                      msg: required
                    - param: advertiser_id
                      msg: must be an integer
  /component_creatives/v1.0/version:
    get:
      tags:
      - Component Creatives
      security: []
      summary: Get Group Version Info
      description: Get group version info
      operationId: Get-group-version-info
      responses:
        '200':
          description: ''
          content:
            application/json:
              examples:
                response:
                  value:
                    version: cfb1074-20190419202430
  /component_creatives/v1.0/approvals:
    get:
      tags:
      - Component Creatives
      security: []
      summary: List Creative Approvals
      description: '**⚠️ Deprecated** — Use `GET /v3.0/approvals` instead.


        List Creative Approvals'
      operationId: List-Creative-Approvals
      parameters:
      - name: atomic_creative_ids
        in: query
        description: Actually, an integer or comma-delimited list not to exceed 50 items
        required: true
        schema:
          type: string
      responses:
        '200':
          description: See below
          content:
            application/json:
              examples:
                response:
                  value:
                    data:
                    - atomic_creative_id: '6226793'
                      net_status: REJECTED
                      sources:
                        sharethrough: REJECTED
                        triplelift: PENDING
                    - atomic_creative_id: '6242534'
                      net_status: N/A
                      sources:
                        sharethrough: N/A
                        triplelift: N/A
                    - atomic_creative_id: '6242535'
                      net_status: REJECTED
                      sources:
                        sharethrough: REJECTED
                        triplelift: N/A
                    meta:
                      code: 200
                      status: success
                      type: approvals
    post:
      tags:
      - Component Creatives
      security: []
      summary: Post an Image or Subtitle Asset
      description: '**⚠️ Deprecated** — Use `POST /v3.0/creatives` instead.


        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}'
      operationId: Post-an-Image-or-Subtitle-Asset
      parameters:
      - name: adama_session
        in: header
        description: See below
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/Create-a-new-creativeBody'
      responses:
        '201':
          description: '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_"'
          content:
            application/json:
              examples:
                response:
                  value:
                    data:
                      advertiser_id: 100178
                      advertiser_name: Brooklyn Bubblegum Co.
                      assets:
                      - asset_id: 1538
                        asset_type: text
                        asset_value: new body
                        component_human_name: Body
                        component_id: 6
                      - asset_id: 1539
                        asset_type: image
                        component_human_name: Image
                        component_id: 2
                        image_file_size: null
                        image_filename: mediamathlogo.png
                        image_height: 100
                        image_url: https://s3.amazonaws.com/mm-component-creative/1479403779621_227082bd4ced0f888aa0066f06ea1402_mediamathlogo.png
                        image_width: 160
                      - asset_id: 311
                        asset_type: subtitle
                        component_human_name: Subtitle
                        component_id: 12
                        subtitle_filename: test.srt
                        subtitle_url: https://s3.amazonaws.com/mm-component-creative-api-qa11/1509985844769_eb5b2640445f1e13a63def2f6d194d5f_test.srt
                      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
        '400':
          description: ''
          content:
            application/json:
              examples:
                response:
                  value:
                    meta:
                      code: 400
                      status: error
                      message: Validation Error
                    errors:
                    - param: creative_name
                      msg: required
                    - param: advertiser_id
                      msg: must be an integer
  /component_creatives/v1.0/creatives/{atomic_creative_id}/eligibility:
    get:
      tags:
      - Component Creatives
      security: []
      summary: Get Creative's Eligibility Details
      description: '**⚠️ Deprecated** — Use `GET /v3.0/creatives/{atomic_creative_id}/eligibility` instead.


        Get creative''s eligibility details'
      operationId: Get-details-about-a-creatives-eligibility
      parameters:
      - name: atomic_creative_id
        in: path
        description: See below
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              examples:
                response:
                  value:
                    data:
                    - ad_format:
                        external_id: AUDIENCE_NETWORK_OUTSTREAM_VIDEO
                        name: Audience Network In-Stream Video
                        simple_name: In-stream
                      eligible: false
                      optional_components: []
                      required_components:
                      - id: '11'
                        name: Video
                        present: false
                      - id: '3'
                        name: Page ID
                        present: false
                      - id: '4'
                        name: Destination URL
                        present: true
                      supplier: Facebook
                      supplier_platform: Facebook Audience Network
                    - ad_format:
                        external_id: DESKTOP_FEED_STANDARD
                        name: Desktop Newsfeed - Image
                        simple_name: Desktop
                      eligible: false
                      optional_components: []
                      required_components:
                      - id: '2'
                        name: Image
                        present: true
                      - id: '3'
                        name: Page ID
                        present: false
                      - id: '4'
                        name: Destination URL
                        present: true
                      - id: '6'
                        name: Body
                        present: false
                      supplier: Facebook
                      supplier_platform: Facebook Newsfeed
                    - ad_format:
                        external_id: DESKTOP_FEED_STANDARD
                        name: Desktop Newsfeed - Video
                        simple_name: Desktop
                      eligible: false
                      optional_components: []
                      required_components:
                      - id: '11'
                        name: Video
                        present: false
                      - id: '3'
                        name: Page ID
                        present: false
                      - id: '4'
                        name: Destination URL
                        present: true
                      - id: '6'
                        name: Body
                        present: false
                      supplier: Facebook
                      supplier_platform: Facebook Newsfeed
                    - ad_format:
                        external_id: INSTAGRAM_STANDARD
                        name: Instagram Feed - Image
                        simple_name: Image
                      eligible: false
                      optional_components: []
                      required_components:
                      - id: '2'
                        name: Image
                        present: true
                      - id: '3'
                        name: Page ID
                        present: false
                      - id: '4'
                        name: Destination URL
                        present: true
                      - id: '6'
                        name: Body
                        present: false
                      supplier: Facebook
                      supplier_platform: Instagram
                    - ad_format:
                        external_id: INSTAGRAM_STANDARD
                        name: Instagram Feed - Video
                        simple_name: Video
                      eligible: false
                      optional_components: []
                      required_components:
                      - id: '11'
                        name: Video
                        present: false
                      - id: '3'
                        name: Page ID
                        present: false
                      - id: '4'
                        name: Destination URL
                        present: true
                      - id: '6'
                        name: Body
                        present: false
                      supplier: Facebook
                      supplier_platform: Instagram
                    - ad_format:
                        external_id: INSTANT_ARTICLE_STANDARD
                        name: Instant Articles - Image
                        simple_name: Image
                      eligible: false
                      optional_components: []
                      required_components:
                      - id: '2'
                        name: Image
                        present: true
                      - id: '3'
                        name: Page ID
                        present: false
                      - id: '4'
                        name: Destination URL
                        present: true
                      supplier: Facebook
                      supplier_platform: Facebook Instant Articles
                    - ad_format:
                        external_id: INSTANT_ARTICLE_STANDARD
                        name: Instant Articles - Video
                        simple_name: Video
                      eligible: false
                      optional_components: []
                      required_components:
                      - id: '11'
                        name: Video
                        present: false
                      - id: '3'
                        name: Page ID
                        present: false
                      - id: '4'
                        name: Destination URL
                        present: true
                      supplier: Facebook
                      supplier_platform: Facebook Instant Articles
                    - ad_format:
                        external_id: INSTREAM_VIDEO_DESKTOP
                        name: In-Stream Video (Desktop)
                        simple_name: Desktop
                      eligible: false
                      optional_components: []
                      required_components:
                      - id: '11'
                        name: Video
                        present: false
                      - id: '3'
                        name: Page ID
                        present: false
                      - id: '4'
                        name: Destination URL
                        present: true
                      supplier: Facebook
                      supplier_platform: Facebook In-Stream Video
                    - ad_format:
                        external_id: INSTREAM_VIDEO_MOBILE
                        name: In-Stream Video (Mobile)
                        simple_name: Mobile
                      eligible: false
                      optional_components: []
                      required_components:
                      - id: '11'
                        name: Video
                        present: false
                      - id: '3'
                        name: Page ID
                        present: false
                      - id: '4'
                        name: Destination URL
                        present: true
                      supplier: Facebook
                      supplier_platform: Facebook In-Stream Video
                    - ad_format:
                        external_id: MESSENGER_MOBILE_INBOX_MEDIA
                        name: Messenger Home
                        simple_name: Home
                      eligible: false
                      optional_components: []
                      required_components:
                      - id: '2'
                        name: Image
                        present: true
                      - id: '3'
                        name: Page ID
                        present: false
                      - id: '4'
                        name: Destination URL
                        present: true
                      supplier: Facebook
                      supplier_platform: Facebook Messenger
                    - ad_format:
                        external_id: MOBILE_BANNER
                        name: Audience Network Banner
                        simple_name: Banner
                      eligible: false
                      optional_components:
                      - id: '5'
                        name: View Tag
                        present: false
                      required_components:
                      - id: '2'
                        name: Image
                        present: true
                      - id: '3'
                        name: Page ID
                        present: false
                      - id: '4'
                        name: Destination URL
                        present: true
                      supplier: Facebook
                      supplier_platform: Facebook Audience Network
                    - ad_format:
                        external_id: MOBILE_FEED_STANDARD
                        name: Mobile Newsfeed - Image
                        simple_name: Mobile
                      eligible: false
                      optional_components: []
                      required_components:
                      - id: '2'
                        name: Image
                        present: true
                      - id: '3'
                        name: Page ID
                        present: false
                      - id: '4'
                        name: Destination URL
                        present: true
                      - id: '6'
                        name: Body
                        present: false
                      supplier: Facebook
                      supplier_platform: Facebook Newsfeed
                    - ad_format:
                        external_id: MOBILE_FEED_STANDARD
                        name: Mobile Newsfeed - Video
                        simple_name: Mobile
                      eligible: false
                      optional_components: []
                      required_components:
                      - id: '11'
                        name: Video
                        present: false
                      - id: '3'
                        name: Page ID
                        present: false
                      - id: '4'
                        name: Destination URL
                        present: true
                      - id: '6'
                        name: Body
                        present: false
                      supplier: Facebook
                      supplier_platform: Facebook Newsfeed
                    - ad_format:
                        external_id: MOBILE_INTERSTITIAL
                        name: Audience Network Interstitial - Image
                        simple_name: Interstitial
                      eligible: false
                      optional_components: []
                      required_components:
                      - id: '2'
                        name: Image
                        present: true
                      - id: '3'
                        name: Page ID
                        present: false
                      - id: '4'
                        name: Destination URL
                        present: true
                      supplier: Facebook
                      supplier_platform: Facebook Audience Network
                    - ad_format:
                        external_id: MOBILE_INTERSTITIAL
                        name: Audience Network Interstitial - Video
                        simple_name: Interstitial
                      eligible: false
                      optional_components: []
                      required_components:
                      - id: '11'
                        name: Video
                        present: false
                      - id: '3'
                        name: Page ID
                        present: false
                      - id: '4'
                        name: Destination URL
                        present: true
                      supplier: Facebook
                      supplier_platform: Facebook Audience Network
                    - ad_format:
                        external_id: MOBILE_NATIVE
                        name: Audience Network Native - Image
                        simple_name: Native
                      eligible: false
                      optional_components: []
                      required_components:
                

# --- truncated at 32 KB (98 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mediamath/refs/heads/main/openapi/mediamath-component-creatives-api-openapi.yml