> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Maestro ABM as a data source

> Bring your Maestro ABM accounts, segments, contacts, dossiers, plays and touchpoints to Nekt.

Maestro ABM is an account-based marketing (ABM) platform: sales and marketing teams organize the companies they target into accounts and segments, map the contacts of each one, prepare dossiers, and run plays made of touchpoints (emails, calls, gifts, events) while Maestro scores engagement and influence. This connector reads the **Maestro Data API** and brings your accounts, segments, contacts, dossiers, plays and touchpoints, including custom fields, tags and the indicators Maestro calculates.

> [!NOTE]
>
> The connector only reads data. It never creates, changes or deletes anything in Maestro.

## Configuring Maestro ABM as a Source

In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Maestro ABM option from the list of connectors.

Click **Next** and you'll be prompted to add your access.

### 1. Add account access

The connector signs in with a **Maestro Data API key**. Only an **ADMIN** user of your Maestro company can create one, and the full key is shown only once, right after it is created, so copy it at that moment. If you don't know where to create the key in your Maestro account, ask Maestro's support for a Data API key.

The following configuration is available:

* **API Key**: The Maestro Data API key of your company.

The key reads the data of the Maestro company it belongs to. Once you're done, click **Next**.

### 2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.

> Tip: The stream can be found more easily by typing its name.

Select the streams and click **Next**.

### 3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.

* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: **Accounts**, **Segments** and **Contacts** support **Incremental** sync: after the first sync, only records created or changed since the previous sync are read. **Dossiers**, **Plays** and **Touchpoints** are always synced as **Full table**, because their scores and indicators are recalculated by Maestro all the time.

Once you are done configuring, click **Next**.

### 4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters.

To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers.md), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).

Optionally, you can configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).

Once you are ready, click **Next** to finalize the setup.

### 5. Check your new source

You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

> [!WARNING]
>
> For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.

### What happens when access is missing

* If the API key is wrong or was revoked, the sync fails and no table is changed. Ask an ADMIN user to create a new key and update it in this source.
* If Maestro says your company's subscription or trial has ended, or that the company is deactivated, the sync fails and no table is changed.
* If Maestro refuses one table to the key, that table is skipped and not updated, the other tables keep syncing, and the sync log names the table.
* If a table synced as Full table that had rows comes back completely empty, that table's sync fails instead of emptying it, and the log says so. If you really removed all that data in Maestro, run a **Full sync** of the source to accept the empty table.

# Streams and Fields

## Available streams

The table below lists every stream, its **slug** (the exact identifier to pass when creating the source via API) and a short description.

| Stream | Slug | Sync | Description |
| - | - | - | - |
| Accounts | `accounts` | Incremental | Organizations your company follows, with company data, address, tags, custom fields and their linked contacts and plays. |
| Segments | `segments` | Incremental | Accounts marked as segments, with the same fields as Accounts. |
| Contacts | `contacts` | Incremental | People linked to the accounts, with job title, email, phone, address, tags, custom fields, accounts and touchpoints. |
| Dossiers | `dossiers` | Full table | Sales-support material per account, contact or play, with its notes. |
| Plays | `plays` | Full table | Commercial action plans with goals, budget, dates, scores and indicators, accounts, opportunities, learnings and touchpoints. |
| Touchpoints | `touchpoints` | Full table | Actions run inside each play, with owners, channel, budget, scores, influence, accounts and contacts reached, learnings and notes. |

> [!NOTE]
>
> Archived and inactive records are included, with `is_active` false (and `archived` true on plays and touchpoints), so you can filter them in your queries. Nested information (custom fields, linked contacts, dossier details, play learnings, notes) comes as JSON text. Every table also has an `extra_fields` column with any field Maestro sends that has no column yet.

## Fields by stream

