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

# Entities

> Manage companies and organizations in your CRM

## Overview

Entities represent the companies and organizations you work with in the music industry. This includes labels, publishers, distributors, and more. Entities are automatically extracted from contracts and can be linked to artists, writers, and relations.

## Entity Information

### Core Fields

| Field                 | Description                                  |
| --------------------- | -------------------------------------------- |
| **Name**              | Entity name                                  |
| **Email**             | Contact email address                        |
| **Phone**             | Phone number                                 |
| **Address**           | Business address                             |
| **Reminders Enabled** | Whether to receive reminders for this entity |

### Identifiers

Entities support flexible identifiers as name/value pairs. Common examples:

| Example Name       | Description                 |
| ------------------ | --------------------------- |
| **VAT**            | VAT registration number     |
| **IBAN**           | Bank account number         |
| **Company Number** | Company registration number |
| **Tax ID**         | Tax identification number   |

You can add any identifier type relevant to your business.

### Associated Data

| Field          | Description                                      |
| -------------- | ------------------------------------------------ |
| **Artists**    | Artists associated with this entity              |
| **Writers**    | Writers associated with this entity              |
| **Relations**  | Contact persons at this entity                   |
| **Contracts**  | Contracts where this entity is a party           |
| **Statements** | Royalty statements from or involving this entity |

## Viewing Entities

### List View

The entities list shows:

* Entity name
* Associated artists
* Associated writers
* Associated relations
* Linked status (if integrations are configured)
* Merge badge showing consolidated records

### Views

Switch between two views using the dropdown:

| View                 | Description                                 |
| -------------------- | ------------------------------------------- |
| **View by Entities** | Lists all entities with their associations  |
| **View by Artists**  | Groups entities by their associated artists |

### Sorting

Click the **Sort** button to toggle between ascending and descending order by name.

## Entity Detail View

Click **View** on any entity to see full details:

### Tabs

<Tabs>
  <Tab title="Details">
    A single scrollable page that brings together the entity's core information and all of its associated data. See [Details sections](#details-sections) below.
  </Tab>

  <Tab title="Timeline">
    AI-generated chronological view of all agreements involving this entity. See [Agreement Timeline](/projects/crm/agreement-timeline) for details.
  </Tab>

  <Tab title="Balances">
    AI-generated balance overview derived from this entity's contracts. Each balance item shows a title, the contracts it was extracted from, and the AI's reasoning. A Consolidation Summary at the top explains how balances across multiple contracts were grouped together.
  </Tab>
</Tabs>

### Details sections

The **Details** tab is a single page that brings together the entity's core information and its associated data. A sidebar on the left lists each section — click an entry to jump to it, and the sidebar highlights the section you're currently viewing as you scroll. On smaller screens the sidebar is replaced by a dropdown selector.

| Section        | Description                                                               |
| -------------- | ------------------------------------------------------------------------- |
| **Entity**     | Core entity information including name, contact details, and identifiers. |
| **Contracts**  | All contracts where this entity is a party.                               |
| **Statements** | Royalty statements from or involving this entity.                         |
| **Artists**    | Artists associated with this entity.                                      |
| **Writers**    | Writers associated with this entity.                                      |
| **Relations**  | Contact persons and representatives at this entity.                       |

#### Pinning sections

Use the pin icon next to any section in the sidebar to move that section to the top of the page, so the data you care about most appears first. Pin as many sections as you like — pinned sections are reordered to the top, and the page jumps to the section you just pinned. Click the pin again to unpin.

<Tip>
  Your pinned sections are remembered between visits, so the layout you set up stays in place the next time you open an entity.
</Tip>

## Adding Entities

### From Contract Extraction

Entities are automatically added when contracts are uploaded:

1. Upload a contract to Smart Drive
2. AI extracts party information
3. Entities are matched to existing records or created new
4. Review and verify details

<Note>
  Entities are primarily extracted from contracts. All entity data flows from your contract processing.
</Note>

## Editing Entities

<Steps>
  <Step title="Open Entity">
    Navigate to the entity detail view.
  </Step>

  <Step title="Click Edit">
    Click **Actions** → **Edit** in the banner.
  </Step>

  <Step title="Make Changes">
    Update entity information including:

    * Name
    * Address
    * Email
    * Phone
    * Reminders Enabled
    * Identifiers (add, edit, or remove)
  </Step>

  <Step title="Save">
    Click **Save** to apply changes.
  </Step>
</Steps>

## Managing Identifiers

Identifiers are flexible name/value pairs for tracking business identifiers:

<Steps>
  <Step title="Open Entity Edit">
    Navigate to the entity and click **Actions** → **Edit**.
  </Step>

  <Step title="Add Identifier">
    Click **Add** next to Identifiers.
  </Step>

  <Step title="Enter Details">
    Enter a name (e.g., "VAT", "IBAN") and the corresponding value.
  </Step>

  <Step title="Save">
    Click **Save** to store the identifier.
  </Step>
