Audiences from a customer list¶
Custom Audience allows advertisers to target their ads to a specific set of people with whom they have already established a relationship.
Audiences can be defined using Apple’s Advertising Identifier (IDFA), or Android’s advertising ID (GPADVID). Once created, these segments will be available for targeting using the TargetingAttribute service. A user will remain in an audience for 30 days from the moment their device was added, unless removed earlier using the API.
Fields¶
Audiences from customer lists have the following fields:
Name |
Description |
Type |
Add |
Update |
---|---|---|---|---|
|
The unique identifier of the audience. |
long |
N/A |
Required |
|
The id of the advertiser that owns the audience. |
long |
Required |
N/A |
|
The name of the audience segment. Maximum is 255 characters. |
string |
Required |
Optional |
|
A description for the segment. Maximum is 255 characters. |
string |
Optional |
Optional |
|
Must be set to CUSTOM. |
enum |
Required |
Read-Only |
|
Approximate unique user count for the segment. |
long |
Read-Only |
Read-Only |
|
User count for the most recent upload. |
long |
Read-Only |
Read-Only |
|
The status of the segment. Can be ACTIVE or DELETED, and is set to ACTIVE by default. |
enum |
Optional |
Optional |
Create a new audience
Method: To create a new audience, you will first need to create a blank audience by making a POST call to the audience endpoint with the required fields. Batch create is supported. The response will be the newly created audience, or a list of multiple new audiences if an array is passed.
For example:
POST https://api.gemini.yahoo.com/v3/rest/audience
Data passed
{
"advertiserId": 947366,
"name": "subscribers",
"type": "CUSTOM"
}
Example response
{
"errors": null,
"timestamp": "2015-06-30 22:05:06",
"response": {
"type": "CUSTOM",
"id": 20064660,
"advertiserId": 4387,
"name": "subscribers",
"description": "subscribers",
"status": "ACTIVE"
}
}
Add people to an audience
Method: After an audience has been created, you can add people to it using Apple’s Advertising Identifier (IDFA) or Android advertising ID by making a POST call to https://api.gemini.yahoo.com/v2/rest/audience/<audience_id>/people and passing in a “payload” JSON object that includes the following parameters:
Field |
Type |
Description |
---|---|---|
|
enum |
The |
|
JSON array |
The list of customer identifiers, for example: [ |
The response will include a confirmation that your data is being uploaded. For example:
POST https://api.gemini.yahoo.com/v3/rest/audience/20064660/people
Data passed
{
"payload": {
"schema": "IDFA",
"data": [
"idfa1",
"idfa2",
"idfa3",
"idfa4"
]
}
}
Example response
{
"errors": null,
"timestamp": "2015-07-01 6:12:28",
"response": {
"status": "PROCESSING"
}
}
You can add up to 10,000 people in a single “data” JSON array. If you would like to add more in a single POST call, you can also upload audience data by passing in a CSV file containing one device id per row. You should use form-data in your request, with “file” as the key. The request URL needs to indicate the audience id as well as the schema (IDFA or GPADVID).
For example:
POST https://api.gemini.yahoo.com/v3/rest/audience/20064660/file?schema=IDFA
The response will be similar to when passing in JSON. You can add up to 10M ids in a single file. If your audience is larger than 10M you can upload multiple files.
Check upload progress
Your segment will be updated within minutes with the people you have uploaded. You can check the status of the most recent upload by making a GET call to
https://api.gemini.yahoo.com/v3/rest/audience/<audience id>/progress
The response will include the count of users successfully added to the segment:
https://api.gemini.yahoo.com/v3/rest/audience/20064660/progress
{
"errors": null,
"timestamp": "2015-10-02 16:43:50",
"response": {
"status": "COMPLETED",
"count": 4000,
"failed": 0,
"errors": [],
"completedTime": "2015-10-02 16:43:48"
}
}
If invalid ids are passed, the response will include the count of invalid entries as well as a sample of ids that failed to upload:
https://api.gemini.yahoo.com/v3/rest/audience/20064660/progress
{
"errors": null,
"timestamp": "2015-10-02 16:48:57",
"response": {
"status": "COMPLETED",
"count": 0,
"failed": 4,
"errors": [
{
"details": "invalid idfa1",
"message": "Invalid id"
},
{
"details": "invalid idfa2",
"message": "Invalid id"
},
{
"details": "invalid idfa3",
"message": "Invalid id"
},
{
"details": "invalid idfa4",
"message": "Invalid id"
}
],
"completedTime": "2015-10-02 16:48:34"
}
}
Remove people from an audience
Method: You can remove people from an existing audience by making an HTTP DELETE call to https://api.gemini.yahoo.com/v3/rest/audience/audience_id/people/ passing in the same fields needed for adding people to an audience.
For example:
DELETE https://api.gemini.yahoo.com/v3/rest/audience/20064478/people
Data passed
{
"schema": "IDFA",
"data": [
"idfa4",
"idfa3"
]
}
Example response
{
"errors": null,
"timestamp": "2015-07-01 20:15:41",
"response": {
"status": "PROCESSING"
}
}
You can also remove people from an audience by making a DELETE call and passing in a CSV file similar to how CSV files are passed to add people to an audience.
Read audience data
Method: To read audience data, you can make a GET call to the audience endpoint and pass in the following parameters:
Name |
Description |
Type |
---|---|---|
|
The id of the parent advertiser. |
long |
|
The maximum number of rows to retrieve. Value should not be greater than 500. |
int |
|
The start index or the first element to retrieve. |
int |
Example: GET call for specific audience:
https://api.gemini.yahoo.com/v3/rest/audience/20064478
The response will be the relevant audiences:
{
"errors": null,
"timestamp": "2015-07-01 20:21:32",
"response": {
"type": "CUSTOM",
"id": 20064478,
"name": "subscribers",
"description": "subscribers",
"cnt": 1500954,
“lastUploadCnt”:1500954,
"status": "ACTIVE"
}
}
Example: GET call for a filtered list of audiences:
https://api.gemini.yahoo.com/v3/rest/audience/?advertiserId=947366
The response will be the relevant audiences:
{
"errors": null,
"timestamp": "2015-07-01 20:24:48",
"response": [
{
"type": "CUSTOM",
"id": 20064478,
"name": "idfa segment 1",
"description": "idfa segment 1",
"cnt": 2000000,
“lastUploadCnt”:2000000,
"status": "ACTIVE"
},
{
"type": "CUSTOM",
"id": 20064480,
"name": "idfa segment 2",
"description": "idfa segment 2",
"cnt": 3000000,
“lastUploadCnt”:3000000
"status": "ACTIVE"
}
]
}
Update existing audiences
Method: To update one or more existing audiences, make a PUT call with one or more audience objects. Specify the fields to update; note that id and type are the only required parameters, other fields are optional. The result will be the list of updated objects. Partial update is supported; fields that are either not passed or passed as null will be ignored for the update.
For example:
PUT https://api.gemini.yahoo.com/v3/rest/audience
Data passed
{
"type": "CUSTOM",
"id": 20064480,
"name": "updated segment name"
}
Example response
{
"errors": null,
"timestamp": "2015-07-02 2:43:16",
"response": {
"type": "CUSTOM",
"id": 20064480,
"name": "updated segment name",
"description": null,
"cnt": 750450,
“lastUploadCnt”:750450,
"status": "ACTIVE"
}
}
Delete an audience
Method: To delete an audience, make a PUT call with the audience object.
Name |
Description |
---|---|
|
The ID of the object to delete. |
|
The audience type. |
|
The status of the object set to be deleted. |
Note
In v2, the DELETE operation is supported for both single and multiple ids.
For example:
PUT https://api.gemini.yahoo.com/v3/rest/audience
DELETE https://api.gemini.yahoo.com/v3/rest/audience/{id}
DELETE https://api.gemini.yahoo.com/v3/rest/audience?id=123&id=1234&...
Data passed
{
"type": "CUSTOM",
"id": 20064480,
"status": "DELETED"
}
Example response
{
"errors": null,
"timestamp": "2015-07-02 2:46:39",
"response": {
"type": "CUSTOM",
"id": 20064480,
"name": "custom audience name",
"description": null,
"cnt": 100000,
“lastUploadCnt”:100000,
"status": "DELETED"
}
}