{"__v":0,"_id":"58f174524518c40f005977b6","category":{"__v":0,"_id":"58f173f792f9020f009cad16","project":"55de06fa57f7b20d0097636b","version":"55de06fa57f7b20d0097636e","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"},"parentDoc":null,"project":"55de06fa57f7b20d0097636b","user":"55de06e19db51a0d0064947d","version":{"__v":14,"_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","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"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-04-15T01:16:02.748Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"## Overview\n\nThis document is targeted at platforms which collect or store data on behalf of customers and who wish to transmit that data into the customers’ seat on the PushSpring Console as 1st Party data segments.  Once the data has been ingested, you can then deep-link the mutual customer directly to the audience composition report associated with the newly imported audience.\n\nThe process of integrating with PushSpring to accomplish this is quite simple.  First, PushSpring will give you a set of Amazon Web Services credentials, plus an S3 bucket and path prefix.  This location will be used by you to write data files containing the 1st party data that you want PushSpring to ingest, for all mutual customers.  Second, you will call a REST API telling PushSpring to ingest each file you write, specifying which mutual customer owns the 1st party data we will ingest from that file.  You identify the customer to us via an OAuth access token that has been given back to you from an OAuth Implicit Grant flow (documented below) through which the customer has authenticated their PushSpring seat.  The general flow is:\n\n- (One Time) User clicks a \"Connect to PushSpring\" button or link on your platform.  User is then taken through the OAuth flow, authenticating with PushSpring, and generating an access token which you can store.\n\n- Each time the user has a new segment of 1st Party data they wish to send to their seat on the PushSpring console, you will write the file(s) to the S3 bucket path/prefix and then call our Audience Ingest API to begin the ingest process.\n\n- (Optional) You can call our API to request the status of each ingestion, and display that to the user.  This response will also include a PushSpring segment ID which you can use to construct a deep link into the PushSpring Console to make it easy for the customer to see the ingested data on our platform.\n\n## OAuth Configuration\n\nIn order to establish a link between a customer's account on your system and their PushSpring account, PushSpring supports an OAuth 2.0 Implicit Grant flow (documented at [https://tools.ietf.org/html/rfc6749#section-4.2](https://tools.ietf.org/html/rfc6749#section-4.2)).  PushSpring will provide you with a **client_id** to be used during the OAuth flow, and you will provide to PushSpring the valid redirection endpoint URIs that are allowed to be used after a customer successfully authenticates.  You may specify more than one endpoint to us if, for instance you want to set up a separate test environment, but note we will validate the endpoints passed in during OAuth against this list.\n\nThe resulting token that you receive after a successful OAuth flow should be stored as an opaque blob.  It will be required when calling APIs on the user's behalf.  The token is valid for one year. After a year the PushSpring user will need to renew the token by repeating the OAuth flow.\n\n**Sample flow:**\n* Embed a link on your page like: https://oauth.pushspring.com/login?client_id=<partner id>&redirect_uri=https://<partnersite>/<landingpage>\n  * Note the redirect_url value **must** match one you have pre-submitted to PushSpring.\n* User clicks on link\n* User lands on https://oauth.pushspring.com/login and we show a customized login page.\n* User logs in\n* We redirect back to your redirect_uri including an access_token like:  https://<partnersite>/<landingepage>?access_token=asdlfkjasldasdpfoiasdfasdlkfjasdl\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Other OAuth Params\",\n  \"body\": \"You may use the OAuth-documented state parameter as a nonce and we will pass it back to you unchanged. You may pass the other OAuth params in the specification but we currently ignore them.\"\n}\n[/block]\n## Using the Audience API for data ingest\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 credentials and a S3 bucket/path prefix.  You will then create the data files to be imported, upload each file to S3 and then post to the audience API endpoint to tell PushSpring to queue the import job on behalf of the customer.  \n\nIngests are batched and will complete in the order submitted. \n\n[The full Audience API is documented here](doc:audience).\n\n[The file format you should use for ingestion is documented here](doc:audience-file-format-for-ingest).\n\n## Deep-linking to the Audience in the PushSpring Console\n\nWhen PushSpring ingests an audience segment from your platform, you can create a deep link over to the PushSpring Audience Composition report for that ingested data.  Simply take the value of the \"default_warehouse_segment_id\" that you can get when calling for the status of an ingested audience, and construct a URL of the form\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://console.pushspring.com/segments/<default_warehouse_segment_id>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"overview-3","type":"basic","title":"First Party Data Ingest API"}

First Party Data Ingest API


## Overview This document is targeted at platforms which collect or store data on behalf of customers and who wish to transmit that data into the customers’ seat on the PushSpring Console as 1st Party data segments. Once the data has been ingested, you can then deep-link the mutual customer directly to the audience composition report associated with the newly imported audience. The process of integrating with PushSpring to accomplish this is quite simple. First, PushSpring will give you a set of Amazon Web Services credentials, plus an S3 bucket and path prefix. This location will be used by you to write data files containing the 1st party data that you want PushSpring to ingest, for all mutual customers. Second, you will call a REST API telling PushSpring to ingest each file you write, specifying which mutual customer owns the 1st party data we will ingest from that file. You identify the customer to us via an OAuth access token that has been given back to you from an OAuth Implicit Grant flow (documented below) through which the customer has authenticated their PushSpring seat. The general flow is: - (One Time) User clicks a "Connect to PushSpring" button or link on your platform. User is then taken through the OAuth flow, authenticating with PushSpring, and generating an access token which you can store. - Each time the user has a new segment of 1st Party data they wish to send to their seat on the PushSpring console, you will write the file(s) to the S3 bucket path/prefix and then call our Audience Ingest API to begin the ingest process. - (Optional) You can call our API to request the status of each ingestion, and display that to the user. This response will also include a PushSpring segment ID which you can use to construct a deep link into the PushSpring Console to make it easy for the customer to see the ingested data on our platform. ## OAuth Configuration In order to establish a link between a customer's account on your system and their PushSpring account, PushSpring supports an OAuth 2.0 Implicit Grant flow (documented at [https://tools.ietf.org/html/rfc6749#section-4.2](https://tools.ietf.org/html/rfc6749#section-4.2)). PushSpring will provide you with a **client_id** to be used during the OAuth flow, and you will provide to PushSpring the valid redirection endpoint URIs that are allowed to be used after a customer successfully authenticates. You may specify more than one endpoint to us if, for instance you want to set up a separate test environment, but note we will validate the endpoints passed in during OAuth against this list. The resulting token that you receive after a successful OAuth flow should be stored as an opaque blob. It will be required when calling APIs on the user's behalf. The token is valid for one year. After a year the PushSpring user will need to renew the token by repeating the OAuth flow. **Sample flow:** * Embed a link on your page like: https://oauth.pushspring.com/login?client_id=<partner id>&redirect_uri=https://<partnersite>/<landingpage> * Note the redirect_url value **must** match one you have pre-submitted to PushSpring. * User clicks on link * User lands on https://oauth.pushspring.com/login and we show a customized login page. * User logs in * We redirect back to your redirect_uri including an access_token like: https://<partnersite>/<landingepage>?access_token=asdlfkjasldasdpfoiasdfasdlkfjasdl [block:callout] { "type": "info", "title": "Other OAuth Params", "body": "You may use the OAuth-documented state parameter as a nonce and we will pass it back to you unchanged. You may pass the other OAuth params in the specification but we currently ignore them." } [/block] ## Using the Audience API for data ingest 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 credentials and a S3 bucket/path prefix. You will then create the data files to be imported, upload each file to S3 and then post to the audience API endpoint to tell PushSpring to queue the import job on behalf of the customer. Ingests are batched and will complete in the order submitted. [The full Audience API is documented here](doc:audience). [The file format you should use for ingestion is documented here](doc:audience-file-format-for-ingest). ## Deep-linking to the Audience in the PushSpring Console When PushSpring ingests an audience segment from your platform, you can create a deep link over to the PushSpring Audience Composition report for that ingested data. Simply take the value of the "default_warehouse_segment_id" that you can get when calling for the status of an ingested audience, and construct a URL of the form [block:code] { "codes": [ { "code": "https://console.pushspring.com/segments/<default_warehouse_segment_id>", "language": "text" } ] } [/block]