How Publishers Should Capture Metadata in Requests to Maximize Royalty Collection

Capture clean metadata at intake — so publishers like Kobalt and Madverse can collect every royalty

Hook: Every missed or malformed field in your request intake is a lost royalty. As streaming payouts fragment across territories and as publisher partnerships (like Kobalt’s January 2026 deal with Madverse) expand cross-border collection, publishers and creators need near-perfect metadata from day one.

This guide gives publisher-facing product teams, platform engineers and creator-tool integrators a pragmatic field-level plan and API mapping for request intake forms. Follow these recommendations to deliver clean, auditable metadata that partners can ingest automatically — minimizing reconciliation friction and maximizing royalty collection.

Why metadata quality matters in 2026

Recent trends (late 2025 & early 2026) make metadata hygiene a top business issue:

• Streaming platforms now split payments more granularly (per-track, per-territory, per-use), increasing sensitivity to metadata errors.
• Publisher networks are consolidating global admin: Kobalt’s new partnership with Madverse (Jan 2026) pushes thousands of South Asian works into a global collection pipeline — but only if metadata is compliant.
• AI-generated and hybrid works are rising; rights and contributor attribution must be explicit at intake to avoid disputes.
• Automated ingestion APIs are becoming standard; publishers expect structured payloads that map to PROs, ISWC/ISRC, IPI/CAE identifiers and contractual attachments.

High-level intake principles

1. Collect authoritative identifiers first. ISWC/ISRC/IPI/CAE, or explicit "pending" state if not assigned.
2. Normalize names and roles. Use controlled vocabularies (DDEX roles, PRO role enums) and provide autocomplete against authority lists where possible.
3. Capture splits as precise decimals or integer shares. Avoid ambiguous language like "half" or "split equally."
4. Record provenance and consent. Who submitted, when, and an uploaded signed commissioning agreement.
5. Design for international inputs. Unicode-normalize, accept transliterations, and store both local-script and romanized versions.

Form field recommendations — the exact fields to collect

Below are recommended fields organized by logical groups. For each field we show purpose, validation, and how to map to a publisher ingestion API.

Work / Composition

• work_title (required)
  • Purpose: Primary title of the composition.
  • Validation: 1–255 characters, trim whitespace, Unicode NFC normalization.
  • API mapping: work.title
• alternate_titles (optional)
  • Purpose: International/localized titles, live/alternate names.
  • Validation: Array of objects {title, language_code (ISO 639-1)}.
  • API mapping: work.alternate_titles[]
• iswc (optional/conditional)
  • Purpose: International Standard Musical Work Code (if assigned).
  • Validation: Regex ^T-\d{3}\.\d{3}\.\d{3}-\d$ or accept "pending" flag.
  • API mapping: work.identifiers.iswc
• genre_tags (optional)

Recording / Sound

• isrc (optional/conditional)
  • Purpose: Sound recording identifier; important if publishers also administer recording rights or coordinate with record labels.
  • Validation: 12 characters, appropriate issuer prefix or "pending".
  • API mapping: recording.identifiers.isrc
• recording_title, release_date, label

Contributors (composer, lyricist, performer, producer)

This is the most critical section for publishers. Capture each contributor as a structured object.

• contributors[] (required — at least one)
  • Fields per contributor:
    • full_name (required) — 1–200 chars
    • role (required) — picklist (composer, lyricist, arranger, producer, performer, publisher)
    • ipi_number / cae_ipi (optional but highly recommended) — standardized if known
    • pro_affiliation (optional) — PRO name and membership id
    • share (required) — decimal (e.g., 33.3333) or integer shares; must sum to 100.0000 for ownership shares
    • email (optional) — for verification/token delivery
    • local_script_name (optional)
  • Validation: roles use controlled vocabulary; shares validated both client- and server-side; IPI regex must match country-specific formats when available.
  • API mapping: work.contributors[]: {name, role, identifiers: {ipi, pro_id}, share_decimal}

Publisher / Administration

• publisher_entities[]
  • publisher_name (required if publisher claim exists)
  • publisher_ipi_number (strongly recommended)
  • publisher_role (admin, sub-publisher, sub-publishing_agreement)
  • publisher_share_decimal
  • publisher_contact_email (required for contract delivery)
  • API mapping: work.publishers[]

