{"__v":0,"_id":"57dc1d4d2cfd450e00643504","category":{"__v":0,"_id":"57dc1bbd3ed3450e00dc9ea7","project":"55de06fa57f7b20d0097636b","version":"55de06fa57f7b20d0097636e","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-09-16T16:20:13.682Z","from_sync":false,"order":9999,"slug":"partner-attributes-api","title":"Data Marketplace Partner Ingestion API"},"parentDoc":null,"project":"55de06fa57f7b20d0097636b","user":"55de06e19db51a0d0064947d","version":{"__v":10,"_id":"55de06fa57f7b20d0097636e","project":"55de06fa57f7b20d0097636b","createdAt":"2015-08-26T18:35:38.642Z","releaseDate":"2015-08-26T18:35:38.642Z","categories":["55de06fb57f7b20d0097636f","55f1962e3936d52d00fb3c8f","55f1970339e3e8190068b2b8","55f1970d229b772300779a1f","55f1971cfd98c42300acc605","55f1d5c7fd98c42300acc69f","563cbfe4260dde0d00c5e9d4","5644cf437f1fff210078e690","57dc1bbd3ed3450e00dc9ea7","58a600a2243dd30f00fd8773"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-09-16T16:26:53.099Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"Attributes represent the tags or segments of data you plan to make available in the PushSpring Audience Console.  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.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Naming Conventions for Attributes\"\n}\n[/block]\nRather 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.\n\nWe recommend you use the sequence \" / \" (space followed by forward slash followed by space) in between hierarchical elements.\n\nFor example, PushSpring organizes some of its Attributes as follows:\n\nInterest & Activity / Arts & Entertainment / Music Lovers\nInterest & Activity / Arts & Entertainment / Music Lovers / Concertgoers\nInterest & Activity / Arts & Entertainment / Music Lovers / Music Streamers\nInterest & Activity / Arts & Entertainment / Photo & Video Enthusiasts\nInterest & Activity / Arts & Entertainment / Photo & Video Enthusiasts / Photo Editors\nInterest & Activity / Arts & Entertainment / Photo & Video Enthusiasts / Photo Printers\n\nAs you can see, this naming convention organizes a visual hierarchy of Attributes for customers to choose from when building segments.\n\nPlease note the PushSpring 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.\n\nOne 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.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Declaring Attributes\"\n}\n[/block]\nAttributes must be declared to the PushSpring platform using the APIs below before they appear in the files you sent to PushSpring for ingestion.\n\nWhen 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.\n\nIf you prefer to use your own internal identifier for each Attribute, our platform supports that.  When you declare the Attribute to PushSpring, you can optionally supply a \"Partner Foreign Key\".  Once declared to us, you can then use that Partner Foreign Key in data files instead.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Attribute Device Count\"\n}\n[/block]\nA 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 PushSpring 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.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"API Endpoint\"\n}\n[/block]\nAll operations described below are associated with https://api.pushspring.com/partner/attribute .\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"List Attributes\"\n}\n[/block]\nRetrieves a list of all attributes you have defined.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"Authorization: Bearer <APIKEY>\\\" https://api.pushspring.com/partner/attribute \",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n**Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[  \\n   {  \\n      \\\"attribute_id\\\":3,\\n      \\\"name\\\":\\\"Auto Shoppers\\\",\\n      \\\"description\\\":\\\"People who have shopped for car in last 30 days\\\",\\n      \\\"visible\\\":true,\\n      \\\"device_count\\\":\\\"23456\\\",\\n      \\\"ttl\\\":null\\n   },\\n   {  \\n      \\\"attribute_id\\\":4,\\n      \\\"name\\\":\\\"Job Hunter\\\",\\n      \\\"description\\\":\\\"People who are hunting for a job\\\",\\n      \\\"visible\\\":false,\\n      \\\"device_count\\\":\\\"0\\\",\\n      \\\"ttl\\\":null\\n   }\\n ]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"Get Attribute\"\n}\n[/block]\nGet a single attribute.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"Authorization: Bearer <APIKEY>\\\" https://api.pushspring.com/partner/attribute/3\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n**Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{  \\n      \\\"attribute_id\\\":3,\\n      \\\"name\\\":\\\"Auto Shoppers\\\",\\n      \\\"description\\\":\\\"People who have shopped for car in last 30 days\\\",\\n      \\\"visible\\\":true,\\n      \\\"device_count\\\":\\\"23456\\\",\\n      \\\"ttl\\\":null\\n   }\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Get Attribute by Name\"\n}\n[/block]\nAlternate method to get a single attribute.  Keyed on name.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET -H \\\"Authorization: Bearer <APIKEY>\\\" \\\"https://api.pushspring.com/partner/attribute?name=test3\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n**Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"attribute_id\\\": 4,\\n  \\\"name\\\": \\\"test3\\\",\\n  \\\"description\\\": \\\"Another test\\\",\\n  \\\"visible\\\": false,\\n  \\\"device_count\\\": \\\"0\\\",\\n  \\\"ttl\\\": null,\\n  \\\"partner_foreign_key\\\": null\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Get Attribute by Partner Foreign Key\"\n}\n[/block]\nAlternate method to get a single attribute.  Keyed on partner_foreign_key.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET -H \\\"Authorization: Bearer <APIKEY>\\\"  \\\"https://api.pushspring.com/partner/attribute?partner_foreign_key=124\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n**Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"attribute_id\\\": 1,\\n  \\\"name\\\": \\\"Updated Test\\\",\\n  \\\"description\\\": \\\"Updated Test\\\",\\n  \\\"visible\\\": false,\\n  \\\"device_count\\\": \\\"0\\\",\\n  \\\"ttl\\\": 10,\\n  \\\"partner_foreign_key\\\": \\\"124\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"Create Attribute\"\n}\n[/block]\nCreates a new attribute\n\n**Parameters** \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Required\",\n    \"h-2\": \"Type\",\n    \"0-0\": \"name\",\n    \"0-1\": \"Y\",\n    \"0-2\": \"string\",\n    \"1-0\": \"description\",\n    \"1-1\": \"Y\",\n    \"1-2\": \"string\",\n    \"3-0\": \"ttl\",\n    \"3-1\": \"N\",\n    \"3-2\": \"integer\",\n    \"4-0\": \"visible\",\n    \"4-1\": \"N\",\n    \"4-2\": \"booelan\",\n    \"h-3\": \"Description\",\n    \"0-3\": \"Name of attribute.  Descriptive to end user.  Shows up in PushSpring console.  Must be unique.\",\n    \"1-3\": \"Description of what the attribute represents.  Shows up in PushSpring console.\",\n    \"3-3\": \"Time to live for device in days.  If not specified devices are not expired from the attribute.  Devices are expired once a day.\",\n    \"4-3\": \"If not specified defaults to false.  Whether or not the attribute shows up in the PushSpring console.\",\n    \"2-0\": \"partner_foreign_key\",\n    \"2-1\": \"N\",\n    \"2-2\": \"string\",\n    \"2-3\": \"Key in partner system.  When importing data either the attribute_id or this key may be used.  Must be unique.\\n\\nCannot contain a ,\"\n  },\n  \"cols\": 4,\n  \"rows\": 5\n}\n[/block]\n**Sample** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST -H \\\"Authorization: Bearer <APIKEY>\\\" -H \\\"Content-Type: application/json\\\" -d '{\\n\\t\\\"name\\\": \\\"Sample\\\",\\n\\t\\\"description\\\":\\\"A sample attribute\\\",\\n\\t\\\"category\\\": \\\"Sample\\\"\\n}' \\\"https://api.pushspring.com/partner/attribute\\\"\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nResponse\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"attribute_id\\\":8\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"patch\",\n  \"title\": \"Update Attribute\"\n}\n[/block]\nUpdates an attribute.  Only the included parameters are updated.  \n\n**Parameters**\nSame as Create Attribute\n\n**Sample** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X PATCH -H \\\"Authorization: Bearer <APIKEY>\\\" -H \\\"Content-Type: application/json\\\" -d '{\\n\\t\\\"description\\\": \\\"Updated Sample\\\",\\n\\t\\\"visible\\\": true\\n}' \\\"https://api.pushspring.com/partner/attribute/1\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n**Response**\n\nIf successful returns a 204 No content","excerpt":"","slug":"attribute","type":"basic","title":"Attributes"}
Attributes represent the tags or segments of data you plan to make available in the PushSpring Audience Console. 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. [block:api-header] { "type": "basic", "title": "Naming Conventions for Attributes" } [/block] 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 forward slash followed by space) in between hierarchical elements. For example, PushSpring 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 PushSpring 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. 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. [block:api-header] { "type": "basic", "title": "Declaring Attributes" } [/block] Attributes must be declared to the PushSpring platform using the APIs below before they appear in the files you sent to PushSpring 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 PushSpring, you can optionally supply a "Partner Foreign Key". Once declared to us, you can then use that Partner Foreign Key in data files instead. [block:api-header] { "type": "basic", "title": "Attribute Device Count" } [/block] 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 PushSpring 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. [block:api-header] { "type": "basic", "title": "API Endpoint" } [/block] All operations described below are associated with https://api.pushspring.com/partner/attribute . [block:api-header] { "type": "get", "title": "List Attributes" } [/block] Retrieves a list of all attributes you have defined. [block:code] { "codes": [ { "code": "curl --header \"Authorization: Bearer <APIKEY>\" https://api.pushspring.com/partner/attribute ", "language": "curl" } ] } [/block] **Response** [block:code] { "codes": [ { "code": "[ \n { \n \"attribute_id\":3,\n \"name\":\"Auto Shoppers\",\n \"description\":\"People who have shopped for car in last 30 days\",\n \"visible\":true,\n \"device_count\":\"23456\",\n \"ttl\":null\n },\n { \n \"attribute_id\":4,\n \"name\":\"Job Hunter\",\n \"description\":\"People who are hunting for a job\",\n \"visible\":false,\n \"device_count\":\"0\",\n \"ttl\":null\n }\n ]", "language": "json" } ] } [/block] [block:api-header] { "type": "get", "title": "Get Attribute" } [/block] Get a single attribute. [block:code] { "codes": [ { "code": "curl --header \"Authorization: Bearer <APIKEY>\" https://api.pushspring.com/partner/attribute/3", "language": "curl" } ] } [/block] **Response** [block:code] { "codes": [ { "code": "{ \n \"attribute_id\":3,\n \"name\":\"Auto Shoppers\",\n \"description\":\"People who have shopped for car in last 30 days\",\n \"visible\":true,\n \"device_count\":\"23456\",\n \"ttl\":null\n }", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Get Attribute by Name" } [/block] Alternate method to get a single attribute. Keyed on name. [block:code] { "codes": [ { "code": "curl -X GET -H \"Authorization: Bearer <APIKEY>\" \"https://api.pushspring.com/partner/attribute?name=test3\"", "language": "curl" } ] } [/block] **Response** [block:code] { "codes": [ { "code": "{\n \"attribute_id\": 4,\n \"name\": \"test3\",\n \"description\": \"Another test\",\n \"visible\": false,\n \"device_count\": \"0\",\n \"ttl\": null,\n \"partner_foreign_key\": null\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Get Attribute by Partner Foreign Key" } [/block] Alternate method to get a single attribute. Keyed on partner_foreign_key. [block:code] { "codes": [ { "code": "curl -X GET -H \"Authorization: Bearer <APIKEY>\" \"https://api.pushspring.com/partner/attribute?partner_foreign_key=124\"", "language": "curl" } ] } [/block] **Response** [block:code] { "codes": [ { "code": "{\n \"attribute_id\": 1,\n \"name\": \"Updated Test\",\n \"description\": \"Updated Test\",\n \"visible\": false,\n \"device_count\": \"0\",\n \"ttl\": 10,\n \"partner_foreign_key\": \"124\"\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "post", "title": "Create Attribute" } [/block] Creates a new attribute **Parameters** [block:parameters] { "data": { "h-0": "Field", "h-1": "Required", "h-2": "Type", "0-0": "name", "0-1": "Y", "0-2": "string", "1-0": "description", "1-1": "Y", "1-2": "string", "3-0": "ttl", "3-1": "N", "3-2": "integer", "4-0": "visible", "4-1": "N", "4-2": "booelan", "h-3": "Description", "0-3": "Name of attribute. Descriptive to end user. Shows up in PushSpring console. Must be unique.", "1-3": "Description of what the attribute represents. Shows up in PushSpring console.", "3-3": "Time to live for device in days. If not specified devices are not expired from the attribute. Devices are expired once a day.", "4-3": "If not specified defaults to false. Whether or not the attribute shows up in the PushSpring console.", "2-0": "partner_foreign_key", "2-1": "N", "2-2": "string", "2-3": "Key in partner system. When importing data either the attribute_id or this key may be used. Must be unique.\n\nCannot contain a ," }, "cols": 4, "rows": 5 } [/block] **Sample** [block:code] { "codes": [ { "code": "curl -X POST -H \"Authorization: Bearer <APIKEY>\" -H \"Content-Type: application/json\" -d '{\n\t\"name\": \"Sample\",\n\t\"description\":\"A sample attribute\",\n\t\"category\": \"Sample\"\n}' \"https://api.pushspring.com/partner/attribute\"", "language": "text" } ] } [/block] Response [block:code] { "codes": [ { "code": "{\n \"attribute_id\":8\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "patch", "title": "Update Attribute" } [/block] Updates an attribute. Only the included parameters are updated. **Parameters** Same as Create Attribute **Sample** [block:code] { "codes": [ { "code": "curl -X PATCH -H \"Authorization: Bearer <APIKEY>\" -H \"Content-Type: application/json\" -d '{\n\t\"description\": \"Updated Sample\",\n\t\"visible\": true\n}' \"https://api.pushspring.com/partner/attribute/1\"", "language": "curl" } ] } [/block] **Response** If successful returns a 204 No content