Skip to main content
Use these routes to find the values that a campaign’s targeting fields accept. geo_targets takes location IDs for countries, regions, and DMAs from the geo-target catalog. include_audience_ids and exclude_audience_ids take the IDs of customer lists that you upload. Set these fields with POST /advertiser-dashboard/campaigns or PATCH /advertiser-dashboard/campaigns/{campaign_id}.

​
GET /advertiser-dashboard/geo-targets

Search the geo-target catalog, page through it, or resolve a batch of location IDs. The catalog has countries, regions, and DMAs. Results are ordered by target type, country code, name, and location ID.
​
string
Matches a case-insensitive part of name or canonical_name, or an exact location_id or country_code.
​
string
Show only one country (ISO 3166-1 alpha-2).
​
string
Show only country, region, or dma entries.
​
string
A comma-separated list of location IDs to resolve, at most 500. When you send it, Gravity ignores q, country_code, target_type, and cursor. The items keep the order that you asked for, and IDs that aren’t in the catalog go to not_found.
​
integer
default:"50"
The page size. Gravity clamps it to the range 1 to 1000 and returns the value it used.
​
string
The next_cursor value from the previous page.
AR, CL, CO, PE, UY, IL, SA, and TR are Gravity country aliases, not catalog location IDs. A campaign accepts them in geo_targets and targets the whole country. A cursor that Gravity didn’t return, or more than 500 location_ids, returns 422.
Request
Response

​
GET /advertiser-dashboard/geo-targets/{location_id}

Resolve one location ID. The response is one catalog entry, in the same shape as an item above. If the ID isn’t a supported country, region, or DMA, the response is 404.

​
POST /advertiser-dashboard/audiences/custom-list

Upload a customer list as a new audience. Send a multipart/form-data body. Gravity hashes emails and phone numbers when it reads the file and doesn’t store the raw values. The response is 201 with the new audience.
​
file
required
A UTF-8 CSV file of emails, phone numbers, or SHA-256 hashes, one value in each cell. Separate values with commas or new lines. A first row of column headers (for example email or phone) is optional. When a header names a column as email or phone, Gravity reads the hashed values in that column as that type. At most 20 MB and 500,000 identifiers.
​
string
The audience name, at most 255 characters. If you leave it out, Gravity makes a name from the file name.
Gravity matches the list against its users in a background job that runs every hour. Until then, size and last_materialized_at are null.
Request
Response 201

​
GET /advertiser-dashboard/audiences

List the audiences of your account, newest first. Each item has the same shape as the upload response. Archived audiences aren’t in the list. Besides uploaded lists (custom_list), source can be ad_clicks, conversions, site_visits, ad_views, clicked_no_conversion, conversion_event, or composite for audiences made in the dashboard.

​
GET /advertiser-dashboard/audiences/{audience_id}

Get one audience with its delivery_status. After you attach an uploaded list to a campaign, check this status until ready is true. If the audience isn’t in your account, the response is 404.

​
DELETE /advertiser-dashboard/audiences/{audience_id}

Archive an audience and remove it from the targeting of every campaign that uses it. The response is 204. If the audience isn’t in your account, the response is 404.