Commissioning & Contractual

• commissioned_by (required for commissions) — client or platform name
• commission_date (required) — ISO 8601 date
• commission_fee — amount + currency (use ISO 4217)
  • Validation: decimal, two decimals for currencies; store currency code.
• signed_contract_url — upload or e-sign token; required for publisher ingestion if the publisher asks
• API mapping: work.commissioning

Rights & Usage

• rights_granted — controlled multi-select (mechanical, performance, sync, print, master)
• territories — ISO 3166-1 alpha-2 codes; allow ALL or specific lists
• exclusivity — boolean + notes
• API mapping: work.rights

Files & Attachments

• lyrics_file (optional but recommended) — accept .txt, .lrc, .pdf
• score_file (optional) — .pdf, MusicXML
• audio_preview — 30s MP3/MP4 (for verification)
• contract_scan — required for high-value or publisher-claimed works
• API mapping: work.assets[] (include mime type, checksum, and storage token)

Validation rules & UX patterns that prevent bad data

Bad UX leads to bad metadata. Implement these patterns to improve data quality:

• Inline validation with authoritative suggestions. Use autocomplete for known contributors and publishers, querying your authority index or third-party PUID services.
• Real-time share math. Show a dynamic sum of shares, refuse submission if sum != 100.0000 (or provide a clear explanation when using integer shares).
• Field-level hints & examples. Example: IPI: "Include only numbers; no spaces."
• Two-stage submission for missing IDs. Allow 'pending' for ISWC/ISRC but require follow-up within N days; create a lifecycle webhook for updates.
• Transliteration assistance. Offer a toggle that captures both native-script and romanized names.
• File checksum and virus scan. Ensure all uploads are stored with SHA-256 checksum for audit trails.

API mapping: a practical JSON schema example

Publishers like Kobalt/Madverse will expect a structured payload. Below is a condensed example payload to POST to a publisher ingestion endpoint. Adjust field names to your platform, but preserve the structure and identifier fields.

{
  "work": {
    "title": "Evening Train",
    "alternate_titles": [{"title":"Shaam Ki Rail","language":"hi"}],
    "identifiers": {"iswc": "T-123.456.789-0", "pending_iswc": false},
    "contributors": [
      {"name":"Asha Patel","role":"composer","identifiers":{"ipi":"12345678901"},"share":50.0},
      {"name":"Ravi Kumar","role":"lyricist","identifiers":{"ipi":"10987654321"},"share":50.0}
    ],
    "publishers": [
      {"name":"Madverse Music Group","ipi":"20123456789","role":"administrator","share":100.0}
    ],
    "rights": {"mechanical":true,"performance":true,"territories":["IN","US","GB"]},
    "commissioning": {"commissioned_by":"BrandX","commission_date":"2025-12-10","fee":{"amount":2500.00,"currency":"USD"},"contract_url":"https://storage.example/contract.pdf"},
    "assets": [
      {"type":"lyrics","url":"https://storage.example/lyrics.txt","checksum":"sha256:..."},
      {"type":"audio_preview","url":"https://storage.example/preview.mp3","duration_seconds":30}
    ]
  }
}

Notes: Use ISO date formats, currency codes, and territory codes. Include checksums and storage tokens rather than raw file bytes where possible.

Webhook lifecycle and reconciliation flows

Good integrations are asynchronous. Publish these webhooks to your partners:

• submission.created — initial intake received (include a submission_id)
• submission.incomplete — missing required IDs or documents (publisher or system requests follow-up)
• submission.ingested — publisher accepted and ingested into admin system (includes assigned admin_id)
• identifier.assigned — ISWC/ISRC assigned post-submission (map back to submission_id)
• royalty.evaluate — publisher requests clarification or contract for a detected claim

Include version, timestamp, a signature (HMAC) for webhook authenticity, and a retry policy. Provide human-friendly messages and machine-readable codes.

Handling edge cases

Missing identifiers

If an ISWC/ISRC/IPI is not yet available, accept a pending flag and require a follow-up. Implement a scheduled job that alerts submitters and publishers after N days (typical 30–90 days) to prevent orphaned works.

AI-assisted contributions

