Upsert user data
  • 22 Feb 2024
  • 9 Minutes to read

    Upsert user data


      Article Summary

      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
      Your title goes here
      If you want to limit access to the Upsert API for users with a UCD API Key or control data transmission through this API, you can implement IP restrictions. This ensures that only Upsert API requests from approved IP addresses will be accepted. If you're interested in making such a custom adjustment, please reach out to the Insider team.

      Endpoint and Headers

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

      Headers

      HeaderSample ValueDescription
      X-PARTNER-NAMEmybrandThis is your partner name. Navigate to Inone > Inone Settings > Account Preferences to copy your partner name. The partner name should be lowercase.
      X-REQUEST-TOKEN1a2b3c4e5d6fThis key is required to authorize your request. Refer to API Authentication Tokens to generate your token.
      Content-Typeapplication/jsonThis 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.

      Each user object must have at least one attributes object or one events object.
      your title goes here
      No default attribute is mandatory. If you use attributes object in the request, you need to have at least one attribute in your object.
      your title goes here
      You can use event group ID to group the events of the same type if you send multiple events of this type.
      Your title goes here
      When sending events via the Upsert API, ensure that the values fall within the TTL (Time-to-Live) of the events. Events with timestamps exceeding the TTL will not be written. You can refer here for further information.

      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.

      ParameterDescriptionData TypeRequired
      usersArray of user information such as identifiers, attributes and events.ArrayYes
      identifiersUser's identifier information.ObjectYes
      attributesAttributes object of user information such as gender, age.ObjectNo
      emailAttribute. User's email address, can be used as an identifier.StringNo
      phone_numberAttribute. User's phone number in E.164 format (e.g. +6598765432), can be used as an identifier.StringNo
      email_optinAttribute. User's permission for marketing emails:
      True = emails allowed;
      False = email not allowed
      BooleanNo
      gdpr_optinAttribute. 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
      BooleanNo
      sms_optinAttribute. User's permission for SMS:
      True = SMS allowed;
      False = SMS not allowed
      BooleanNo
      whatsapp_optinAttribute. User's permission for WhatsApp Message:
      True = WhatsApp Message allowed
      False = WhatsApp Message not allowed
      BooleanNo
      nameAttribute. User's name.StringNo
      surnameAttribute. User's surname.StringNo
      birthdayAttribute. 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

      genderAttribute. Gender of the userStringNo
      ageAttribute. Age of the userNumberNo
      languageLanguage information of the userStringNo
      countryAttribute. Country information of the user in ISO 3166-1 alpha-2 format.StringNo
      cityAttribute. City information of the user.StringNo
      list_idAttribute. Newsletter contact list IDs (users are added directly).Numbers (Number array)No
      eventsList of eventsArrayNo
      event_name
      Name of the eventStringYes
      timestamp
      Event. Event time, the purchase date for the purchase event in RFC3339 format.DatetimeYes
      event_params
      Event parameters for purchase-related properties.ObjectNo
      • custom
      Object consisting of custom event parametersObjectNo
      event_group_id
      Event group IDStringNo (Yes only when the event_name is purchase or cart_page_view)
      product_id
      Event. Unique product ID.StringNo
      name
      Event. Name of the product.StringNo
      taxonomy
      Event. Category tree of the product.ArrayNo
      currency
      Event. Currency used for product pricing, in ISO 4217 format (e.g. USD).StringNo (Yes only when the event_name is purchase or cart_page_view)
      quantity
      Event. Quantity of the product.IntegerNo (Yes only when the event_name is purchase)
      unit_price
      Event. Price of the product without any discount(s).FloatNo
      unit_sale_price
      Event. Unit price of the product.FloatNo (Yes only when the event_name is purchase or cart_page_view)
               localeEvent. Locale of the user.StringNo
      color
      Event. Color of the product (selected by user).StringNo
      size
      Event. Size of the product (selected by user).StringNo
      shipping_cost
      Event. Shipping cost of the items in basket.StringNo
      promotion_name
      Event. Name of the promotion.StringNo
      promotion_discount
      Event. Total amount of discount applied by promotions.FloatNo

      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.

      Your title goes here
      The sample request below sends the default purchase event. To see the other default events and event parameters that you can use in your requests, refer to 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",
              "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.

      Your title goes here
      insider_id is an internal ID maintained by the Insider for each user. To find the insider_id, you can refer to the Profile ID on the User Profile.
      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.

      Was this article helpful?


      ESC

      Eddy, a super-smart generative AI, opening up ways to have tailored queries and responses