{"_id":"58f17509e7093e0f00388aeb","parentDoc":null,"project":"55de06fa57f7b20d0097636b","version":{"_id":"55de06fa57f7b20d0097636e","project":"55de06fa57f7b20d0097636b","__v":14,"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","58ed1bdc068f780f00f64602","58f13b3a4f0ee50f00e24e81","58f173f792f9020f009cad16","591b42f8e633fd0f00077c5a"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"user":"55de06e19db51a0d0064947d","__v":2,"category":{"_id":"58f173f792f9020f009cad16","project":"55de06fa57f7b20d0097636b","version":"55de06fa57f7b20d0097636e","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-04-15T01:14:31.085Z","from_sync":false,"order":9,"slug":"firstparty-data-ingestion","title":"First Party Data Ingest API"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-04-15T01:19:05.840Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"code":"curl -X GET \\\n  https://api.pushspring.com/v2/firstparty/audience \\\n  -H 'authorization: Bearer <apikey>' \\\n  -H 'cache-control: no-cache' \\\n  -H 'x-user-token: <usertoken>'","language":"curl"}]},"method":"get","results":{"codes":[{"name":"","code":"[\n  {\n    \"audience_id\": 40,\n    \"name\": \"Test\",\n    \"unique_devices\": 383992,\n    \"default_warehouse_segment_id\": 90418,\n    \"status\": 2,\n    \"created_at\": \"2015-09-04T14:32:05.194Z\",\n    \"updated_at\": \"2016-09-01T21:25:25.122Z\",\n    \"uploaded_devices\": 384317,\n    \"matched_devices\": 71485\n  },\n  {\n    \"audience_id\": 424,\n    \"name\": \"Test 2\",\n    \"unique_devices\": 12341,\n    \"default_warehouse_segment_id\": 90699,\n    \"status\": 0,\n    \"created_at\": \"2016-11-11T21:51:59.237Z\",\n    \"updated_at\": \"2016-11-11T21:52:16.245Z\",\n    \"uploaded_devices\": 20000,\n    \"matched_devices\": 9876\n  }\n]","language":"json","status":200}]},"settings":"","auth":"required","params":[{"_id":"58f17721e7093e0f00388aec","ref":"","in":"header","required":false,"desc":"User token from OAuth integration","default":"","type":"string","name":"x-user-token"},{"_id":"58f177534518c40f005977b7","ref":"","in":"header","required":false,"desc":"Api key as bearer token","default":"","type":"string","name":"Authorization"}],"url":"/v2/firstparty/audience"},"isReference":false,"order":1,"body":"## Overview\n\nThe Audience API endpoint allows you to instruct PushSpring to ingest a file containing Advertising Identifiers and optionally events from S3.  When you are provisioned by PushSpring as a First Party Data API partner, you will be given a set of Amazon Web Services S3 credentials and a bucket/path prefix.  You will then create the data files to be imported, upload each file to Amazon S3 and then post to the audience API endpoint to tell PushSpring to queue the import job on behalf of the customer.  \n\nImports are batched and will complete in the order submitted. \n\n[The file format you should use for ingestion is documented here](doc:audience-file-format-for-ingest). \n\n[block:api-header]\n{\n  \"title\": \"Endpoint\"\n}\n[/block]\nhttps://api.pushspring.com/v1/firstparty/audience\n[block:api-header]\n{\n  \"title\": \"List Audiences\"\n}\n[/block]\nLists previously imported audiences.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\\\\n  https://api.pushspring.com/v2/firstparty/audience \\\\\\n  -H 'authorization: Bearer <apikey>' \\\\\\n  -H 'cache-control: no-cache' \\\\\\n  -H 'x-user-token: <usertoken>'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n**Results**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[\\n    {\\n    \\\"audience_id\\\": 40,\\n    \\\"name\\\": \\\"Test\\\",\\n    \\\"unique_devices\\\": 383992,\\n    \\\"default_warehouse_segment_id\\\": 90418,\\n    \\\"status\\\": 2,\\n    \\\"created_at\\\": \\\"2015-09-04T14:32:05.194Z\\\",\\n    \\\"updated_at\\\": \\\"2016-09-01T21:25:25.122Z\\\",\\n    \\\"uploaded_devices\\\": 384317,\\n    \\\"matched_devices\\\": 71485\\n  },\\n  {\\n    \\\"audience_id\\\": 424,\\n    \\\"name\\\": \\\"Test2\\\",\\n    \\\"unique_devices\\\": 12436,\\n    \\\"default_warehouse_segment_id\\\": 90699,\\n    \\\"status\\\": 0,\\n    \\\"created_at\\\": \\\"2016-11-11T21:51:59.237Z\\\",\\n    \\\"updated_at\\\": \\\"2016-11-11T21:52:16.245Z\\\",\\n    \\\"uploaded_devices\\\": 20000,\\n    \\\"matched_devices\\\": 9875\\n  }\\n]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nMost of the response parameters are self-explanatory.  The \"default_warehouse_segment_id\" can be used to deep-link the customer to the Audience Composition report in the PushSpring Console for this ingested segment, as documented on [First Party Data Ingest API](doc:overview-3).\n[block:api-header]\n{\n  \"title\": \"Get Audience Details\"\n}\n[/block]\nGets the details about a single audience.\n\nThere are two status columns in this result.  The top level one indicates the overall status of the import operation.  The one at the files array level shows the status for each file loaded.\n\nStatus codes:\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Code\",\n    \"h-1\": \"Meaning\",\n    \"0-0\": \"0\",\n    \"0-1\": \"Pending\",\n    \"1-0\": \"1\",\n    \"1-1\": \"Running\",\n    \"2-0\": \"2\",\n    \"2-1\": \"Finished with no errors\",\n    \"3-0\": \"3\",\n    \"3-1\": \"Error loading\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\nEach file goes through a simple validation step where we validate it is only two columns and that the first column contains what appear **to** be valid mobile advertising ids.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\\\\n  https://api.pushspring.com/v2/firstparty/audience/<audience_id> \\\\\\n  -H 'authorization: Bearer <apikey>' \\\\\\n  -H 'cache-control: no-cache' \\\\\\n  -H 'x-user-token: <usertoken>'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n**Results** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"audience_id\\\": 422,\\n  \\\"name\\\": \\\"Test 2\\\",\\n  \\\"unique_devices\\\": 1234,\\n  \\\"default_warehouse_segment_id\\\": 90316,\\n  \\\"status\\\": 0,\\n  \\\"created_at\\\": \\\"2016-11-10T19:31:29.895Z\\\",\\n  \\\"updated_at\\\": \\\"2017-02-16T16:23:29.084Z\\\",\\n  \\\"uploaded_devices\\\": 1500,\\n  \\\"matched_devices\\\": 996,\\n  \\\"file\\\": [\\n    {\\n      \\\"s3_path\\\": \\\"<partnerprefix>/file.csv\\\",\\n      \\\"status\\\" : 0,\\n      \\\"rows_uploaded\\\": 1500,\\n      \\\"updated_at\\\": \\\"2017-04-17T17:36:31.629Z\\\"\\n    }\\n  ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nHere again, hopefully most of the response parameters are self-explanatory.  The \"default_warehouse_segment_id\" can be used to deep-link the customer to the Audience Composition report in the PushSpring Console for this ingested segment, as documented on [First Party Data Ingest API](doc:overview-3).\n[block:api-header]\n{\n  \"title\": \"Create Audience\"\n}\n[/block]\nCreates an audience and batches it for import.  If you want to import multiple files you can specify a prefix like: customerx/audiencey/.  This would load all files that begin with this prefix.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\\\\n  https://api.pushspring.com/v2/firstparty/audience \\\\\\n  -H 'authorization: Bearer <apikey>' \\\\\\n  -H 'cache-control: no-cache' \\\\\\n  -H 'content-type: application/json' \\\\\\n  -H 'x-user-token: <usertoken>' \\\\\\n  -d '{\\n  \\\"name\\\": \\\"Test Audience\\\",\\n  \\\"file_path\\\":\\\"MatchedAudienceEvents.csv\\\"\\n}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n** Results **\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"audience_id\\\": 620\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Append files to an existing audience\"\n}\n[/block]\nAllows you to add additional data to an existing audience.  All files are merged and deduplicated.  If you specify a file you have already loaded it will be ignored. If you want to import multiple files you can specify a prefix like: customerx/audiencey/.  This would load all files that begin with this prefix.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X PATCH \\\\\\n  http://localhost:3002/v2/firstparty/audience/620 \\\\\\n  -H 'authorization: Bearer <apikey>' \\\\\\n  -H 'cache-control: no-cache' \\\\\\n  -H 'content-type: application/json' \\\\\\n  -H 'x-user-token: <usertoken>' \\\\\\n  -d '{\\n  \\\"file_path\\\":\\\"MatchedAudienceNoEvents.csv\\\"\\n}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n** Results **\n\nNo data will come back.  Success is a HTTP Status Code of 204 / No content.","excerpt":"","slug":"audience","type":"basic","title":"Audience Ingest API"}

