Creatives API
The Creatives API allows you to manage your creatives (get and create).
Authentication
Get Creatives
Description: 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).
Required Parameters: None
Method: GET
Endpoint: https://api.ironsrc.com/advertisers/v2/creatives?
Parameters:
|
Name
|
Mandatory
|
Data type
|
Description |
|---|---|---|---|
| type | No | String | Filter creatives of a specified type. (Options: videoAndCarousel, videoAndFullScreen, videoAndInteractiveEndCard, playable 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. |
Request Example
Get https://api.ironsrc.com/advertisers/v2/creatives?
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": 8,
"requestId": "MTE0MTU4LjMwMC4yMDAuMTE="
}The API returns by default the first 3000 assets.
For better performance – we strongly recommend to work with pagination requests in all cases,
To do so you should use ‘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 ‘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/v2/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": 8,
"requestId": "MTE0MTU4LjMwMC4yMDAuMTE"
}For the next pages, use the requestId from the response and the required pageNumber.
For example: https://api.ironsrc.com/advertisers/v2/creatives?requestId=MTE0MTU4LjMwMC4yMDAuMTE&pageNumber=2
Keep increasing the ‘pageNumber’ param to get the following pages.
Create Creatives
Description: Use this API in order 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/v2/creatives?
|
Name
|
Mandatory
|
Data type
|
Description
|
|---|---|---|---|
| titleId | Yes | Number | The title ID. |
| creatives | Yes | Array<Creative> | An array of creatives |
Creative object:
|
Name
|
Mandatory
|
Data type
|
Description
|
|---|---|---|---|
| name | Yes | String | Name of the 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. |
Assets usageTypes:
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).
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]
}