Creative API

Use the Creative API v4 to programmatically create, update, and organize your ad creatives for campaign deployment.

Read time 4 minutes

Last updated 4 hours ago

The Creatives API allows you to manage your creatives (GET, CREATE, and UPDATE). Authentication Type: Bearer API Authentication

Get creative sets

Use this API to retrieve a list of your creatives. The response will include the following:

id

titleId

type

name

language

orientation

and a list of the assets (

id

and

usageType

of each asset). Method: GET Request Example URL: https://api.ironsrc.com/advertisers/v4/creatives Required Parameters: None

Parameters

Name	Required	Data type	Description
`type`	No	String	Filter creatives of a specified type. Can be one of the following: videoAndCarousel, videoAndFullScreen, playable, videoAndInteractiveEndCard, interactiveVideo.
`titleId`	No	Number	Filter creatives of a specific title.
`requestId`	No	String	Used for paginated requests.
`pageNumber`	No	Number	Used for paginated requests.
`resultsBulkSize`	No	Number	Used for paginated requests.

Response example


{
  "creatives": [
    {
      "id": 300,
      "titleId": 200,
      "name": "300 - Test creative 100 - 300",
      "type": "videoAndFullScreen",
      "language": "ru",
      "orientation": "all",
      "assets": [
        {
          "id": 1,
          "usageType": "left"
        }
      ]
    },
    {
      "id": 200,
      "titleId": 200,
      "name": "200 - Test creative - 200",
      "type": "videoAndFullScreen",
      "language": "ru",
      "orientation": "all",
      "assets": [
        {
          "id": 1,
          "usageType": "left"
        }
      ]
    },
    {
      "id": 101,
      "titleId": 200,
      "name": "101 - Test creative - 101",
      "type": "playable",
      "language": "he",
      "orientation": "all",
      "assets": [
        {
          "id": 1,
          "usageType": "left"
        }
      ]
    },
    {
      "id": 100,
      "titleId": 200,
      "name": "100 - Test creative - 100",
      "type": "videoAndCarousel",
      "language": "en",
      "orientation": "all",
      "assets": [
        {
          "id": 1,
          "usageType": "left"
        }
      ]
    },
    {
      "id": 10,
      "titleId": 100,
      "name": "Test creative name iec",
      "type": "interactiveVideo",
      "language": "cn",
      "orientation": "all",
      "assets": [
        {
          "id": 14,
          "usageType": "interactiveEndCard"
        }
      ]
    },
    {
      "id": 7,
      "titleId": 100,
      "name": "Test banner creative",
      "type": "templateBanner",
      "language": "en",
      "orientation": "all",
      "assets": []
    },
    {
      "id": 3,
      "titleId": 100,
      "name": "Test creative name 3",
      "type": "videoAndFullScreen",
      "language": "ru",
      "orientation": "all",
      "assets": [
        {
          "id": 1,
          "usageType": "tabletLandscape"
        },
        {
          "id": 4,
          "usageType": "video"
        },
        {
          "id": 5,
          "usageType": "phonePortrait"
        },
        {
          "id": 6,
          "usageType": "phoneLandscape"
        },
        {
          "id": 7,
          "usageType": "tabletPortrait"
        }
      ]
    },
    {
      "id": 1,
      "titleId": 100,
      "name": "Test creative name",
      "type": "videoAndCarousel",
      "language": "en",
      "orientation": "all",
      "assets": [
        {
          "id": 1,
          "usageType": "left"
        },
        {
          "id": 2,
          "usageType": "middle"
        },
        {
          "id": 3,
          "usageType": "right"
        },
        {
          "id": 4,
          "usageType": "video"
        }
      ]
    }
  ],
  "totalResultsCount": 11,
  "requestId": "MTE0MTU4LjMwMC4yMDAuMTE="
}

Get campaign creative sets

Use this API to retrieve a list of the assigned creatives for a given campaign. Method: GET Request Example URL: https://api.ironsrc.com/advertisers/v4/creatives/campaignCreatives/:campaignId Required Parameters: campaignId

Response example


{
    "creatives": [
        {
            "id": 338306,
            "lastUpdate": "2020-10-19T15:02:27.000Z",
            "storePage": null
        },
        {
            "id": 630755,
            "lastUpdate": "2023-04-30T08:45:41.000Z",
            "storePage": null
        },
        {
            "id": 950135,
            "lastUpdate": "2023-07-24T21:31:02.000Z",
            "storePage": "hello2"
        }
    ]
}

Pagination request

The API returns by default the first 3000 creatives. In order to get more creatives, you can use a pagination request. We strongly recommend to work with pagination requests in all cases for a better performance. To do so you should use the

resultsBulkSize

parameter. This parameter will limit the amount of the results you get in the response. In order to get the next bulk of results, use the

pageNumber

parameter, combined with the

requestId

parameter - which is received in the first response.

Pagination request example URL

In the first request you set the results number limitation: https://api.ironsrc.com/advertisers/v4/creatives?resultsBulkSize=2

