Creative API v4
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’ param 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 Parameters:
| 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 e.g 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<{id: Number; storePage?: String;}> | 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
}