Matilda (Actions) Destination

1. In Segment, open Catalog and select Destinations.
2. Search for "Matilda (Actions)" and add it as a destination.
3. Select the Source that should send data to the Matilda (Actions) destination and enter a name for your destination.
4. Open the Matilda app, go to Settings, select Segment from the sidebar, and copy your Matilda API key.
5. Return to the Segment app, open the Matilda (Actions) destination configuration, and paste your Matilda API key into the API Key field.
6. Click Save.

Build your own Mappings. Combine supported triggers with the following Matilda-supported actions:

Use Identify calls to create or update a User record in Matilda.

When an Identify call includes an email address, Matilda:

1. Creates or updates the User using that email address.
2. Looks for an existing Person with the same email address.
3. Links the User to that Person if one exists.
4. Creates a new Person if Matilda doesn't find a matching Person.

By default, this mapping runs on Identify events.

In Matilda:

• A Person represents a real human.
• A User represents that person inside your product or SaaS application.

A single Person might be multiple Users.

For example, one Person might show up in different products, accounts, or workspaces as multiple Users, but they're just one human.

This mapping assumes your Identify call includes:

• Email address: Used to create or update the User and match or create the related Person.
• ID: Used as the external identifier for the User.

You can map extra fields from your Segment event to Matilda attributes. For example, you might send product-specific properties such as role, plan, status, or permissions as additional attributes on the User or Person.

On the Edit Mapping page, the values from your Segment event, or custom text, and the Matilda attribute slug or ID are displayed.

By default, the User object includes only a small set of attributes. Segment recommends that you create any custom User attributes you need in Matilda before sending Identify calls.

Use Group calls to create or update a workspace record in Matilda.

This mapping uses two keys:

• domain (required)
• groupId or workspaceId (optional secondary key)

When a Group call includes a domain, Matilda:

• Creates or updates the workspace or company record using domain as the primary unique key.
• If you include groupId or workspaceId, Matilda uses it as a secondary key for better matching.
• Links or update the related workspace or company record.

If you don't include a domain, Matilda ignores workspace or company updates or creation for that Group event.

By default, this mapping runs on Group events.

In Matilda:

• Company: represents a real company.
• Workspace: represents a workspace, tenant, account, or group inside your product.

A Company can have multiple Workspaces, but you can assosciate a Workspace with the Company that it belongs to.

This mapping assumes your Group call includes:

• A required domain, used to match or create the workspace or company record.
• An optional id (groupId or workspaceId) used as a secondary unique key.

You can also map extra event properties to Workspace or Company attributes. For example, you might send fields like billing plan, workspace size, lifecycle stage, region, or account owner as additional attributes.

By default, the Workspace object includes only a limited set of attributes. Segment recommends that you create your own custom Workspace attributes in Matilda before sending Group calls.

On the Edit Mapping page, values from your Segment event, or custom text, and the Matilda attribute slug or ID are displayed.

The destination accepts Track calls and can map attributes for downstream activity and enrichment flows. Use Identify and Group as the primary create or update flows for users, persons, workspaces, and company entities.

Matilda separates real-world entities from product-specific entities:

• People and Companies represent real people and real companies.
• Users and Workspaces represent those entities inside your product or connected SaaS apps.

Because of this model:

• You can link one Person can to many Users.
• You can link one Company to many Workspaces.
• Users and workspaces can carry product-specific attributes.
• People and companies can act as the shared real-world records behind them.

This structure makes it easier to unify customer data across products, workspaces, and accounts.

You can send computed traits and audiences generated using Engage to this destination as a user property. To learn more about Engage, schedule a demo.

For user-property destinations, an identify call is sent to the destination for each user being added and removed. The property name is the snake_cased version of the audience name, with a true/false value to indicate membership. For example, when a user first completes an order in the last 30 days, Engage sends an Identify call with the property order_completed_last_30days: true. When the user no longer satisfies this condition (for example, it's been more than 30 days since their last order), Engage sets that value to false.

When you first create an audience, Engage sends an Identify call for every user in that audience. Later audience syncs only send updates for users whose membership has changed since the last sync.

Segment lets you change these destination settings from the Segment app without having to touch any code.