Track Writers & Contributors (API)

When you create a track through the LabelGrid public API, you describe the people behind it with two separate arrays: one for song credits (who did what) and one for publishing splits (who owns the composition and their percentage). This guide explains what each array expects and the rules that run when you create a track.

Two arrays per track

Each track carries two independent arrays:

• contributors[] — song credits: who did what on the track.
• writers[] — publishing splits: who owns the composition and their percentage.

Both arrays reference a writer profile by writerId (camelCase) or writer_id (snake_case). Send exactly one of the two — sending both is rejected. The ID must match a writer you own.

Both arrays point at the same writer registry — the writers you create through the Writers endpoint. So a contributor and a publishing-split writer reference the same underlying writer record.

contributors[] — required at create

contributors[] is required on create, with at least one entry. Each entry has:

• writerId / writer_id
• roles[] — 1 to 3 roles, drawn from the Contributor Roles reference list
• ai_contribution — none, partly, or all

Rules that fire when you POST a track:

• Cover all three role categories — across your contributors, there must be at least one Performer, one Composition & Lyrics, and one Production & Engineering role.
• At least one human — ai_contribution can’t be all for every contributor.
• No duplicate writer IDs across the contributors array.

writers[] — publishing splits (optional at create, required to distribute)

writers[] is optional to create a track, but required to distribute the release — every track needs at least one writer with a Composer or Lyricist role and a percentage share, the shares on each track must total 100%, and instrumentals are not exempt. So a track saves fine without writers, but a release whose tracks have none won’t pass validation and can’t be approved for distribution.

Each entry has:

• writerId / writer_id
• roles[] — at least one role; the only allowed values are Composer and Lyricist
• percentage_share — a number from 0 to 100

Rules:

• Splits must total 100% — the percentage_share values across all writers must sum to 100.
• No duplicate writer IDs.
• No duplicate roles for a single writer.

master_splits[] — recording shares (we fill these in for you)

Master splits divide recording revenue. Like writers[], they’re required before a release can be distributed — but unlike writers[], you rarely have to send them: when you omit master_splits, LabelGrid creates a default split for the track using your label’s default share (50% unless you’ve changed it on the label), with the remainder divided evenly across the track’s artists. Master splits are used for royalty accounting inside LabelGrid and are never sent to stores.

If you’re importing a catalogue in bulk, leave master_splits out and let the defaults apply. Send it only for tracks that need a custom division — and if your label’s default share isn’t the one you want, change it on the label before you import.

When you do send it, each entry has:

• entity_type — label or artist
• entity_id — the ID of that label or artist
• percentage_share — a number from 0 to 100

Rules:

• At least one entry if the array is present.
• Shares must total 100%.

Caution

Once you send master_splits, you own the split: an array whose shares don’t total 100% is rejected, and no default is created for that track. If you don’t want a custom division, omit the field entirely rather than sending a partial array.

A minimal example

{
  "title": "Track One",
  "contributors": [
    {
      "writerId": "wr_123",
      "roles": ["Vocals", "Composer", "Producer"],
      "ai_contribution": "none"
    }
  ],
  "writers": [
    {
      "writerId": "wr_123",
      "roles": ["Composer", "Lyricist"],
      "percentage_share": 100
    }
  ]
}

Common errors

• Use the plural roles, not role.
• Use percentage_share, not share.
• Don’t send both writerId and writer_id on the same entry.
• For publishing-split writers, only Composer and Lyricist are accepted as roles.
• Leaving writers[] off a track saves fine but blocks distribution later — every track needs at least one writer, and the splits must add up to exactly 100%.
• Sending a partial master_splits array — one that doesn’t total 100% is rejected. Omit the field entirely and we’ll create the default split for you.

Related

• API Overview — endpoints, authentication, and the full reference (including the Contributor Roles reference data)
• Writers & Contributors — how writer profiles work in your catalog