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

# Suggestions

> Spotify-powered suggestions for unmatched statement assets

<Info>
  Accepting a suggestion creates a new item in your [Catalog](/projects/catalog/overview) and matches it to the statement asset.
</Info>

## What are Suggestions?

Suggestions are Spotify metadata recommendations for your unmatched statement assets. When statement recordings or compositions remain unmatched after the automatic matching process, Royaltyport searches Spotify's catalog using identifiers (ISRC or UPC) to find potential matches and enrich your data.

## When Suggestions are Created

Suggestions are automatically generated for statement assets that:

1. **Remain unmatched** after the matching flow completes
2. **Have valid identifiers** (ISRC or UPC) that aren't already in your catalog
3. **Aren't part of your contract-extracted catalog** yet

<Note>
  Your catalog is built from recordings and compositions extracted from your uploaded contracts. Suggestions help you identify assets in statements that aren't yet covered by your contracts.
</Note>

### The Suggestion Flow

<Steps>
  <Step title="Statement Processing">
    When a statement is uploaded, assets are extracted and the matching flow runs.
  </Step>

  <Step title="Identify Unmatched">
    Assets that don't match any catalog item (from contracts) are flagged as unmatched.
  </Step>

  <Step title="Extract Identifiers">
    ISRCs and UPCs are collected from unmatched assets.
  </Step>

  <Step title="Search Spotify">
    Spotify's API is queried using these identifiers to find matching tracks.
  </Step>

  <Step title="Store Suggestions">
    Spotify metadata is saved as suggestions linked to your statement assets.
  </Step>
</Steps>

## How Suggestions Work

### Search Methods

Suggestions are found using two search methods:

| Method          | Identifier | Priority  | Description                                                                            |
| --------------- | ---------- | --------- | -------------------------------------------------------------------------------------- |
| **ISRC Search** | ISRC       | Primary   | Searches Spotify by International Standard Recording Code. Most accurate method.       |
| **UPC Search**  | UPC        | Secondary | Searches Spotify by Universal Product Code (barcode). Used when ISRC is not available. |

## Recording Suggestions

For statement recordings, the system searches Spotify using:

### ISRC Lookup

When a recording has a valid ISRC:

1. Spotify is queried with `isrc:{ISRC_CODE}`
2. Returns the matching track with full metadata
3. Album information is also retrieved

### UPC Lookup (Fallback)

When no ISRC is available but UPC exists:

1. Spotify is queried with `upc:{UPC_CODE}`
2. Returns the matching album
3. Track information is extracted from the album

### Data Retrieved

| Field            | Description                     |
| ---------------- | ------------------------------- |
| **Track Name**   | Official Spotify track title    |
| **Artists**      | All credited artists            |
| **Album**        | Album name and artwork          |
| **Release Date** | Official release date           |
| **Duration**     | Track length                    |
| **Spotify ID**   | Unique Spotify track identifier |
| **ISRC**         | Verified ISRC from Spotify      |
| **Popularity**   | Spotify popularity score        |

## Composition Suggestions

For statement compositions, the system also searches Spotify by ISRC:

1. Uses the ISRC from the composition statement
2. Finds the recording on Spotify
3. Extracts writer and composition metadata where available

<Note>
  Spotify primarily contains recording metadata. For comprehensive composition data (writers, publishers, splits), additional sources may be needed.
</Note>

## Viewing Suggestions

### Accessing Suggestions

To view suggestions for your unmatched assets:

<Steps>
  <Step title="Go to Assets">
    Navigate to **Statements** → **Assets** (Recordings or Compositions).
  </Step>

  <Step title="Open Actions Menu">
    Click the **Actions** menu (three dots icon) in the top right.
  </Step>

  <Step title="View Suggestions">
    Select **View Suggestions**. A notification dot appears on the menu when suggestions are available.
  </Step>
</Steps>

### Suggestions Dialog

The suggestions dialog shows:

* **Spotify Track Info** - Name, artists, album artwork
* **Identifiers** - ISRC, Spotify ID
* **Match Confidence** - How the suggestion was found (ISRC vs UPC)
* **Actions** - Accept, reject, or create catalog item
* **Suggestion Count** - Total number of available suggestions

<Tip>
  Use the per-page selector at the bottom of the dialog to control how many suggestions are shown at once. Options include up to 50,000 rows — useful when you have a large backlog of unmatched assets to review in one session.
</Tip>

## Using Suggestions

### Accept Suggestion

When a suggestion is correct:

