- 22 Feb 2024
- 9 Minutes to read
Upsert User Data
- Updated on 22 Feb 2024
- 9 Minutes to read
Overview
Upsert API enables you to send attributes and events of the users to Insider. It enables you to insert and update user data whenever you need it. We have also replaced CRM API with Upsert User Data APIs to give you more capabilities like:
- Supporting multiple and custom identifiers
- Supporting all events
- Improved response messages
You can possibly use the upsert user data for the following use cases:
- Sending offline purchases or any other events.
- Sending leads that are collected from any other platform
- Sending segments that are prepared in-house
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
You can send two data types to our data ingestion API: attributes and events.
An attribute is a single, static piece of information about a user, such as gender, age, or loyalty class. When you send data to an array attribute for a user, the new values are added to existing ones by default behavior. If you don't want to append values but to overwrite the array attributes, you need to add "append": false or"not_append": true to the request. An event is a collection of information such as purchased products or visited stores. Any update request for an existing user with the same event name will append it to the collection.
Using Upsert API, you can import the historical data. While importing the historical data, if there is an active Architect on event element or the data stream is set, and the imported data meet the conditions of the journey and the data stream, Architect's on event elements or data stream can be triggered.
For example, you send the purchase events from one year ago to users with Upsert API. If, at the same time, there is an active Architect journey that was set with purchase condition using the on event element, users will enter this journey since they meet the condition based on their data from one year ago.
To prevent historical data from entering the current journey, a boolean flag called “skip_hook” is available in the Upsert request body. Thanks to this flag, you can choose whether to trigger the data stream, or use Architect on event starter for the imported data.
This flag is not mandatory. If not specified, it is taken as “skip_hook”: false by default. If you do not want to trigger the data stream, it should be skip_hook: true.
Parameter | Description | Data Type | Required |
---|---|---|---|
users | Array of user information such as identifiers, attributes and events. | Array | Yes |
identifiers | User's identifier information. | Object | Yes |
attributes | Attributes object of user information such as gender, age. | Object | No |
Attribute. User's email address, can be used as an identifier. | String | No | |
phone_number | Attribute. User's phone number in E.164 format (e.g. +6598765432), can be used as an identifier. | String | No |
email_optin | Attribute. User's permission for marketing emails: True = emails allowed; False = email not allowed | Boolean | No |
gdpr_optin | Attribute. User's permission for Insider campaigns, data collection and processing: False = user will not see any Insider campaign or receive any message from any channel; True or empty = Insider may interact with the user through personalization campaigns | Boolean | No |
sms_optin | Attribute. User's permission for SMS: True = SMS allowed; False = SMS not allowed | Boolean | No |
whatsapp_optin | Attribute. User's permission for WhatsApp Message: True = WhatsApp Message allowed False = WhatsApp Message not allowed | Boolean | No |
name | Attribute. User's name. | String | No |
surname | Attribute. User's surname. | String | No |
birthday | Attribute. User's birthday in RFC 3339 format (e.g. 1993-03-12T00:00:00Z). Note: Send the birthdays without the time offset. | Date/Time | No |
gender | Attribute. Gender of the user | String | No |
age | Attribute. Age of the user | Number | No |
language | Language information of the user | String | No |
country | Attribute. Country information of the user in ISO 3166-1 alpha-2 format. | String | No |
city | Attribute. City information of the user. | String | No |
list_id | Attribute. Newsletter contact list IDs (users are added directly). | Numbers (Number array) | No |
events | List of events | Array | No |
event_name | Name of the event | String | Yes |
timestamp | Event. Event time, the purchase date for the purchase event in RFC3339 format. | Datetime | Yes |
event_params | Event parameters for purchase-related properties. | Object | No |
| Object consisting of custom event parameters | Object | No |
event_group_id | Event group ID | String | No (Yes only when the event_name is purchase or cart_page_view) |
product_id | Event. Unique product ID. | String | No |
name | Event. Name of the product. | String | No |
taxonomy | Event. Category tree of the product. | Array | No |
currency | Event. Currency used for product pricing, in ISO 4217 format (e.g. USD). | String | No (Yes only when the event_name is purchase or cart_page_view) |
quantity | Event. Quantity of the product. | Integer | No (Yes only when the event_name is purchase) |
unit_price | Event. Price of the product without any discount(s). | Float | No |
unit_sale_price | Event. Unit price of the product. | Float | No (Yes only when the event_name is purchase or cart_page_view) |
locale | Event. Locale of the user. | String | No |
color | Event. Color of the product (selected by user). | String | No |
size | Event. Size of the product (selected by user). | String | No |
shipping_cost | Event. Shipping cost of the items in basket. | String | No |
promotion_name | Event. Name of the promotion. | String | No |
promotion_discount | Event. Total amount of discount applied by promotions. | Float | No |
If your company obtains your users' consent in compliance with the local regulations, make sure to pass the GDPR opt-in field to Insider. If you want to stop collecting and processing the data of an identified user, GDPR opt-in field should have the false value. Insider cannot be held liable if these obligations are not fulfilled and reserves the right to seek compensation from your company.
Sample Example
Sample Request
The request body consists of a users array. Each user must have an identifiers object.
curl --location --request POST 'https://unification.useinsider.com/api/user/v1/upsert' \
--header 'X-PARTNER-NAME: mybrand' \
--header 'X-REQUEST-TOKEN: 1a2b3c4e5d6f' \
--header 'Content-Type: application/json' \
--data-raw '{
"skip_hook": false,
"users": [
{
"identifiers": {
"email": "sample@useinsider.com",
"uuid": "1x2y3z",
"custom": {
"user_loyalty_id": "xyz123"
}
},
"attributes": {
"email_optin": true,
"age": 30,
"language": "en_US",
"list_id": [
1,
2
],
"birthday": "1980-01-01T00:00:00Z",
"custom": {
"favorite_color": [
"green"
]
}
},
"not_append": true,
"events": [
{
"event_name": "purchase",
"timestamp": "2021-01-10T21:35:20Z",
"event_params": {
"product_id": "ABC21000",
"name": "Your Product Name",
"unit_price": 990.9,
"unit_sale_price": 890.9,
"event_group_id": "ORDER123",
"taxonomy": [
"Electronic",
"Phone"
],
"currency": "USD",
"quantity": 1
}
},
{
"event_name": "account_created",
"timestamp": "2021-01-17T14:41:21+03:00",
"event_params": {
"custom": {
"customer_type": "trial",
"trial_start_date": "2021-01-17T14:39:21+03:00",
"trial_end_date": "2021-01-24T14:41:21+03:00"
}
}
}
]
}
]
}'
The request body below contains insider_id.
curl --location --request POST 'https://unification.useinsider.com/api/user/v1/upsert' \
--header 'X-PARTNER-NAME: mybrand' \
--header 'X-REQUEST-TOKEN: 1a2b3c4e5d6f' \
--header 'Content-Type: application/json' \
--data-raw '{
"skip_hook": false,
"users": [
{
"insider_id": "sampleinsiderid",
"attributes": {
"email_optin": true,
"age": 30,
"language": "en_US",
"list_id": [
1,
2
],
"birthday": "1980-01-01T00:00:00Z",
"custom": {
"favorite_color": [
"green"
]
}
},
"not_append": true,
"events": [
{
"event_name": "purchase",
"timestamp": "2021-01-10T21:35:20Z",
"event_params": {
"product_id": "ABC21000",
"name": "Your Product Name",
"unit_price": 990.9,
"unit_sale_price": 890.9,
"event_group_id": "ORDER123",
"taxonomy": [
"Electronic",
"Phone"
],
"currency": "USD",
"quantity": 1
}
},
{
"event_name": "account_created",
"timestamp": "2021-01-17T14:41:21+03:00",
"event_params": {
"custom": {
"customer_type": "trial",
"trial_start_date": "2021-01-17T14:39:21+03:00",
"trial_end_date": "2021-01-24T14:41:21+03:00"
}
}
}
]
}
]
}'
Sample Responses
200 OK
To receive such response below for the purchase event, you need to include event_group_id and unit_sale_price parameters together in your request.
{
"data": {
"successful": {},
"fail": {
"count": 1,
"errors": {
"users.0.events.0.event_params.*.required": [
"event_group_id parameter is required on purchase event",
"unit_sale_price parameter is required on purchase event"
]
}
}
}
}
200 OK
For the request below, you need to use an identifier for the user, which can be either insider_id or UUID, email or phone number or a custom attribute.
{
"data": {
"successful": {},
"fail": {
"count": 1,
"errors": {
"users.0.events.0.event_params.*.required": [
"event_group_id parameter is required on purchase event",
"unit_sale_price parameter is required on purchase event"
],
"users.0.identifiers.required": [
"either insider_id or idenifiers must be specified"
],
"users.0.insider_id.required": [
"either insider_id or idenifiers must be specified"
]
}
}
}
}
200 OK
For the request below, you need to have the valid email address in the format stated in the parameters table.
{
"data": {
"successful": {},
"fail": {
"count": 1,
"errors": {
"users.0.events.0.event_params.*.required": [
"event_group_id parameter is required on purchase event",
"unit_sale_price parameter is required on purchase event"
],
"users.0.identifiers.*.regexp(^.+@.+\\..+$)": [
"not a valid email address: sample"
]
}
}
}
}
200 OK
For the request below, you need to have the valid UUID in the format stated in the parameters table.
{
"data": {
"successful": {},
"fail": {
"count": 1,
"errors": {
"users.0.events.0.event_params.*.required": [
"event_group_id parameter is required on purchase event",
"unit_sale_price parameter is required on purchase event"
],
"users.0.identifiers.*.type(string)": [
"uuid must be string: 12345"
]
}
}
}
}
200 OK
For the request below, you need to have the valid identifier in the format stated in the parameters table.
{
"data": {
"successful": {},
"fail": {
"count": 1,
"errors": {
"users.0.events.0.event_params.*.required": [
"event_group_id parameter is required on purchase event",
"unit_sale_price parameter is required on purchase event"
],
"users.0.identifiers.*.in(defaults_column)": [
"key must be one of phone_number(pn), email(em) or uuid"
]
}
}
}
}
200 OK
For the request below, you need to have the valid phone number in the format stated in the parameters table.
{
"data": {
"successful": {},
"fail": {
"count": 1,
"errors": {
"users.0.events.0.event_params.*.required": [
"event_group_id parameter is required on purchase event",
"unit_sale_price parameter is required on purchase event"
],
"users.0.identifiers.*.regexp(^\\+[1-9]\\d{6,14}$)": [
"user has an invalid phone number: 12345"
]
}
}
}
}
400 Bad Request
If you do not include user in your request, you receive an error shown below:
{"error":"users must be defined: bad request"}
429 Too Many Requests
If you exceed the rate limits, you receive an error shown below:
{
"error": "rejected: too many requests"
}
Error Codes
- 400 Bad Request
- 500 Internal Server Error
- 403 Forbidden
If you receive a 403 response, make sure to stop or pause the current data sending, check your headers, and correct them if they are incorrect, and resume your integration after the fix, and retry the failed requests. If your headers are correct and you still see any issue in the response, you should create a ticket to Insider's Operational Excellence Team.
Limitations
- All functions must be executed with a simple HTTPS POST request.
- Only new data can be inserted and updated with this API. No data can be retrieved.
- The request token should be provided on the request header. If the token is incorrect, no operation will be executed.
- The entire request must not exceed 5 MB.
- Each request can upsert the data for a maximum of 1,000 records (user).
- The rate limit is 25,000 requests per minute.
- The value of X-PARTNER-NAME header should be lowercase.