Define reusable entities

An entity is a reusable definition of a data object’s shape: its field names, types, and nested structure. Define the shape of a core object from a service you use, then build multiple templates around those same fields. This speeds up template creation and lets your integrations pass the service’s object through without rebuilding a field-by-field mapping for every template. For example, a Stripe Customer entity describes the structure of Stripe’s Customer object. You can reuse that definition for a customer-created notification and a customer-updated notification. Each template presents the object differently, while both accept the same shape.

Entity, sample data, and template

Part	Purpose	Stripe example
Entity	Defines the reusable object shape	Customer fields such as `id`, `name`, and `email`
Sample data	Supplies representative values for a preview	One synthetic Customer object
Template	Defines the message content and layout	A customer-created or customer-updated notification

Create one entity definition for the object type, not a new entity for each individual customer. The definition supports template authoring; it does not sync customer records or subscribe to service events.

Define a service object’s shape

Open Entities and select New Entity.
Choose Import from JSON and name the entity Stripe Customer. Include the service and object type in the name so other template authors know what it represents.
Paste a representative JSON object with synthetic values. Preserve the field names and nesting your integration will supply.
Create the entity, then open it to review the inferred fields. You can also use Manual Creation and define fields yourself.

This simplified example includes only a few fields from the Stripe Customer object; it is not a complete Stripe schema:

{
  "id": "cus_example",
  "object": "customer",
  "name": "Alex Morgan",
  "email": "alex@example.com",
  "metadata": { "account_reference": "ACCT-123" }
}

JSON import infers fields from the supplied example and initially marks them required. Review optional fields, null values, and array item types against the service’s actual payloads. One example cannot describe every possible variation. Keep the source field paths intact so templates can use the object as delivered.

Reuse the entity across templates

In the builder’s sample-data panel, open Entity Data, browse the entities, and select Stripe Customer. Selecting an entity generates starter sample values and replaces the template’s current sample data, so preserve any test cases you want to keep first. Use JSON Editor to replace generated values with representative synthetic data and select Apply Changes. Build a customer-created template using the entity’s field paths:

New customer: {{name}}
Email: {{email}}
Stripe ID: {{id}}

Select the same entity in a second template and change the message for an update notification:

Customer updated: {{name}}
Account: {{metadata.account_reference}}
Stripe ID: {{id}}

The field definition is reusable; the message layout and choice of fields belong to each template. You do not need to redefine the Customer shape for every event or display every field it contains.

Map the incoming object once

For Stripe’s customer.created and customer.updated snapshot events, the Customer object is in event.data.object. See Stripe’s event types. Configure your automation or backend to choose the appropriate template for the event type and pass that Customer object as the LithoBlocks request’s data value:

// Mapping inside your integration; event is the incoming Stripe event.
const templateData = event.data.object;
// Use templateData as the `data` value in your compile or send request.

Both templates then use paths such as {{name}} and {{metadata.account_reference}}. The integration selects the object from the event envelope once, preserving its fields instead of renaming them separately for each template. See Send with the API for the complete request format. If you instead pass the entire Stripe event as the request’s data, the Customer name is at {{data.object.name}}. Your entity definition and preview data must match that envelope too. LithoBlocks does not automatically unwrap an event when you select an entity. This approach applies to any service with recurring object shapes, such as an issue, order, or support ticket. Reuse an entity when events supply the same object structure; define a different entity when they supply a different object type.

Keep the shape aligned with the source

Preview each template with representative payloads, including missing and null fields. Use conditional blocks for optional content. Entity field definitions do not replace validation in your integration: missing text placeholders can remain unresolved even when compilation succeeds. When the source shape changes, review the entity, sample datasets, placeholder paths, and integration mapping together. Test a new template version before switching integrations, and review associated data and templates before deleting an entity. For API consumers, GET /v1/templates/{id}/input-schema describes the selected template’s derived input requirements. It is separate from the reusable service-object definition and is not a complete schema for that service. Sample data · Placeholders

Templates

Data and reuse

Build an example

Define reusable entities

Entity, sample data, and template

Define a service object’s shape

Reuse the entity across templates

Map the incoming object once

Keep the shape aligned with the source

​Entity, sample data, and template

​Define a service object’s shape

​Reuse the entity across templates

​Map the incoming object once

​Keep the shape aligned with the source

Entity, sample data, and template

Define a service object’s shape

Reuse the entity across templates

Map the incoming object once

Keep the shape aligned with the source