</Steps>

## Smart Linking & Deduplication

### Automatic Matching

When contracts are processed, entities are automatically matched using:

1. **Exact Name Match** - Direct name comparison
2. **Embedding Match** - Semantic similarity using AI embeddings
3. **AI Semantic Matching** - Fuzzy matching for name variations (e.g., "Sony Music" vs "Sony Music Entertainment Inc.")

### AI-Powered Deduplication

When a potential duplicate is detected, the AI evaluates:

* Name similarity and legal variations (Ltd, Inc, GmbH, etc.)
* Address and contact information overlap

The system automatically merges duplicates when confident, preserving all data from both records.

### Viewing Merge Reasoning

When entities are automatically merged, you can view the AI's reasoning:

<Steps>
  <Step title="Open Parent Entity">
    Navigate to the primary entity record.
  </Step>

  <Step title="View Merged Records">
    On the Details tab, scroll down to see merged records (entities that were consolidated into this one).
  </Step>

  <Step title="View Reasoning">
    Hover over the lightbulb icon next to any merged entity to see why the AI determined they were the same company.
  </Step>
</Steps>

<Note>
  When clicking on a merged entity from anywhere in the platform, you'll be automatically redirected to the parent (primary) entity record.
</Note>

### Unmerging Entities

If entities were incorrectly merged:

<Steps>
  <Step title="Open Parent Entity">
    Navigate to the primary entity record.
  </Step>

  <Step title="View Merged Records">
    On the Details tab, find the merged records (entities consolidated into this one).
  </Step>

  <Step title="Click Unmerge">
    Click **Unmerge** next to the incorrectly merged record.
  </Step>

  <Step title="Confirm">
    The entity becomes independent again and appears in the main entities list.
  </Step>
</Steps>

## Agreement Timeline

The **Timeline** tab shows an AI-generated chronological view of all agreements involving this entity. For a full description of what the timeline shows and how it works, see [Agreement Timeline](/projects/crm/agreement-timeline). That page also explains how the Agreement Timeline differs from [IP Groups](/projects/contracts/ip-groups).

## Entity Balances

The **Balances** tab shows an AI-generated financial balance overview for the entity, derived from its contracts.

### What is shown

| Element                   | Description                                                                                                    |
| ------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Consolidation Summary** | An expandable card at the top that explains how balances from multiple contracts were grouped and consolidated |
| **Balance items**         | Individual balance entries, each with a title, linked contracts, and AI reasoning                              |
| **Linked contracts**      | Clickable badges showing which contracts each balance was extracted from — click to open the contract          |
| **Reasoning**             | Expand the reasoning section on each balance item to see how the AI arrived at that balance                    |

<Note>
  Balances are automatically generated by AI from your contracts. They are not available for the project entity — only for companies and organizations you work with.
</Note>

## Bulk Actions

Enable edit mode by clicking the bolt icon to perform bulk operations:

1. Click the bolt icon to enter edit mode
2. Select entities using the checkboxes
3. Perform bulk actions on selected entities

## Integrations

### Managing Integrations

Administrators can link entities to external systems:

<Steps>
  <Step title="Open Actions Menu">
    Click the three-dot menu next to the bolt icon.
  </Step>

  <Step title="Select Manage Integrations">
    Click **Manage integrations**.
  </Step>

  <Step title="Link Entities">
    Connect entities to external payee records.
  </Step>
</Steps>

<Note>
  Integration management is only available to administrators.
</Note>

## Deleting Entities

<Steps>
  <Step title="Open Entity">
    Navigate to the entity you want to delete.
  </Step>

  <Step title="Click Actions">
    Click **Actions** in the banner.
  </Step>

  <Step title="Select Delete">
    Click **Delete** and confirm the action.
  </Step>
</Steps>

<Warning>
  Deleting an entity is permanent and cannot be undone.
</Warning>

## Best Practices

<AccordionGroup>
  <Accordion title="Add identifiers">
    Include VAT numbers, IBANs, and other business identifiers for better record keeping.
  </Accordion>

  <Accordion title="Review merged records">
    On the entity Details tab, verify AI-merged records are correct.
  </Accordion>

  <Accordion title="Keep contact info updated">
    Maintain current email, phone, and address for smooth communication.
  </Accordion>

  <Accordion title="Enable reminders">
    Turn on reminders for entities with important contractual obligations.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Artists" icon="user-music" href="/projects/crm/artists">
    Learn about managing artists and performers.
  </Card>

  <Card title="Writers" icon="pen" href="/projects/crm/writers">
    Learn about managing songwriters and composers.
  </Card>
</CardGroup>