Lookalike Audiences

Overview

A lookalike audience expands the reach of first-party audiences by identifying audience users that are similar to your customers. You can build lookalike audiences based on custom data, Yahoo data and third-party data.

Note

You can only build a lookalike audience for one advertiser at a time, not for an entire seat.

Endpoint

https://dspapi.admanagerplus.yahoo.com/traffic/audiences/lookalike

Fields

The Lookalike audience object contains the following fields:

Name Description Type Add Update
id ID of the audience segment. integer N/A Required
name Name of the segment. text Required Optional
status

Current status of the segment.

  • ACTIVE - (Default Value) Active.
  • INACTIVE - Inactive
text Optional Optional
accountId Advertiser/account ID associated with this segment. Refer to Advertisers. integer Required Required
seedAudienceId Associated seed audience id. You must perform a search for seed audiences to get this Id. Refer to Search Seed Audiences. integer Required N/A
countries Array of country names. Use the name field from the Supported Countries response. array Required N/A
expectedSize Expected size for the modeled audience. The audience size will be within 10% of this value. Default is 30 million (users). integer Required Optional
seedAudienceName (Read-Only) Seed audience name. text N/A N/A
seedAudienceType (Read-Only) Seed audience type. text N/A N/A
createdAt (Read-Only) Creation timestamp. datetime N/A N/A

Read Audience (Single)

To retrieve data for a specific Lookalike Audience, make a GET call with the parameters specified below.

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/lookalike/{id}?accountId={accountId}
Name Description Type Required?
id Audience / Segment ID integer Y
accountId Account or Advertiser ID integer Y

The response will be the Lookalike Audience segment associated with the given ID.

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/lookalike/50379978?accountId=1356341

Example Response

{
  "response": {
    "id": 50379978,
    "name": "Lookalike",
    "seedAudienceId": 50378341,
    "seedAudienceName": "hp_sets_installer_ie_20171108_59083",
    "seedAudienceType": "EMAIL",
    "createdAt": "2017-11-10",
    "accountId": 1356341,
    "expectedSize": 1000000,
    "countries": [
      "United States"
    ],
    "status": "ACTIVE"
  },
  "errors": null,
  "timeStamp": "2017-12-01T21:41:09Z"
}

Update Audience

To update an existing Lookalike Audience, make a PUT call with a payload body and id parameter. The response will be the updated Audience.

Partial update is supported; fields that are either not passed or passed as null will be ignored during update.

Note

After you create a lookalike audience, you can rename it, change its status, or adjust its size. You cannot change the seed audience for a lookalike audience once you create it.

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/lookalike/{id}
Name Description Type Required?
id Audience / Segment ID integer Y

Example Request

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/lookalike/50379978

Example Payload

{
  "name": "Lookalike-PUT",
  "accountId": 1356341,
  "expectedSize": 1500,
  "status": "INACTIVE"
}

Example Response

{
  "response": {
    "id": 50379978,
    "name": "Lookalike-PUT",
    "seedAudienceId": 50378341,
    "seedAudienceName": "hp_sets_installer_ie_20171108_59083",
    "seedAudienceType": "EMAIL",
    "createdAt": "2017-11-10",
    "accountId": 1356341,
    "expectedSize": 1500,
    "countries": [
      "United States"
    ],
    "status": "INACTIVE"
  },
  "errors": null,
  "timeStamp": "2017-12-01T22:26:09Z"
}

Create Audience

To create a new Lookalike Audience, make a POST call with a payload body. The response will be the newly created Audience.

Note

Lookalike audiences take about 24 hours to populate.

Example Request

POST https://dspapi.admanagerplus.yahoo.com/traffic/audiences/lookalike

Example Payload

{
  "name": "Lookalike",
  "seedAudienceId": 50378341,
  "accountId": 1356341,
  "expectedSize": 1000000,
  "countries": [
    "United States"
  ],
  "status": "ACTIVE"
}

Example Response