> [accordion] Accounts
>
> Organizations your company follows in Maestro (segments are in their own table). Archived accounts come with `is_active` false.
>
> Table: `accounts` · Primary key: `id` · Sync: Incremental (by `last_modified_at`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier of the account. |
> | `name` | String | Name of the organization. |
> | `ein` | String | Tax identifier of the organization (CNPJ or EIN). |
> | `description` | String | Free-text description of the account. |
> | `industry` | String | Industry of the organization. |
> | `employee_count` | String | Number of employees, as text (a value or a registered range). |
> | `revenue` | String | Revenue of the organization, as free text. |
> | `website` | String | Website of the organization. |
> | `address_zip_code` | String | ZIP or postal code of the address. |
> | `address_country` | String | Country of the address. |
> | `address_state` | String | State or province of the address. |
> | `address_city` | String | City of the address. |
> | `address_geolocation` | String | Geographic location registered for the address. |
> | `address_number` | String | Street number of the address. |
> | `address_complement` | String | Address complement (suite, floor, block, etc.). |
> | `social_media_linkedin` | String | LinkedIn profile of the organization. |
> | `social_media_instagram` | String | Instagram profile of the organization. |
> | `social_media_twitter` | String | Twitter/X profile of the organization. |
> | `tags` | Array of strings | Names of the tags applied to the account. |
> | `custom_fields` | String | Custom fields defined by the company and filled on the record: id, technical name, type, label and current value of each (JSON array). |
> | `contacts` | String | Contacts linked to the account: name and whether each one is active (JSON array). |
> | `plays` | String | Plays the account takes part in: name of each play (JSON array). |
> | `is_active` | Boolean | False when the account was archived or deactivated; true otherwise. |
> | `created_by_user_id` | String | Identifier of the user who created the account. Null when not recorded. |
> | `created_by_user_name` | String | Full name of the user who created the account. Null when the user is not found. |
> | `created_at` | Datetime | Date and time the record was created, in UTC. |
> | `updated_at` | Datetime | Date and time of the last change, in UTC. Null when the record was never changed. |
> | `last_modified_at` | Datetime | Time of the last change of the record in UTC: updated\_at, or created\_at when the record was never changed. Used as the incremental replication key. |
> | `extra_fields` | String | Fields returned by Maestro that this connector does not map to a column yet (or values that did not fit their column), keyed by their original names (JSON object). |

> [accordion] Segments
>
> Accounts marked as segments in Maestro, with the same fields as Accounts.
>
> Table: `segments` · Primary key: `id` · Sync: Incremental (by `last_modified_at`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier of the segment. |
> | `name` | String | Name of the organization. |
> | `ein` | String | Tax identifier of the organization (CNPJ or EIN). |
> | `description` | String | Free-text description of the segment. |
> | `industry` | String | Industry of the organization. |
> | `employee_count` | String | Number of employees, as text (a value or a registered range). |
> | `revenue` | String | Revenue of the organization, as free text. |
> | `website` | String | Website of the organization. |
> | `address_zip_code` | String | ZIP or postal code of the address. |
> | `address_country` | String | Country of the address. |
> | `address_state` | String | State or province of the address. |
> | `address_city` | String | City of the address. |
> | `address_geolocation` | String | Geographic location registered for the address. |
> | `address_number` | String | Street number of the address. |
> | `address_complement` | String | Address complement (suite, floor, block, etc.). |
> | `social_media_linkedin` | String | LinkedIn profile of the organization. |
> | `social_media_instagram` | String | Instagram profile of the organization. |
> | `social_media_twitter` | String | Twitter/X profile of the organization. |
> | `tags` | Array of strings | Names of the tags applied to the segment. |
> | `custom_fields` | String | Custom fields defined by the company and filled on the record: id, technical name, type, label and current value of each (JSON array). |
> | `contacts` | String | Contacts linked to the segment: name and whether each one is active (JSON array). |
> | `plays` | String | Plays the segment takes part in: name of each play (JSON array). |
> | `is_active` | Boolean | False when the segment was archived or deactivated; true otherwise. |
> | `created_by_user_id` | String | Identifier of the user who created the segment. Null when not recorded. |
> | `created_by_user_name` | String | Full name of the user who created the segment. Null when the user is not found. |
> | `created_at` | Datetime | Date and time the record was created, in UTC. |
> | `updated_at` | Datetime | Date and time of the last change, in UTC. Null when the record was never changed. |
> | `last_modified_at` | Datetime | Time of the last change of the record in UTC: updated\_at, or created\_at when the record was never changed. Used as the incremental replication key. |
> | `extra_fields` | String | Fields returned by Maestro that this connector does not map to a column yet (or values that did not fit their column), keyed by their original names (JSON object). |

> [accordion] Contacts
>
> People linked to one or more accounts. Inactive contacts come with `is_active` false.
>
> Table: `contacts` · Primary key: `id` · Sync: Incremental (by `last_modified_at`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier of the contact. |
> | `name` | String | Name of the contact. |
> | `description` | String | Free-text description of the contact. |
> | `role` | String | Job title of the contact in the organization. |
> | `industry` | String | Industry of the contact. |
> | `email` | String | Email address of the contact. |
> | `phone` | String | Phone number of the contact. |
> | `birth_date` | Datetime | Birth date of the contact. |
> | `social_media_linkedin` | String | LinkedIn profile of the contact. |
> | `social_media_instagram` | String | Instagram profile of the contact. |
> | `social_media_twitter` | String | Twitter/X profile of the contact. |
> | `social_media_website` | String | Personal or professional website of the contact. |
> | `address_zip_code` | String | ZIP or postal code of the address. |
> | `address_country` | String | Country of the address. |
> | `address_state` | String | State or province of the address. |
> | `address_city` | String | City of the address. |
> | `address_geolocation` | String | Geographic location registered for the address. |
> | `address_number` | String | Street number of the address. |
> | `address_complement` | String | Address complement (suite, floor, block, etc.). |
> | `tags` | Array of strings | Names of the tags applied to the contact. |
> | `custom_fields` | String | Custom fields defined by the company and filled on the record: id, technical name, type, label and current value of each (JSON array). |
> | `accounts` | String | Accounts the contact is linked to: name and whether each one is active (JSON array). |
> | `touchpoints` | String | Touchpoints the contact takes part in: name of each touchpoint (JSON array). |
> | `is_active` | Boolean | False when the contact was archived or deactivated; true otherwise. |
> | `created_by_user_id` | String | Identifier of the user who created the contact. Null when not recorded. |
> | `created_by_user_name` | String | Full name of the user who created the contact. Null when the user is not found. |
> | `created_at` | Datetime | Date and time the record was created, in UTC. |
> | `updated_at` | Datetime | Date and time of the last change, in UTC. Null when the record was never changed. |
> | `last_modified_at` | Datetime | Time of the last change of the record in UTC: updated\_at, or created\_at when the record was never changed. Used as the incremental replication key. |
> | `extra_fields` | String | Fields returned by Maestro that this connector does not map to a column yet (or values that did not fit their column), keyed by their original names (JSON object). |

> [accordion] Dossiers
>
> Sales-support material per account, contact or play, with its free notes. Read in full on every sync.
>
> Table: `dossiers` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier of the dossier. |
> | `name` | String | Name of the dossier. |
> | `type` | String | Type of the dossier, as defined in Maestro. |
> | `tags` | Array of strings | Names of the tags applied to the dossier. |
> | `linked_play_ids` | Array of strings | Identifiers of the plays linked to the dossier. |
> | `details` | String | Details of the dossier, one item per account, contact or play, with the content fields (product, opportunity, pains, reasons to act, competitors, sales history, questions and answers, etc.) (JSON array). |
> | `notes` | String | Free notes of the dossier, with text and creation and update dates (JSON array). |
> | `created_at` | Datetime | Date and time the record was created, in UTC. |
> | `updated_at` | Datetime | Date and time of the last change, in UTC. Null when the record was never changed. |
> | `extra_fields` | String | Fields returned by Maestro that this connector does not map to a column yet (or values that did not fit their column), keyed by their original names (JSON object). |

> [accordion] Plays
>
> Commercial action plans with goals, budget, dates and the indicators Maestro calculates. Read in full on every sync.
>
> Table: `plays` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier of the play. |
> | `name` | String | Name of the play. |
> | `description` | String | Free-text description of the play. |
> | `tags` | Array of strings | Names of the tags applied to the play. |
> | `owner_username` | String | Username of the person responsible for the play. |
> | `created_by_user_name` | String | First and last name of the user who created the play. Null when the user is not found. |
> | `type` | String | Type of the play, as defined in Maestro. |
> | `total_score` | Number | Total score accumulated by the play. |
> | `is_active` | Boolean | False when the play was deactivated; true otherwise. |
> | `goal` | String | Goal of the play, as text. |
> | `target` | Number | Numeric target of the play. |
> | `budget` | Number | Planned budget of the play. |
> | `start_date` | Datetime | Start date of the play. |
> | `end_date` | Datetime | Actual end date of the play. Null while it is in progress. |
> | `expected_end_date` | Datetime | Expected end date of the play. |
> | `total_score_average` | Number | Average of the total score, calculated by Maestro. |
> | `score_average` | Number | Average of the play's scores, calculated by Maestro. |
> | `interaction_average` | Number | Average number of interactions of the play, calculated by Maestro. |
> | `contacts_count` | Number | Number of contacts involved in the play. |
> | `decision_journey` | Number | Decision journey indicator of the customer, calculated by Maestro. |
> | `purchase_journey` | Number | Purchase journey indicator of the customer, calculated by Maestro. |
> | `meetings_count` | Number | Number of meetings held in the play. |
> | `bdr_perception` | Number | BDR perception of the play, as recorded by the team (scale defined by Maestro). |
> | `response_time` | Number | Response time of the customer, as calculated by Maestro. |
> | `pain_level` | Number | Pain level identified in the customer, as recorded in the play. |
> | `metrics` | Number | Value of the play's metrics, as calculated by Maestro. |
> | `metrics_percentage` | Number | Percentage of metrics used in the response calculation. |
> | `previous_play` | String | Reference to the previous play, when the play is part of a sequence. |
> | `next_play` | String | Next linked play, as stored by Maestro (free value; JSON when it is an object or a list). |
> | `interacted_contacts_count` | Number | Number of contacts that were interacted with. |
> | `interacted_key_decision_leaders_count` | Number | Number of key decision leaders (KDLs) that were interacted with. |
> | `avg_touchpoint_response_time` | Number | Average response time of the play's touchpoints. |
> | `archived` | Boolean | True when the play is archived. |
> | `accounts` | String | Accounts of the play, with the score of each (JSON array). |
> | `opportunities` | String | Opportunities linked to the play (JSON array). |
> | `learning` | String | Learnings recorded by the teams at the end of the play: sale outcome, win probability, failure cause, revenue and budget spent, decision makers' engagement (JSON array). |
> | `touchpoints` | String | Summary of the play's touchpoints: type, dates, owners, channel, budget, score and influence (JSON array). |
> | `created_at` | Datetime | Date and time the record was created, in UTC. |
> | `updated_at` | Datetime | Date and time of the last change, in UTC. Null when the record was never changed. |
> | `extra_fields` | String | Fields returned by Maestro that this connector does not map to a column yet (or values that did not fit their column), keyed by their original names (JSON object). |

> [accordion] Touchpoints
>
> Relationship actions run inside each play, with owners, contacts reached, interactions, scores and notes. Read in full on every sync.
>
> Table: `touchpoints` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier of the touchpoint. |
> | `name` | String | Name of the touchpoint. |
> | `play_name` | String | Name of the play the touchpoint belongs to. |
> | `owner_username` | String | Username of the person responsible for the touchpoint. |
> | `created_by_user_name` | String | First and last name of the user who created the touchpoint. Null when the user is not found. |
> | `tags` | Array of strings | Names of the tags applied to the touchpoint. |
> | `type` | String | Type of the touchpoint, as defined in Maestro. |
> | `channel` | String | Channel through which the touchpoint is executed, when informed. |
> | `description` | String | Free-text description of the touchpoint. |
> | `responsibles` | Array of strings | People responsible for executing the touchpoint. |
> | `is_active` | Boolean | False when the touchpoint was deactivated; true otherwise. |
> | `archived` | Boolean | True when the touchpoint is archived. |
> | `total_score` | Number | Total score of the touchpoint, calculated by Maestro. |
> | `sum_score` | Number | Sum of the scores recorded on the touchpoint. |
> | `weight` | Number | Weight of the touchpoint in the play's score calculation. |
> | `budget` | Number | Planned budget of the touchpoint. |
> | `influence_level` | Number | Influence level of the touchpoint, calculated by Maestro. |
> | `influence_category` | String | Influence category of the touchpoint, calculated by Maestro. |
> | `interactions_count` | Number | Total number of interactions recorded on the touchpoint. |
> | `interaction_percentage_average` | Number | Average interaction percentage across the touchpoint's accounts. |
> | `avg_response_time_days` | Number | Average response time of the touchpoint, in days. |
> | `start_date` | Datetime | Start date of the touchpoint. |
> | `end_date` | Datetime | End date of the touchpoint. |
> | `completed_at` | Datetime | Date the touchpoint was completed (task finished). Null when not completed yet. |
> | `accounts` | String | Accounts reached by the touchpoint, with score, interactions and the contacts of each (JSON array). |
> | `contacts` | String | Contacts involved in the touchpoint, with job title, buying role and interaction date (JSON array). |
> | `learning` | String | Learnings of the touchpoint: next step, engaged decision makers, contacts who replied and additional information (JSON array). |
> | `notes` | String | Free notes of the touchpoint, with text and creation and update dates (JSON array). |
> | `created_at` | Datetime | Date and time the record was created, in UTC. |
> | `updated_at` | Datetime | Date and time of the last change, in UTC. Null when the record was never changed. |
> | `extra_fields` | String | Fields returned by Maestro that this connector does not map to a column yet (or values that did not fit their column), keyed by their original names (JSON object). |

## Implementation Notes

* **Incremental tables use `last_modified_at`.** Maestro leaves `updated_at` empty on records that were never changed, so `last_modified_at` holds `updated_at`, or `created_at` when the record was never changed. Maestro does not document whether its "changed since" filter also returns records that were created and never changed, so the connector protects you in two ways: whenever the number of records in a table changes and the filter has not yet been seen returning such records, it reads the whole table in that sync; and every incremental table reads its whole list at least once every 7 days. In the rare case where a record is created while another one is removed between two syncs, the new record can take up to 7 days to appear.
* **Linked lists inside a record** (for example the contacts listed inside an account) are refreshed in the incremental tables only when that record itself changes. Schedule an occasional **Full sync** of the source if you rely on those lists.
* **Accounts turned into segments** (or back) appear in both the Accounts and the Segments tables, because Maestro does not report that a record left a list. A **Full sync** of the source removes the old copy.
* **Records deleted in Maestro** stay in the incremental tables (Accounts, Segments, Contacts), because Maestro does not report deletions. A **Full sync** removes them. The Full table tables drop them on the next sync.
* **Request limit.** Maestro limits the number of requests per minute for your whole company, shared with your other integrations. When the limit is reached the sync waits and continues; it only takes longer.
* **Not synced**: the API key list and the API usage reports of the Maestro Data API (they need a user login, not an API key).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.