<Steps>
  <Step title="Review Suggestion">
    Verify the Spotify data matches your asset.
  </Step>

  <Step title="Click Accept">
    Accept the suggestion to use the metadata.
  </Step>

  <Step title="Create or Link">
    Create a new catalog item or link to existing.
  </Step>
</Steps>

### Reject Suggestion

When a suggestion is incorrect:

<Steps>
  <Step title="Click Reject">
    Mark the suggestion as incorrect.
  </Step>

  <Step title="Manual Match">
    Manually search for the correct catalog item.
  </Step>
</Steps>

### Create Catalog Item

Use suggestion data to create a new catalog item:

<Steps>
  <Step title="Click Create">
    Select "Create from Suggestion".
  </Step>

  <Step title="Review Data">
    Verify and edit the pre-filled metadata.
  </Step>

  <Step title="Save">
    New catalog item is created and linked.
  </Step>
</Steps>

<Note>
  After accepting suggestions and creating catalog items, the dialog may show a processing state while the system finalises the matches. Once complete, any statement assets with the same fingerprint will be automatically matched from now on — you won't need to manually handle those assets in future statements.
</Note>

## Triggering Suggestions

### Automatic Processing

Suggestions are automatically generated:

* After statement processing completes
* When new unmatched assets are detected
* During scheduled background sync

### Checking for New Suggestions

After processing new statements, check for suggestions:

<Steps>
  <Step title="Go to Assets">
    Navigate to **Statements** → **Assets**.
  </Step>

  <Step title="Check Notification">
    Look for the notification dot on the Actions menu indicating new suggestions.
  </Step>

  <Step title="View Suggestions">
    Open **Actions** → **View Suggestions** to review and process them.
  </Step>
</Steps>

## Why Assets Remain Unmatched

Assets typically remain unmatched when:

| Scenario                    | Explanation                                              |
| --------------------------- | -------------------------------------------------------- |
| **No matching contract**    | The asset isn't covered by any uploaded contract         |
| **Missing from extraction** | The contract mentions the asset but extraction missed it |
| **Different identifiers**   | Statement uses different ISRC/UPC than catalog           |
| **Title variations**        | Statement title doesn't match catalog naming             |

<Tip>
  Suggestions help you identify revenue from assets not yet in your contracts. Consider adding these assets to your catalog or investigating why they're appearing in statements.
</Tip>

## Limitations

### Spotify Coverage

| Scenario                  | Result                  |
| ------------------------- | ----------------------- |
| **Track on Spotify**      | Suggestion found        |
| **Track not on Spotify**  | No suggestion available |
| **Invalid ISRC/UPC**      | No suggestion available |
| **Regional restrictions** | May affect results      |

### Data Completeness

Spotify provides:

* ✓ Recording metadata (title, artists, album)
* ✓ ISRCs for recordings
* ✓ Album artwork and release dates
* ✗ Writer/publisher information (limited)
* ✗ Rights ownership data

## Best Practices

<AccordionGroup>
  <Accordion title="Ensure identifiers are present">
    Statements with ISRCs generate better suggestions. Work with distributors to ensure ISRCs are included.
  </Accordion>

  <Accordion title="Review before accepting">
    Always verify suggestions match your assets before accepting.
  </Accordion>

  <Accordion title="Use for catalog enrichment">
    Suggestions are great for adding artwork, Spotify IDs, and verified metadata to your catalog.
  </Accordion>

  <Accordion title="Investigate unmatched assets">
    Unmatched assets with suggestions may indicate revenue from assets not covered by your contracts.
  </Accordion>

  <Accordion title="Process in batches">
    Let the system process suggestions in batches for optimal performance.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="No suggestions found">
    * Verify the asset has a valid ISRC or UPC
    * Check if the track exists on Spotify
    * Some older or regional releases may not be on Spotify
  </Accordion>

  <Accordion title="Wrong suggestion">
    * ISRCs can sometimes be reused or incorrect in statements
    * Reject the suggestion and manually match
    * Report data quality issues to your distributor
  </Accordion>

  <Accordion title="Suggestions not appearing">
    * Processing may still be in progress
    * Check the processing status in Files
    * Manually trigger suggestion search if needed
  </Accordion>
</AccordionGroup>

## Related Features

<CardGroup cols={2}>
  <Card title="Assets Overview" icon="list" href="/projects/statements/assets/overview">
    View all statement assets.
  </Card>

  <Card title="Asset Matching" icon="link" href="/projects/statements/assets/matching">
    Manual and rule-based matching.
  </Card>
</CardGroup>