Connect API
Version 1
A newer version of the OpenPlay Music API is available. Check out the OpenPlay Music API (Version 2) documentation to see all of the new features and start migrating your integrations.
curl
to make a request to the API, including your
API Key ID
as the basic authentication username with
-u
curl https://connect.openplaymusic.com/v1/ \
-u {API Key Id}
These apply to all parts of the OpenPlay Connect API.
The OpenPlay Connect API uses JSON exclusively. All requests return JSON responses. Requests that require a request body expect it to be in JSON format.
There are JSON libraries available for all popular, and many unpopular, programming languages.
Breaking changes will not be introduced without changing the API version.
New features and data will be added to the current API version without incrementing the version.
Backwards-incompatible changes, such as changing or removing features or data, will be released with a new version of the API.
Backwards-incompatible changes may occasionally be required to avoid security issues.
Previous API versions will be deprecated and removed over time.
Requests that return multiple records will be paginated
to 50 records by default.
You can get more records with the page parameter.
The response body will contain links to the
next page, the
previous page, the
first page, and the
last page. It is a good idea to use these
links instead of trying to construct your own URLs.
You can paginate through a maximum of 10000 records for a given query. Apply additional filters if needed to narrow down results to an amount that can be paginated through.
To ensure fair use and maintain system stability, we enforce rate limits on all API requests.
If you exceed the allowed number of requests, the API will respond with a
429 Too Many Requests
status code.
The response will also include a
Retry-After
header indicating how many seconds you should wait before making another request.
Retry-After
value.
HTTP/1.1 429 Too Many Requests
Retry-After: 5
Content-Type: application/json
{
"error": "Rate limit exceeded; retry after 5 seconds"
}
The OpenPlay Connect API uses Basic Authentication over HTTPS to authenticate access. You will need an API Key which consists of an API Key ID and API Secret Key in order to authenticate.
API Key management can be found under
→ API
Keys in either OpenPlay Music or OpenPlay Platform.
To generate a new API Key click the New button. After clicking New you will be able to enter a description of the new API Key. Upon clicking Save Changes the new API Key will be generated and you will be shown the API Key ID and API Secret Key.
Important This is the only time you will be able to see the API Secret Key. For security it is not retrievable. Treat it as a password and store it somewhere safe such as a password manager.
If you lose your API Secret Key you can generate a new API Key at any time. You should also revoke your old API Key if it is no longer in use so that it cannot be used to access your data. It is a good practice to rotate your API Keys on a regular basis to prevent the spread of an unknowingly leaked key.
The DESCRIPTION field is only for reference and can be changed at any time without affecting the operation of the API Key.
All requests to the API are authenticated using Basic Authentication over HTTPS.
Basic Authentication is convenient but comes with some security considerations to be aware of:
Because many HTTP/S clients allow embedding Basic Authentication credentials in the URL they may end up appearing in logs if your code is logging requests before they go out. This can then be a security risk if someone has, or gets access to, those logs. It is best to never embed your credentials in the URL to avoid them appearing in any intermediary logs.
Your credentials are secured over HTTPS so once the request is made they cannot be intercepted. The API does not log the API Secret Key used to make incoming requests.
Basic Authentication headers are sent base64 encoded. Base64 encoding is trivially reversible so treat the authentication header just like your API Secret Key in plain text. Be cautious when logging or exposing your request headers.
Revoking an API Key will disallow the API Key from being used to access the OpenPlay Connect API. You can revoke an API Key and generate a new one at any time. It is a good practice to periodically revoke and generate new API Keys for all of your integrations.
Click the Revoke button on any API Key to revoke the API Key. You will be prompted to confirm the action. Upon confirmation the API Key will be immediately unusable.
Revocation cannot be reversed. You will instead need to generate a new API Key and update the credentials used for any integrations.
curl https://connect.openplaymusic.com/v1/ \
-u {API Key Id}
Webhooks allow you to be notified automatically when specific events occur.
Webhooks work by sending an HTTP POST request to your server every time a specific event happens. This allows you keep external systems up to date without having to poll the OpenPlay Connect API.
You might use Webhooks for everything from sending a custom email whenever a new Artist is added to updating an external finance system every time a Release is distributed.
Webhooks send an HTTP POST request from OpenPlay to your server. In order to receive the request you will need to be running a server, accessible from the internet, configured to handle the request.
Webhooks will allow non-secure HTTP requests when testing, however active Webhooks must be sent over a secure HTTPS connection with a valid SSL certificate.
To get started developing a server endpoint you can use a free tool like Ngrok to expose a server running on your computer to the internet.
Your server needs to be configured to handle an HTTP POST request at a URL of your choosing. You will then configure the webhook to POST to whatever URL you have configured in your server.
Like the API the Webhooks use JSON exclusively. The webhook will send the POST request with an example JSON body:
{
id: 93813,
mode: "live",
event: {
source: "OpenPlay Platform"
name: "release_distributed",
id: 498183
}
}
The id in the webhook body is the
ID of the related Release, and the
GET a Release
endpoint can then be queried using that ID to get additional
Release details.
Upon receiving the webhook your server should respond with a status code in the 200 range. We will consider any 2xx status code to be a success.
The status will appear in the Distribution Log of the Release the webhook was sent for indicating whether the webhook succeeded or failed.
Timeout Your server must respond with a 2xx status code within a few seconds. If your server takes too long OpenPlay will consider the request timed out. A consistent pattern of timeouts may lead to your Webhook being automatically disabled. Ensure a fast response by delaying heavy processing until after responding.
OpenPlay will not automatically retry failed webhook requests.
Webhooks can be configured under
→
Webhooks.
Click the New button to add a new Webhook.
The NAME field is only used to help differentiate Webhooks in the list. You can use any name you like and can change it at any time without affecting the operation of the webhook.
Set the URL to the full URL of your server and configured request path, for instance (using ngrok):
http://9baa79f.ngrok.io/webhook
Inactive webhooks will allow sending to HTTP URLs. When your webhook is ready to go live you can switch the webhook to Active. Active webhooks require sending to a HTTPS URL with a valid SSL certificate.
You can test that your Active webhook is working by switching to Active mode and sending a test request. The webhook will only start sending once your changes are saved.
You can switch a webhook between Active and Inactive at any time. Your webhook will only send requests while it is active.
You can test your webhooks from the same place you configure them. When viewing a Webhook you will see a TESTING section below the webhook details.
To send a test enter the ID of any Release in OpenPlay and click Send Test Request. OpenPlay will send a test request to the Webhook's URL with the same data as a live Webhook request.
Test webhook requests are sent with mode: "test"
in the body, while active webhook requests have mode: "live".
Request and response details will appear in the UI after sending the test to aid in verifying and debugging your Webhook configuration.
Each Webhook is created with a Secret Token. The Secret Token is used to HMAC sign each Webhook request sent from OpenPlay. The request from OpenPlay will have an Authorization-Signature header that can then be used, with the Secret Token, to verify that the request came from OpenPlay and that the request body was not tampered with.
Important As the name implies the Secret Token is meant to be kept secret. It will be used by the receiver to validate the incoming message but is never sent in a request itself. Anyone with access to the Secret Token could potentially sign requests for that Webhook as if they had come from OpenPlay. In the event your Secret Token may be compromised the simplest thing to do is to configure a new Webhook, which will have a new Secret Token, and disable the compromised one.
Webhook requests sent from OpenPlay have an HTTP request header:
Authorization-Signature. This is the
SHA-256 HMAC hex digest generated from the Secret Token and the
request body.
After receiving the request you can verify the request is from
OpenPlay, and unmodified, by calculating the signature on your
side from the same Secret Token and the received request body. If
the signature you calculated matches the signature sent in the
Authorization-Signature HTTP header then
you can verify that it was sent from OpenPlay and has not been
modified.
To calculate the signature on your side you will need to use the exact same algorithm and components as the signature was generated with. This includes formatting (like whitespace) so be careful not to pre-process the request body before verifying it. There are HMAC and SHA-256 digest algorithms for pretty much every programming language -- an example in a Ruby webserver might look like:
request.body.rewind
body = request.body.read
signature = "sha256=" + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), ENV["SECRET_TOKEN"], body)
halt 401 if !Rack::Utils.secure_compare(signature, request.headers[:"Authorization-Signature"])
Important
Many programming languages have a constant-time string comparison
method available like secure_compare in
Ruby above. Using a constant-time comparison (instead of the
something like ==) can help reduce the
risk of leaking information from your server via timing attacks.
You can see previous webhook requests and their statuses in the table of PAST REQUESTS AND RESPONSES when viewing a webhook.
You can also see the status of a webhook for a particular Release on the distribution log for that Release in Platform.
Webhooks will not be automatically retried if they are unable to send.
While we are actively expanding our API, the following expansive list of OpenPlay Connect API endpoints is available today:
Search releases in OpenPlay. Use the q parameter to
narrow down the results. Requests that return multiple releases will be paginated
to 50 releases by default. You can get more releases
with the page parameter.
The response body will contain links to the
next page, the
previous page, the
first page, and the
last page. It is a good idea to use these
links instead of trying to construct your own URLs.
Important Currently we only allow pagination through the first 10000 releases.
OpenPlay Platform All submissions of a Release are available via this same API.
| Name | Type | Description |
|---|---|---|
q
|
string | The query can contain one or more search keywords. Remember that query string components must be percent-encoded |
page
|
integer | Page number of the results to fetch. |
filters[upc]
|
string | UPC to filter by |
filters[project_number]
|
string | Project Number to filter by |
filters[label][]
|
array of strings | Filter for records belonging to a Label with this name. This parameter can be used multiple times to include multiple Labels. |
Multiple filters and the q parameter can be combined to narrow down your search.
curl -u {API Key Id} https://connect.openplaymusic.com/v1/releases/?q=If+Thats+What+It+Takes&filters[upc]=555555555555&filters[label][]=Awesome+Records&filters[label][]=Smooth+Records
curl -u {API Key Id} https://connect.openplaymusic.com/v1/releases/
{
"next": null,
"previous": null,
"last": "https://connect.openplaymusic.com/v1/releases/?page=1",
"first": "https://connect.openplaymusic.com/v1/releases/?page=1",
"current_page": 1,
"total_results": 2,
"result_range": "1 - 2",
"results": [
{
"title": "If That's What It Takes",
"upc": "555555555555",
"id": "195-14"
},
{
"title": "If That's What It Takes",
"upc": "555555555555",
"id": "93813"
}
]
}
Retrieve a JSON representation of a Release from the API. You will need to use the Release ID in order to request the Release data. The Release ID can be found in the URL of your browser when you browse to a Release. The Release ID also appears in the summary of every Release. If you are using Webhooks the Release ID will be sent along with the Webhook.
curl -u {API Key Id} https://connect.openplaymusic.com/v1/releases/195-14/
{
"id": "195-14",
"title": "If That's What It Takes",
"version": null,
"upc": "555555555555",
"release_date": "1982-01-18",
"release_number": "55555-ABC55-5",
"original_release_date": "1981-08-03",
"parental_advisory": "Non-Applicable",
"pline_year": 1982,
"pline_owner": "Regular Records",
"pline_license": "under license",
"cline_year": 1982,
"cline_owner": "Regular Records",
"cline_license": "under license",
"artist_display_name": "Michael McDonald",
"artist_name_format": "Artist Name",
"artist_type": "Recording Entity",
"compilation_type": null,
"music_type": "pop",
"label": {
"name": "Regular Records"
},
"display_label": "REGULAR Records",
"configuration": "Digital Album",
"genre": "R&B",
"sub_genre": null,
"metadata_language": "English",
"metadata_language_country": null,
"audio_language": null,
"audio_presentation": null,
"resolution_type": null,
"studio_name": null,
"partners": {
"excluded": false,
"partner_names": [
"Apple Inc",
"Spotify"
]
},
"release_price_tier": "3 Mid Track Price EP Bundle",
"audio_track_price_tier": "Middle-Tier Track price",
"video_track_price_tier": "Premium-Tier Video price",
"cover_art": true,
"preorder": false,
"earliest_preorder_date": null,
"primary_contributions": [
{
"id": 5101014,
"artist": "Michael McDonald",
"position": 1
}
],
"project": {
"title": "Michael McDonald Project",
"number": "94",
"master_project": {
"title": "Michael McDonald Catalogue",
"number": "93"
}
},
"contributions": [
{
"id": 5000011,
"artist": "Kenny Loggins",
"role": "Vocals",
"type": "Background",
"category": "Non Featured Artist",
"position": 1
}
],
"discs": [
{
"upc": "555555555555",
"number": 1,
"tracks": [
{
"id": 5000123,
"title": "I Keep Forgettin'",
"version": null,
"artist_display_name": "Michael McDonald",
"isrc": "USOPY8255555",
"parental_advisory": "Non-Applicable",
"pline_year": 1982,
"pline_owner": "Regular Records",
"pline_license": "under license",
"cline_year": 1982,
"cline_owner": "Regular Records",
"cline_license": "under license",
"preorder_only": false,
"earliest_instant_grat_date": null,
"earliest_prestream_date": null,
"number": 1,
"duration": 225,
"genre": "R&B",
"sub_genre": null,
"artist_name_format": "Artist Name",
"artist_type": "Recording Entity",
"metadata_language": "English",
"metadata_language_country": "United States",
"audio_language": "English",
"audio_hook": 0,
"audio_sample_length": 60,
"primary_contributions": [
{
"id": 5100013,
"artist": "Michael McDonald",
"position": 1
}
],
"contributions": [],
"works": [
{
"id": 5000001,
"title": "I Keep Forgettin'",
"iswc": "T-345246800-1",
"language": "English",
"label_work_code": "WORKS123",
"music_type": "pop",
"agency": "McDonald Publishing",
"lyrics": "I keep forgettin' we're not in love anymore\nI keep forgettin' things will never be the same again\nI keep forgettin' how you made that so clear\nI keep forgettin'\n",
"copyright_year": 1982,
"contributions": [
{
"id": 5000101,
"position": 1,
"affiliation": "BMG",
"split_percent": 50.0,
"country": "All",
"artist": "Ed Sanford",
"role": "Author"
},
{
"id": 5000102,
"position": 2,
"affiliation": "BMG",
"split_percent": null,
"country": "All",
"artist": "Michael McDonald",
"role": "Author"
}
],
"publishers": [
{
"id": 5001001,
"position": 1,
"rights_administrator": "SESAC",
"affiliation": "BMG",
"split_percent": 100.0,
"publisher": "Yacht Times",
"country": "All"
}
]
}
]
}
]
}
],
"status": "Submitted"
}
OpenPlay Platform All previous submissions of a Release are available via this same API. To request a previously submitted version use the submitted Release ID from OpenPlay Platform.
The response format is similar for data from OpenPlay Music and OpenPlay Platform.
curl -u {API Key Id} https://connect.openplaymusic.com/v1/releases/93813/
{
"id": "93813",
"tenant_release_id": "195-14",
"title": "If That's What It Takes",
"version": null,
"upc": "555555555555",
"release_date": "1982-01-18",
"release_number": "55555-ABC55-5",
"original_release_date": "1981-08-03",
"parental_advisory": "Non-Applicable",
"pline_year": 1982,
"pline_owner": "Regular Records",
"pline_license": "under license",
"cline_year": 1982,
"cline_owner": "Regular Records",
"cline_license": "under license",
"artist_display_name": "Michael McDonald",
"artist_name_format": "Artist Name",
"artist_type": "Recording Entity",
"compilation_type": null,
"music_type": "pop",
"label": {
"name": "Regular Records"
},
"display_label": "REGULAR Records",
"configuration": "Digital Album",
"genre": "R&B",
"sub_genre": null,
"metadata_language": "English",
"metadata_language_country": null,
"audio_language": null,
"audio_presentation": null,
"resolution_type": null,
"studio_name": null,
"partners": {
"excluded": false,
"partner_names": [
"Apple Inc",
"Spotify"
]
},
"release_price_tier": "3 Mid Track Price EP Bundle",
"audio_track_price_tier": "Middle-Tier Track price",
"video_track_price_tier": "Premium-Tier Video price",
"cover_art": true,
"preorder": false,
"earliest_preorder_date": null,
"primary_contributions": [
{
"id": 5101014,
"artist": "Michael McDonald",
"position": 1
}
],
"project": {
"title": "Michael McDonald Project",
"number": "94",
"master_project": {
"title": "Michael McDonald Catalogue",
"number": "93"
}
},
"contributions": [
{
"id": 5000011,
"artist": "Kenny Loggins",
"role": "Vocals",
"type": "Background",
"category": "Non Featured Artist",
"position": 1
}
],
"discs": [
{
"upc": "555555555555",
"number": 1,
"tracks": [
{
"id": 5000123,
"title": "I Keep Forgettin'",
"version": null,
"artist_display_name": "Michael McDonald",
"isrc": "USOPY8255555",
"parental_advisory": "Non-Applicable",
"pline_year": 1982,
"pline_owner": "Regular Records",
"pline_license": "under license",
"cline_year": 1982,
"cline_owner": "Regular Records",
"cline_license": "under license",
"preorder_only": false,
"earliest_instant_grat_date": null,
"earliest_prestream_date": null,
"number": 1,
"duration": 225,
"genre": "R&B",
"sub_genre": null,
"artist_name_format": "Artist Name",
"artist_type": "Recording Entity",
"metadata_language": "English",
"metadata_language_country": "United States",
"audio_language": "English",
"audio_hook": 0,
"audio_sample_length": 60,
"primary_contributions": [
{
"id": 5100013,
"artist": "Michael McDonald",
"position": 1
}
],
"contributions": [],
"works": [
{
"id": 5000001,
"title": "I Keep Forgettin'",
"iswc": "T-345246800-1",
"language": "English",
"label_work_code": "WORKS123",
"music_type": "pop",
"agency": "McDonald Publishing",
"lyrics": "I keep forgettin' we're not in love anymore\nI keep forgettin' things will never be the same again\nI keep forgettin' how you made that so clear\nI keep forgettin'\n",
"copyright_year": 1982,
"contributions": [
{
"id": 5000101,
"position": 1,
"affiliation": "BMG",
"split_percent": 50.0,
"country": "All",
"artist": "Ed Sanford",
"role": "Author"
},
{
"id": 5000102,
"position": 2,
"affiliation": "BMG",
"split_percent": null,
"country": "All",
"artist": "Michael McDonald",
"role": "Author"
}
],
"publishers": [
{
"id": 5001001,
"position": 1,
"rights_administrator": "SESAC",
"affiliation": "BMG",
"split_percent": 100.0,
"publisher": "Yacht Times",
"country": "All"
}
]
}
]
}
]
}
],
"submission_number": "1 of 1"
}
Create a new Release in OpenPlay Music. The structure for creating a Release can also include most of the associated data that can be created along with a Release (such as contributions, artist, tracks, works, etc).
With the sample
curl
command, this request body would go in a
release.json
file
title
string
configuration
string
The main release type. Different release configurations have different features and validations (for instance audio vs video configurations).
label
string
display_title
string
version_title
string
Used to distinguish multiple versions of the same record. (Example: 'Live')
version_display_title
string
display_label
string
Used to market a particular asset on digital partner sites. To be displayed on the online retailer's site or service.
genre
string
genre choice also determines valid sub_genre choices (if available)
sub_genre
string or null
sub_genre choices (if available) are dependent on genre choice.
See genre for list of valid options.
series_name
string
Name of the Series (Example: 'Greatest Hits Collection')
release_date
string
Primary release date associated with the Release
release_time
string
original_release_date
string
The date this Release was originally released if previously released.
artist_display_name
string
upc
string
UPC (US 12-digit code with optional leading zeros) or EAN (Europe 13-digit code with optional leading zero)
catalog_number
string
A local release number or catalog number used internally to uniquely identify the release
music_type
string
Type of Music (May impact available metadata fields)
audio_language
string
Primary language of recorded audio
metadata_language
string
Language in which the metadata is written
metadata_language_country
string
Country that the Metadata Language is associated with
compilation_type
string
Indicates if the Release is a compilation or if the Release contains audio used for the soundtrack of a Film or Television show
parental_advisory
string
promotional
string
If checked, this Release is a promotion (non-commercial) release
box_set
string
If checked, this Release is part of a box set
indie_exclusive
string
If checked, this Release is an Indie Exclusive
soundtrack
string
If checked, this Release contains audio used for the soundtrack of a Film or Television show
audio_presentation
string
The format of the associated audio
resolution_type
string
The type of HD content. Digital configurations only.
studio
string
Studio Name for MFiT Releases. Digital configurations only.
pline_year
string
pline_owner
string
pline_license
string
cline_year
string
cline_owner
string
cline_license
string
keywords
string
Additional keywords to find this content by. Separate keywords with space. Use - or _ for compound words (i.e. 'funky-soul')
internal_synopsis
string
Summary information meant for internal use. This data is not passed to downstream systems or partners.
notes
string
Supplementary information meant for internal use. This data is not passed to downstream systems or partners.
distribution_group_id
string
rights_period
string
rights_expiry_rule
string
lost_rights
string
e.g. "The license has expired and you've lost the right to distribute this release"
lost_rights_on
string
lost_rights_reason
string
partner_restrictions
string
distribution_notes
string
license
string
track_listing_embargo
string
audio_embargo
string
cover_art_embargo
string
product_details_embargo
string
partners
partners
object
release_price_tier
string
track_price_tier
string
Digital configurations only.
primary_contributions
array of
primary_contributions
objects
primary_contributions.id
string
Unique ID of the record. The ID for each record is returned from the record's Search API, and appears in the browser URL when viewing the record in the application.
primary_contributions.artist
string
The primary artist associated with this record. Must exactly match the name of an existing Artist or a new one will be created.
primary_contributions.featured
string
contributions
array of
contributions
objects
contributions.id
string
Unique ID of the record. The ID for each record is returned from the record's Search API, and appears in the browser URL when viewing the record in the application.
contributions.artist
string
The primary artist associated with this record. Must exactly match the name of an existing Artist or a new one will be created.
contributions.role
string
contributions.type
string
More specific Type of Role the artist played. Valid type choice depends on role choice.
See role for list of valid options.
discs
array of
discs
objects
Discs associate tracks (via disc_tracks) to releases. A release may have 1 or more discs, and those discs may have 1 or more tracks (via disc_tracks).
discs.upc
string
Individual discs on multi-disc releases may sometimes have separate UPCs. They may be internal tracking UPCs rather than registered product UPCs.
discs.tracks
array of
tracks
objects
discs.tracks.title
string
discs.tracks.track_type
string
The configuration type of this Track
discs.tracks.display_title
string
discs.tracks.version_title
string
Version of Track (Example: Live)
discs.tracks.version_display_title
string
discs.tracks.genre
string
genre choice also determines valid sub_genre choices (if available)
discs.tracks.sub_genre
string or null
sub_genre choices (if available) are dependent on genre choice.
See genre for list of valid options.
discs.tracks.isrc
string
ISRC associated with this Track
discs.tracks.parental_advisory
string
A flag used to identify if a Track contains explicit material. This will impact any Release that contains this Track. 'Edited' represents the clean version.
discs.tracks.global_instant_grat_date
string
discs.tracks.global_prestream_date
string
discs.tracks.duration
string
discs.tracks.preview_in
string
discs.tracks.sample_length
string
discs.tracks.metadata_language
string
Language in which the metadata is written
discs.tracks.metadata_language_country
string
Country that the Metadata Language is associated with
discs.tracks.audio_language
string
Primary language of recorded audio
discs.tracks.audio_presentation
string
The format of the associated audio
discs.tracks.primary_recording_location
string
Location where audio was recorded
discs.tracks.other_recording_locations
array of
strings
discs.tracks.recording_end_date_year
string
The year in which the recording of this track was completed
discs.tracks.session_performance_type
string
Type of Performance of the recording
discs.tracks.session_type
string
Type of session of the recorded track. Can be Studio or Live.
discs.tracks.music_type
string
Type of Music (May impact available metadata fields)
discs.tracks.artist_display_name
string
discs.tracks.pline_year
string
discs.tracks.pline_owner
string
discs.tracks.pline_license
string
discs.tracks.cline_year
string
discs.tracks.cline_owner
string
discs.tracks.cline_license
string
discs.tracks.keywords
string
Additional keywords to find this content by. Separate keywords with space. Use - or _ for compound words (i.e. 'funky-soul')
discs.tracks.notes
string
Supplementary information meant for internal use. This data is not passed to downstream systems or partners.
discs.tracks.primary_contributions
array of
primary_contributions
objects
discs.tracks.primary_contributions.id
string
Unique ID of the record. The ID for each record is returned from the record's Search API, and appears in the browser URL when viewing the record in the application.
discs.tracks.primary_contributions.artist
string
The primary artist associated with this record. Must exactly match the name of an existing Artist or a new one will be created.
discs.tracks.primary_contributions.featured
string
discs.tracks.contributions
array of
contributions
objects
discs.tracks.contributions.id
string
Unique ID of the record. The ID for each record is returned from the record's Search API, and appears in the browser URL when viewing the record in the application.
discs.tracks.contributions.artist
string
The primary artist associated with this record. Must exactly match the name of an existing Artist or a new one will be created.
discs.tracks.contributions.role
string
discs.tracks.contributions.type
string
More specific Type of Role the artist played. Valid type choice depends on role choice.
See role for list of valid options.
discs.tracks.works
array of
works
objects
discs.tracks.works.title
string
discs.tracks.works.music_type
string
Type of Music (May impact available metadata fields)
discs.tracks.works.iswc
string
The International Standard Musical Work Code associated with this Work
discs.tracks.works.label_work_code
string
A code used internally to uniquely identify the release.
discs.tracks.works.copyright_year
string
discs.tracks.works.language
string
Language in which the Work is written
discs.tracks.works.agency
string
Royalty/licensing agency for this published Work (Example: BMI, ASCAP, Harry Fox).
discs.tracks.works.keywords
string
Additional keywords to find this content by. Separate keywords with space. Use - or _ for compound words (i.e. 'funky-soul')
discs.tracks.works.description
string
Full description of the Work
discs.tracks.works.contributions
array of
contributions
objects
discs.tracks.works.contributions.artist
string
The primary artist associated with this record. Must exactly match the name of an existing Artist or a new one will be created.
discs.tracks.works.contributions.id
string
Unique ID of the record. The ID for each record is returned from the record's Search API, and appears in the browser URL when viewing the record in the application.
discs.tracks.works.contributions.role
string
discs.tracks.works.contributions.affiliation
string
The affiliation
discs.tracks.works.contributions.split_percentage
string
The percentage split
discs.tracks.works.contributions.country
string
discs.tracks.works.publishers
array of
publishers
objects
discs.tracks.works.publishers.publisher
string
discs.tracks.works.publishers.id
string
Unique ID of the record. The ID for each record is returned from the record's Search API, and appears in the browser URL when viewing the record in the application.
discs.tracks.works.publishers.rights_administrator
string
The Rights Administrator
discs.tracks.works.publishers.affiliation
string
The affiliation
discs.tracks.works.publishers.split_percentage
string
The percentage split
discs.tracks.works.publishers.country
string
curl https://{subdomain}.openplaymusic.com/connect/v1/releases/ \
-u {API Key Id} \
-H "Content-Type: application/json" \
-d@./release.json
{
"title": "If That's What It Takes",
"configuration": "Digital Album",
"label": "Smooth Records Group",
"display_title": "Michael McDonald New Soul Classics",
"version_title": "API Version",
"version_display_title": "Special Edition",
"display_label": "Smooth Records Group, Inc.",
"sub_genre": null,
"series_name": "Soul Classics",
"release_date": "2022-03-11",
"release_time": "12:30:00",
"original_release_date": "1981-11-13",
"artist_display_name": "Michael McDonald & Friends",
"upc": "000000000017",
"catalog_number": "SRG00001",
"music_type": "pop",
"audio_language": "English",
"metadata_language": "English",
"metadata_language_country": "US",
"compilation_type": "Single-Artist Release",
"parental_advisory": "Non-Applicable",
"promotional": true,
"audio_presentation": "Stereo",
"pline_year": "1981",
"pline_owner": "Smooth Records Group",
"pline_license": "Under License",
"cline_year": "1981",
"cline_owner": "Smooth Records Group",
"cline_license": "Under License",
"keywords": "soul classics",
"internal_synopsis": "Digital bonus for limited edition blue vinyl",
"notes": "Also comes with free hat",
"distribution_group_id": 6002212,
"rights_period": "perpetuity",
"partner_restrictions": "Apple & Tower Records",
"distribution_notes": "Limited to 300 copies",
"license": "Owned",
"track_listing_embargo": "1981-11-05",
"primary_contributions": [
{
"artist": "Michael McDonald"
},
{
"artist": "Kenny Loggins",
"featured": true
}
],
"contributions": [
{
"artist": "Michael McDonald"
},
{
"artist": "Kenny Loggins"
}
],
"discs": [
{
"upc": "000000000024",
"tracks": [
{
"track_type": "audio",
"title": "Playin' by the Rules",
"display_title": "Playin' by the Rules Special Edition",
"version_title": "Bonus Edition",
"version_display_title": "Special Bonus Edition",
"sub_genre": null,
"isrc": "USOPM2200001",
"parental_advisory": "Non-Applicable",
"global_instant_grat_date": "2022-03-10",
"global_prestream_date": null,
"duration": "PT3M48S",
"preview_in": "PT43S",
"sample_length": "PT30S",
"metadata_language": "English",
"metadata_language_country": "United States",
"audio_language": "English",
"primary_recording_location": "US",
"other_recording_locations": [
"FR",
"DE"
],
"recording_end_date_year": "1981",
"session_performance_type": "Vocal",
"session_type": "Studio",
"music_type": "pop",
"audio_presentation": "Stereo",
"artist_display_name": "Michael McDonald & Friends",
"pline_year": "1981",
"pline_owner": "Smooth Records Group",
"pline_license": "Under License",
"cline_year": "1981",
"cline_owner": "Smooth Records Group",
"cline_license": "Under License",
"keywords": "modern r&b classics",
"notes": "Hat not included",
"primary_contributions": [
{
"artist": "Michael McDonald"
},
{
"artist": "Kenny Loggins",
"featured": true
},
{
"artist": "Ed Sanford",
"featured": true
}
],
"contributions": [
{
"artist": "Michael McDonald"
},
{
"artist": "Kenny Loggins"
}
],
"works": [
{
"title": "Playin' by the Rules Act 1",
"music_type": "pop",
"iswc": "T-123456789-0",
"label_work_code": "SRG-W-00001",
"copyright_year": 1981,
"language": "English",
"agency": "Harry Fox Agency",
"keywords": "pop soul hits",
"description": "Written by Michael McDonald and Ed Sanford, this is one of 7 acts in the Playin' by the Rules suite.",
"contributions": [
{
"artist": "Michael McDonald",
"role": "Author",
"affiliation": "ASCAP",
"split_percentage": 50,
"country": "Worldwide"
},
{
"artist": "Ed Sanford",
"role": "Composer",
"affiliation": "ASCAP",
"split_percentage": 30,
"country": "United States"
}
],
"publishers": [
{
"publisher": "Smooth Music Publishing Ltd.",
"rights_administrator": "Smooth Records Distribution Worldwide",
"affiliation": "ASCAP",
"split_percentage": 20,
"country": "Worldwide"
},
{
"publisher": "Smooth Music Publishing Ltd.",
"rights_administrator": "Smooth Records Distribution France",
"affiliation": "ASCAP",
"split_percentage": 50,
"country": "France"
}
]
},
{
"title": "Playin' by the Rules Act 2"
}
]
},
{
"track_type": "video",
"title": "I Keep Forgettin'"
}
]
},
{
"upc": "000000000031",
"tracks": [
{
"track_type": "audio",
"title": "Love Lies",
"global_prestream_date": "2022-03-09"
}
]
}
],
"partners": {
"excluded": false,
"partner_names": [
"Deezer",
"Spotify"
]
},
"release_price_tier": "Premium",
"track_price_tier": "Budget"
}
OpenPlay Platform Partner Deliveries are currently available only for OpenPlay Platform.
Partner Deliveries automatically package and send Release assets and metadata (as a DDEX package) to external partners whenever a Release is distributed, allowing you to customize your distribution workflow.
Partner Deliveries work similarly to Webhooks. They are configured with a URL for a desired recipient's webserver, then any time a Release is distributed OpenPlay will generate a full DDEX export of the Release metadata and assets and send an HTTP POST request to the configured URL with a link to download the package. This allows you to automate delivery of Release data to third-party partners, and allows them to automate their ingest process via OpenPlay.
Partner Deliveries are configured almost exactly like
Webhooks. The key
difference between the two is that the Partner Delivery will be
delivered with a url parameter in the
request body where the receiver can download the Release DDEX.
Refer to the Configuring Webhooks documentation for more about configuring Webhooks.
Partner Deliveries work exactly like Webhooks. Refer to the Receiving Webhooks documentation for more about Receiving Webhooks, the same setup applies to receiving a Partner Delivery.
Once configured the only difference between Webhooks and Partner
Deliveries is that the request body will have a
url parameter with a link to download
the Release DDEX package:
{
id: 93813,
mode: "live",
url: "https://op-music-xyz.s3.us-east-1.amazonaws.com/tmp/43cb5561-f761-9aa3-c0e6-af5351109cfa/00555555555555_20210422232304195.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKXY5EXAMPLEEXAMPLEA%2F20210422%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210422T232304Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&X-Amz-Signature=0cfaEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE22f7",
event: "release",
event_details: {
source: "OpenPlay Platform",
name: "release",
id: 8019382
},
release: {
"id": 93813,
"tenant_id": 483,
"upc": "555555555555"
}
}
Important The URL will expire in 72 hours, after which the file will no longer be available for download. The receiver must download the file within 72 hours.
The receiver should validate the sender and integrity of all Partner Deliveries using the same method as Webhooks. Refer to Securing Webhooks for details.
Partner Deliveries will always be sent every time a Release is approved for delivery in OpenPlay Platform, or in other words, every time a Release is released.
By default Partner Deliveries will also be sent every time a Release takedown is approved in OpenPlay Platform. This behavior can be configured for each Partner Delivery by checking or unchecking the Deliver Takedowns option.
The body of the Partner Delivery contains an event
key. The value of this key will indicate whether the Partner
Delivery is for a event: "release" event or a
event: "takedown" event.
The event_details key contains additional
details about the event. event_details.name
is the same as the event key.
event_details.id is the ID of the event,
which can be used to skip already-processed events in case of
network issues leading to retries.
Partner Deliveries for takedown events will also indicate a
takedown in the DDEX package by omitting a DealList
(and therefore sending no valid deals) with the DDEX delivery.