Recipient Identity & Properties Implementation Guide

This guide shows how to implement user tracking in zenSurveys by adding identity parameters and custom properties to your survey.

Use these features to associate responses with specific users and attach metadata for segmentation.

Definitions

Identities: Unique identifier for the respondent (string, max 255 chars). Valid types:
- email: Email address (required format: customer@domain.com)
- custom: Any string identifier (e.g., user_id, order_number)
Properties: Metadata key-value pairs attached to responses. Format: string keys, array of values (max 50 values per key)
Recipient: The survey respondent whose identity and properties you're tracking

1. URL Parameters Implementation for Link & Email Embed Surveys

Start with the base URL:

https://zenresponses.zenloop.com/?orgId=7038&surveyId=859

Add recipient identification (required format):

https://zenresponses.zenloop.com/?<encoded>&identity[value]=your_identifier&identity[type]=email_or_custom

Optional recipient details:

&first_name=john&last_name=brown

Required Parameters

identity[value]: Respondent identifier (e.g., email address or custom ID)
identity[type]: Must be email or custom

Optional Parameters

identity[first_name]: First name (max 100 characters)
identity[last_name]: Last name (max 100 characters)

Adding Properties

Attach metadata using this syntax:

&properties[Key]=Value

Example with typical business properties:

&properties[account_tier]=premium&properties[region]=EMEA

Example with multiple values per property:

&properties[purchased_products][]=laptop&properties[purchased_products][]=monitor

Complete Example

Production-ready implementation example:

https://zenresponses.zenloop.com/?eyJvcmdJZCI6IjQxNDUiLCJzdXJ2ZXlJZCI6IjkyNiJ9=&identity[value]=john.brown@zenloop.com&identity[type]=email&identity[first_name]=John&identity[last_name]=Brown&properties[account_tier]=enterprise&properties[feature_usage][]=api&properties[feature_usage]=analytics

2. Website Embed & Overlay Implementation

For dynamic website integration, implement this script before the loader:

<script>
  window.Zenloop_Survey_Recipient = {
    identity: 'user123@company.com',
    identity_type: 'email',
    first_name: 'John',
    last_name: 'Doe',
    properties: {
      account_tier: ['enterprise'],
      active_features: ['api', 'analytics'],
      subscription_months: [12]
    }
  };

</script>
<script id="zl-website-overlay-loader" async src="https://website-overlay.zenloop.com/loader/zenloop.load.min.js?survey={survey-id}"></script>

FAQ

Q: What happens if validation fails?

A: The survey will still load, but identity/properties won't be attached. Check browser console for errors.

Q: How do I debug implementation issues?

A: Use browser dev tools to inspect URL parameters or JavaScript objects. Verify all required fields are properly formatted.

Q: How do I test the implementation?

A: Use a test survey first with sample data, then check the response in your dashboard.

Support Centre