Upsert User Data

Upsert API enables you to send users' attributes and events to Insider. It allows you to insert and update user data whenever you need it. You can 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

POST https://unification.useinsider.com/api/user/v1/upsert

Headers

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 the existing ones by default. If you don't want to append values but overwrite the array attributes, you need to add "not_append": true or "append": false to the request. If you use both together, the value you provide for "append" will be accepted. 

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 historical data. While importing historical data, if there is an active Architect On Event element or the data stream is set, and the imported data meets the conditions of the journey and the data stream, the Architect On Event element or data stream can be triggered.

For example, you send the purchase events from one year ago to users with Upsert API. At the same time, if an active Architect journey is set with a purchase condition using the On Event element, users will enter this journey because they meet the condition based on their data from a year ago.

A boolean flag called “skip_hook” is available in the Upsert request body to prevent historical data from entering the current journey. Thanks to this flag, you can choose whether to trigger the data stream or use the 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.

Insider allows these parameters to send:

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 Requests

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"
          ]
        }
      },
      "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,
  "error_callback_endpoint":"http://your-error-callback-endpoint.yourdomain.com",
  "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"
            }
          }
        }
      ]
    }
  ]
}'

The request below sends data for two users, each with their own attributes, events, and custom parameters.

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,
    "error_callback_endpoint":"http://your-error-callback-endpoint.yourdomain.com",
    "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"
              }
            }
          }
        ]
      },
      {
        "insider_id": "sampleinsiderid_2",
        "attributes": {
          "email_optin": true,
          "age": 23,
          "language": "en_US",
          "list_id": [
            1,
            2
          ],
          "birthday": "1996-08-08T00:00:00Z",
          "custom": {
            "favorite_color": [
              "blue"
            ]
          }
        },
        "not_append": true,
        "events": [
          {
            "event_name": "purchase",
            "timestamp": "2024-01-10T21:35:20Z",
            "event_params": {
              "product_id": "CYD21000",
              "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": "2022-02-17T14:41:21+03:00",
            "event_params": {
              "custom": {
                "customer_type": "trial",
                "trial_start_date": "2021-04-17T14:39:21+03:00",
                "trial_end_date": "2021-04-24T14:41:21+03:00"
              }
            }
          }
        ]
      }
    ]
  }'

Sample Responses

200 OK

This response indicates that the event_group_id and unit_sale_price parameters are included together in the request for the purchase event.

{
    "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. Besides, you can also send these attributes as attributes if any one of them is not an identifier.

{
    "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 a 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 a 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 a 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"}

400 Bad Request

The entire request must be no larger than 5 MB in size. If you send more than that limit, you receive an error shown below:

{"error": "request body is bigger than maximum allowed size 5,000,000 bytes"}

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
• 429 Too Many Requests

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 in 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 data for a maximum of 1,000 records (user).
• The rate limit is shared with the Delete User Attribute, allowing a total of 25,000 requests per minute, which means you can process up to 25 million user records per minute with full batching.
• The value of X-PARTNER-NAME header should be lowercase.