{
  "response": {
    "id": 50379978,
    "name": "Lookalike",
    "seedAudienceId": 50378341,
    "seedAudienceName": "hp_sets_installer_ie_20171108_59083",
    "seedAudienceType": "EMAIL",
    "createdAt": "2017-12-01",
    "accountId": 1356341,
    "expectedSize": 1000000,
    "countries": [
      "United States"
    ],
    "status": "ACTIVE"
  },
  "errors": null,
  "timeStamp": "2017-12-01T22:30:37Z"
}

Delete Audience

Audience deletion is not supported by the API.

Search Seed Audiences (Filtered)

To retrieve list of seeds for specific type, make a GET call with the parameters specified below:

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/lookalike/search?accountId={accountId}&segment={segment}&access={access}&query={query}&limit={limit}&page={page}
Name Description Type Required?
accountId Account or Advertiser ID. integer Y
segment

Seed segment (audience) type.

text Y
access

Segment access control.

  • OWNED - Segments owned by advertiser.
  • DIRECT_SHARED - Segments which have been explicitly shared with an advertiser. Does not include GLOBAL segments and segments shared to seat.
  • SHARED - GLOBAL segments, direct shared segments, or segments owned or shared to seat. These segments are visible to every advertiser in any seat.
  • ALL - (Default)
text N
query Search term. Use url encoding conventions (i.e. a space should be replaced with a + or %20). text N
limit Total number of items to return. Default is 20. integer N
page Page number. integer N

The response will be a list of matching segments which can be used to create a Lookalike audience. The response contains the following fields of interest:

Name Description
id Unique ID of the segment. This value will be used as seedAudienceId when creating a new Lookalike audience.
name Segment name.
status

Current status of the segment.

  • ACTIVE
  • INACTIVE
segmentType Seed audience type.
reachCount Number of unique user in this segment.

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/lookalike/search?accountId=1356341&access=OWNED&segment=WEBSITE

Example Response

{
  "response": [
    {
      "id": 50387897,
      "name": "HK_Property_Men_All",
      "status": "ACTIVE",
      "segmentType": "WEBSITE",
      "reachCount": 223437
    },
    {
      "id": 50387894,
      "name": "HK_Property_Men_Fashion & Grooming",
      "status": "ACTIVE",
      "segmentType": "WEBSITE",
      "reachCount": 34
    },
    {
      "id": 50387893,
      "name": "HK_Property_Men_Auto",
      "status": "ACTIVE",
      "segmentType": "WEBSITE",
      "reachCount": 10933
    }
  ],
  "errors": null,
  "timeStamp": "2017-12-01T22:50:36Z"
}

Get Supported Countries

To retrieve supported countries, make a GET call with the parameters specified below. The response will be a list of countries.

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/lookalike/supported_countries

Example Response

