# Music Catalog Reconciliation (`sabya-services/music-catalog-reconciliation`) Actor

Compare your recording catalog with registration exports, review missing or conflicting song links, and download the corrections you approve.

- **URL**: https://apify.com/sabya-services/music-catalog-reconciliation.md
- **Developed by:** [Sabya Das](https://apify.com/sabya-services) (community)
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$50.00 / 1,000 recordings

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Music Catalog Reconciliation

Find missing or conflicting song links before updating your recording catalog. Compare your catalog with registration exports you supply, review the evidence, and download the ISRC–MLC Song Code pairs you approve.

Use it when a catalog has blank song codes, two exports disagree, or you need a review list before making corrections. You can compare up to three registration exports in one run.

### Start with a file preview

1. Set your Apify account’s General resource access to **Restricted before adding files**. Only upload data you are authorized to process.
2. In **Input**, start with **Catalog files** and **Preview files**. Try the small example, or replace it with your catalog and first registration export. Use pasted text, a file upload, or a private store record for each file; clear the example text before using an upload or store record.
3. For uploads, use an existing store explicitly set to **Restricted**, then select that same store in the form to grant read access. A store that inherits account access settings needs to be set to Restricted first.
4. Check the preview for missing columns or mapping problems. Enter your column names where needed. The preview checks file layout and estimates the maximum comparison price; it does no matching and creates no audit events.
5. When the files are ready, select **Reconcile catalog**, set a maximum cost per run, and start the comparison.

Give each registration export a recognizable name. To include a second or third export, enter its name and add its file. You can save the preview’s column mapping for later files with the same layout.

### Review before downloading corrections

Open the comparison report to see suggested links, conflicting codes and recordings that need more information. The action queues separate match review, catalog fixes, registration research and source conflicts.

Download the HTML report and open it locally to review the evidence. Choose **APPROVE**, **REJECT** or **DEFER**, enter the reviewer name, and confirm your review. You can then download approved pairs and proposed fills for blank catalog song codes. Existing different codes are left for you to resolve.

To finish later, keep the complete `audit.json` and use **Export reviewed matches** with your completed decisions CSV. This uses the existing comparison and creates no new audit events. You can also review and export from the downloaded report offline, without installing anything.

Nothing is submitted to a registry or changed in your source files. Research hints are leads to investigate; they cannot be approved as matches.

### What files do I need?

| File | Required columns | Useful optional columns |
| --- | --- | --- |
| Recording catalog | `catalog_id`, `isrc`, `title` | `artist`, `version`, `writer_ipis`, `iswc`, `mlc_song_code` |
| Registration export | `reference_id`, `mlc_song_code`, `title` | `iswc`, `writer_ipis`, `isrc`, `version`, `registration_status` |

Column names can be mapped to your own headers. Keep identifiers as text to preserve leading zeros. Separate multiple writer IPIs with semicolons. An ISWC is optional; a vendor’s internal work ID cannot stand in for an MLC Song Code.

CSV, TSV, JSON arrays and NDJSON are supported. **Export Excel worksheets as CSV** before uploading. JSON cells must contain strings. CSV/TSV supports quoted commas and newlines, UTF-8 or BOM-marked UTF-16LE, and header rows 1–50.

Each comparison accepts up to **2,000 catalog rows** and **10,000 reference rows across three files**. Uploaded/private-record files are limited to **8 MiB each**; inline catalog text to **1 MiB** and each inline reference to **3 MiB**. Large cells or unusually dense evidence can reach processing limits sooner; the report identifies incomplete comparisons. Audio files, archives and arbitrary download URLs are unsupported.

### Price

**$0.05 per recording checked in a paid comparison.** For example, 100 eligible recordings cost $5. Each unique valid ISRC is charged once per run, regardless of duplicate rows, reference files or findings.

Previewing files, exporting an existing reviewed audit and reviewing the downloaded report create **no audit events**. Invalid input, insufficient evidence and rows withheld by your run’s cost limit are free. A completed comparison can be billed even when it finds no match or finds a conflict.

**Starting a fresh reconciliation is a new purchase**, including when the files have not changed. Use the existing report or Export reviewed matches to finish reviewing without buying another comparison. Check the run summary for coverage and billing state; an unknown charged count is not zero. If a run or download is interrupted, inspect the existing run before starting another paid comparison.

### Understanding the results

An agreeing link or a candidate still needs your review before export. Conflicting identifiers block approval; multiple sources do not outvote contradictory evidence. Missing or malformed evidence can leave a recording unresolved. A “no reference match” result means no plausible work was found in the usable files you supplied.

The comparison uses the identifiers, titles and writer details in your files. It does not search The MLC, PROs or other live registries. Results do not establish ownership, registration status or royalties owed.

### Privacy and support

Runs check Restricted access to their run, default storage and results before processing. This check can take about a minute. Keep input stores, downloaded reports, audits, tokens and signed links private. Access settings do not undo earlier sharing or revoke people you authorize; isolation from unrelated authenticated accounts has not been independently verified. Delete runs and their default storage through Apify Console when no longer needed. Named input and history stores have separate lifetimes and are not automatically deleted.

For help, open this Actor’s **Issues** tab. Include the run ID, selected mode, error code and what you expected. Do not post catalog files, tokens or signed links. Report suspected duplicate or incorrect charges there so they can be reviewed and corrected or refunded through Apify.

<details>
<summary>API reference and runnable examples</summary>

#### Prepare a small example

Use your Apify token in the local `APIFY_TOKEN` environment variable. The examples use synthetic inline files, so no input-store grant is needed. They select the `latest` build. Set your account’s General resource access to Restricted before sending input.

For your own files, set `rightsToProcessConfirmed` to `true` only after confirming you are authorized to process them. The generated API form leaves this confirmation off.

Save as `preview-input.json`:

```json
{
  "contractVersion": "2.0",
  "mode": "preview",
  "rightsToProcessConfirmed": true,
  "catalog": {
    "source": "inline",
    "format": "csv",
    "value": "catalog_id,isrc,title,writer_ipis\nC001,USZZZ2600001,River Light,00023456789\n"
  },
  "references": [{
    "id": "registration",
    "label": "Synthetic registration export",
    "asOf": "2026-11-07",
    "file": {
      "source": "inline",
      "format": "csv",
      "value": "reference_id,mlc_song_code,title,writer_ipis\nR001,SYNTHA1,River Light,00023456789\n"
    }
  }]
}
```

Save as `reconcile-input.json`. This starts a fresh paid comparison of one eligible recording, with a maximum audit price of $0.05:

```json
{
  "contractVersion": "2.0",
  "mode": "reconcile",
  "rightsToProcessConfirmed": true,
  "catalog": {
    "source": "inline",
    "format": "csv",
    "value": "catalog_id,isrc,title,writer_ipis\nC001,USZZZ2600001,River Light,00023456789\n"
  },
  "references": [{
    "id": "registration",
    "label": "Synthetic registration export",
    "asOf": "2026-11-07",
    "file": {
      "source": "inline",
      "format": "csv",
      "value": "reference_id,mlc_song_code,title,writer_ipis\nR001,SYNTHA1,River Light,00023456789\n"
    }
  }]
}
```

#### Start, poll and download

This Bash script requires `curl` and Python 3. It starts one run, polls it for up to three minutes and downloads the summary and raw HTML. It defaults to the free preview. To run the paid example, use `INPUT=reconcile-input.json bash run-example.sh`.

Save as `run-example.sh`:

```bash
#!/usr/bin/env bash
set -euo pipefail
: "${APIFY_TOKEN:?Set APIFY_TOKEN locally before running}"
INPUT="${INPUT:-preview-input.json}"

curl --silent --show-error --fail-with-body --request POST \
  'https://api.apify.com/v2/acts/sabya-services~music-catalog-reconciliation/runs?build=latest&memory=512&timeout=120&maxTotalChargeUsd=0.05&forcePermissionLevel=LIMITED_PERMISSIONS' \
  --header "Authorization: Bearer $APIFY_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary "@$INPUT" --output run.json
RUN_ID="$(python3 -c 'import json; print(json.load(open("run.json"))["data"]["id"])')"
STORE_ID="$(python3 -c 'import json; print(json.load(open("run.json"))["data"]["defaultKeyValueStoreId"])')"
STATUS="READY"
for ((attempt=0; attempt<60; attempt++)); do
  curl --silent --show-error --fail-with-body \
    "https://api.apify.com/v2/actor-runs/$RUN_ID" \
    --header "Authorization: Bearer $APIFY_TOKEN" --output run-status.json
  STATUS="$(python3 -c 'import json; print(json.load(open("run-status.json"))["data"]["status"])')"
  case "$STATUS" in
    SUCCEEDED|FAILED|TIMED-OUT|ABORTED) break ;;
  esac
  sleep 3
done
if [[ "$STATUS" != "SUCCEEDED" ]]; then
  printf 'Run %s ended or is still running with status %s. Inspect this run before retrying.\n' "$RUN_ID" "$STATUS" >&2
  exit 1
fi
curl --silent --show-error --fail-with-body \
  "https://api.apify.com/v2/key-value-stores/$STORE_ID/records/summary.json" \
  --header "Authorization: Bearer $APIFY_TOKEN" --output summary.json
HTML_KEY="$(python3 -c 'import json; s=json.load(open("summary.json")); keys={a["key"] for a in s["artifacts"]}; print(next(k for k in ("preview.html", "report.html") if k in keys))')"
curl --silent --show-error --fail-with-body \
  "https://api.apify.com/v2/key-value-stores/$STORE_ID/records/$HTML_KEY?attachment=true" \
  --header "Authorization: Bearer $APIFY_TOKEN" --output "$HTML_KEY"
python3 - "$HTML_KEY" <<'PY'
import hashlib, json, pathlib, sys
path = pathlib.Path(sys.argv[1])
data = path.read_bytes()
entry = next(a for a in json.load(open("summary.json"))["artifacts"] if a["key"] == path.name)
if len(data) != entry["bytes"] or hashlib.sha256(data).hexdigest() != entry["sha256"]:
    raise SystemExit("Download does not match the summary. Keep the existing run and check the download.")
print("Verified download:", path)
PY
```

Open the downloaded HTML locally. The `?attachment=true` parameter returns unmodified bytes; Apify’s HTML view may apply security changes. See the [record download documentation](https://docs.apify.com/api/v2/key-value-store-record-get). The hash check confirms download integrity, not registration truth or an independent signature.

Fetch other files listed in `summary.json` through the same authenticated record endpoint. For a comparison, keep `audit.json` and `decisions-template.csv` if you plan to export later. Never share tokens or signed download capabilities.

#### Private file inputs and reviewed exports

For a private record, use `{"source":"kvRecord","store":"STORE_ID","key":"file.csv","format":"auto"}` as a file source. Supply the same store ID in `catalogStore`, or `reference1Store` through `reference3Store`, to grant Limited read access. These selectors must match the file sources. Uploads accept only Apify private-record URLs with a 17-character store ID and a flat key, without query strings or fragments; arbitrary URLs are rejected.

To export reviewed pairs from an existing audit, send `contractVersion: "2.0"`, `mode: "reviewedExport"`, `rightsToProcessConfirmed: true`, the complete parsed `audit.json` in `auditContext`, completed decisions CSV text in `decisions`, and `reviewedMatchesConfirmed: true`. This creates no new audit events. Decision headers are `audit_id,isrc,suggested_mlc_song_code,decision,material_sha256,note,reviewer`. Use the generated template: stale, duplicate, unconfirmed or ineligible approvals are rejected. Hints cannot be approved. Every new audit requires fresh approval.

Read `summary.json` for actual artifact keys, coverage and `charge`. `requestedUnits` is not proof of payment; `chargedUnits: null` means unknown. `PENDING` and `UNCERTAIN_RECONCILIATION_REQUIRED` need reconciliation of the existing run before retrying. `CONFIRMED` records a provider event count, not bank settlement. A download failure is not a reason to purchase another audit.

</details>

# Actor input Schema

## `contractVersion` (type: `string`):

Choose Catalog files for preview, file uploads and reviewed exports. Choose CSV text pair to use the two CSV boxes near the bottom of this form.

## `rightsToProcessConfirmed` (type: `boolean`):

Confirm you have the rights and permissions to process the catalog and registration data you supply. Required before processing or charging.

## `nativeForm` (type: `boolean`):

Keep checked to use the catalog, registration export and review fields below. Select Catalog files as the input layout.

## `mode` (type: `string`):

Preview checks your files and estimates the maximum comparison price without matching or audit events. Reconcile starts a fresh paid comparison. Export reviewed matches uses an existing audit with no new audit events.

## `runLabel` (type: `string`):

An optional name to help you recognize this comparison. Avoid confidential details.

## `catalogText` (type: `string`):

Paste CSV, TSV, a JSON array or NDJSON. Replace the example with your data, or clear this box before uploading a file or selecting a private record. Keep identifiers as text.

## `catalogUpload` (type: `string`):

Upload into an existing store explicitly set to Restricted, then select that same store below to grant Limited access. Use the Apify private-record upload link without a query or fragment. Stores that inherit account access settings must be set to Restricted before use.

## `catalogStore` (type: `string`):

Choose the explicitly Restricted store holding this file. For an upload, select the same store used above. The selection grants read access; API inputs need this selector too.

## `catalogKey` (type: `string`):

Enter the file record key when reading from the selected store, for example catalog.csv.

## `catalogFormat` (type: `string`):

Use auto to detect CSV, TSV, JSON or NDJSON, or select the format yourself. Export Excel worksheets as CSV before uploading.

## `catalogHeaderRow` (type: `integer`):

For CSV/TSV, enter the row containing column names (1–50). Leave empty to use the first row.

## `catalogMapping` (type: `object`):

Common header names are recognized automatically. For missing or ambiguous columns, enter the exact header from your file. A vendor work_id is not an MLC Song Code.

## `reference1Text` (type: `string`):

Paste CSV, TSV, a JSON array or NDJSON. Replace the example with your data, or clear this box before uploading a file or selecting a private record. Keep identifiers as text.

## `reference1Upload` (type: `string`):

Upload into an existing store explicitly set to Restricted, then select that same store below to grant Limited access. Use the Apify private-record upload link without a query or fragment. Stores that inherit account access settings must be set to Restricted before use.

## `reference1Store` (type: `string`):

Choose the explicitly Restricted store holding this file. For an upload, select the same store used above. The selection grants read access; API inputs need this selector too.

## `reference1Key` (type: `string`):

Enter the file record key when reading from the selected store, for example catalog.csv.

## `reference1Format` (type: `string`):

Use auto to detect CSV, TSV, JSON or NDJSON, or select the format yourself. Export Excel worksheets as CSV before uploading.

## `reference1HeaderRow` (type: `integer`):

For CSV/TSV, enter the row containing column names (1–50). Leave empty to use the first row.

## `reference1Mapping` (type: `object`):

Common header names are recognized automatically. For missing or ambiguous columns, enter the exact header from your file. A vendor work_id is not an MLC Song Code.

## `reference1Id` (type: `string`):

Use a short unique ID for this source, with letters, numbers, underscores or hyphens. Keep it the same when comparing later exports.

## `reference1Label` (type: `string`):

Give this export a recognizable name. If left empty, the report uses Customer reference.

## `reference1AsOf` (type: `string`):

Optional export date in YYYY-MM-DD format. This records the date you supply; it does not verify registration status.

## `reference2Text` (type: `string`):

Paste CSV, TSV, a JSON array or NDJSON. Leave this box empty when uploading a file or selecting a private record. Keep identifiers as text.

## `reference2Upload` (type: `string`):

Upload into an existing store explicitly set to Restricted, then select that same store below to grant Limited access. Use the Apify private-record upload link without a query or fragment. Stores that inherit account access settings must be set to Restricted before use.

## `reference2Store` (type: `string`):

Choose the explicitly Restricted store holding this file. For an upload, select the same store used above. The selection grants read access; API inputs need this selector too.

## `reference2Key` (type: `string`):

Enter the file record key when reading from the selected store, for example catalog.csv.

## `reference2Format` (type: `string`):

Use auto to detect CSV, TSV, JSON or NDJSON, or select the format yourself. Export Excel worksheets as CSV before uploading.

## `reference2HeaderRow` (type: `integer`):

For CSV/TSV, enter the row containing column names (1–50). Leave empty to use the first row.

## `reference2Mapping` (type: `object`):

Common header names are recognized automatically. For missing or ambiguous columns, enter the exact header from your file. A vendor work_id is not an MLC Song Code.

## `reference2Id` (type: `string`):

Use a short unique ID for this source, with letters, numbers, underscores or hyphens. Keep it the same when comparing later exports.

## `reference2Label` (type: `string`):

Enter a name to include this additional export. Leave empty to skip it.

## `reference2AsOf` (type: `string`):

Optional export date in YYYY-MM-DD format. This records the date you supply; it does not verify registration status.

## `reference3Text` (type: `string`):

Paste CSV, TSV, a JSON array or NDJSON. Leave this box empty when uploading a file or selecting a private record. Keep identifiers as text.

## `reference3Upload` (type: `string`):

Upload into an existing store explicitly set to Restricted, then select that same store below to grant Limited access. Use the Apify private-record upload link without a query or fragment. Stores that inherit account access settings must be set to Restricted before use.

## `reference3Store` (type: `string`):

Choose the explicitly Restricted store holding this file. For an upload, select the same store used above. The selection grants read access; API inputs need this selector too.

## `reference3Key` (type: `string`):

Enter the file record key when reading from the selected store, for example catalog.csv.

## `reference3Format` (type: `string`):

Use auto to detect CSV, TSV, JSON or NDJSON, or select the format yourself. Export Excel worksheets as CSV before uploading.

## `reference3HeaderRow` (type: `integer`):

For CSV/TSV, enter the row containing column names (1–50). Leave empty to use the first row.

## `reference3Mapping` (type: `object`):

Common header names are recognized automatically. For missing or ambiguous columns, enter the exact header from your file. A vendor work_id is not an MLC Song Code.

## `reference3Id` (type: `string`):

Use a short unique ID for this source, with letters, numbers, underscores or hyphens. Keep it the same when comparing later exports.

## `reference3Label` (type: `string`):

Enter a name to include this additional export. Leave empty to skip it.

## `reference3AsOf` (type: `string`):

Optional export date in YYYY-MM-DD format. This records the date you supply; it does not verify registration status.

## `auditStore` (type: `string`):

Use the complete audit.json from the comparison you reviewed. A history snapshot cannot authorize exports. Select its explicitly Restricted store to grant read access, or paste JSON below.

## `auditKey` (type: `string`):

Enter the JSON record key in the selected private store.

## `auditText` (type: `string`):

Use the complete audit.json from the comparison you reviewed. A history snapshot cannot authorize exports. Paste the JSON here instead of selecting a store record.

## `profileStore` (type: `string`):

Reuse mapping-profile.json from a preview. Changed file layouts need a new mapping; fields entered above take precedence. Select its explicitly Restricted store to grant read access, or paste JSON below.

## `profileKey` (type: `string`):

Enter the JSON record key in the selected private store.

## `profileText` (type: `string`):

Reuse mapping-profile.json from a preview. Changed file layouts need a new mapping; fields entered above take precedence. Paste the JSON here instead of selecting a store record.

## `previousStore` (type: `string`):

Use an earlier history.json to compare findings. Previous approvals do not authorize new exports. Select its explicitly Restricted store to grant read access, or paste JSON below.

## `previousKey` (type: `string`):

Enter the JSON record key in the selected private store.

## `previousText` (type: `string`):

Use an earlier history.json to compare findings. Previous approvals do not authorize new exports. Paste the JSON here instead of selecting a store record.

## `decisionsText` (type: `string`):

Paste rows from decisions-template.csv, with APPROVE, REJECT or DEFER for each pair you reviewed. Approvals must belong to the supplied audit and need the review confirmation below.

## `historyStore` (type: `string`):

Choose an explicitly Restricted private store to save a separate history record for each run. This grants read and write access; records are not automatically deleted.

## `previousHistoryKey` (type: `string`):

Enter the exact mcr-history--<runId>.json key to compare with. The latest/index records do not automatically select an earlier comparison.

## `reviewedMatchesConfirmed` (type: `boolean`):

Confirm your review before downloading approved pairs. The file has ISRC and MLC Song Code columns; nothing is submitted to The MLC or another registry.

## `catalogCsv` (type: `string`):

For the CSV text pair layout: paste comma-separated UTF-8 CSV with a header row. Required columns: catalog_id, isrc, title. Optional: artist, version, writer_ipis (semicolon-separated), iswc, mlc_song_code. Limit: 2,000 rows / 1 MiB.

## `registrationsCsv` (type: `string`):

For the CSV text pair layout: paste your comma-separated UTF-8 registration export. Required columns: reference_id, mlc_song_code, title. Optional: iswc, writer_ipis, isrc, version, registration_status. Limit: 10,000 rows / 3 MiB.

## `referenceSource` (type: `string`):

For the CSV text pair: give the export a short name so you can identify its source in the report. The source is supplied by you and is not independently verified.

## `referenceAsOf` (type: `string`):

For the CSV text pair: enter the export date as YYYY-MM-DD, or a date-time with timezone.

## `columnMapping` (type: `object`):

For the CSV text pair: map fields to your headers, for example {"catalog":{"isrc":"ISRC Code"},"registrations":{"mlc_song_code":"Song Code"}}. Identifier columns are never guessed.

## `previousAuditJson` (type: `string`):

For the CSV text pair: paste its earlier history.json or audit.json, up to 1 MiB. Comparisons need the same matching rules; incompatible evidence is marked NOT_COMPARABLE.

## `approvedMatchesCsv` (type: `string`):

For the CSV text pair: use isrc,mlc_song_code columns containing current-run SUPPLIED_LINK_AGREES or CANDIDATE_REVIEW suggestions. Confirm review above. Invalid, blank, duplicate or stale rows stop before charging. Limit: 2,000 rows / 256 KiB. This starts a fresh comparison; use Export reviewed matches with a file audit to avoid buying another comparison.

## Actor input object example

```json
{
  "contractVersion": "2.0",
  "rightsToProcessConfirmed": false,
  "nativeForm": true,
  "mode": "preview",
  "catalogText": "catalog_id,isrc,title,writer_ipis\nEXAMPLE1,USZZZ2600001,Example recording,00023456789\n",
  "reference1Text": "reference_id,mlc_song_code,title,writer_ipis\nEXAMPLE1,SYNTHA1,Example recording,00023456789\n",
  "reference1Label": "Example registration export",
  "reviewedMatchesConfirmed": false
}
```

# Actor output Schema

## `summary` (type: `string`):

Check coverage, billing state and the files actually generated by this run. Download links depend on the selected mode.

## `report` (type: `string`):

View the results, reasons and suggested next actions. For interactive offline review, use Download comparison report.

## `review` (type: `string`):

One row per result, with reasons and candidate codes. Spreadsheet formula prefixes are escaped.

## `audit` (type: `string`):

The evidence and results of this comparison, needed for later reviewed exports. Exporting an existing audit does not create a new one.

## `changes` (type: `string`):

Available when a compatible earlier comparison was supplied.

## `approvedMlcMatches` (type: `string`):

Only eligible pairs you reviewed and approved. Download the CSV for your own workflow; it is never submitted automatically.

## `results` (type: `string`):

Browse recording results, candidate codes and reasons.

## `history` (type: `string`):

A compact record for comparing findings later. It cannot replace the complete audit for reviewed exports.

## `preview_json` (type: `string`):

Preview results: detected formats, column mapping issues and maximum comparison price. No matching or audit events.

## `preview_html` (type: `string`):

Check file layout and mapping before starting a paid comparison. Use Download file preview to open it locally.

## `mapping_profile_json` (type: `string`):

Save this preview mapping for later files with the same layout.

## `decisions_template_csv` (type: `string`):

Complete APPROVE, REJECT or DEFER rows for this audit. Keep the audit ID and evidence digest unchanged.

## `queues_json` (type: `string`):

Counts for review, catalog fixes, registration research, source conflicts and no action.

## `export_receipt_json` (type: `string`):

Records the audit and reviewed pairs used to create these downloads.

## `catalog_patch_csv` (type: `string`):

Proposed fills for empty MLC Song Code cells, only after approval and for unique catalog targets. Existing different values are not overwritten.

## `hygiene_csv` (type: `string`):

Formatting and data-quality issues to investigate separately from matching results.

## `hints_json` (type: `string`):

Possible leads with supporting and conflicting evidence. Hints cannot be approved or exported as matches and do not add charges.

## `registration_worklist_csv` (type: `string`):

Rows to investigate using your own registration records. This file is not a registration or a claim for royalties.

## `queue_approve_reject_csv` (type: `string`):

Suggested pairs to approve, reject or defer after checking the evidence.

## `queue_fix_catalog_csv` (type: `string`):

Recording rows needing corrections or more information.

## `queue_research_registration_csv` (type: `string`):

Rows needing further registration research.

## `queue_resolve_source_conflict_csv` (type: `string`):

Contradictory evidence to resolve before approving a match.

## `queue_no_action_csv` (type: `string`):

Rows placed in the no-action queue for this comparison.

## `reportDownload` (type: `string`):

Download unmodified HTML after reconciliation. Open locally to review evidence, record decisions and download approved corrections.

## `previewDownload` (type: `string`):

Download unmodified preview HTML to check your files locally. Available after Preview files.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "contractVersion": "2.0",
    "rightsToProcessConfirmed": false,
    "nativeForm": true,
    "mode": "preview",
    "catalogText": `catalog_id,isrc,title,writer_ipis
EXAMPLE1,USZZZ2600001,Example recording,00023456789`,
    "reference1Text": `reference_id,mlc_song_code,title,writer_ipis
EXAMPLE1,SYNTHA1,Example recording,00023456789`,
    "reference1Label": "Example registration export"
};

// Run the Actor and wait for it to finish
const run = await client.actor("sabya-services/music-catalog-reconciliation").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "contractVersion": "2.0",
    "rightsToProcessConfirmed": False,
    "nativeForm": True,
    "mode": "preview",
    "catalogText": """catalog_id,isrc,title,writer_ipis
EXAMPLE1,USZZZ2600001,Example recording,00023456789
""",
    "reference1Text": """reference_id,mlc_song_code,title,writer_ipis
EXAMPLE1,SYNTHA1,Example recording,00023456789
""",
    "reference1Label": "Example registration export",
}

# Run the Actor and wait for it to finish
run = client.actor("sabya-services/music-catalog-reconciliation").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "contractVersion": "2.0",
  "rightsToProcessConfirmed": false,
  "nativeForm": true,
  "mode": "preview",
  "catalogText": "catalog_id,isrc,title,writer_ipis\\nEXAMPLE1,USZZZ2600001,Example recording,00023456789\\n",
  "reference1Text": "reference_id,mlc_song_code,title,writer_ipis\\nEXAMPLE1,SYNTHA1,Example recording,00023456789\\n",
  "reference1Label": "Example registration export"
}' |
apify call sabya-services/music-catalog-reconciliation --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,sabya-services/music-catalog-reconciliation"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/d6YZc7SstFT8I4hng/builds/I9jgJ5ouaY62xISCL/openapi.json