Send Event Data with an Array of Objects Parameter

After you define the parameter, you start sending events that carry the array.

Array of Objects data must be sent inside the dedicated object_event_params field. This is the only accepted location:

• POST /api/user/v1/upsert → users[].events[].object_event_params

Scalar parameters continue to be sent in event_params and can coexist with Array of Objects parameters in the same event.

Send an event with an Array of Objects parameter (Upsert API)

curl --location --request POST 'https://unification.useinsider.com/api/user/v1/upsert' \
--header 'X-PARTNER-NAME: PARTNER_NAME_GOES_HERE' \
--header 'X-REQUEST-TOKEN: TOKEN_GOES_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
  "users": [
    {
      "identifiers": {
        "email": "sample@useinsider.com",
        "uuid": "1x2y3z"
      },
      "events": [
        {
          "event_name": "purchase_completed",
          "timestamp": "2026-04-01T10:00:00Z",
          "event_params": {
            "transaction_id": "ORD-9001",
            "total_price": 3698,
            "currency": "TRY"
          },
          "object_event_params": {
            "items": [
              {
                "product_id": "SKU-010",
                "product_name": "Nike Air Max",
                "category": "Shoes",
                "unit_price": 2499,
                "quantity": 1,
                "is_discounted": true,
                "tags": ["sale", "new"]
              },
              {
                "product_id": "SKU-022",
                "product_name": "Levi 501 Jeans",
                "category": "Clothing",
                "unit_price": 1199,
                "quantity": 1,
                "is_discounted": false,
                "tags": ["new"]
              }
            ]
          }
        }
      ]
    }
  ]
}'

Response example:

{
    "data": {
        "successful": {
            "count": 1
        },
        "fail": {}
    }
}

Send an event with nested sub-object keys

If an object key is defined as Object, its sub-object keys are sent as a nested object inside each array item:

"object_event_params": {
  "items": [
    {
      "product_id": "SKU-010",
      "unit_price": 2499,
      "charges": {
        "shipping": 49,
        "tax": 449
      }
    }
  ]
}

Send a Single Object

If you send a single object instead of an array, the value is automatically wrapped into a one-element array. Both of the following are stored identically:

"object_event_params": { "items": { "product_id": "SKU-010" } }
"object_event_params": { "items": [ { "product_id": "SKU-010" } ] }

How values are handled

• Date values are normalized to UTC on ingestion. Send them in ISO 8601 format, for example "2026-04-01T14:30:00Z".

• String values are stored as sent, including case. Comparisons in segmentation are case-sensitive.

• Nested objects are flattened to parent.child keys, matching the schema defined in the panel.

• Multiple Array of Objects parameters can be sent on the same event, for example items and shipping_addresses together.

• Reserved internal field names cannot be used as object keys and are rejected.

Ingestion Behavior

Ingestion separates two classes of problems: structural violations fail the record, and schema mismatches are silently dropped.

• Structural violations: The record is rejected with an error

• Schema mismatches: Silently dropped; the event is still stored.

A parameter that is not registered in the panel is not stored. Register the parameter first, then send the event.

Error message examples

• Exceeding the maximum number of objects in one array

{
    "data": {
        "successful": {},
        "fail": {
            "count": 1,
            "errors": {
                "users.0.events.0.object_event_params.items": [
                    "exceeds max objects 50"
                ]
            }
        }
    }
}

• Exceeding the maximum number of keys inside one object

{
    "data": {
        "successful": {},
        "fail": {
            "count": 1,
            "errors": {
                "users.0.events.0.object_event_params.items": [
                    "object[0] exceeds max keys per object 20"
                ]
            }
        }
    }
}

Update and Delete

Array of Objects event parameters are insert-only.

• There is no add, merge, replace, or remove action for event parameters. Unlike Array of Objects attributes, the array cannot be patched after the event is written.

• Sending an Array of Objects parameter key through the event update endpoint is rejected with an error, so partially corrupting an existing event is not possible.

• To correct a value, send the event again with the correct payload following your regular event ingestion rules.