Pagination response example


{
  "creatives": [{
            "id": 300,
            "titleId": 200,
            "name": "300 - Test creative 100 - 300",
            "type": "videoAndFullScreen",
            "language": "ru",
            "orientation": "all",
            "assets": [{"id": 1, "usageType": "left"}]
        },
        {
            "id": 200,
            "titleId": 200,
            "name": "200 - Test creative - 200",
            "type": "videoAndFullScreen",
            "language": "ru",
            "orientation": "all",
            "assets": [{"id": 1, "usageType": "left"}]
        }
    ],
    "totalResultsCount": 9,
    "requestId": "MjE2MDkzLjUwMTEwMC4yLjE5"
}

For the next pages, use the requestId from the response and the required

pageNumber

. For example: https://api.ironsrc.com/advertisers/v2/creatives?requestId=MjE2MDkzLjUwMTEwMC4yLjE5&pageNumber=2 Keep increasing the

pageNumber

parameter to get the following pages.

Create a creative set

Use this API to create a new creative. Multiple creatives for a title can be created in a single API call. Method: POST Content type: application/json Request Example URL: https://api.ironsrc.com/advertisers/v4/creatives Required Parameters: None

Body paramters

Name	Required	Data type	Description
`titleId`	Yes	Number	The title ID.
`creatives`	Yes	`Array<Creative>`	An array of creatives

Creative object

Name	Required	Data type	Description
`name`	Yes	String	Name of creative
`type`	Yes	String	Type of the creative, options: videoAndCarousel, videoAndFullScreen, videoAndInteractiveEndCard, playable
`language`	Yes	String	2 letter (for example, english="EN")
`assets`	Yes	`Array<Assets>`	List of asset ids + usageType

Asset usage type

For videoAndCarousel creative:
- video (mp4)
- left (image)
- middle (image)
- right (image)
For videoAndFullScreen creative:
- video (mp4)
- phonePortrait (image)
- phoneLandscape (image)
- tabletPortrait (image, optional)
- tabletLandscape (image, optional)
For videoAndInteractiveEndCard creative:
- video (mp4)
- interactiveEndCard (html)
For Playable creative
- playable (html)

Note

Creative objects contain the following: name, type, language and a list of assets.

For example:


{
    "name": "carousel creative example",
    "assets": [
        {
            "usageType": "video",
            "id": 4
        },
        {
            "usageType": "left",
            "id": 2
        },
        {
            "usageType": "middle",
            "id": 1
        },
        {
            "usageType": "right",
            "id": 3
        }
    ],
    "language": "EN",
    "type": "videoAndCarousel"
}

Full request example


{
    "titleId": titleId,
    "creatives": [
        {
            "name": "carousel creative example",
            "assets": [
                {
                    "usageType": "video",
                    "id": 4
                },
                {
                    "usageType": "left",
                    "id": 2
                },
                {
                    "usageType": "middle",
                    "id": 1
                },
                {
                    "usageType": "right",
                    "id": 3
                }
            ],
            "language": "AR",
            "type": "videoAndCarousel"
        },
        {
            "name": "IEC creative example",
            "assets": [
                {
                    "usageType": "interactiveEndCard",
                    "id": 13
                },
                {
                    "usageType": "video",
                    "id": 4
                }
            ],
            "language": "EN",
            "type": "videoAndInteractiveEndCard"
        },
        {
            "name": "Full screen creative example",
            "assets": [
                {
                    "usageType": "video",
                    "id": 4
                },
                {
                    "usageType": "phonePortrait",
                    "id": 9
                },
                {
                    "usageType": "phoneLandscape",
                    "id": 10
                }
            ],
            "language": "AR",
            "type": "videoAndFullScreen"
        }
    ]
}

Response example


{
    "success": true,
    "ids": [1,2,3]
}

Update a creative set

Use this API to add/update/remove creatives from campaigns. Multiple creatives can be removed, added, or updated for a single campaign. Method: PUT Content type: application/json Request Example URL: https://api.ironsrc.com/advertisers/v4/creatives/assign/:campaignId Required Parameters: campaignId

Body parameters

Name	Required	Data type	Description
`update`	No	`Array<Number>` , `Array<storePage>`	Creative to update/add to a single campaign
`remove`	No	`Array<Number>`	Creative to remove in a single campaign

Full request example


{
    "update": [
        {"id": 300, "storePage": "test"},
        {"id": 200}
    ],
    "remove": [100, 400]
}

Response example


{
    "success": true
}

Creative API

Get creative sets

Parameters

Name

Required

Data type

Description

Response example

Get campaign creative sets

Response example

Pagination request

Pagination request example URL

Pagination response example

Create a creative set

Body paramters

Name

Required

Data type

Description

Creative object

Name

Required

Data type

Description

Asset usage type

Full request example

Response example

Update a creative set

Body parameters

Name

Required

Data type

Description

Full request example

Response example