​
Overview

This guide explains how to integrate Hardal Analytics with Insider’s API using Hardal’s Custom API connections. By setting up this integration, you can automatically send user events, attributes, and other analytics data collected through Hardal directly to Insider’s Unified Customer Database (UCD).

This integration uses Insider’s Upsert User Data API, which allows you to send both user attributes and events from Hardal, enabling seamless data synchronization between platforms.

​
Prerequisites

Before setting up the integration, ensure you have:

  • A Hardal account with tracking implemented on your website or application

  • Access to Hardal’s Marketing Destinations section

  • An Insider account with API access

  • API credentials from Insider:

    • Partner Name (visible on the dropdown menu next to your username)

    • Request Token (API key) from Insider’s Integration Settings

​
Setting Up a Custom API Connection in Hardal

1

Access Marketing Destinations

  1. Log into your Hardal dashboard

  2. Navigate to “Connections”

  3. Click “Add Destination”

2

Select Custom API Template

  1. From the template options, select “Custom API”

  2. Click “Create” to begin configuring the connection

3

Configure Basic Connection Settings

Set up the following basic connection parameters:

SettingValue
Endpoint LabelInsider Integration
Endpoint IDinsider-integration
Endpoint URLhttps://unification.useinsider.com/api/user/v1/upsert
Request MethodPOST
Content Typeapplication/json
4

Add Authentication Headers

Configure the required headers for Insider API authentication:

{
  "headers": {
    "X-PARTNER-NAME": "your_partner_name",
    "X-REQUEST-TOKEN": "your_api_token"
  }
}

Make sure to use your actual Insider partner name (in lowercase) and API token. The partner name can be found in the dropdown next to your username on the Insider dashboard, and the API token can be generated in Integration Settings.

5

Configure Request Format

Set up the request format to properly map Hardal data to Insider’s expected format:

{
  "users": [
    {
      "identifiers": {
        "email": "##user.email##",
        "uuid": "##user_id##",
        "custom": {
          "hardal_id": "##user_id##"
        }
      },
      "attributes": {
        "email_optin": ##user.email_optin##,
        "name": "##user.name##",
        "surname": "##user.surname##",
        "gender": "##user.gender##",
        "country": "##user.country##",
        "city": "##user.city##",
        "language": "##user.language##",
        "custom": {
          "source": "hardal_analytics"
        }
      },
      "events": [
        {
          "event_name": "##event_name##",
          "timestamp": "##created_at##",
          "event_params": ##properties##
        }
      ]
    }
  ]
}

