Audiences from a customer list

Overview

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
id The unique identifier of the audience. long N/A Required
advertiserId The id of the advertiser that owns the audience. long Required N/A
name The name of the audience segment. Maximum is 255 characters. string Required Optional
description A description for the segment. Maximum is 255 characters. string Optional Optional
type Must be set to CUSTOM. enum Required Read-Only
cnt Approximate unique user count for the segment. long Read-Only Read-Only
lastUploadCnt User count for the most recent upload. long Read-Only Read-Only
status 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
schema enum The schema field can be either IDFA (Apple’s advertising identifier) or GPADVID (Android’s advertising identifier).
data JSON array The list of customer identifiers, for example: [idfa1, idfa2, idfa3].

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
advertiserID The id of the parent advertiser. long
mr The maximum number of rows to retrieve. Value should not be greater than 500. int
si 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
id The ID of the object to delete.
type The audience type.
status 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"
          }
      }