Insider User Data APIs API

openapi: 3.2.0
info:
  title: Insider User Data APIs API
  version: 1.0.0
  contact:
    name: Insider One Support
    email: support@useinsider.com
    url: https://academy.insiderone.com/docs/insider-one-apis-1
  termsOfService: https://insiderone.com/terms-of-use/
  description: 'Operations tagged User Data APIs across 2 of this provider''s published API definitions: insider-contact-openapi.yml, insider-unification-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://contact.useinsider.com
- url: https://unification.useinsider.com
tags:
- name: User Data APIs
paths:
  /fps/v1/upload:
    post:
      operationId: uploadFirstPartySegments
      summary: Upload first-party segments
      tags:
      - User Data APIs
      description: The First-Party Segment API allows you to easily create a first-party segment through an API.
      security:
      - PartnerName: []
      - RequestToken: []
      requestBody:
        content:
          application/json:
            example:
              segmentName: My Segment Name
              fileUrl: https://s3.amazonaws.com/sample_csv_file.csv
              callbackUrl: https://localhost/12345
              attributeName: em
      responses:
        '429':
          $ref: '#/components/responses/TooManyRequests'
    servers:
    - url: https://contact.useinsider.com
  /api/raw/v1/export:
    post:
      operationId: exportRawUserData
      summary: Export raw user data
      tags:
      - User Data APIs
      description: This API prepares the raw user data, exports it into Insider's AWS S3 Bucket, and returns a link to your webhook endpoint as a response.
      security:
      - PartnerName: []
      - RequestToken: []
      requestBody:
        content:
          application/json:
            examples:
              default:
                value:
                  segment:
                    segment_id: 123456789
                  attributes:
                  - '*'
                  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
                  format: parquet
                  hook: xyz.test.com
              export-app-push-results-with-raw-user-data:
                summary: Export app push results with raw user data
                value:
                  segment:
                    segment_id: 123456789
                  attributes:
                  - iid
                  - udid
                  - pn
                  - uuid
                  - em
                  - app_version
                  - mo
                  - ov
                  events:
                    start_date: 1693907940
                    end_date: 1693994340
                    wanted:
                    - event_name: push_delivered
                      params:
                      - timestamp
                      - camp_id
                      - camp_type
                      - variant_id
                    - event_name: push_session
                      params:
                      - timestamp
                      - camp_id
                      - camp_type
                      - variant_id
                  format: csv
                  hook: xyz.test.com
              export-app-template-results-with-raw-user-data:
                summary: Export app template results with raw user data
                value:
                  segment:
                    segment_id: 123456789
                  attributes:
                  - iid
                  - udid
                  - pn
                  - uuid
                  - em
                  - app_version
                  - mo
                  - ov
                  events:
                    start_date: 1693907940
                    end_date: 1693994340
                    wanted:
                    - event_name: inapp_seen
                      params:
                      - timestamp
                      - inapp_id
                      - variant_id
                      - dismiss_type
                  format: csv
                  hook: xyz.test.com
              export-app-survey-results-with-raw-user-data:
                summary: Export app survey results with raw user data
                value:
                  segment:
                    segment_id: 123456789
                  attributes:
                  - iid
                  - udid
                  - pn
                  - uuid
                  - em
                  - app_version
                  - mo
                  - ov
                  events:
                    start_date: 1606311893
                    end_date: 1611582293
                    wanted:
                    - event_name: survey_result
                      params:
                      - timestamp
                      - answer
                      - camp_id
                      - question
                      - variant_id
                  format: parquet
                  hook: xyz.test.com
      responses:
        '200':
          description: OK
        '429':
          $ref: '#/components/responses/TooManyRequests'
    servers:
    - url: https://unification.useinsider.com
  /api/user/v1/attribute/delete:
    post:
      operationId: deleteUserAttribute
      summary: Delete user attribute
      tags:
      - User Data APIs
      description: This API enables you to delete your customer attributes when you need to.
      security:
      - PartnerName: []
      - RequestToken: []
      requestBody:
        content:
          application/json:
            example:
              users:
              - identifiers:
                  email: sample@mail.com
                  uuid: 1x2y3z
                  custom:
                    custom_identifier: xyz123
                whole:
                - name
                - surname
                - email_optin
                partial:
                  list_id:
                  - 1
                  - 2
                custom:
                  whole:
                  - custom_string_attribute
                  - custom_array_attribute
                  partial:
                    custom_array_attribute:
                    - value1
                    - value2
                    - value3
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                data:
                  successful:
                    count: 1
                  fail: {}
        '429':
          $ref: '#/components/responses/TooManyRequests'
    servers:
    - url: https://unification.useinsider.com
  /api/user/v1/identity:
    patch:
      operationId: updateIdentifiers
      summary: Update identifiers
      tags:
      - User Data APIs
      description: 'This API enables you to update the value of the identifiers that are already associated with users.


        For example, an existing user that is already a known user to Insider may have updated their email address in your system. Accordingly, you may need to change the identifier(s) of this user. With this API, you can change the value of an existing identifier to a new value.


        Body Parameters

        Each PATCH request must have an identifier type, old value, and new value specified in it. You can use either one of the default identifiers which are uuid, email, and phone_number, or any one of the custom identifiers you are using.


        Parameter

        Description

        Data Type

        Required


        old_identifier

        User’s current identifier value

        Object

        Yes


        new_identifier

        User’s next identifier value

        Object

        Yes


        custom

        User’s custom identifiers information

        Object

        No


        email

        User''s email address

        String

        No


        phone_number

        User''s phone number in E.164 format (e.g. +6598765432)

        String

        No


        uuid

        User''s unique user identifier

        String

        No


        Sample Body

        Below is a sample body with default identifiers.


        {

        "old_identifier": {

        "email": "sample@mail.com"

        },

        "new_identifier": {

        "email": "sample2@mail.com"

        }

        }


        Below is a sample body with custom identifiers.


        {

        "old_identifier": {

        "custom": {

        "user_loyalty_id": "xyz123"

        }

        },

        "new_identifier": {

        "custom": {

        "user_loyalty_id": "xyz123"

        }

        }

        }


        Sample Responses

        400 Bad Request

        The following response returns if the identifier values are the same.


        {

        "error": "identifier values are the same: bad request"

        }


        400 Bad Request

        The following response returns if you do not have 1 entry for both new and old identifiers.


        {

        "error": "there must be exactly 1 entry for both new and old identifiers: bad request"

        }


        Limitations

        When sending your request, make sure to follow these limitations.


        All functions must be executed with a simple HTTPS PATCH request.


        The request token should be provided in the request header. If the token is incorrect, no operation will be executed.


        A single HTTPS PATCH request can pass only one record (user).


        A maximum of 2000 requests can be sent per minute.


        Identifiers that are to be replaced should be of the same type.


        The entire request must not exceed 5 MB.


        The value of X-PARTNER-NAME header should be lowercase.'
      security:
      - PartnerName: []
      - RequestToken: []
      requestBody:
        content:
          application/json:
            example:
              old_identifier:
                email: sample@mail.com
              new_identifier:
                email: sample2@mail.com
      responses:
        '200':
          description: OK
          content:
            application/json:
              example: {}
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      operationId: deleteIdentifiers
      summary: Delete identifiers
      tags:
      - User Data APIs
      description: 'This API enables you to delete the value of the identifiers that are already associated with users.


        For example, an existing user that is already a known user to Insider may have deleted their phone number from your system. Accordingly, you may need to delete the phone number of this user. With this API, you can delete the value of an existing identifier.


        This deletion action cannot be undone. Please carefully consider before proceeding.


        Body Parameters

        Each DELETE request must have an identifier type, and the value specified in it. You can use either one of the default identifiers, which are uuid, email, and phone_number, or any one of the custom identifiers you are using.


        If the user is associated with only one identifier, you cannot delete it.


        Parameter

        Description

        Data Type

        Required


        identifiers

        User’s current identifier in use

        Object

        Yes


        custom

        User’s custom identifiers information

        Object

        No


        email

        User''s email address

        String

        No


        phone_number

        User''s phone number in E.164 format (e.g. +6598765432)

        String

        No


        uuid

        User''s unique user identifier

        String

        No


        Sample Body

        Below is a sample body with a default identifier.


        {

        "identifiers": {

        "email": "sample@mail.com"

        }

        }


        Below is a sample body with a custom identifier.


        {

        "identifiers": {

        "custom": {

        "user_loyalty_id": "xyz123"

        }

        }

        }


        Sample Responses

        400 Bad Request

        The following response returns if the user has only one identifier.


        {

        "error": "you cannot delete the sole identifier specified for a user: bad request"

        }


        429 Too Many Requests

        If you exceed the rate limits, you receive an error shown below:


        {

        "error": "rejected: too many requests"

        }


        Limitations

        When sending your request, make sure to follow these limitations.


        All functions must be executed with a simple HTTPS DELETE request.


        The request token should be provided in the request header. If the token is incorrect, no operation will be executed.


        A single HTTPS DELETE request can pass only 1 record (user).


        A maximum of 25,000 requests can be sent per minute.


        Identifier that are to be deleted cannot be the only identifier associated with the corresponding user profile.


        The entire request must not exceed 5 MB.


        The value of X-PARTNER-NAME header should be lowercase.'
      security:
      - PartnerName: []
      - RequestToken: []
      requestBody:
        content:
          application/json:
            example:
              identifiers:
                email: sample@mail.com
      responses:
        '200':
          description: Delete identifiers
        '429':
          $ref: '#/components/responses/TooManyRequests'
    servers:
    - url: https://unification.useinsider.com
  /api/user/v1/profile:
    post:
      operationId: getUserProfiles
      summary: Get user profiles
      tags:
      - User Data APIs
      description: This API returns the attributes and events you request for a single user that you specify by an identifier.
      security:
      - PartnerName: []
      - RequestToken: []
      requestBody:
        content:
          application/json:
            example:
              identifiers:
                email: johndoe@email.com
              attributes:
              - email
              - name
              - surname
              - custom
              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
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                attributes:
                  email_optin: true
                events:
                  homepage_view:
                  - referrer: https://posh.useinsider.com/customer/account/login/referer/aHR0cHM6Ly9wb3NoLnVzZWluc2lkZXIuY29tL2Ntcy9ub3JvdXRlL2luZGV4Lw%2C%2C/
                    source: web
                  - referrer: https://posh.useinsider.com/bess-yoga-short.html
                    source: web
                  - referrer: https://posh.useinsider.com/customer/account/login/referer/aHR0cHM6Ly9wb3NoLnVzZWluc2lkZXIuY29tL2Ntcy9ub3JvdXRlL2luZGV4Lw%2C%2C/
                    source: web
                  - referrer: https://posh.useinsider.com/customer/account/login/referer/aHR0cHM6Ly9wb3NoLnVzZWluc2lkZXIuY29tL2Ntcy9ub3JvdXRlL2luZGV4Lw%2C%2C/
                    source: web
                  - referrer: https://posh.useinsider.com/bess-yoga-short.html
                    source: web
                  - referrer: https://posh.useinsider.com/bess-yoga-short.html
                    source: web
                  - referrer: https://posh.useinsider.com/bess-yoga-short.html
                    source: web
                  - referrer: https://posh.useinsider.com/apps/insider/insider-sw-sdk.js
                    source: web
                  - referrer: https://posh.useinsider.com/?SID=gtqfg0af2g3fopr1qio4hsjdso
                    source: web
        '429':
          $ref: '#/components/responses/TooManyRequests'
    servers:
    - url: https://unification.useinsider.com
  /api/user/v1/upsert:
    post:
      operationId: upsertUserData
      summary: Upsert user data
      tags:
      - User Data APIs
      description: Upsert API enables you to send users' attributes and events to Insider.
      security:
      - PartnerName: []
      - RequestToken: []
      requestBody:
        content:
          application/json:
            example:
              users:
              - identifiers:
                  email: sample@mail.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:
                    loyalty: Gold
                events:
                - event_name: purchase
                  timestamp: '2021-01-10T21:35:20Z'
                  event_params:
                    product_id: AGH210070
                    unit_price: 990.9
                    unit_sale_price: 890.9
                    event_group_id: ORDER123
                    taxonomy:
                    - Electronic
                    - Phone
                    currency: USD
                - 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'
      responses:
        '200':
          description: OK
          content:
            application/json:
              examples:
                default:
                  value:
                    data:
                      successful:
                        count: 1
                      fail: {}
                upsert-email-and-phone-number-attributes:
                  value:
                    data:
                      successful:
                        count: 1
                      fail: {}
                invalid-event-name:
                  value:
                    data:
                      successful: {}
                      fail:
                        count: 1
                        errors:
                          users.0.events.0.event_name.*.regexp(^[a-z0-9][a-zA-Z0-9._-]*$):
                          - 'invalid event name: homepageView'
              example:
                data:
                  successful:
                    count: 2
                  fail: {}
        '429':
          $ref: '#/components/responses/TooManyRequests'
    servers:
    - url: https://unification.useinsider.com
components:
  responses:
    TooManyRequests:
      description: Too Many Requests. The published per-endpoint rate limit was exceeded; back off and retry, honouring Retry-After when present.
      content:
        application/json:
          example:
            message: Too Many Requests
            status: 429
  securitySchemes:
    PartnerName:
      type: apiKey
      in: header
      name: X-PARTNER-NAME
      description: Insider One partner (account) name, lowercase.
    RequestToken:
      type: apiKey
      in: header
      name: X-REQUEST-TOKEN
      description: Insider One API key (request token) generated in the InOne panel.
externalDocs:
  description: Insider One API reference
  url: https://academy.insiderone.com/docs/api-reference-welcome
x-refined-from:
- insider-contact-openapi.yml
- insider-unification-openapi.yml
x-provenance:
  generated: '2026-08-13'
  method: derived
  source: postman/insider-one-apis.postman_collection.json
  source_url: https://documenter.gw.postman.com/api/collections/24851117/2sB3dSR9bM
  publisher_page: https://developers.insiderone.com/
  note: Insider One publishes a single public Postman collection covering every REST API. This document is the subset of that collection served from analytics.api.useinsider.com.