The metadata of the uploaded file can be set after the upload by appending an upload id, or you can simply append the metadata array to the original upload query as meta and it’ll be applied then.

Also remember that you can set metadata after your tracks have been published with the Tracks API or by using the site tools. Downloading a copy of your metadata, editing, then reuploading as a CSV is what most of our clients prefer for large changes.

The API uses the standard fieldset, rather than whatever your site has them named, so you don’t have to recode your integration if someone renames something. Meaning if you’ve renamed Catalog into Katalog because your site is in German, you still need to send in data with the standard Catalog field.


This request will return the standard fieldset for your site. This matches the CSV Metadata export format, if you do an export from Admin → Manage Metadata → Export Data.

Try it out:

Interested Parties data has multiple values (and subvalues), so they’ll come back like Writer {X} First Name. Publishers have multiple collection interests, so they’ll be formatted like Publisher {X} Collection Share Percentage {Y}. You’ll set the data exactly the same way and the indexing starts at 1. See the Example Response.

Custom fields are specific to your site, so they need to be marked differently in case you have a custom field that conflicts with a standard one. For example, you would send in something like ...&meta[Custom: External ID]=123314. Your custom fields will show up in the standard fieldset, so you can see what’s on there. If you need to add a custom field, you’ll need to do it from the site admin panel at Admin > Manage Metadata > Fields > Custom Fields.

Param Required Description
upload_id yes The id of the upload you wish to set metadata for
meta yes The array, keyed to the standard fieldset, with the updated metadata
formats no Comma-separated mp3, wav, and/or aiff, indicating which formats to generate if not supplied

Metadata requests can also be made during upload, by simply appending the relevant meta array to the /api/import/upload request.

Example Response

upload_id: 51223,
status: 'uploaded',
formats: ['mp3', 'wav', 'aiff'],
sources: [
meta: {
"Title": "My Title.",
"Filename": "myfile.mp3",
"Album": "My Album",
"Publisher 1 Company": "My Music Inc",
"Publisher 1 PRO Affiliation": "SESAC",
"Publisher 1 CAE/IPI": "70045654889",
"Publisher 1 Ownership Share": 15,
"Publisher 1 Role": "Original Publisher",
"Publisher 1 Collection Share Percentage 1": 27,
"Publisher 1 Collection Share Territory 1": "UNITED STATES",
"Publisher 1 Collection Share Percentage 2": 11,
"Publisher 1 Collection Share Territory 2": "AFGHANISTAN",

Field Notes

Certain fields cannot be set, most notably: SourceAudio ID and Duration. These are assigned by the system, and will cause an error if you attempt to send them in. Another quirk of the system is that Release Date needs to be sent in an YYYY-MM-DD format, rather than a unix timestamp (which is what is returned).

Album Art

Album Artwork will automatically be pulled from your ID3 tags, but you can also set it manually with a URL. Since we’re doing this on the track level, the album is updated each time, and the import process is distributed, you cannot guarantee what track will be last and finally update the album, thus the safest method will be to set the url on each track and let it do it each time. If the inefficiency of this bothers you, use the Tracks API instead and set it on one track once they’re published. The final sizes created are at the native size and 150x150. Make sure you supply a square image if you want to avoid stretching. This can be done as part of other setMetadata parameters, it’s just broken out into its own section for clarity.

If the url you supply does not have the image extension on it, then you also need to supply the Album Artwork Type when you send it in. We accept jpg, gif, and png.

Example: /api/import/setMetadata?upload_id=12345&meta[Album Artwork]=[Album Artwork Type]=jpg&token={token-goes-here}

Note: Album Artwork and Album Artwork Type are not in the standard fieldset and will not be returned.