- 22 Apr 2024
- 5 Minutes to read
Export Raw User Data
- Updated on 22 Apr 2024
- 5 Minutes to read
Overview
This API prepares the raw user data, exports it into Insider's AWS S3 Bucket and returns a link to your webhook endpoint as a response. This link enables you to have access to the raw user data and to transfer it to your end.
The API prepares the raw user data for all users for all attributes of those requested, and for a list of events and the event parameters of these events. You can filter to narrow down the user set (e.g. the raw user data can return the users that have made a purchase in the last day).
The API can prepare the raw data for attributes and events together. You can choose the events that you will get, and choose the attributes that will be added to each event entry.
You should provide a webhook endpoint in the request to be notified when the export link is ready. After sending a request, your webhook endpoint receives an export link as follows to have access to the raw user data.
https://insider-data-export.useinsider.com/{partner name}/p/{file name}
You can export raw user data in the following use-cases:
- To analyze user information using a business intelligence tool.
- Sync the data that you want via daily jobs.
To add our IP addresses to your approved list for whitelisting, reach out to the Insider team.
Endpoint and Headers
Headers
Header | Sample Value | Description |
---|---|---|
X-PARTNER-NAME | mybrand | This is your partner name. Navigate to Inone > Inone Settings > Account Preferences to copy your partner name. The partner name should be lowercase. |
X-REQUEST-TOKEN | 1a2b3c4e5d6f | This key is required to authorize your request. Refer to API Authentication Tokens to generate your token. |
Content-Type | application/json | This header specifies the media type of the resource. |
Body Parameters
Before starting the implementation, make sure to share the following information with Insider team:
- A webhook endpoint that will be notified when the export link is ready
- A preferred format: CSV or Parquet
- A list of attributes, events, and event parameters that you want to export
- A dynamic segment that you want to export
Parameter | Description | Data Type | Required |
---|---|---|---|
segment | Segment ID of the user filter. To find your Dynamic Segment ID, navigate to Audience > Segments > Saved Segments > Dynamic Segments. Click on the Segment whose ID you want to get. You can see it on the top right corner on the summary page. | Object | Yes |
attributes | Array of attributes | Array (of string) | Yes (if the body does not have the events object) |
events | Array of events | Object | Yes (if the body does not have the attributes object) |
start_date | Beginning of the date range for the wanted events | Number | Yes (if the body has the events object) |
end_date | End of the date range for the wanted events | Number | Yes (if the body has the events object) |
wanted | Object of the wanted events | Array | Yes (if the body has the events object) |
event_name | Name of the event | String | Yes (if the body has the events object) |
params | Event parameters of the event | Array (of string) | Yes (if the body has the events object) |
filters | Event parameter filters (only one filter is allowed per event_name) | Array (of object) | No |
key | Event parameter name to be filtered by | String | Yes (if the body has the filters object) |
operator | Name of the operator to be applied on the values. The valid operators are eq (equals to), ne (not equals to), lt (less than), gt (greater than), lteq (less than or equal to), gteq (greater than or equal to). | String | Yes (if the body has the filters object) |
values | Event parameter values | Array (of string or number) | Yes (if the body has the filters object) Only one of values and values_url should be provided. |
values_url | File URL containing event parameter values (file should have one column without any headers) | String | Yes (if the body has the filters object) Only one of values and values_url should be provided. |
format | The export format | String | Yes |
hook | Your webhook endpoint | String | Yes |
Sample Example
Sample Request
The sample below displays a request to get the raw user data with all attributes.
curl --location --request POST 'https://unification.useinsider.com/api/raw/v1/export' \
--header 'X-PARTNER-NAME: mybrand' \
--header 'X-REQUEST-TOKEN: 1a2b3c4d5e6f' \
--header 'Content-Type: application/json' \
--header 'Cookie: __cfduid=d1a0bc0c8335c7fecbd3485839787329b1615112066' \
--data-raw '{
"segment": {
"segment_id": 123456789
},
"attributes":[
"*"
],
"events":{
"start_date":1606311893,
"end_date":1611582293,
"wanted":[
{
"event_name":"email_click",
"params":[
"email_campaign_id",
"timestamp"
],
"filters": [
{
"key": "email_campaign_id",
"operator": "eq",
"values": [369, 877]
}
]
},
{
"event_name":"item_added_to_cart",
"params":[
"product_id",
"name",
"timestamp"
]
},
{
"event_name":"journey_entered",
"params":[
"journey_id",
"timestamp"
]
}
]
},
"format":"parquet",
"hook":"xyz.test.com"
}'
The sample below displays a request to get the raw user data with selected attributes.
curl --location --request POST 'https://unification.useinsider.com/api/raw/v1/export' \
--header 'X-PARTNER-NAME: mybrand' \
--header 'X-REQUEST-TOKEN: 1a2b3c4d5e6f' \
--header 'Content-Type: application/json' \
--header 'Cookie: __cfduid=d1a0bc0c8335c7fecbd3485839787329b1615112066' \
--data-raw '{
"segment": {
"segment_id": 123456789
},
"attributes": [
"last_visited_product",
"email",
"name"
],
"events":{
"start_date":1606311893,
"end_date":1611582293,
"wanted":[
{
"event_name":"email_click",
"params":[
"email_campaign_id",
"timestamp"
],
"filters": [
{
"key": "email_campaign_id",
"operator": "eq",
"values": [369, 877]
}
]
},
{
"event_name":"item_added_to_cart",
"params":[
"product_id",
"name",
"timestamp"
]
},
{
"event_name":"journey_entered",
"params":[
"journey_id",
"timestamp"
]
}
]
},
"format":"parquet",
"hook":"xyz.test.com"
}'
Sample Responses
200 OK
When the data is ready to download, you will receive the export link on your webhook URL as displayed below.
{"url":"https://insider-data-export.useinsider.com/{partner name}/p/{file name}"}
429 Too Many Requests
If you exceed the rate limits, you receive an error shown below:
{
"error": "rejected: too many requests"
}
- 400 Empty Partner
- 400 Empty Token
- 403 Authentication Failed
Limitations
- All functions must be executed with a simple HTTPS POST request.
- Only a response that states if the request is successful or failed can be received via this API. No data can be inserted.
- The request token should be provided on the request header. If the token is incorrect, the operation will not be executed.
- The exported data can be in CSV, Parquet or JSON formats.
- The export link expires in 24 hours after it is ready.
- The rate limit is 1 request per day. The API can be called only once in 24 hours with respect to the UTC time zone. The limitation timeline resets at UTC 00:00.
- The value of X-PARTNER-NAME header should be lowercase.