Audience API

Integrate the Audience API to include or exclude specific users in their campaign, based on lists of device IDs supplied by the advertisers.

Read time 4 minutes

The Audience API allows advertisers to include or exclude specific users in their campaign, based on lists of device IDs supplied by the advertisers.

How do I define my audience set?

The ironSource Audience API supports two kinds of Audience lists: Suppression and Targeting.

Suppression lists

Suppression lists are associated with the campaign through a package name and platform, for example "com.facebook.katana" and "android". Each Suppression list supports one respective platform, either IDFA or GAID. This type of audience set operates as a blacklist. After a Suppression list is uploaded into our database, the audience set will automatically be opted out from every campaign that has a matching package name and platform.

Targeting lists

Targeting lists consist of device IDs which are defined and identified by the advertier, these lists can be included for different campaigns regardless of package name. This audience list supports both IDFA and GAID which can be update through the API. Targeting lists aren't automatically associated to any given campaign; an Account Manager must assist in either opting in or out of the list of devices per campaign. See the following table for example cases on when to use the above audience lists:

	Objective	Set Up	Mandatory Fields
Suppression list	Block users from a specific campaign	Automatically blacklisted	Package name & Platform
Targeting lists	Create retargeting campaigns or target any given audience set	Must be uploaded by AM	Advertiser ID

Authentication ID

For our system to identify your API requests, you will need an authentication ID. Follow these steps to generate this credential:

Generate your Authorization Header and Add it to Your PHP Code

To generate your Authorization header, you'll need to obtain your ironSource account's secret key:

Log in to the ironSource dashboard.
Click on your profile in the top right corner of the dashboard and select My Account from within the dropdown.
Then go to the Reporting API tab and you'll find your secret key.
Next, encode your
```
username:secret
```
key based on the base64 version and add an Authorization header in your code with your encoded
```
username:secret
```
key.

Note

Authentication is based on basic HTTP Authentication with HTTPS.

PHP code example to generate a username using secretkey with base64


 <?php
$crl = curl_init();
$base64encoded = base64_encode("[username]:[secret key]");
$header = array();
$header[] = 'Authorization: Basic '. $base64encoded;
 $URL='https://platform.ironsrc.com/partners/publisher/applications/<API Method>';
 curl_setopt($crl, CURLOPT_URL, $URL);
curl_setopt($crl, CURLOPT_HTTPHEADER, $header);
 $response = curl_exec($crl);
 curl_close($crl);
?>

API structure

The API consists of 5 requests: Metadata of audiences:

Show - displays the details of all existing audiences
Create - build a new audience
Delete - delete an existing audience

Device Id Updates:

```
AddAudience
```
- Add device list to existing audience
```
RemoveAudience
```
- Remove device list from an existing audience

API requests

Show

Displays the details of all existing audiences - GET request.

Field	Description	Data type
`audiences`	A list of objects that contain information about an audience	Array
`id`	ID of the audience list	Int
`type`	suppression static / targeting	String
`name`	Name of the audience list	String
`description`	Description of the audience list	String
`bundleId`	Package name of the source app	String
`platform`	Platform of the source app - “android” or “ios” or null	String
`lastModified`	Last update date of the audience list	Date
`hasActiveCampaigns`	True when audience has an active campaign running - False in any other case	Boolean

Example Request: https://platform-api.supersonic.com/audience/api/show Response will be code 200 for a non-empty list empty / 204 for an empty list. Example of a non-empty list:


{
  "count": 1,
  "audiences": [
    {
      "id": 1,
      "type": "targeting",
      "name": "batz",
      "description": "batz",
      "bundleId": "com.adsd.sdf",
      "platform": "android",
      "lastModified": "2017-01-31T20:00:00.000Z",
      "hasActiveCampaigns": true
    }
  ]
}

Create

You can easily create a new audience. This creates an empty audience with metadata only. POST Request.

Field	Description	Data Type	Required
`type`	supression static, targeting	String	Yes
`name`	Name of the audience	String	Yes
`description`	Description of the audience	String	Yes
`bundleID`	Package name of the source app	String or null	- No - if audienceType is only targeting - Yes - if audienceType is suppression static (you can fill trackId instead for iOS apps)
`trackId`	apple store id	String	- No - if audienceType is only targeting - Yes - if audienceType is suppression static and bundleID is empty
`platform`	Platform of the source app:“android” or “ios” or empty	String (android, ios) or null	- No - if audienceType is only targeting - Yes - if audienceType is supression static

Request example: https://platform-api.supersonic.com/audience/api/create

Request body


{
  "type": "suppression_static",
  "name": "batz",
  "description": "batz",
  "bundleId": "com.adsd.sdf",
  "platform": "android"
}

On success: Response code 200 is returned with created or existing ID.

{id : 67567fhgf6786786}

Delete

You can easily delete an existing audience.

Field	Description	Data Type	Required
`id`	ID of the audience	Int	Yes

Request example: https://platform-api.supersonic.com/audience/api/{id} Request body:

{"id":"67567fhgf6786786"}

On success: HTTP Response code 200 is returned with type, name, description, bundleId, platform.

Response example


{
  "type": "suppression_static",
  "name": "batz",
  "description": "batz",
  "bundleId": "com.adsd.sdf",
  "platform": "android"
}

Add or remove audience

You can add or remove a device list to existing audience in one call. There are three main scenarios in which you will want to use this API:

Add devices to a defined list
Remove devices from a defined list
Switch a specific device ID from one list to another

Note

We currently support up to 35,000 devices per request or message body of up to 250 kb.

Field	Description	Data Type	Required
`addAudience`	The specific audience list to which you'd like to add device ids	List	Yes
`deviceIds`	deviceId strings	List	Yes
`removeAudience`	The specific audience list from where you'd like to remove device ids	List	Yes

Example

Request example: https://platform-api.supersonic.com/audience/api Request body:

When adding devices, leave the
```
removeAudience
```
field empty.
When removing devices, leave the
```
addAudience
```
field empty.
There should only be values in both the
```
addAudience
```
and
```
removeAudience
```
fields if you are switching a device id from one list to the other.

The following are three examples of the different scenarios:

Add device IDs


{
  "addAudience": ["1","2"],
  "removeAudience": [],
  "deviceIds": [
     "66b728c2-f9a4-4d87-82ef-ce07414nili1",
     "66b728c2-f9a4-4d87-82ef-ce07414nili1"
      ]
}

On success: Response code 200

Remove device IDs


{
  "addAudience": [],
  "removeAudience": ["1","2"],
  "deviceIds": [
     "66b728c2-f9a4-4d87-82ef-ce07414nili1",
     "66b728c2-f9a4-4d87-82ef-ce07414nili1"
      ]
}

On success: Response code 200

Switch device IDs from one list to the other


{
  "addAudience": ["1","2"],
  "removeAudience": ["4","5"],
  "deviceIds": [
     "66b728c2-f9a4-4d87-82ef-ce07414nili1",
     "66b728c2-f9a4-4d87-82ef-ce07414nili1"
      ]
}

On success: Response code 200

Audience API

How do I define my audience set?

Suppression lists

Targeting lists

Objective

Set Up

Mandatory Fields

Authentication ID

Generate your Authorization Header and Add it to Your PHP Code

PHP code example to generate a username using secretkey with base64

API structure

API requests

Show

Field

Description

Data type

Create

Field

Description

Data Type

Required

Request body

Delete

Field

Description

Data Type

Required

Response example

Add or remove audience

Field

Description

Data Type

Required

Example