Skip to content

Create Place List

Request

Create a place list with inline circle places.

Only circle places are supported. API users must provide latitude, longitude, and radius_meters for each place. geometry_type is returned by the API and must not be supplied by users.

Before creating Place List locations through the API, API users must accept the sensitive-location attestation by including sensitive_location_attestation: true in the request body. Accepting this field confirms the following attestation on behalf of the API user for this request:

I represent and warrant that these locations are not being used to
target or identify individuals at sensitive locations, and that I have
the rights and consents necessary for this targeting, including consent
to share with third parties where required.

For guidance on what qualifies as a sensitive location, see Places attestation guidelines.

Requests submitted without sensitive_location_attestation, or with it set to any value other than true, are rejected with a 400 invalid-request error on /sensitive_location_attestation. This is a per-request acknowledgment, not a one-time account-level setting.

The attestation language may be updated over time.

Security
Auth0(Required scopes: offline_accessmanage:services)
Bodyapplication/jsonrequired
organization_idinteger, (int32), [ 1 .. 2147483647 ]required
Example:100048
namestring, <= 255 charactersrequired
Example:"Starbucks Stores - New York"
descriptionstring or null
Example:"NYC flagship + competitor zones"
sensitive_location_attestationbooleanrequired

Required and must be true for Place List content writes.

Value:true
placesArray of objects, [ 1 .. 10000 ] items(place_create)required

Circle places to create. Within one place list, nonblank external_id values must be unique and circle geometry (latitude, longitude, radius_meters) must be unique after coordinate truncation to four decimal places.

curl -i -X POST \
  https://api.mediamath.com/api/v3.0/place_lists \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "organization_id": 100048,
    "name": "Starbucks Stores - New York",
    "description": "NYC flagship + competitor zones",
    "sensitive_location_attestation": true,
    "places": [
      {
        "name": "Times Square",
        "external_id": "STORE-001",
        "latitude": 40.7589,
        "longitude": -73.9851,
        "radius_meters": 1000
      }
    ]
  }'

Responses

Place list response

Bodyapplication/json
dataobject(place_list_full)
metaobject(single_metadata)
Response
{ "data": { "id": 126, "entity_type": "place_list", "version": 2, "organization_id": 100048, "name": "Starbucks Stores - New York", "description": "NYC flagship + competitor zones", "filename": "starbucks_new_york.csv", "content_updated_on": "2019-08-24T14:15:22Z", "places_count": 42, "strategy_count": 0, "created_on": "2019-08-24T14:15:22Z", "updated_on": "2019-08-24T14:15:22Z", "places": [ … ] }, "meta": { "status": "success" } }