The Get User Profiles API returns selected attributes and events for a single user identified by a unique identifier. It accepts the identifier along with an attribute list, event list, and date range, and responds with the requested data.
This API can be used for use cases such as personalizing content for external providers or connecting user profiles to services like call centers.
Endpoint and Headers
Visit our Postman collection to test this request.
Headers
Header | Sample Value | Description |
|---|---|---|
X-PARTNER-NAME | mybrand | This is your partner name. Navigate to Inone Settings > Account Settings to copy your partner name. The partner name should be lowercase. |
X-REQUEST-TOKEN | 1a2b3c4d5e6f | 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
Each POST body must have an identifiers object.
Each request must include an attribute or an event object to return the corresponding user profiles. If the events object is used, its required keys must be provided as outlined in the table below.
Parameter | Description | Data Type | Required |
|---|---|---|---|
identifiers | Identifier key | Object | Required |
attributes | Array of wanted attributes | Array (of string) | Yes (if the body does not have the events object) |
events | Object 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 (Epoch Timestamp) | Yes (if the body has the events object) |
end_date | End of the date range for the wanted events | Number (Epoch Timestamp) | 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 | Wanted event parameters of the event | Array (of string) | Yes (if the body has the events object) |
quota | Flag to display quota usage | Boolean | No |
For this API, use journey_campaign_name as the journey event's name parameter.
Sample Request
The sample below shows a request to fetch user data by identifier. Attributes and events can be specified to control the response. For multi-word names, use an underscore (_) (e.g., email_optin, homepage_view).
curl --location --request POST 'https://unification.useinsider.com/api/user/v1/profile' \
--header 'X-REQUEST-TOKEN: 1a2b3c4d5e6f' \
--header 'X-PARTNER-NAME: mybrand' \
--header 'Content-Type: application/json' \
--data-raw '{
"identifiers":{
"email":"example@useinsider.com"
},
"attributes":[
"email",
"name",
"surname"
],
"events":{
"start_date":1606311893,
"end_date":1611582293,
"wanted":[
{
"event_name":"email_click",
"params":[
"campaign_id",
"timestamp"
]
},
{
"event_name":"item_added_to_cart",
"params":[
"product_id",
"name",
"timestamp"
]
},
{
"event_name":"journey_entered",
"params":[
"journey_id",
"timestamp"
]
}
]
},
"quota": true
}'The sample below displays a request to fetch user data with a custom attribute. For custom attributes, add a c_ prefix (e.g., c_member_code).
curl --location --request POST 'https://unification.useinsider.com/api/user/v1/profile' \
--header 'X-REQUEST-TOKEN: 1a2b3c4d5e6f' \
--header 'X-PARTNER-NAME: mybrand' \
--header 'Content-Type: application/json' \
--data-raw '{
"identifiers": {
"email": "example@useinsider.com"
},
"attributes": [
"email",
"name",
"surname",
"c_member_code"
],
"events": {
"start_date": 1606311893,
"end_date": 1611582293,
"wanted": [
{
"event_name": "email_click",
"params": [
"campaign_id",
"timestamp"
]
},
{
"event_name": "item_added_to_cart",
"params": [
"product_id",
"name",
"timestamp"
]
},
{
"event_name": "journey_entered",
"params": [
"journey_id",
"timestamp"
]
}
]
},
"quota": true
}'The sample below shows a request to retrieve user data using the insider_id, an internal ID maintained by Insider One for each user. You can find the insider_id as the Profile ID on the User Profiles page.
curl --location --request POST 'https://unification.useinsider.com/api/user/v1/profile' \
--header 'X-REQUEST-TOKEN: 1a2b3c4d5e6f' \
--header 'X-PARTNER-NAME: mybrand' \
--header 'Content-Type: application/json' \
--data-raw '{
"insider_id": "sampleinsiderid",
"attributes": [
"email",
"name",
"surname"
],
"events": {
"start_date": 1606311893,
"end_date": 1611582293,
"wanted": [
{
"event_name": "email_click",
"params": [
"campaign_id",
"timestamp"
]
},
{
"event_name": "item_added_to_cart",
"params": [
"product_id",
"name",
"timestamp"
]
},
{
"event_name": "journey_entered",
"params": [
"journey_id",
"timestamp"
]
}
]
},
"quota": true
}'Sample Responses
200 OK
{
"attributes": {
"email": "example@useinsider.com",
"name": "John",
"surname": "Doe",
"iid": "insider-id-user-1"
},
"events": {
"email_click": [
{
"campaign_id": 1456,
"created_date": "2021-01-06T23:34:09Z"
},
{
"campaign_id": 1245,
"created_date": "2021-01-01T12:56:21Z"
}
],
"item_added_to_cart": [
{
"product_id": "3254634",
"name": "Blue Shirt",
"created_date": "2021-01-04T15:04:34Z"
}
]
},
"quota": {
"cost": 2.5,
"used": 2.5,
"total": 1000
}
}404 Not Found
{"error":"no such user for these identifiers: no data"}429 Too Many Requests
If you exceed the rate limits, you receive an error shown below:
{
"error": "rejected: too many requests"
}Limitations
All functions must be executed with a simple HTTPS POST request.
Only new data can be retrieved via this API. No data can be inserted.
The request token should be provided in the request header. If the token is incorrect, the operation will not be executed.
The API can prepare the data only for one user specified by the identifier.
If the limit_per_source value is set, then only that many events are assigned from every source. For example, if the limit_per_source value is set to 1 for the purchase event, then one purchase event is acquired from email, web, and other sources.
To view payload quota usage, set Quota=true.
The quota is limited to 1000 units per minute.
The size of the user base and the number of event types determine quota usage. The attribute number or set of attributes doesn't matter.
The value of X-PARTNER-NAME header should be lowercase.
The default limit shown here is a standard baseline. If your use case requires higher capacity, feel free to reach out to the Insider One team — we can adjust it to fit your needs.