Overview

Nested Objects allow you to group related information together in a clean, structured way, instead of spreading it across many separate properties. This keeps your data organized, easier to manage, and simpler to understand.

With Nested Objects, you can send rich, structured user and event properties to CleverTap in JSON format. Instead of creating multiple flat properties for related information, you bundle them into a single logical structure.

This approach helps you do the following:

• Reduce the number of separate properties in your account
• Keep related data in one place, making it easier to maintain
• Build more scalable segmentation, especially when tracking repeating entities such as subscriptions, policies, cart items, or user preferences
• Enable more precise targeting and personalization based on structured data

The following example shows how nesting levels are structured inside a user profile payload. Each deeper level represents a field nested inside an object or array under profileData.

Examples

• Nested Objects for user properties: User profile information, such as subscriptions, insurance policies, preferences, and so on.
• Nested Objects for custom event properties: Shopping cart contents, product line items, transaction metadata, and more.

For more information on implementation, including JSON examples, refer to Ingesting Nested Objects via CleverTap APIs.

Advantages

When you use Nested Objects in CleverTap, you have the following advantages:

• Model real-world entities without breaking them into multiple fields: Store structured data as it exists in your business system. For example, you can store multiple policies under a single Policies property, instead of creating separate fields such as Policy_1_ID, Policy_2_ID, and so on.

• Target users more granularly: Create segments based on nested attributes.

• Reduce engineering effort: Send structured JSON payloads directly through CleverTap without flattening.

Use Cases

Businesses across industries use Nested Objects to personalize engagement:

Nested Objects for User Properties

• BFSI: Notify customers when key stakeholders, such as policy beneficiaries or account nominees, lack email addresses. For example, segment users whose Policies.Beneficiaries.Email field is empty.
• Media & Entertainment: Target users based on nested viewing preferences, such as preferred genres, languages, or favorite shows, stored directly in profile metadata. This enables a higher Click-Through Rate (CTR) on recommendations and reduces churn by improving personalization accuracy.

Nested Objects for Custom Event Properties

• Healthcare: Send medication reminders or follow-up test notifications based on nested appointment details. This helps reduce missed follow-ups and improves patient compliance.
• Travel & Hospitality: Trigger personalized follow-ups based on booking preferences such as room type, meal plan, or service requests. This improves guest experience and reduces booking cancellations by confirming preferences proactively.

Nested Objects for User Properties and Custom Event Properties

You can use Nested Objects in both user properties and custom event properties to store structured JSON without flattening fields.

• For user properties, Nested Objects help model complex profile-level attributes such as subscriptions, policies, preferences, beneficiaries, and so on.
• For custom event properties, Nested Objects allow you to send structured event-level payloads such as cart details, order line items, transaction metadata, policy updates, booking information, and more.

Nested Objects in custom event properties follow the same structure and validation rules as Nested Objects in user properties. Event properties follow the same schema enforcement rules to ensure consistent ingestion and prevent failures.

Examples

You can send Nested Objects through CleverTap ingestion APIs so that structured data becomes available for segmentation, personalization, and campaign targeting.

• Sending a user property with multiple insurance policies and nested beneficiaries
• Sending a user property with nested subscription tiers and device preferences
• Sending an event such as Claim Filed with nested claim details (claim amount, policy ID, document status)
• Sending an event such as Order Confirmation with nested cart details and line items
• Sending an event such as Content Watched with nested viewing metadata (genre, duration watched, language, completion status)

This unified support enables consistent modeling of structured data across both profile and event ingestion.

Use Nested Objects across Platforms

After ingestion, Nested Object fields are available across CleverTap, including user profiles, segmentation filters, and campaign personalization.

• Profile Page: View structured objects stored in a user’s profile. Each nested user property is shown as a dot-separated field under the User Properties tab on the profile. For example, Courses.EnrolledModules.Instructor.Name.

• Segmentation Builder: Create conditions using nested attributes, such as Policies.Beneficiaries.Email. You can combine multiple nested conditions to create granular filters. For example, you can segment users who have at least one policy with an overdue premium or a beneficiary missing contact information.

The following image shows how nested fields appear within profile data and can be used to create filters in the Segmentation Builder:

The following image shows how nested fields appear for event properties and can be used to create filters in the Segmentation Builder:

• Liquid Tags: Use Liquid Tags to personalize Campaign content using attributes stored inside Nested Objects in user properties and custom event properties. You can reference nested fields directly in Push Notifications, Emails, and In-App messages.

The following image shows the Liquid Tags for Nested Objects in user properties:

You can use dot notation in Liquid Tags to reference nested fields inside user properties. This allows you to dynamically personalize campaign content, such as addressing a user’s policy type or beneficiary name.

The following image shows the Liquid Tags for Nested Objects in custom event properties:

In the above example, {{ Event.courses_in_cart[0].courses[0].name | default: "courses in cart" }} is used. The message dynamically inserts the name of the first course from the first item inside the courses_in_cart array when the event triggers. If the value is unavailable, it falls back to the default text courses in cart.

This shows how you can access deeply nested event attributes, including arrays within arrays, to personalize real-time messages triggered by custom events.

📘

Dashboard Limitations with Nested User Properties in Segments

You may view this message in some areas of the Dashboard:

"Nested user property queries aren’t supported yet. Choose a segment without nested properties to proceed."

Nested user property segments are not yet supported in areas such as Predictions and Bulletins. To continue, use or create a segment with only standard (non-nested) user properties in such areas of the product.

System Considerations

CleverTap enforces some system limits to maintain performance and stability. The following table lists the limits applied during nested object ingestion to ensure consistent data handling:

Best Practices

Follow these practices to maintain data quality:

• Use consistent schema definitions across integrations.
• Send only valid objects; CleverTap drops null or empty objects automatically.
• Monitor object size and array length to stay within system limits.
• Use clear attribute names for easier targeting.
• Avoid changing nested key names frequently after implementation.

FAQs

Can I use Nested Objects in SDK, CSV, or SFTP uploads?

Nested Objects are supported through the REST API and SDK. Nested Objects are not supported through CSV or SFTP uploads. For more information, refer to Ingesting Nested Objects via CleverTap APIs.

Can I query deeply nested fields in segmentation?

Yes, you can query up to three levels in supported segmentation workflows.

What happens if I exceed the payload size or nesting limits?

CleverTap drops extra elements or returns an error if a payload exceeds size or maximum nesting limits.

Are Nested Objects included in exports?

No. Nested Objects are not included in API-based exports.

Does this feature affect performance?

Queries on Nested Objects may take longer when segmentation conditions include multiple nested filters or when nested arrays contain many elements. To maintain performance, avoid using large arrays in frequently queried fields and limit segmentation rules to essential nested attributes.