Overview

Nested Objects allow you to group related information 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 to make 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.

Advantages

Using nested objects in CleverTap provides the following advantages:

• Model real-world entities without breaking them into multiple fields: Store structured data as it exists in your business system.

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

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

About Nested Objects

Use nested objects when storing related attributes that logically belong together.

Common examples include the following:

• User Properties
  • Profile information
  • Subscriptions
  • Insurance policies and more
• Custom Event Properties
  • Shopping cart content
  • Product line items
  • Transaction details and so on

Nesting Depth and Limits

CleverTap supports up to 3 levels of nesting. The root key is Level 0. Each nested object or array inside the root adds one level of depth.

User Properties

The following example shows nesting depth for a user property:

{
  "InsuranceDetails": {
    "Policy": [
      {
        "PolicyID": "POL123",
        "Beneficiary": [
          {
            "Name": "John Doe"
          }
        ]
      }
    ]
  }
}

The table below describes the nesting depth for each key in the example above:

Event Properties

The following example shows nesting depth for an event property:

{
  "Courses_In_Cart": [
    {
      "Id": 10,
      "Courses": [
        {
          "Name": "B.Tech CSE",
          "Sub_Courses": [
            {
              "Name": "Data Structures"
            }
          ]
        }
      ]
    }
  ]
}

The table below describes the nesting depth for each key in the example above:

📘

Note

At each level (1, 2, and 3), a maximum of 5 keys can be objects or arrays. The remaining keys must be primitive values such as strings, numbers, or booleans.

Best Practices

Follow these practices to maintain data quality:

• Use consistent schema definitions across integrations
• Send only valid objects
• Monitor payload size and array length
• Use clear attribute names
• Avoid frequent schema changes after implementation
• Avoid deeply nested structures

References

• To learn how to use nested objects within user properties, refer to Nested Objects in User Properties.
• To understand how to implement nested objects in custom event properties, refer to Nested Objects in Custom Event Properties.
• To view SDK-specific implementation details and platform limits for nested objects, refer to Ingesting Nested Objects using CleverTap SDKs.
• To learn how to send nested objects using the CleverTap API, refer to Ingesting Nested Objects using CleverTap APIs.

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.

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 the size limit or the maximum nesting limit.

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.