MediaMath Atomic Creatives API

openapi: 3.0.0
info:
  title: Campaigns Ad Servers Atomic Creatives API
  description: 'MediaMath Campaign Management API


    [Postman Collection](https://apidocs.mediamath.com/guides/postman-collections)

    '
  version: 3.0.1807
  contact:
    url: https://support.infillion.com/
servers:
- url: https://api.mediamath.com/api/v3.0
  description: Live Server
security:
- Auth0:
  - offline_access
  - manage:services
tags:
- name: Atomic Creatives
  description: Atomic Creatives
paths:
  /creative_draft:
    post:
      operationId: preview-creative-assets
      summary: Preview creative assets before uploading
      description: "This endpoint allows you to preview creative assets before they are permanently uploaded to the system. \nIt validates the files and metadata, returning a preview of what will be created without actually \nstoring the creatives. This is useful for verifying that your files and metadata are correct before \ncommitting to the upload.\n"
      tags:
      - Atomic Creatives
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - filename
              - metadata
              properties:
                filename:
                  type: array
                  description: Creative asset files to upload
                  minItems: 1
                  maxItems: 10
                  items:
                    type: string
                    format: binary
                    x-allowed-extensions:
                    - .gif
                    - .jpg
                    - .jpeg
                    - .png
                    - .tiff
                    - .tif
                    - .svg
                    - .swf
                    - .htm
                    - .html
                    - .css
                    - .js
                    - .woff
                    - .woff2
                    - .ttf
                    - .otf
                    - .zip
                    x-max-file-size: 10485760
                metadata:
                  type: object
                  description: JSON string containing metadata for all files
                  required:
                  - advertiser_id
                  properties:
                    advertiser_id:
                      type: integer
                      format: int32
                      minimum: 0
                      example: 123
                    is_https:
                      type: boolean
                      default: true
                    submissions:
                      type: array
                      description: This (optional) array should contain an entry for each file being uploaded (or the files inside the outer zip for HTML5 creatives), with details about the creative. If omitted, the system will attempt to infer details from the uploaded file itself.
                      items:
                        type: object
                        required:
                        - name
                        - click_through_url
                        properties:
                          name:
                            type: string
                            example: one.jpg
                          click_through_url:
                            type: string
                            format: uri
                            example: https://example.com/clickThrough
                          landing_page:
                            type: string
                            format: uri
                            example: https://example.com/landing
                          concept_id:
                            type: integer
                            format: int32
                            minimum: 0
                            example: 123
                          backup:
                            type: string
                            example: backup_image.jpg
                            description: Optional backup image filename for HTML5 creatives. Used as a fallback when HTML5 content cannot be displayed.
            examples:
              single_image:
                summary: Single image preview request
                value:
                  filename:
                  - banner_300x250.jpg
                  metadata:
                    advertiser_id: 100212
                    is_https: true
                    submissions:
                    - name: banner_300x250.jpg
                      click_through_url: https://example.com/click
                      landing_page: https://example.com/landing
                      concept_id: 4157184
              multiple_images:
                summary: Multiple images preview request
                value:
                  filename:
                  - medium_image8.jpg
                  - medium_image10.jpg
                  metadata:
                    advertiser_id: 100212
                    is_https: false
                    submissions:
                    - name: medium_image8.jpg
                      click_through_url: click1
                      landing_page: https://example1.com
                      concept_id: 4157184
                    - name: medium_image10.jpg
                      click_through_url: click2
                      landing_page: https://example2.com
                      concept_id: 4157184
              html5_creative:
                summary: HTML5 creative (zip) preview request - backup can be omitted if it has the same filename as main file (interactive_ad) differing only in extension
                value:
                  filename:
                  - html5_wrap_file.zip
                  metadata:
                    advertiser_id: 100212
                    is_https: true
                    submissions:
                    - name: interactive_ad.zip
                      click_through_url: https://brand.example.com/click
                      landing_page: https://brand.example.com/products
                      concept_id: 3001
      responses:
        '200':
          description: Preview generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      uploaded_files:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                      metadata:
                        type: object
                        properties:
                          advertiser_id:
                            type: integer
                            format: int32
                          is_https:
                            type: boolean
                          submissions:
                            type: array
                            items:
                              type: object
                              properties:
                                name:
                                  type: string
                                landing_page:
                                  type: string
                                  format: uri
                                click_through_url:
                                  type: string
                                concept_id:
                                  type: integer
                                  format: int32
                                backup:
                                  type: string
                  meta:
                    type: object
                    properties:
                      status:
                        type: string
              examples:
                single_image:
                  summary: Single image preview
                  value:
                    data:
                      uploaded_files:
                      - name: banner_300x250.jpg
                      metadata:
                        advertiser_id: 100212
                        is_https: true
                        submissions:
                        - name: banner_300x250.jpg
                          landing_page: https://example.com/landing
                          click_through_url: https://example.com/click
                          concept_id: 4157184
                    meta:
                      status: success
                multiple_images:
                  summary: Multiple images preview
                  value:
                    data:
                      uploaded_files:
                      - name: medium_image8.jpg
                      - name: medium_image10.jpg
                      metadata:
                        advertiser_id: 100212
                        is_https: false
                        submissions:
                        - name: medium_image8.jpg
                          landing_page: https://example1.com
                          click_through_url: click1
                          concept_id: 4157184
                        - name: medium_image10.jpg
                          landing_page: https://example2.com
                          click_through_url: click2
                          concept_id: 4157184
                    meta:
                      status: success
                html5_creative:
                  summary: HTML5 creative preview (zip)
                  value:
                    data:
                      uploaded_files:
                      - name: interactive_ad.zip
                      metadata:
                        advertiser_id: 100212
                        is_https: true
                        submissions:
                        - name: interactive_ad.zip
                          landing_page: https://brand.example.com/products
                          click_through_url: https://brand.example.com/click
                          concept_id: 3001
                    meta:
                      status: success
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    nullable: true
                  meta:
                    type: object
                    properties:
                      status:
                        type: string
                      error:
                        type: string
              examples:
                missing_required_field:
                  summary: Missing required metadata field
                  value:
                    data: null
                    meta:
                      status: error
                      error: 'Missing required field: advertiser_id'
                invalid_file_type:
                  summary: Invalid file extension
                  value:
                    data: null
                    meta:
                      status: error
                      error: 'Invalid file type. Allowed extensions: .gif, .jpg, .jpeg, .png, .tiff, .tif, .svg, .swf, .htm, .html, .css, .js, .woff, .woff2, .ttf, .otf, .zip'
                file_too_large:
                  summary: File size exceeds limit
                  value:
                    data: null
                    meta:
                      status: error
                      error: File size exceeds maximum allowed size of 10MB
  /creative_upload:
    post:
      operationId: upload-creative-assets
      summary: Creative assets upload
      description: "Upload creative assets to the system and create atomic creatives. This endpoint processes the uploaded \nfiles and metadata, validates them, and stores them permanently in the system. Once uploaded, the \ncreatives can be associated with campaigns and strategies.\n"
      tags:
      - Atomic Creatives
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - filename
              - metadata
              properties:
                filename:
                  type: array
                  description: Creative asset files to upload
                  minItems: 1
                  maxItems: 10
                  items:
                    type: string
                    format: binary
                    x-allowed-extensions:
                    - .gif
                    - .jpg
                    - .jpeg
                    - .png
                    - .tiff
                    - .tif
                    - .svg
                    - .swf
                    - .htm
                    - .html
                    - .css
                    - .js
                    - .woff
                    - .woff2
                    - .ttf
                    - .otf
                    - .zip
                    x-max-file-size: 10485760
                metadata:
                  type: object
                  description: JSON string containing metadata for all files
                  required:
                  - advertiser_id
                  - submissions
                  properties:
                    advertiser_id:
                      type: integer
                      format: int32
                      minimum: 0
                      example: 123
                    is_https:
                      type: boolean
                      default: true
                    submissions:
                      type: array
                      description: This array should contain an entry for each file being uploaded (or the files inside the outer zip for HTML5 creatives), with details about the creative.
                      minItems: 1
                      items:
                        type: object
                        required:
                        - name
                        - click_through_url
                        - concept_id
                        properties:
                          name:
                            type: string
                            maxLength: 256
                            example: one.jpg
                            description: The name of the creative file. For HTML5 creatives, this should match the filename inside the zip (e.g., "interactive_ad.zip"). For zip files containing images, this should match the filename inside the zip. For non-HTML5 creatives, this should match the uploaded filename.
                          click_through_url:
                            type: string
                            format: uri
                            example: https://example.com/clickThrough
                          landing_page:
                            type: string
                            format: uri
                            example: https://example.com/landing
                          concept_id:
                            type: integer
                            format: int32
                            minimum: 0
                            example: 123
                          backup:
                            type: string
                            example: backup_image.jpg
                            description: Optional backup image filename for HTML5 creatives. Used as a fallback when HTML5 content cannot be displayed.
                          creative_name:
                            type: string
                            maxLength: 256
                            example: My Custom Creative Name
                            description: Optional display name for the atomic creative. When provided, this overrides the default name (i.e. the filename).
            examples:
              single_upload:
                summary: Single creative upload request
                value:
                  filename:
                  - holiday_banner_728x90.jpg
                  metadata:
                    advertiser_id: 100212
                    is_https: true
                    submissions:
                    - name: holiday_banner_728x90.jpg
                      click_through_url: https://shop.example.com/holiday-sale
                      landing_page: https://shop.example.com/landing/holiday
                      concept_id: 1001
              multiple_images:
                summary: Multiple images upload request
                value:
                  filename:
                  - Adobe_Easy_728x90.zip
                  - Adobe_Easy_300x600.zip
                  metadata:
                    advertiser_id: 100212
                    is_https: true
                    submissions:
                    - name: Adobe_Easy_728x90.zip
                      click_through_url: click
                      landing_page: https://example.com
                      concept_id: 4253705
                    - name: Adobe_Easy_300x600.zip
                      click_through_url: click
                      landing_page: https://example.com
                      concept_id: 4253705
              html5_creative_upload:
                summary: HTML5 creative (zip) upload request - backup can be omitted if it has the same filename as main file (interactive_ad) differing only in extension
                value:
                  filename:
                  - html5_wrap_file.zip
                  metadata:
                    advertiser_id: 100212
                    is_https: true
                    submissions:
                    - name: interactive_ad.zip
                      click_through_url: https://brand.example.com/click
                      landing_page: https://brand.example.com/products
                      concept_id: 3001
              html5_creative_upload_with_backup:
                summary: HTML5 creative (zip) upload request with backup image
                value:
                  filename:
                  - html5_wrap_file.zip
                  metadata:
                    advertiser_id: 100212
                    is_https: true
                    submissions:
                    - name: interactive_ad.zip
                      click_through_url: https://brand.example.com/click
                      landing_page: https://brand.example.com/products
                      concept_id: 3001
                      backup: interactive_ad_backup.jpg
      responses:
        '200':
          description: Upload completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          format: int64
                        version:
                          type: integer
                        entity_type:
                          type: string
                        advertiser_id:
                          type: integer
                          format: int32
                        concept_id:
                          type: integer
                          format: int32
                        concept_name:
                          type: string
                        name:
                          type: string
                        width:
                          type: integer
                        height:
                          type: integer
                        file_type:
                          type: string
                        is_https:
                          type: boolean
                        is_multi_creative:
                          type: boolean
                        has_sound:
                          type: boolean
                        rich_media:
                          type: boolean
                        status:
                          type: boolean
                        built:
                          type: boolean
                        build_date:
                          type: string
                          format: date-time
                        built_by_user_id:
                          type: integer
                          format: int32
                        created_on:
                          type: string
                          format: date-time
                        last_modified:
                          type: string
                          format: date-time
                        external_identifier:
                          type: string
                        tpas_ad_tag_name:
                          type: string
                        updated_on:
                          type: string
                          format: date-time
                        click_url:
                          type: string
                          format: uri
                        ad_format:
                          type: string
                        expansion_trigger:
                          type: string
                        expansion_direction:
                          type: string
                        ad_server_type:
                          type: string
                        t1as:
                          type: boolean
                        edited_tag:
                          type: string
                        click_through_url:
                          type: string
                        approval_status:
                          type: string
                        media_type:
                          type: string
                        is_mraid:
                          type: boolean
                        sizmek_tag_status:
                          type: string
                        sizmek_creative_status:
                          type: string
                  meta:
                    type: object
                    properties:
                      status:
                        type: string
                      count:
                        type: integer
                      total_count:
                        type: integer
                      offset:
                        type: integer
                      next_page:
                        type: string
                        format: uri
              examples:
                single_image_upload:
                  summary: Single image creative uploaded
                  value:
                    data:
                    - id: 11990780
                      version: 0
                      entity_type: atomic_creative
                      advertiser_id: 100212
                      concept_id: 4253705
                      concept_name: Concept A
                      name: banner_300x250.jpg
                      width: 300
                      height: 250
                      file_type: jpg
                      is_https: true
                      is_multi_creative: false
                      has_sound: false
                      rich_media: false
                      status: true
                      built: false
                      build_date: '2025-12-12T19:17:31Z'
                      built_by_user_id: 22612
                      created_on: '2025-12-12T19:17:31Z'
                      last_modified: '2025-12-12T19:17:31Z'
                      external_identifier: mm12345.678901
                      tpas_ad_tag_name: banner_300x250
                      updated_on: '2025-12-12T19:17:31Z'
                      click_url: https://example.com
                      ad_format: DISPLAY
                      expansion_trigger: MOUSEOVER
                      expansion_direction: NONRESTRICTED
                      ad_server_type: TERMINALONE
                      t1as: true
                      edited_tag: ''
                      click_through_url: https://example.com/click
                      approval_status: PENDING
                      media_type: display
                      is_mraid: false
                      sizmek_tag_status: NOT_USED
                      sizmek_creative_status: NOT_USED
                    meta:
                      status: success
                      count: 1
                      total_count: 1
                      offset: 0
                      next_page: https://api.mediamath.com/creative_upload?page_offset=0
                multiple_creatives_upload:
                  summary: HTML5 creative upload - multiple creatives
                  value:
                    data:
                    - id: 11990782
                      version: 0
                      entity_type: atomic_creative
                      advertiser_id: 100212
                      concept_id: 4253705
                      concept_name: Concept A
                      name: Adobe_Easy_728x90
                      width: 728
                      height: 90
                      file_type: html5
                      is_https: true
                      is_multi_creative: false
                      has_sound: false
                      rich_media: false
                      status: true
                      built: false
                      build_date: '2025-12-12T19:17:31Z'
                      built_by_user_id: 22612
                      created_on: '2025-12-12T19:17:31Z'
                      last_modified: '2025-12-12T19:17:31Z'
                      external_identifier: mm87682.637552
                      tpas_ad_tag_name: Adobe_Easy_728x90
                      updated_on: '2025-12-12T19:17:31Z'
                      click_url: https://example.com
                      ad_format: DISPLAY
                      expansion_trigger: MOUSEOVER
                      expansion_direction: NONRESTRICTED
                      ad_server_type: TERMINALONE
                      t1as: true
                      edited_tag: <!DOCTYPE html>...
                      click_through_url: click
                      approval_status: PENDING
                      media_type: display
                      is_mraid: false
                      sizmek_tag_status: NOT_USED
                      sizmek_creative_status: NOT_USED
                    - id: 11990783
                      version: 0
                      entity_type: atomic_creative
                      advertiser_id: 100212
                      concept_id: 4253705
                      concept_name: Concept A
                      name: Adobe_Easy_300x600
                      width: 728
                      height: 90
                      file_type: html5
                      is_https: true
                      is_multi_creative: false
                      has_sound: false
                      rich_media: false
                      status: true
                      built: false
                      build_date: '2025-12-12T19:17:32Z'
                      built_by_user_id: 22612
                      created_on: '2025-12-12T19:17:32Z'
                      last_modified: '2025-12-12T19:17:32Z'
                      external_identifier: mm47594.615037
                      tpas_ad_tag_name: Adobe_Easy_300x600
                      updated_on: '2025-12-12T19:17:32Z'
                      click_url: https://example.com
                      ad_format: DISPLAY
                      expansion_trigger: MOUSEOVER
                      expansion_direction: NONRESTRICTED
                      ad_server_type: TERMINALONE
                      t1as: true
                      edited_tag: <!DOCTYPE html>...
                      click_through_url: click
                      approval_status: PENDING
                      media_type: display
                      is_mraid: false
                      sizmek_tag_status: NOT_USED
                      sizmek_creative_status: NOT_USED
                    meta:
                      status: success
                      count: 2
                      total_count: 2
                      offset: 0
                      next_page: https://api.mediamath.com/creative_upload?page_offset=0
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    nullable: true
                  meta:
                    type: object
                    properties:
                      status:
                        type: string
                      error:
                        type: string
              examples:
                validation_error:
                  summary: Validation failed
                  value:
                    data: null
                    meta:
                      status: error
                      error: 'Invalid metadata: submissions array cannot be empty'
                invalid_concept:
                  summary: Invalid concept ID
                  value:
                    data: null
                    meta:
                      status: error
                      error: Concept ID 999 not found for advertiser 100212
                file_processing_error:
                  summary: File processing failed
                  value:
                    data: null
                    meta:
                      status: error
                      error: 'Failed to process file: corrupted zip archive'
                unauthorized_advertiser:
                  summary: Unauthorized advertiser access
                  value:
                    data: null
                    meta:
                      status: error
                      error: User does not have access to advertiser 100212
  /atomic_creatives:
    get:
      operationId: list-atomic-creatives
      summary: List Atomic Creatives
      description: Get a list of atomic creatives
      tags:
      - Atomic Creatives
      parameters:
      - $ref: '#/components/parameters/extended'
      responses:
        '200':
          $ref: '#/components/responses/atomic_creative_collection'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '404':
          $ref: '#/components/responses/error'
    post:
      summary: Create atomic creative
      description: Create an atomic creative
      tags:
      - Atomic Creatives
      operationId: post-atomic_creatives
      parameters:
      - $ref: '#/components/parameters/extended'
      responses:
        '201':
          $ref: '#/components/responses/atomic_creative'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '404':
          $ref: '#/components/responses/error'
      requestBody:
        $ref: '#/components/requestBodies/atomic_creative_create'
  /atomic_creatives/{atomic_creative_id}:
    get:
      operationId: get-atomic-creative
      summary: Get an Atomic Creative
      description: Get an atomic creative by ID
      tags:
      - Atomic Creatives
      responses:
        '200':
          $ref: '#/components/responses/atomic_creative'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '404':
          $ref: '#/components/responses/error'
      parameters:
      - $ref: '#/components/parameters/extended'
      - schema:
          type: integer
        name: atomic_creative_id
        in: path
        required: true
        description: Numeric ID of the atomic creative to get
    post:
      summary: Update an atomic creative
      description: Update an atomic creative by ID
      tags:
      - Atomic Creatives
      operationId: post-atomic_creatives-atomic_creative_id
      responses:
        '200':
          $ref: '#/components/responses/atomic_creative'
        '400':
          $ref: '#/components/responses/error'
        '401':
          $ref: '#/components/responses/error'
        '403':
          $ref: '#/components/responses/error'
        '404':
          $ref: '#/components/responses/error'
        '409':
          $ref: '#/components/responses/error'
      requestBody:
        $ref: '#/components/requestBodies/atomic_creative_update'
      parameters:
      - $ref: '#/components/parameters/extended'
      - schema:
          type: integer
        name: atomic_cre

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