{
  "supportedCountries": [
    {
      "isoCode": "AF",
      "name": "Afghanistan"
    },
    {
      "isoCode": "AX",
      "name": "Aland Islands"
    },
    {
      "isoCode": "AL",
      "name": "Albania"
    },
    {
      "isoCode": "DZ",
      "name": "Algeria"
    },
    {
      "isoCode": "AS",
      "name": "American Samoa"
    },
    {
      "isoCode": "AD",
      "name": "Andorra"
    },
    {
      "isoCode": "AO",
      "name": "Angola"
    },
    {
      "isoCode": "AI",
      "name": "Anguilla"
    },
    {
      "isoCode": "AQ",
      "name": "Antarctica"
    },
    {
      "isoCode": "AG",
      "name": "Antigua and Barbuda"
    },
    {
      "isoCode": "AR",
      "name": "Argentina"
    },
    {
      "isoCode": "AM",
      "name": "Armenia"
    },
    {
      "isoCode": "AW",
      "name": "Aruba"
    },
    {
      "isoCode": "AU",
      "name": "Australia"
    },
    {
      "isoCode": "AT",
      "name": "Austria"
    },
    {
      "isoCode": "AZ",
      "name": "Azerbaijan"
    },
    {
      "isoCode": "BS",
      "name": "Bahamas"
    },
    {
      "isoCode": "BH",
      "name": "Bahrain"
    },
    {
      "isoCode": "BD",
      "name": "Bangladesh"
    },
    {
      "isoCode": "BB",
      "name": "Barbados"
    },
    {
      "isoCode": "BY",
      "name": "Belarus"
    },
    {
      "isoCode": "BE",
      "name": "Belgium"
    },
    {
      "isoCode": "BZ",
      "name": "Belize"
    },
    {
      "isoCode": "BJ",
      "name": "Benin"
    },
    {
      "isoCode": "BM",
      "name": "Bermuda"
    },
    {
      "isoCode": "BT",
      "name": "Bhutan"
    },
    {
      "isoCode": "BO",
      "name": "Bolivia"
    },
    {
      "isoCode": "BA",
      "name": "Bosnia and Herzegovina"
    },
    {
      "isoCode": "BW",
      "name": "Botswana"
    },
    {
      "isoCode": "BR",
      "name": "Brazil"
    },
    {
      "isoCode": "IO",
      "name": "British Indian Ocean Territory"
    },
    {
      "isoCode": "VG",
      "name": "British Virgin Islands"
    },
    {
      "isoCode": "BN",
      "name": "Brunei Darussalam"
    },
    {
      "isoCode": "BG",
      "name": "Bulgaria"
    },
    {
      "isoCode": "BF",
      "name": "Burkina Faso"
    },
    {
      "isoCode": "KH",
      "name": "Cambodia"
    },
    {
      "isoCode": "CM",
      "name": "Cameroon"
    },
    {
      "isoCode": "CA",
      "name": "Canada"
    },
    {
      "isoCode": "CV",
      "name": "Cape Verde"
    },
    {
      "isoCode": "KY",
      "name": "Cayman Islands"
    },
    {
      "isoCode": "CF",
      "name": "Central African Republic"
    },
    {
      "isoCode": "TD",
      "name": "Chad"
    },
    {
      "isoCode": "CL",
      "name": "Chile"
    },
    {
      "isoCode": "CN",
      "name": "China"
    },
    {
      "isoCode": "CO",
      "name": "Colombia"
    },
    {
      "isoCode": "KM",
      "name": "Comoros"
    },
    {
      "isoCode": "CG",
      "name": "Congo"
    },
    {
      "isoCode": "CD",
      "name": "Congo - The Democratic Rep Of"
    },
    {
      "isoCode": "CK",
      "name": "Cook Islands"
    },
    {
      "isoCode": "CR",
      "name": "Costa Rica"
    },
    {
      "isoCode": "HR",
      "name": "Croatia (Local Name - Hrvatska)"
    },
    {
      "isoCode": "CY",
      "name": "Cyprus"
    },
    {
      "isoCode": "CZ",
      "name": "Czech Republic"
    },
    {
      "isoCode": "DK",
      "name": "Denmark"
    },
    {
      "isoCode": "DJ",
      "name": "Djibouti"
    },
    {
      "isoCode": "DM",
      "name": "Dominica"
    },
    {
      "isoCode": "DO",
      "name": "Dominican Republic"
    },
    {
      "isoCode": "EC",
      "name": "Ecuador"
    },
    {
      "isoCode": "EG",
      "name": "Egypt"
    },
    {
      "isoCode": "SV",
      "name": "El Salvador"
    },
    {
      "isoCode": "GQ",
      "name": "Equatorial Guinea"
    },
    {
      "isoCode": "ER",
      "name": "Eritrea"
    },
    {
      "isoCode": "EE",
      "name": "Estonia"
    },
    {
      "isoCode": "ET",
      "name": "Ethiopia"
    },
    {
      "isoCode": "FK",
      "name": "Falkland Islands (Malvinas)"
    },
    {
      "isoCode": "FO",
      "name": "Faroe Islands"
    },
    {
      "isoCode": "FJ",
      "name": "Fiji"
    },
    {
      "isoCode": "FI",
      "name": "Finland"
    },
    {
      "isoCode": "FR",
      "name": "France"
    },
    {
      "isoCode": "GF",
      "name": "French Guiana"
    },
    {
      "isoCode": "PF",
      "name": "French Polynesia"
    },
    {
      "isoCode": "GA",
      "name": "Gabon"
    },
    {
      "isoCode": "GM",
      "name": "Gambia"
    },
    {
      "isoCode": "GE",
      "name": "Georgia"
    },
    {
      "isoCode": "DE",
      "name": "Germany"
    },
    {
      "isoCode": "GH",
      "name": "Ghana"
    },
    {
      "isoCode": "GI",
      "name": "Gibraltar"
    },
    {
      "isoCode": "GR",
      "name": "Greece"
    },
    {
      "isoCode": "GL",
      "name": "Greenland"
    },
    {
      "isoCode": "GD",
      "name": "Grenada"
    },
    {
      "isoCode": "GP",
      "name": "Guadeloupe"
    },
    {
      "isoCode": "GU",
      "name": "Guam"
    },
    {
      "isoCode": "GT",
      "name": "Guatemala"
    },
    {
      "isoCode": "GN",
      "name": "Guinea"
    },
    {
      "isoCode": "GW",
      "name": "Guinea-Bissau"
    },
    {
      "isoCode": "GY",
      "name": "Guyana"
    },
    {
      "isoCode": "HT",
      "name": "Haiti"
    },
    {
      "isoCode": "VA",
      "name": "Holy See (Vatican City State)"
    },
    {
      "isoCode": "HN",
      "name": "Honduras"
    },
    {
      "isoCode": "HK",
      "name": "Hong Kong"
    },
    {
      "isoCode": "HU",
      "name": "Hungary"
    },
    {
      "isoCode": "IS",
      "name": "Iceland"
    },
    {
      "isoCode": "IN",
      "name": "India"
    },
    {
      "isoCode": "ID",
      "name": "Indonesia"
    },
    {
      "isoCode": "IR",
      "name": "Iran (Islamic Republic Of)"
    },
    {
      "isoCode": "IQ",
      "name": "Iraq"
    },
    {
      "isoCode": "IE",
      "name": "Ireland"
    },
    {
      "isoCode": "IL",
      "name": "Israel"
    },
    {
      "isoCode": "IT",
      "name": "Italy"
    },
    {
      "isoCode": "JM",
      "name": "Jamaica"
    },
    {
      "isoCode": "JP",
      "name": "Japan"
    },
    {
      "isoCode": "JO",
      "name": "Jordan"
    },
    {
      "isoCode": "KZ",
      "name": "Kazakhstan"
    },
    {
      "isoCode": "KE",
      "name": "Kenya"
    },
    {
      "isoCode": "KI",
      "name": "Kiribati"
    },
    {
      "isoCode": "KR",
      "name": "Korea - South"
    },
    {
      "isoCode": "KW",
      "name": "Kuwait"
    },
    {
      "isoCode": "KG",
      "name": "Kyrgyzstan"
    },
    {
      "isoCode": "LA",
      "name": "Lao Peoples Democratic Republic"
    },
    {
      "isoCode": "LV",
      "name": "Latvia"
    },
    {
      "isoCode": "LB",
      "name": "Lebanon"
    },
    {
      "isoCode": "LS",
      "name": "Lesotho"
    },
    {
      "isoCode": "LR",
      "name": "Liberia"
    },
    {
      "isoCode": "LY",
      "name": "Libyan Arab Jamahiriya"
    },
    {
      "isoCode": "LI",
      "name": "Liechtenstein"
    },
    {
      "isoCode": "LT",
      "name": "Lithuania"
    },
    {
      "isoCode": "LU",
      "name": "Luxembourg"
    },
    {
      "isoCode": "MO",
      "name": "Macau"
    },
    {
      "isoCode": "MK",
      "name": "Macedonia - The Frm Yugoslav Rep Of"
    },
    {
      "isoCode": "MG",
      "name": "Madagascar"
    },
    {
      "isoCode": "MW",
      "name": "Malawi"
    },
    {
      "isoCode": "MY",
      "name": "Malaysia"
    },
    {
      "isoCode": "MV",
      "name": "Maldives"
    },
    {
      "isoCode": "ML",
      "name": "Mali"
    },
    {
      "isoCode": "MT",
      "name": "Malta"
    },
    {
      "isoCode": "MH",
      "name": "Marshall Islands"
    },
    {
      "isoCode": "MQ",
      "name": "Martinique"
    },
    {
      "isoCode": "MR",
      "name": "Mauritania"
    },
    {
      "isoCode": "MU",
      "name": "Mauritius"
    },
    {
      "isoCode": "YT",
      "name": "Mayotte"
    },
    {
      "isoCode": "MX",
      "name": "Mexico"
    },
    {
      "isoCode": "FM",
      "name": "Micronesia - Federated States Of"
    },
    {
      "isoCode": "MD",
      "name": "Moldova - Republic Of"
    },
    {
      "isoCode": "MC",
      "name": "Monaco"
    },
    {
      "isoCode": "MN",
      "name": "Mongolia"
    },
    {
      "isoCode": "ME",
      "name": "Montenegro"
    },
    {
      "isoCode": "MS",
      "name": "Montserrat"
    },
    {
      "isoCode": "MA",
      "name": "Morocco"
    },
    {
      "isoCode": "MZ",
      "name": "Mozambique"
    },
    {
      "isoCode": "MM",
      "name": "Myanmar"
    },
    {
      "isoCode": "NA",
      "name": "Namibia"
    },
    {
      "isoCode": "NP",
      "name": "Nepal"
    },
    {
      "isoCode": "NL",
      "name": "Netherlands"
    },
    {
      "isoCode": "NC",
      "name": "New Caledonia"
    },
    {
      "isoCode": "NZ",
      "name": "New Zealand"
    },
    {
      "isoCode": "NI",
      "name": "Nicaragua"
    },
    {
      "isoCode": "NE",
      "name": "Niger"
    },
    {
      "isoCode": "NG",
      "name": "Nigeria"
    },
    {
      "isoCode": "MP",
      "name": "Northern Mariana Islands"
    },
    {
      "isoCode": "NO",
      "name": "Norway"
    },
    {
      "isoCode": "OM",
      "name": "Oman"
    },
    {
      "isoCode": "PK",
      "name": "Pakistan"
    },
    {
      "isoCode": "PW",
      "name": "Palau"
    },
    {
      "isoCode": "PS",
      "name": "Palestinian Territories"
    },
    {
      "isoCode": "PA",
      "name": "Panama"
    },
    {
      "isoCode": "PG",
      "name": "Papua New Guinea"
    },
    {
      "isoCode": "PY",
      "name": "Paraguay"
    },
    {
      "isoCode": "PE",
      "name": "Peru"
    },
    {
      "isoCode": "PH",
      "name": "Philippines"
    },
    {
      "isoCode": "PL",
      "name": "Poland"
    },
    {
      "isoCode": "PT",
      "name": "Portugal"
    },
    {
      "isoCode": "PR",
      "name": "Puerto Rico"
    },
    {
      "isoCode": "QA",
      "name": "Qatar"
    },
    {
      "isoCode": "RE",
      "name": "Reunion"
    },
    {
      "isoCode": "RO",
      "name": "Romania"
    },
    {
      "isoCode": "RU",
      "name": "Russian Federation"
    },
    {
      "isoCode": "RW",
      "name": "Rwanda"
    },
    {
      "isoCode": "KN",
      "name": "Saint Kitts and Nevis"
    },
    {
      "isoCode": "LC",
      "name": "Saint Lucia"
    },
    {
      "isoCode": "MF",
      "name": "Saint Martin"
    },
    {
      "isoCode": "VC",
      "name": "Saint Vincent and the Grenadines"
    },
    {
      "isoCode": "WS",
      "name": "Samoa"
    },
    {
      "isoCode": "SM",
      "name": "San Marino"
    },
    {
      "isoCode": "ST",
      "name": "Sao Tome and Principe"
    },
    {
      "isoCode": "SA",
      "name": "Saudi Arabia"
    },
    {
      "isoCode": "SN",
      "name": "Senegal"
    },
    {
      "isoCode": "RS",
      "name": "Serbia"
    },
    {
      "isoCode": "SC",
      "name": "Seychelles"
    },
    {
      "isoCode": "SL",
      "name": "Sierra Leone"
    },
    {
      "isoCode": "SG",
      "name": "Singapore"
    },
    {
      "isoCode": "SX",
      "name": "Sint Maarten"
    },
    {
      "isoCode": "SK",
      "name": "Slovakia (Slovak Republic)"
    },
    {
      "isoCode": "SI",
      "name": "Slovenia"
    },
    {
      "isoCode": "SB",
      "name": "Solomon Islands"
    },
    {
      "isoCode": "SO",
      "name": "Somalia"
    },
    {
      "isoCode": "ZA",
      "name": "South Africa"
    },
    {
      "isoCode": "ES",
      "name": "Spain"
    },
    {
      "isoCode": "LK",
      "name": "Sri Lanka"
    },
    {
      "isoCode": "SH",
      "name": "St. Helena"
    },
    {
      "isoCode": "SD",
      "name": "Sudan"
    },
    {
      "isoCode": "SR",
      "name": "Suriname"
    },
    {
      "isoCode": "SZ",
      "name": "Swaziland"
    },
    {
      "isoCode": "SE",
      "name": "Sweden"
    },
    {
      "isoCode": "CH",
      "name": "Switzerland"
    },
    {
      "isoCode": "SY",
      "name": "Syrian Arab Republic"
    },
    {
      "isoCode": "TW",
      "name": "Taiwan - Province Of China"
    },
    {
      "isoCode": "TJ",
      "name": "Tajikistan"
    },
    {
      "isoCode": "TZ",
      "name": "Tanzania - United Republic Of"
    },
    {
      "isoCode": "TH",
      "name": "Thailand"
    },
    {
      "isoCode": "TL",
      "name": "Timor-Leste"
    },
    {
      "isoCode": "TG",
      "name": "Togo"
    },
    {
      "isoCode": "TO",
      "name": "Tonga"
    },
    {
      "isoCode": "TT",
      "name": "Trinidad and Tobago"
    },
    {
      "isoCode": "TN",
      "name": "Tunisia"
    },
    {
      "isoCode": "TR",
      "name": "Turkey"
    },
    {
      "isoCode": "TM",
      "name": "Turkmenistan"
    },
    {
      "isoCode": "TC",
      "name": "Turks and Caicos Islands"
    },
    {
      "isoCode": "TV",
      "name": "Tuvalu"
    },
    {
      "isoCode": "VI",
      "name": "US Virgin Islands"
    },
    {
      "isoCode": "UG",
      "name": "Uganda"
    },
    {
      "isoCode": "UA",
      "name": "Ukraine"
    },
    {
      "isoCode": "AE",
      "name": "United Arab Emirates"
    },
    {
      "isoCode": "UK",
      "name": "United Kingdom"
    },
    {
      "isoCode": "US",
      "name": "United States"
    },
    {
      "isoCode": "UY",
      "name": "Uruguay"
    },
    {
      "isoCode": "UM",
      "name": "Us Minor Outlying Islands"
    },
    {
      "isoCode": "UZ",
      "name": "Uzbekistan"
    },
    {
      "isoCode": "VU",
      "name": "Vanuatu"
    },
    {
      "isoCode": "VE",
      "name": "Venezuela"
    },
    {
      "isoCode": "VN",
      "name": "Viet Nam"
    },
    {
      "isoCode": "YE",
      "name": "Yemen"
    },
    {
      "isoCode": "ZM",
      "name": "Zambia"
    },
    {
      "isoCode": "ZW",
      "name": "Zimbabwe"
    }
  ]
}