Attributes

Attributes represent the tags or segments of data you plan to make available in the Audience Marketplace. Each Attribute is made up of a required Name and Description field, both of which will be displayed to users when they are building Custom Segments and working with your data.

Naming Conventions for Attributes

Rather than declaring and managing complicated hierarchical structures for organizing your Attributes, our platform expects you to name your Attributes according to a simple naming convention. Following this convention allows us to group related Attributes in the console and still gives you the ability to control the hierarchy they are displayed with.

We recommend you use the sequence " > " (space followed by greater than followed by space) in between hierarchical elements.

For example, the Audience Marketplace organizes some of its Attributes as follows:

Interest & Activity > Arts & Entertainment > Music Lovers
Interest & Activity > Arts & Entertainment > Music Lovers > Concertgoers
Interest & Activity > Arts & Entertainment > Music Lovers > Music Streamers
Interest & Activity > Arts & Entertainment > Photo & Video Enthusiasts
Interest & Activity > Arts & Entertainment > Photo & Video Enthusiasts > Photo Editors
Interest & Activity > Arts & Entertainment > Photo & Video Enthusiasts > Photo Printers

As you can see, this naming convention organizes a visual hierarchy of Attributes for customers to choose from when building segments.

Please note the Magenta Advertising Platform will not automatically "roll up" attributes. For instance, given the list of Attributes above, if I want the "Music Lovers" Attribute to contain all of the "Concertgoers" and "Music Streamers", I need to add the "Music Lovers" Attribute to every advertising identifier that I put "Concertgoers" or "Music Streamers" on.

We recommend that the actual segment name (last node in the attribute name) does not
exceed 20max characters.

One other note: we suggest you do not include your brand as a component of the Attribute names. Our UI will display your brand as part of listing your Attributes to customers working in the Audience Console.

Attribute Descriptions

Attribute descriptions are displayed in the UI to help prospective buyers understand what’s in each segment. We recommend providing a 500max character description. Also, the more unique the attribute description, the more it can help customers find your attributes in search results.

Example:
It runs like a bull, but mostly it cuts grass. The Toro Company is an American maker of lawn equipment like lawn mowers, snow blowers, and irrigation systems.

Declaring Attributes

Attributes must be declared to the Magenta Advertising Platform using the APIs below before they appear in the files you sent to Magenta Advertising Platform for ingestion.

When you create an Attribute via the API below, you will be given back an Attribute ID. This is the identifier you will use in the files you later send us for ingestion.

If you prefer to use your own internal identifier for each Attribute, our platform supports that. When you declare the Attribute to Magenta Advertising Platform, you can optionally supply a "Partner Foreign Key". Once declared to us, you can then use that Partner Foreign Key in data files instead.

Attribute Device Count

A common problem in delivering your data to other platforms is knowing whether or not they are ingesting the data correctly. The API below allows you to query Magenta Advertising Platform on a per-Attribute basis to see the current count of devices associated with each Attribute. This allows you to validate that ingestion is correctly happening.

API Endpoint

All operations described below are associated with https://api.magentamarketing.com/v1/marketplace/attribute .

List Attributes

Retrieves a list of all attributes you have defined.

curl --header "Authorization: Bearer <APIKEY>" https://api.magentamarketing.com/v1/marketplace/attribute

Response

[  
   {  
      "attribute_id":3,
      "name":"Auto Shoppers",
      "description":"People who have shopped for car in last 30 days",
      "visible":true,
      "device_count":"23456"
   },
   {  
      "attribute_id":4,
      "name":"Job Hunter",
      "description":"People who are hunting for a job",
      "visible":false,
      "device_count":"0"
   }
 ]

Get Attribute

Get a single attribute.

curl --header "Authorization: Bearer <APIKEY>" https://api.magentamarketing.com/v1/marketplace/attribute/3

Response

{  
      "attribute_id":3,
      "name":"Auto Shoppers",
      "description":"People who have shopped for car in last 30 days",
      "visible":true,
      "device_count":"23456"
   }

Get Attribute by Name

Alternate method to get a single attribute. Keyed on name.

curl -X GET -H "Authorization: Bearer <APIKEY>" "https://api.magentamarketing.com/v1/marketplace/attribute?name=test3"

Response

{
  "attribute_id": 4,
  "name": "test3",
  "description": "Another test",
  "visible": false,
  "device_count": "0",
  "partner_foreign_key": null
}

Get Attribute by Partner Foreign Key

Alternate method to get a single attribute. Keyed on partner_foreign_key.

curl -X GET -H "Authorization: Bearer <APIKEY>"  "https://api.magentamarketing.com/v1/marketplace/attribute?partner_foreign_key=124"

Response

{
  "attribute_id": 1,
  "name": "Updated Test",
  "description": "Updated Test",
  "visible": false,
  "device_count": "0",
  "partner_foreign_key": "124"
}

Create Attribute

Creates a new attribute

Parameters

Sample

curl -X POST -H "Authorization: Bearer <APIKEY>" -H "Content-Type: application/json" -d '{
	"name": "Sample",
	"description":"A sample attribute",
	"category": "Sample"
}' "https://api.magentamarketing.com/v1/marketplace/attribute"

Response

{
  "attribute_id":8
}

Update Attribute

Updates an attribute. Only the included parameters are updated.

Parameters
Same as Create Attribute

Sample

curl -X PATCH -H "Authorization: Bearer <APIKEY>" -H "Content-Type: application/json" -d '{
	"description": "Updated Sample",
	"visible": true
}' "https://api.magentamarketing.com/v1/marketplace/attribute/1"

Response

If successful returns a 204 No content