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 custom object of the dedicated object_event_params field. This is the only accepted location:

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

Send the parameter by its name without the c_ prefix, the same way you send custom event parameters in event_params.custom and Array of Objects attributes in object_attributes.custom. For example, a parameter registered as items is sent as object_event_params.custom.items.

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

Important: Array of Objects parameters sent at the top level of object_event_params (outside custom) are not stored. The request still returns a success response, and no error is shown. If your integration sends them at the top level, move them under custom.

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

curl --request POST \
  --url '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' \
  --location \
  --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": {
              "custom": {
                "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": {
  "custom": {
    "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": { "custom": { "items": { "product_id": "SKU-010" } } }
"object_event_params": { "custom": { "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 inside custom, for example, custom.items and custom.shipping_addresses together.

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

• Parameter names inside custom are given without the c_ prefix. A name such as custom.c_items is 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.