Audience Ingest API


## Overview The Audience API endpoint allows you to instruct PushSpring to ingest a file containing Advertising Identifiers and optionally events from S3. When you are provisioned by PushSpring as a First Party Data API partner, you will be given a set of Amazon Web Services S3 credentials and a bucket/path prefix. You will then create the data files to be imported, upload each file to Amazon S3 and then post to the audience API endpoint to tell PushSpring to queue the import job on behalf of the customer. Imports are batched and will complete in the order submitted. [The file format you should use for ingestion is documented here](doc:audience-file-format-for-ingest). [block:api-header] { "title": "Endpoint" } [/block] https://api.pushspring.com/v1/firstparty/audience [block:api-header] { "title": "List Audiences" } [/block] Lists previously imported audiences. [block:code] { "codes": [ { "code": "curl -X GET \\\n https://api.pushspring.com/v2/firstparty/audience \\\n -H 'authorization: Bearer <apikey>' \\\n -H 'cache-control: no-cache' \\\n -H 'x-user-token: <usertoken>'", "language": "curl" } ] } [/block] **Results** [block:code] { "codes": [ { "code": "[\n {\n \"audience_id\": 40,\n \"name\": \"Test\",\n \"unique_devices\": 383992,\n \"default_warehouse_segment_id\": 90418,\n \"status\": 2,\n \"created_at\": \"2015-09-04T14:32:05.194Z\",\n \"updated_at\": \"2016-09-01T21:25:25.122Z\",\n \"uploaded_devices\": 384317,\n \"matched_devices\": 71485\n },\n {\n \"audience_id\": 424,\n \"name\": \"Test2\",\n \"unique_devices\": 12436,\n \"default_warehouse_segment_id\": 90699,\n \"status\": 0,\n \"created_at\": \"2016-11-11T21:51:59.237Z\",\n \"updated_at\": \"2016-11-11T21:52:16.245Z\",\n \"uploaded_devices\": 20000,\n \"matched_devices\": 9875\n }\n]", "language": "json" } ] } [/block] Most of the response parameters are self-explanatory. The "default_warehouse_segment_id" can be used to deep-link the customer to the Audience Composition report in the PushSpring Console for this ingested segment, as documented on [First Party Data Ingest API](doc:overview-3). [block:api-header] { "title": "Get Audience Details" } [/block] Gets the details about a single audience. There are two status columns in this result. The top level one indicates the overall status of the import operation. The one at the files array level shows the status for each file loaded. Status codes: [block:parameters] { "data": { "h-0": "Code", "h-1": "Meaning", "0-0": "0", "0-1": "Pending", "1-0": "1", "1-1": "Running", "2-0": "2", "2-1": "Finished with no errors", "3-0": "3", "3-1": "Error loading" }, "cols": 2, "rows": 4 } [/block] Each file goes through a simple validation step where we validate it is only two columns and that the first column contains what appear **to** be valid mobile advertising ids. [block:code] { "codes": [ { "code": "curl -X GET \\\n https://api.pushspring.com/v2/firstparty/audience/<audience_id> \\\n -H 'authorization: Bearer <apikey>' \\\n -H 'cache-control: no-cache' \\\n -H 'x-user-token: <usertoken>'", "language": "curl" } ] } [/block] **Results** [block:code] { "codes": [ { "code": "{\n \"audience_id\": 422,\n \"name\": \"Test 2\",\n \"unique_devices\": 1234,\n \"default_warehouse_segment_id\": 90316,\n \"status\": 0,\n \"created_at\": \"2016-11-10T19:31:29.895Z\",\n \"updated_at\": \"2017-02-16T16:23:29.084Z\",\n \"uploaded_devices\": 1500,\n \"matched_devices\": 996,\n \"file\": [\n {\n \"s3_path\": \"<partnerprefix>/file.csv\",\n \"status\" : 0,\n \"rows_uploaded\": 1500,\n \"updated_at\": \"2017-04-17T17:36:31.629Z\"\n }\n ]\n}", "language": "json" } ] } [/block] Here again, hopefully most of the response parameters are self-explanatory. The "default_warehouse_segment_id" can be used to deep-link the customer to the Audience Composition report in the PushSpring Console for this ingested segment, as documented on [First Party Data Ingest API](doc:overview-3). [block:api-header] { "title": "Create Audience" } [/block] Creates an audience and batches it for import. If you want to import multiple files you can specify a prefix like: customerx/audiencey/. This would load all files that begin with this prefix. [block:code] { "codes": [ { "code": "curl -X POST \\\n https://api.pushspring.com/v2/firstparty/audience \\\n -H 'authorization: Bearer <apikey>' \\\n -H 'cache-control: no-cache' \\\n -H 'content-type: application/json' \\\n -H 'x-user-token: <usertoken>' \\\n -d '{\n \"name\": \"Test Audience\",\n \"file_path\":\"MatchedAudienceEvents.csv\"\n}'", "language": "curl" } ] } [/block] ** Results ** [block:code] { "codes": [ { "code": "{\n \"audience_id\": 620\n}", "language": "json" } ] } [/block] [block:api-header] { "title": "Append files to an existing audience" } [/block] Allows you to add additional data to an existing audience. All files are merged and deduplicated. If you specify a file you have already loaded it will be ignored. If you want to import multiple files you can specify a prefix like: customerx/audiencey/. This would load all files that begin with this prefix. [block:code] { "codes": [ { "code": "curl -X PATCH \\\n http://localhost:3002/v2/firstparty/audience/620 \\\n -H 'authorization: Bearer <apikey>' \\\n -H 'cache-control: no-cache' \\\n -H 'content-type: application/json' \\\n -H 'x-user-token: <usertoken>' \\\n -d '{\n \"file_path\":\"MatchedAudienceNoEvents.csv\"\n}'", "language": "curl" } ] } [/block] ** Results ** No data will come back. Success is a HTTP Status Code of 204 / No content.