Marketing API

Detailed Targeting

With Targeting Search, you can find targeting with one targeting type in a single API call. With the Detailed Targeting API, you can search for multiple targeting types in a single request at the same time. You can also get suggestions based on your query.

The API has four endpoints: Search, Suggestions, Browse, and Validation.

The response for these endpoints contains the following:

Name Description

id

type: string

Target audience ID

name

type: string

Name of the target audience

audience_size_lower_bound

integer

Estimated lower bound target audience size

audience_size_upper_bound

integer

Estimated upper bound target audience size

path

type: array of strings

Includes the category and any parent categories the targeting falls into

description

type: string

A short description about target audience

If you do not provide limit_type, we filter results with less than 2000 people into four categories: work_employers, work_positions, education_majors, education_schools. Otherwise you get less meaningful results. When you use limit_type we filter for one of those four categories and will not return everything.

Retrieve target audiences for your ads that match your search query. You can provide the following parameters at this endpoint:

curl -G \
-d "q=harvard" \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/targetingsearch
Name Description

q

type: string

Required.

Query string

limit

type: integer

Optional.

Number of results

limit_type

type: string

Optional.

Limit the type of audience to retrieve. Default to all types.

Valid values:

  • interests
  • education_schools
  • education_majors
  • work_positions
  • work_employers
  • relationship_statuses
  • college_years
  • education_statuses
  • family_statuses
  • industries
  • life_events
  • behaviors
  • income

locale

type: string

Optional.

The locale to display audience names and descriptions, if available. Default to ad account's locale

Suggestions

Returns additional audiences you can target based on a few selected audiences you provide.

curl -G \
-d "targeting_list=[{'type':'interests','id':6003263791114}]" \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/targetingsuggestions

Provide these parameters:

Name Description

targeting_list

type: Array of {'type':'{TYPE}', 'id':{ID}}

Required.

Array of {'type':'{TYPE}', 'id':{ID}} pairs as input audience for suggestions.

limit

type: integer

Optional.

Number of results. Default is 30. Maximum is 45.

limit_type

type: string

Optional.

Limit the type of audience to retrieve. Default to all types

Valid values:

  • interests
  • education_schools
  • education_majors
  • work_positions
  • work_employers
  • relationship_statuses
  • college_years
  • education_statuses
  • family_statuses
  • industries
  • life_events
  • behaviors
  • income

locale

type: string

Optional.

The locale to display audience names and descriptions. Default to ad account's locale

Browse

Get targeting in a structured taxonomy for Facebook categories, third party data providers and some interests. Results from this endpoint appear in the Browse functionality in Detailed Targeting UI component in Ads Manager.

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/targetingbrowse

Provide the following optional parameters:

Name Description

limit_type

type: string

Limit the type of audience to retrieve. Default to all types.

locale

type: string

The locale to display audience names and descriptions. Default to ad account's locale

Validation

Verify whether an audience is valid for targeting or not. This is helpful if you already created an ad set and want to verify its targeting spec is still valid. If the targeting is not valid, you should delete it from the targeting spec.

curl -G \
-d "targeting_list=[{'type':'interests','id':6003283735711}, {'type':'relationship_statuses','id':100}]" \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/targetingvalidation

In addition to the standard Detailed Targeting response fields, this endpoint also returns:

Name description

valid

type: boolean

Whether the targeting audience is valid or not

Here is the list of input parameters:

Name Description

targeting_list

type: Array of {'type':'{TYPE}', 'id':{ID}}

Array of {'type':'{TYPE}', 'id':{ID}} pairs for validation. Perferred.

id_list

type: array of strings

Array of IDs for validation. Succeeds only if an ID is uniquely identifiable in our audience database

name_list

type: array of strings

Array of Strings for validation. Interests only, case insensitive

locale

type: string

Locale to display audience names and descriptions. Defaults to ad account's locale

Provide at least one of the following: targeting_list, id_list, and name_list.