Upsert User Data

The Upsert API allows you to send user attributes and events to Insider One. It supports both inserting and updating user data whenever needed.

You can use Upsert User Data for:

• Sending offline purchases or other historical events.
• Sending leads collected from external platforms.
• Sending segments that were 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.

Attributes

• An attribute is a single, static piece of information about a user, such as gender, age, or loyalty class.
• For array attributes, new values are appended by default.
• To overwrite instead of append, include "not_append": true or "append": false in the request.
• If both are included, the value of "append" will take priority.

Events

• An event is a collection of information, such as purchased products or visited stores.
• If you send multiple updates for the same user with the same event name, the new event will be added to the existing collection.

Import historical data with the Upsert API

The Upsert API allows you to import historical data. When you do this, keep in mind:

If an active Architect On Event element or a set data stream is present, and the imported data meets their conditions, the journey or data stream can be triggered.

For example, if you send purchase events from one year ago through the Upsert API, and an Architect journey is active with an On Event condition set to 'purchase', then those users will enter the journey—even though the events occurred a year ago.

A boolean flag called skip_hook is available in the Upsert request body. This flag controls whether historical data should trigger journeys or data streams. This flag is not mandatory. Its rules are:

• skip_hook: false → Default if not specified. Imported data can trigger Architect On Event elements and data streams.
• skip_hook: true → Prevents imported data from triggering Architect journeys or data streams.

Insider One 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 One. If you want to stop collecting and processing the data of an identified user, GDPR opt-in field should have the false value. Insider One 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 contains a users array. Each user must include an identifiers object.

The sample request below shows a purchase event with user attributes. For more supported events and parameters, see Default Events & Attributes.

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",
        "static_segment_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 includes insider_id, an internal ID maintained by Insider One for each user. You can find this value as the Profile ID on the User Profiles page.

It also includes error_callback_endpoint, which is triggered if the upsert request fails due to a unification error. In such cases, Insider One will resend the same payload you initially submitted for that user.

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",
        "static_segment_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. If the request fails, the same payload is returned to your error_callback_endpoint.

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",
          "static_segment_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",
          "static_segment_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, 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 must have a valid email address in the format specified 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 must have a valid identifier in the format specified 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 must provide a valid phone number in the format specified 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 a 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.