The above format uses Hardal variables (enclosed in ##) that will be automatically populated with data from your events. You can customize this mapping based on your specific data structure.

6

Set Up Event Conditions (Optional)

You can set up conditions to control which events are sent to Insider:

  1. Click on “Add Condition”

  2. Select the condition type (e.g., “Event Name”)

  3. Choose the operator (e.g., “equals”, “contains”)

  4. Enter the value (e.g., “purchase” to only send purchase events)

You can create multiple connections with different conditions to send different types of events with customized formats.

7

Test the Connection

  1. Click the “Test Endpoint” button to validate your configuration

  2. Check the response to ensure it’s successful

  3. If you receive any errors, adjust your configuration and test again

8

Save and Activate

  1. Once testing is successful, click “Save” to create the connection

  2. Toggle the connection to “Active” to start sending data

​
Special Event Configuration for Insider

Insider’s API requires specific formatting for different event types. Below are examples for common events:

​
Purchase Event

For purchase events, you need to include additional parameters like event_group_id and unit_sale_price:

{
  "users": [
    {
      "identifiers": {
        "email": "##user.email##",
        "uuid": "##user_id##"
      },
      "events": [
        {
          "event_name": "purchase",
          "timestamp": "##created_at##",
          "event_params": {
            "product_id": "##properties.product_id##",
            "name": "##properties.product_name##",
            "unit_price": ##properties.price##,
            "unit_sale_price": ##properties.sale_price##,
            "event_group_id": "##properties.order_id##",
            "taxonomy": ##properties.categories##,
            "currency": "##properties.currency##",
            "quantity": ##properties.quantity##
          }
        }
      ]
    }
  ]
}

​
User Registration Event

For user registration events:

{
  "users": [
    {
      "identifiers": {
        "email": "##user.email##",
        "uuid": "##user_id##"
      },
      "attributes": {
        "email_optin": true,
        "name": "##user.name##",
        "surname": "##user.surname##"
      },
      "events": [
        {
          "event_name": "account_created",
          "timestamp": "##created_at##",
          "event_params": {
            "custom": {
              "registration_source": "##properties.source##",
              "registration_method": "##properties.method##"
            }
          }
        }
      ]
    }
  ]
}

​
Handling Common Insider API Requirements

​
Required Parameters for Purchase Events

When sending purchase events to Insider, ensure these parameters are included:

  • event_group_id: Required for purchase events (typically an order ID)

  • unit_sale_price: Required for purchase events (the price after discounts)

  • currency: Required for purchase events (in ISO 4217 format, e.g., “USD”)

​
Formatting Timestamps

Insider requires timestamps in RFC 3339 format. Hardal’s ##created_at## variable outputs in this format, but if you’re manipulating dates, ensure they follow this pattern: YYYY-MM-DDThh:mm:ssZ or with timezone offset YYYY-MM-DDThh:mm:ss±hh:mm.

​
Handling Array Attributes

By default, when sending array attributes for a user, Insider adds new values to existing ones. If you want to replace array attributes instead of appending, add "not_append": true to your request:

{
  "users": [
    {
      "identifiers": { ... },
      "attributes": { ... },
      "not_append": true,
      "events": [ ... ]
    }
  ]
}

​
Troubleshooting

​
Example: Complete Custom Connection Configuration

Here’s a complete example of a Custom API configuration for sending both user attributes and purchase events to Insider:

​
Headers Configuration

{
  "headers": {
    "X-PARTNER-NAME": "mybrand",
    "X-REQUEST-TOKEN": "1a2b3c4e5d6f",
    "Content-Type": "application/json"
  }
}

​
Request Body Configuration

{
  "skip_hook": false,
  "users": [
    {
      "identifiers": {
        "email": "##user.email##",
        "uuid": "##user_id##",
        "custom": {
          "user_loyalty_id": "##user.loyalty_id##"
        }
      },
      "attributes": {
        "email_optin": "##user.email_optin##",
        "age": "##user.age##",
        "language": "##user.language##",
        "birthday": "##user.birthday##",
        "custom": {
          "source": "hardal_analytics",
          "favorite_color": "##user.favorite_color##"
        }
      },
      "events": [
        {
          "event_name": "##event_name##",
          "timestamp": "##created_at##",
          "event_params": {
            "product_id": "##properties.product_id##",
            "name": "##properties.product_name##",
            "unit_price": "##properties.price##",
            "unit_sale_price": "##properties.sale_price##",
            "event_group_id": "##properties.order_id##",
            "taxonomy": ["##properties.category##"],
            "currency": "##properties.currency##",
            "quantity": "##properties.quantity##",
            "custom": {
              "source_page": "##page.url##",
              "device_type": "##device_type##"
            }
          }
        }
      ]
    }
  ]
}

When working with the Hardal Custom API, the variable placeholders (like ##user.email##) will be automatically replaced with the actual values when an event is processed. Make sure all variable references match the exact names of your Hardal attributes and properties.

​
Best Practices

  1. Start with critical events: Begin by sending high-value events like purchases and registrations before expanding to other event types.

  2. Monitor data quality: Regularly check both Hardal and Insider dashboards to ensure data is flowing correctly.

  3. Use skip_hook for historical data: When sending historical data, set skip_hook: true to prevent triggering current journeys.

  4. Batch users efficiently: Each request can include up to 1,000 users, but keep request size under 5MB.

  5. Handle errors properly: Implement proper error logging and retry mechanisms for failed requests.

  6. Test thoroughly: Always test your connection with various event types before fully deploying.

  7. Maintain data consistency: Ensure identifiers and event parameters are consistent across platforms.