Since late 2025, platforms increasingly require explicit attribution for AI assistance. Add a boolean ai_assisted and a structured description field. Publishers need this to determine rights eligibility and to negotiate splits.

Split disputes

Capture the source of split calculations (submitted by creator, platform-proposed, or publisher-mediated) and store a signed agreement file. If a dispute is raised, your metadata should show the chain of custody and timestamps.

Security, privacy and compliance

• PII protection. Minimize storing personal data; tokenise banking details and connect to payment providers (Stripe, Payoneer) rather than storing raw account numbers.
• Consent. Record explicit consents for admin assignment, sync with publisher terms, and allow users to withdraw within contractual limits.
• Audit logs. Keep immutable audit trails for changes to shares, contributors, and publisher claims (timestamp, actor, reason).
• GDPR & local laws. Allow data export (for rights owners) and deletion where legally required, while preserving metadata critical for royalty calculations using anonymized references.

Operational checklist for platform teams

Use this quick checklist when rolling out or auditing intake flows:

1. Have a mandatory contributors array with name, role and share.
2. Enforce share-sum validation both client- and server-side.
3. Require a signed or uploaded commissioning agreement for paid commissions.
4. Normalize and store both native and romanized names for international works.
5. Provide autocomplete against an authority index for IPI/PRO lookups.
6. Expose an API endpoint (POST /submissions) and webhooks for ingestion lifecycle events with HMAC signatures.
7. Keep an automated reminder system for pending identifiers.

Real-world example: onboarding Madverse catalog into Kobalt (scenario)

Imagine a Madverse-facing form used in early 2026, immediately after the Kobalt partnership announcement. Madverse needs to feed Kobalt with a stream of works from independent South Asian creators. Implementing the above steps reduces manual reconciliation:

• Madverse captures both Devanagari/Tamil/English names and IPI where available.
• Contributors are validated via autocomplete that matches Kobalt’s authority index, reducing duplicates and misspellings.
• Contracts are uploaded and their SHA-256 checksums included in the submission payload, allowing Kobalt to verify authenticity on ingestion.
• Pending ISWC values are flagged; once Kobalt assigns ISWC via their admin, a webhook updates the original Madverse submission and the platform can notify the creator.

"Kobalt’s global admin reach only pays off when metadata travels cleanly. Automate that cleanliness at intake."

Advanced strategies and future predictions (2026+)

Looking ahead, expect these developments and design your intake accordingly:

• Authority sync APIs. Publishers will expose APIs to validate and link IPI/PRO data in real time — implement OAuth flows to allow on-the-fly lookups.
• Contract-standardization. Machine-readable contract fragments (e.g., JSONLD clauses for splits and territory) will be passed at intake for automated ingestion.
• Micro-rights and micropayments. As micro-licensing grows, expect micro-splits per-use; granular metadata will be required for automated royalties.
• Rights provenance ledgers. Immutable audit ledgers (not necessarily blockchain) will be more common; include checksums and hash pointers to uploaded assets.

Summary: Implement this minimal schema now

If you take one practical step today, implement a single POST /submissions endpoint that accepts the structured payload above, supports "pending" identifiers with deadlines, and emits signed webhooks for ingestion lifecycle events.

That one endpoint — combined with good UX (autocomplete, share math, required contract upload) — will dramatically reduce human reconciliation and increase the percentage of royalties captured by your publisher partners.

Call to action

Start by mapping your current form fields to the schema in this guide. Run a 30-day pilot with a trusted publisher partner (Kobalt, Madverse or similar) and exchange a small sample of ingestions via the webhook lifecycle above.

Need a starter JSON schema or webhook signing example for your engineering team? Contact our integration team to get a downloadable schema and API templates you can drop into your codebase.

Related Reading

• Preventing ‘Fat-Finger’ Outages: Change Control and Automation Guardrails
• Designing a Hedging Dashboard: Live Signals from Commodities, Open Interest, Export Sales and Prediction Markets
• Behind the Scenes: How Actors Prepare to Play Doctors — Insights from Taylor Dearden
• Field Review 2026: Portable Recovery & Comfort Kits for Home Visits — What Works for Care Teams
• Choosing a Friendlier Social Feed: How to Find Paywall-Free Forums for Mental Support