# Matilda (Actions) Destination

## Destination Info

* Refer to it as **Matilda** in the [Integrations object.](/docs/segment/guides/filtering-data/#filtering-with-the-integrations-object)
* This integration is **partner owned.** Please reach out to the partner's support for any issues.
* This destination is **Beta.**

[Matilda](https://www.matilda.io) helps teams manage customer relationships, coordinate work, and automate workflows with AI-powered agents. With this destination, you can use your existing Segment events to create and update records in Matilda. For example, an Identify call can create or update a User and connect that user to a Person in Matilda.

Matilda owns this destination. For setup or support issues, [contact the Matilda support team.](mailto:support@matilda.io).

> \[!IMPORTANT]
>
> The Matilda (Actions) destination is in public beta. Some features may change before the destination is generally available.

## Getting started

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**.

## Destination Settings

| Field   | Description                                                                                                                                                                           | Required | Type   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------ |
| API Key | To find your API key inside Matilda, go to Settings in the bottom-left corner of the screen, then select Segment from the settings sidebar. Copy the API key and paste it above.
 | Yes      | string |

## Available Actions

Build your own Mappings. Combine supported [triggers](/docs/segment/connections/destinations/actions/#components-of-a-destination-action) with the following Matilda-supported actions:

> \[!NOTE]
>
> Individual destination instances have support a maximum of 50 mappings.



## Identify: Create or update users and people

Use [Identify calls](/docs/segment/connections/spec/identify) 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.

### Understanding users and people

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.

### Required fields

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.

### Additional attributes

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.

> \[!NOTE]
>
> You can use either one in this destination to identify customers.
>
> To find an attribute slug, open the relevant object settings page, open the **Attributes** tab, find the attribute, click the **︙** menu, and select **Copy slug**.

## Group: create or update workspaces and companies

Use [Group calls](/docs/segment/connections/spec/group) 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.

### Understanding workspaces and companies

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.

### Required and optional fields

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.

### Additional attributes

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.

> \[!NOTE]
>
> You can use either one in this destination to identify companies.
>
> To find an attribute slug, open the relevant object settings page, open the **Attributes** tab, find the attribute, click the **︙** menu, and select **Copy slug**.

## Track support

The destination accepts [Track calls](/docs/segment/connections/spec/track) 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.

## Data model summary

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.

## Engage

You can send computed traits and audiences generated using [Engage](/docs/segment/engage) to this destination as a **user property**. To learn more about Engage, schedule a [demo](https://segment.com/contact/demo).

For user-property destinations, an [identify](/docs/segment/connections/spec/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.

> \[!NOTE]
>
> Real-time audience syncs to Matilda (Actions)  may take six or more hours for the initial sync to complete. Upon completion, a sync frequency of two to three hours is expected.

## Settings

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

| Field   | Description                                                                                                                                                                           | Required | Type   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------ |
| API Key | To find your API key inside Matilda, go to Settings in the bottom-left corner of the screen, then select Segment from the settings sidebar. Copy the API key and paste it above.
 | Yes      | string |