Send object metadata

Business object analytics (beta) lets you add metadata to the objects you track in Pendo, such as orders, projects, or deals. Object metadata is descriptive information attached to an object, such as status or type, that you can use to filter and compare your object data. Only the current value of each field is stored, so object metadata doesn't track historical changes.

Create your object metadata fields before you send values for them, then send values with the Pendo Web SDK or the API.

Use cases

Use object metadata to:

• Group a funnel by an object metadata field to compare how subgroups move through it. For example, compare completion time by incident severity, or publish rate by guide type.
• Filter an object's analytics to a subset, such as a particular type, status, or category, and compare it against the rest.
• Narrow a dashboard or report to a single object value, such as one course or product line, instead of building a separate view for each one.
• Compare an individual object value against the aggregate to understand why it's an outlier.

Object metadata is available in object analytics and funnels. Retention doesn't support object analytics, so object metadata isn't available in retention.

Before you begin

• The object you want to add metadata to must already be set up in Pendo. For more information, see Analyze business objects.
• Create your object metadata fields before you send values for them. The bulk API rejects values for a field that doesn't exist, and Web SDK values for a missing field aren't reliably stored.
• You must be a subscription admin to create and manage object metadata fields.

Create object metadata fields

Creating a field defines its name and type. The field name is the key you use when you send metadata. Create the field before you send values for it.

1. Go to Settings > Metadata > Object metadata.
2. Select New object metadata.
3. Choose the object, enter a display name and field name, and select a type.

To find the field name for an existing object, open the object's details page and look under the Overview tab in the Details section. You can also find it in Settings > Event properties, in the Field name column.

How it works

The metadata field names and value types you send must match the object metadata fields configured in Pendo. What happens when a value doesn't match a configured field depends on how you send it:

• API. The request fails with a 400 error that names the problem.
• Web SDK. The call doesn't return an error, and the mismatched value isn't reliably stored.

Because the Web SDK doesn't report these errors, confirm your field names and value types in Settings > Metadata > Object metadata before you send. After you create the field or correct the value, send the metadata again. Text values are limited to 5,000 characters.

Send object metadata with the Pendo Web SDK

Use window.pendo.objectMetadata() to associate metadata with a specific object, similar to how you send a Track Event.

window.pendo.objectMetadata(objectId, objectProperty, metadata);

• objectId. The identifier of the specific object, for example order-123.
• objectProperty. The field name of the event property configured as the object, for example orderId.
• metadata. An object containing the configured metadata field names and values.

For example, if orderId is configured as an object with these object metadata fields:

• status. Text
• total. Number (float)
• expedited. Boolean

window.pendo.objectMetadata('order-123', 'orderId', {
    status: 'processing',
    total: 129.5,
    expedited: true,
});

Send object metadata with the API

In the endpoint path, the two event segments are the kind and group route parameters (both event for objects built on event properties), not a duplicated segment.

Send a single update

Send a POST request to update metadata for one object:

POST /api/v1/objectid/event/event/{objectFieldName}/metadata

curl -X POST \
  "https://app.pendo.io/api/v1/objectid/event/event/orderId/metadata" \
  -H "X-Pendo-Integration-Key: $PENDO_INTEGRATION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objectId": "order-123",
    "metadata": {
      "status": "processing",
      "total": 129.5,
      "expedited": true
    }
  }'

Send a bulk update

Send a POST request to update metadata for multiple objects at once:

curl -X POST \
  "https://app.pendo.io/api/v1/objectid/event/event/orderId/metadata/bulk" \
  -H "X-Pendo-Integration-Key: $PENDO_INTEGRATION_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "objectId": "order-123",
      "metadata": {"status": "processing", "expedited": true}
    },
    {
      "objectId": "order-456",
      "metadata": {"status": "delivered", "expedited": false}
    }
  ]'

There's no fixed limit on the number of objects per bulk request. For very large updates, split them into multiple requests.

Validation errors

If a bulk request fails validation, Pendo returns a 400 error naming the problem. In each message, N is the position of the failing item in your request, starting at 0:

• invalid metadata on element N: field not available for setting. The metadata field doesn't exist in Pendo.
• missing object id on element N. The object ID is absent.
• missing metadata on element N. The metadata object is absent.
• Invalid bulk metadata update body. The request body is malformed.
• invalid metadata on element N: string value is too big, limit string size to 5000 characters. A text value exceeds 5,000 characters.

If validation passes but the update fails while saving, the response contains only aggregate counts:

• Status 207: Incomplete update. X failures and Y successes
• Status 500: Incomplete update. X failures and 0 successes

Next steps

• Funnels: group or filter a funnel by object metadata to compare subgroups.
• Analyze business objects: set up an object and analyze its metrics.
• Event properties: how event properties are captured and used.