Status GET /status

This method returns the current server time.

Example request: http://api.7digital.com/1.2/status?country=GB&oauth_consumer_key=YOUR_KEY_HERE

Artist - browse by name GET /artist/browse

This method returns a list of artists from the 7digital catalogue whose names match the start letter(s) supplied.

Example request: http://api.7digital.com/1.2/artist/browse?letter=p&country=US&oauth_consumer_key=YOUR_KEY_HERE

Artist - chart GET /artist/chart

This method returns a territory-specific rolling weekly chart, based on the most purchased artists over the past 7 days.

Example request: http://api.7digital.com/1.2/artist/chart?oauth_consumer_key=YOUR_KEY_HERE&country=GB

Artist - details GET /artist/details

This method returns all available artist details.

Example request: http://api.7digital.com/1.2/artist/details?artistid=1&country=GB&oauth_consumer_key=YOUR_KEY_HERE

Artist - releases GET /artist/releases

This method returns a list of releases by given artist. Releases can be filtered by type.

Example request: http://api.7digital.com/1.2/artist/releases?artistid=1&oauth_consumer_key=YOUR_KEY_HERE&country=GB&pagesize=2&usageTypes=download,subscriptionstreaming,adsupportedstreaming

Method specific error codes:

1001 - Required parameter artistId is missing You must supply a value for the artistId parameter.

1003 - Requested page out of range You specified a page number which does not exist.

Artist - search GET /artist/search

This method returns a list of artists from the 7digital catalogue that match the search query.

Example request: http://api.7digital.com/1.2/artist/search?q=pink&sort=score%20desc&country=US&oauth_consumer_key=YOUR_KEY_HERE&pagesize=2

Method specific error codes:

1001 - Required parameter q is missing You must supply a value for the q parameter.

1003 - Requested page out of range You specified a page number which does not exist.

Artist - top tracks GET /artist/toptracks

This method returns a list of the most popular tracks by artist.

Example request: http://api.7digital.com/1.2/artist/toptracks?artistid=2&oauth_consumer_key=YOUR_KEY_HERE&country=GB&pagesize=2&usageTypes=download,subscriptionstreaming,adsupportedstreaming

Method specific error codes:

1001 - Required parameter artistId is missing You must supply a value for the artistId parameter.

1003 - Requested page out of range You specified a page number which does not exist.

Release - chart GET /release/chart

This endpoint returns a territory-specific rolling weekly chart, based on the most purchased releases over the past 7 days.

Example request: http://api.7digital.com/1.2/release/chart?oauth_consumer_key=YOUR_KEY_HERE&country=GB&pagesize=2&usageTypes=download,subscriptionstreaming,adsupportedstreaming

Method specific error codes:

1003 - Requested page out of range You specified a page number which does not exist.

Release - details GET /release/details

This method returns all available details for a given release.

Example request: http://api.7digital.com/1.2/release/details?releaseid=1046&oauth_consumer_key=YOUR_KEY_HERE&country=GB&usageTypes=download,subscriptionstreaming,adsupportedstreaming

Method specific error codes:

2001 - Release id not licensed for this partner The copyright for the release you requested is owned by a label not currently licensed for your service.

Release - details (batch) GET /release/details/batch

Return details of multiple releases in one request. In the request, releases are identified by release id. There will be one release in the response for every corresponding valid id in the request, and the releases will be in the same order as the requested ids. Releases that are not valid for any reason are omitted from the releases list in the response. They will be included in the errors list, in order, if showErrors is set true.

Example request: https://api.7digital.com/1.2/release/details/batch?releaseids=12345,12346,12347&showerrors=true&oauth_consumer_key=YOUR_KEY_HERE&country=GB&usageTypes=download,subscriptionstreaming,adsupportedstreaming

Method specific error codes:

1001 - Required parameter releaseIds is missing You must supply a value for the releaseIds parameter.

1002 - Invalid value for parameter releaseIds You must supply a comma-separated list of release ids.

Release - search GET /release/search

This method searches the 7digital catalogue for releases matching the search query. Results can be filtered by release type.

Example request: http://api.7digital.com/1.2/release/search?q=no%20surprises&oauth_consumer_key=YOUR_KEY_HERE&country=GB&pagesize=2&usageTypes=download,subscriptionstreaming,adsupportedstreaming

Method specific error codes:

1001 - Required parameter q is missing You must supply a value for the q parameter.

1002 - Invalid value in package ids You must supply only a single integer, or a comma-delimited list of integers for the packageIds parameter. Package ids are listed here.

1003 - Requested page out of range You specified a page number which does not exist.

Release - track listing GET /release/tracks

This method will return a list of all tracks constituting the release.

Example request: http://api.7digital.com/1.2/release/tracks?releaseid=1046&oauth_consumer_key=YOUR_KEY_HERE&country=GB&usageTypes=download,subscriptionstreaming,adsupportedstreaming

Method specific error codes:

2001 - Release id not licensed for this partner The copyright for the release you requested is owned by a label not currently licensed for your service.

Track - chart GET /track/chart

This endpoint returns a territory-specific rolling weekly chart, based on the most purchased tracks over the past 7 days.

Example request: http://api.7digital.com/1.2/track/chart?oauth_consumer_key=YOUR_KEY_HERE&country=GB&pagesize=2&usageTypes=download,subscriptionstreaming,adsupportedstreaming

Method specific error codes:

1003 - Requested page out of range You specified a page number which does not exist.

Track - details GET /track/details

This method returns various track details such as title, duration and price.

Example request: http://api.7digital.com/1.2/track/details?trackid=123456&oauth_consumer_key=YOUR_KEY_HERE&country=GB&usageTypes=download,subscriptionstreaming,adsupportedstreaming

Method specific error codes:

2001 - Track id not licensed for this partner The copyright for the track you requested is owned by a label not currently licensed for your service.

Track - details (batch) GET /track/details/batch

Return details of multiple tracks in one request. In the request, tracks are identified by track id. There will be one track in the response for every corresponding valid id in the request, and the tracks will be in the same order as the requested ids. Tracks that are not valid for any reason are omitted from the tracks list in the response. They will be included in the errors list, in order, if showErrors is set true.

Example request: https://api.7digital.com/1.2/track/details/batch?trackids=2146,1347&showerrors=true&oauth_consumer_key=YOUR_KEY_HERE&country=GB&usageTypes=download,subscriptionstreaming,adsupportedstreaming

Method specific error codes:

1001 - Required parameter trackIds is missing You must supply a value for the trackIds parameter.

1002 - Invalid value for parameter trackIds You must supply a comma-separated list of track ids.

Track - search GET /track/search

This method will search for a track that matches the supplied search query. The following fields will be searched on: track title, artist name, release title and track ISRC.

Example request: http://api.7digital.com/1.2/track/search?q=Happy&oauth_consumer_key=YOUR_KEY_HERE&country=GB&pagesize=2&usageTypes=download,subscriptionstreaming,adsupportedstreaming

Method specific error codes:

1001 - Required parameter q is missing You must supply a value for the q parameter.

1002 - Invalid value in package ids You must supply only a single integer, or a comma-delimited list of integers for the packageIds parameter. Package ids are listed here.

1003 - Requested page out of range You specified a page number which does not exist.

Tag (genre) - list all GET /tag

This method returns a list of all available tags.

Example request: http://api.7digital.com/1.2/tag?oauth_consumer_key=YOUR_KEY_HERE&country=GB

Tag - artist tags GET /artist/tags

This method returns all tags associated with the given artist.

Example request: http://api.7digital.com/1.2/artist/tags?artistid=1&oauth_consumer_key=YOUR_KEY_HERE&country=GB

Tag - top artists GET /artist/bytag/top

This method returns a list of most popular artists tagged by a given tag or list of tags. If multiple tags are supplied only artists matching all of them will be returned.

Example request: http://api.7digital.com/1.2/artist/bytag/top?tags=rock,pop,2000s&oauth_consumer_key=YOUR_KEY_HERE&country=GB&pagesize=2

Method specific error codes:

2001 - None of the provided tag(s) exist. The tags you supplied do not exist.

1003 - Requested page out of range You specified a page number which does not exist.

Tag - release tags GET /release/tags

This method returns all tags associated with the given release.

Example request: http://api.7digital.com/1.2/release/tags?releaseid=155408&oauth_consumer_key=YOUR_KEY_HERE&country=GB

Tag - new releases GET /release/bytag/new

This endpoint returns a list of releases matching a specified genre, ordered by most recent release date.

Example request: http://api.7digital.com/1.2/release/bytag/new?tags=rock&page=2&pageSize=2&oauth_consumer_key=YOUR_KEY_HERE&country=GB&usageTypes=download,subscriptionstreaming,adsupportedstreaming

Method specific error codes:

2001 - None of the provided tag(s) exist The tags you supplied do not exist.

1003 - Requested page out of range You specified a page number which does not exist.

Tag - top releases GET /release/bytag/top

This endpoint returns a list of releases ordered by popularity, for a specified genre.

Example request: http://api.7digital.com/1.2/release/bytag/top?tags=rock&page=1&pageSize=2&oauth_consumer_key=YOUR_KEY_HERE&country=GB&usageTypes=download,subscriptionstreaming,adsupportedstreaming

Method specific error codes:

2001 - None of the provided tag(s) exist The tags you supplied do not exist.

Stream from locker GET /stream/locker

Allows user to stream a previously purchased track from their locker. This endpoint can be used for online plays or offline caching (for plays when the device isn't connected to the Internet). Endpoint's full location: https://stream.svc.7digital.net/stream/locker

Example request: https://stream.svc.7digital.net/stream/locker?country=GB&userid=1234&trackid=123456&formatid=??...

Method specific error codes:

1001 - Error: Missing "parameter name" query parameter. Not all mandatory parameters were specified in the request.

1002 - Invalid value for "parameter name": parameter value. Value for parameter in error message is not valid.

2001 - Track not found. This track isn't available for streaming in your country or shop.

2002 - Pre-release or license availability. Either the requested track is not in the user's locker, or the track is not available for streaming (note that streaming release dates may differ from download or catalogue streaming release dates).

Stream any track (radio use) GET /stream/catalogue

Allows user to stream any track in the 7digital catalogue available in their region. This endpoint is designed for radio style play where individual tracks cannot be selected by the user (i.e. "non-interactive" streaming), and is licensed differently than other streaming endpoints. Tracks can be cached (in an encrypted format) on the end user's device, but all plays from either the cache or live must be reported with the catalogue/log endpoint. Please contact us for more details. Endpoint's full location: https://stream.svc.7digital.net/stream/catalogue

Example request: https://stream.svc.7digital.net/stream/catalogue?country=US&trackid=123456&formatid=??

Method specific error codes:

1001 - Error: Missing "parameter name" query parameter. Not all mandatory parameters were specified in the request.

1002 - Invalid value for "parameter name": parameter value. Value for parameter in error message is not valid.

2001 - Track not found. This track isn't available for streaming in your country or shop.

2002 - Pre-release availability. The track is not available for radio streaming (note that release dates may differ from subscription/locker streaming release dates).

Stream to subscriber GET /stream/subscription

Allows user to stream any track available for streaming in their region, as long as they have a valid subscription account already set up with our subscription system (billed either by 7digital or your system).

This endpoint should only be used when a given device is actively connected to the Internet. For local caching in bulk, to be used for offline plays, see offline/subscription. Tracks can be cached (in an encrypted format) on the end user's device, but all plays from either the cache or live must be reported with the user/subscription/log endpoint.

When the clientId parameter is supplied, mulitple devices will not be allowed to stream concurrently. Device A can start streaming, but if Device B starts, Device A will finish its current track then be blocked from playing again for a short time period. After that time period, Device A can play again, and Device B will become blocked.

Endpoint's full location: https://stream.svc.7digital.net/stream/subscription

Example request: https://stream.svc.7digital.net/stream/subscription?country=GB&userid=1234&trackid=123456&formatid=??

Method specific error codes:

1001 - Error: Missing "parameter name" query parameter. Not all mandatory parameters were specified in the request.

1002 - Invalid value for "parameter name": parameter value. Value for parameter in error message is not valid.

2001 - Track not found. This track isn't available for streaming in your country or shop.

2002 - Pre-release or subscription availability. Either the user does not have a valid subscription account with us, or the track is not available for streaming (note that streaming release dates may differ from download or catalogue streaming release dates).

3201 - Simultaneous stream requests from multiple locations - streaming access temporarily disabled. When the clientId parameter is supplied, mulitple devices will not be allowed to stream concurrently (see endpoint description above for more information).

Stream to subscriber - offline GET /offline/subscription

Allows user to stream any track available for streaming in their region, as long as they have a valid subscription account already set up with our subscription system and their device is registered for offline play with the user/unlimitedStreaming/offline endpoint.

This endpoint should only be used when a given device is caching for offline track play (where it won't be connected to the Internet).

All plays done during offline mode must be reported to the user/subscription/log endpoint as soon as Internet connectivity is restored.

Endpoint's full location: https://stream.svc.7digital.net/offline/subscription

Example request: https://stream.svc.7digital.net/offline/subscription?country=US&userid=1234&trackid=123456&formatid=??&clientId=123

Method specific error codes:

1001 - Error: Missing "parameter name" query parameter. Not all mandatory parameters were specified in the request.

1002 - Invalid value for "parameter name": parameter value. Value for parameter in error message is not valid.

2001 - Track not found. This track isn't available for streaming in your country or shop.

2002 - Pre-release or subscription availability. Either the user does not have a valid subscription account with us, or the track is not available for streaming (note that streaming release dates may differ from download or catalogue streaming release dates).

Authorise device for off-line streaming POST /user/unlimitedStreaming/offline

Used to authorise a device for offline mode. After authorised, a device can download in bulk from the offline/subscription endpoint. The POST body can be sent in either XML or JSON formats.

Example request: POST http://api.7digital.com/1.2/user/unlimitedStreaming/offline?oauth_consumer_key=YOUR_KEY_HERE&oauth_token=... With body: <offlineStatus> <userId>1234</userId> <clientId>e5ada89d-db5b-4d0e-b70b-820796d7d583</clientId> <offlineEnabled>true</offlineEnabled> <country>GB</country> </offlineStatus>

Method specific error codes:

1002 - "parameter name": "reason" User did not specify valid value for mandatory parameter. Check the message for more details.

1003 - This account type cannot register offline device/Maximum number of offline devices registered Client was not successfully registered for offline playback. Check the message for more details.

Device status for off-line streaming GET /user/unlimitedStreaming/offline

Used to check the offline status of a specified device. This status can be changed with a POST to the user/unlimitedStreaming/offline endpoint.

Example request: http://api.7digital.com/1.2/user/unlimitedStreaming/offline?oauth_consumer_key=YOUR_KEY_HERE&clientId=xyz&oauth_token=...

Method specific error codes:

1001 - Missing parameter "parameter name" Not all mandatory parameters were specified in the request.

Devices authorised for off-line streaming GET /user/offlineclients

Used to get list of all of a user's registered devices.

Example request: http://api.7digital.com/1.2/user/offlineclients?oauth_consumer_key=YOUR_KEY_HERE&oauth_token=...

Report a subscriber stream POST /user/subscription/log

Multiple plays can be batched by user into a single POST to this endpoint, and the body can be sent in either XML or JSON formats. Streams that are requested as part of pre-fetching functionality, but never played on the device, should still be logged with a zero second play time.

Situations on when you should and should not log to this endpoint:

Plays from stream/subscription:

Online from our servers: log using this endpoint

Cached on the device (after playing once from our servers): log using this endpoint

Plays from offline/subscription:

Online from our servers (being downloaded for later play, not actively playing from this endpoint): do not log

Cached on the device (after downloading once from our servers): log using this endpoint

Plays from stream/locker:

Online from our servers: do not log

Cached on the device (after playing once from our servers): do not log

XML POST body:

<playLog>
  <playLogItem>
    <trackId>123456</trackId>
    <releaseId>123456</releaseId>
    <formatId>50</formatId>
    <playMode>online</playMode>
    <dateTimePlayed>2014-03-13T11:39:28.8981203Z</dateTimePlayed>
    <totalTimePlayed >12</totalTimePlayed>
    <userAgent>Device version 3, App version 6</userAgent>
  </playLogItem>
</playLog>

JSON POST body:

{
  "playLogItem": [
    {
      "trackId": 123456,
      "releaseId": 123456,
      "formatId": 50,
      "playMode": "online",
      "dateTimePlayed": "2014-03-13T11:39:28.8981203Z",
      "totalTimePlayed": 6,
      "userAgent": "Device version 3, App version 6"
    }
  ]
}

Example request: POST http://api.7digital.com/1.2/user/subscription/log?country=GB&oauth_consumer_key=YOUR_KEY_HERE&oauth_token=...

Method specific error codes:

1003 - User has never had a subscription The user you're trying to log plays for has never had a subscription account in our system (active or not) and therefore couldn't have streamed a subscription track with us.

Report a catalogue stream POST /catalogue/log

Multiple plays (maximum of 100 per request) can be batched into a single POST to this endpoint, and the body can be sent in either XML or JSON formats. Streams that are requested as part of pre-fetching functionality, but never played on the device, should still be logged with a zero second play time.

Situations in which you should log to this endpoint:

Plays from stream/catalogue:

Online from our servers: log using this endpoint

Cached on the device (after playing once from our servers): log using this endpoint

XML POST body:

<playLog>
  <playLogItem>
    <trackId>123456</trackId>
    <releaseId>123456</releaseId>
    <formatId>50</formatId>
    <dateTimePlayed>2014-03-13T11:39:28.8981203Z</dateTimePlayed>
    <totalTimePlayed>12</totalTimePlayed>
    <userAgent>Device version 3, App version 6</userAgent>
    <userId>135</userId>
    <endReason>naturalEnd</endReason>
  </playLogItem>
</playLog>

JSON POST body:

{
  "playLogItem": [
    {
      "endReason": "naturalEnd",
      "userId": "135",
      "userAgent": "Device",
      "totalTimePlayed": "12",
      "dateTimePlayed": "2016-12-19T11:39:28.8981203Z",
      "formatId": "55",
      "releaseId": "5424335",
      "trackId": "54825860"
    }
  ]
}

Example request: POST http://api.7digital.com/1.2/catalogue/log?country=US&oauth_consumer_key=YOUR_KEY_HERE&...

Report a preview stream POST /preview/log

Multiple plays can be batched into a single POST to this endpoint, and the body can be sent in either XML or JSON formats. Previews that are requested as part of pre-fetching functionality, but never played on the device, should still be logged with a zero second play time.

A country parameter is required in the query string. This is for OAuth authorisation, and must be a country your API key has access to. The country property in the POST body is the location in which the user played the clip.

The maximum accepted POST body size is limited to 100KiB.

An HTTP non-200 response means we have not fully saved the logs. Please retry the request, with an increasing backoff with any successive failures.

XML POST body:

<logs>
  <log>
    <country>US</country>
    <trackId>123456</trackId>
    <dateTimePlayed>2014-03-13T11:39:28.8981203Z</dateTimePlayed>
    <totalTimePlayed>12</totalTimePlayed>
    <userAgent>Device version 3, App version 6</userAgent>
    <userId>135</userId>
    <playMode>online</playMode>
  </log>
</logs>

JSON POST body:

{
  "logs": [
    {
      "country": "US",
      "trackId": 123456,
      "dateTimePlayed": "2014-03-13T11:39:28.8981203Z",
      "totalTimePlayed": 12,
      "userAgent": "Device version 3, App version 6",
      "userId": "135",
      "playMode":"online"
    }
  ]
}

Example request: POST http://api.7digital.com/1.2/preview/log?country=GB&oauth_consumer_key=YOUR_KEY_HERE&...

Download track GET /user/downloadtrack

Allows the user to download a purchased track. Endpoint's full location: http://media.geo.7digital.com/media/user/downloadtrack

Example request: http://media.geo.7digital.com/media/user/downloadtrack?trackid=123456&releaseid=123456&formatid=17&country=GB&errorUrl=http%3a%2f%2fexample.com%2ferror&oauth_consumer_key=YOUR_KEY_HERE&...

Method specific error codes:

1001 - Error: Missing "parameter name" query parameter. Not all mandatory parameters were specified in the request.

1002 - Invalid value for "parameter name": parameter value Value for parameter in error message is not valid.

2002 - No licences found for the download request. Either the track ID supplied does not exist or has not been purchased by the user supplied, or the user does not exist, or the track is no longer available for download.

Download release (ZIP) GET /user/download/release

Allows a user to download tracks in a purchased release as a single ZIP file. Endpoint's full location: http://media.geo.7digital.com/media/user/download/release

Example request: http://media.geo.7digital.com/media/user/download/release?releaseid=123456&country=US&oauth_consumer_key=YOUR_KEY_HERE&...

Method specific error codes:

1001 - Error: Missing "parameter name" query parameter. Not all mandatory parameters were specified in the request.

1002 - Invalid value for "parameter name": parameter value Value for parameter in error message is not valid.

2002 - No licences found for the download request. Either the release Id supplied does not exist or has not been purchased by the user supplied, or the user does not exist.

Download purchase (ZIP) GET /user/download/purchase

Allows a user to download tracks purchased in a transaction as a single ZIP file. The highest quality available for each track will be used. Endpoint's full location: http://media.geo.7digital.com/media/user/download/purchase

Example request: http://media.geo.7digital.com/media/user/download/purchase?purchaseId=123456&country-US&oauth_consumer_key=YOUR_KEY_HERE&...

Method specific error codes:

1001 - Error: Missing "parameter name" query parameter. Not all mandatory parameters were specified in the request.

1002 - Invalid value for "parameter name": parameter value Value for parameter in error message is not valid.

2002 - No licences found for the download request. Either the purchase Id supplied does not exist or does not belong to the user supplied, or the user does not exist.

Play preview clip GET /clip/{trackId}

If authorisation is successful the bytes for the clip will be returned to the client. Request url should not be stored for reuse since it expires. Endpoint's full location: http://previews.7digital.com/clip

Example request: http://previews.7digital.com/clip/1234?oauth_consumer_key=YOUR_KEY_HERE&country=GB&...

Method specific error codes:

HTTP: 404 - Track not found: {reason}. The requested track does not have a preview available.

HTTP: 401 - Error: Authorisation failed. The request could not be authorised successfully.

HTTP: 400 - Invalid trackId. The trackId specified is not in a valid format.

HTTP: 400 - Required parameter Country or ShopId is missing. The country/shopId parameter is missing.

Users' locker GET /user/locker

Returns a paged list of releases and tracks for a user's locker (collection of all purchased tracks).

Download limits - several licensors restrict the number of times their content can be re-downloaded. This is indicated in the lockerTrack.remainingDownloads property. If the value reaches 0 then the given track can't be re-downloaded anymore (download attempts resulting in an error message). Given the download limits vary from licensor to licensor we DO NOT recommend to display the remaining downloads to end users to avoid confusion. But we DO recommend to disable the download button (and provide an explanatory message) when all downloads have been used up. To improve end user experience you can also display a friendly warning when only 1 last re-download remains. Streaming from locker does not affect remaining downloads and tracks with their re-download limits used up can still be streamed.

Availability - in some cases releases might be removed from the 7digital catalogue (or from a particular service only), this is indicated in the lockerRelease.available property. If the value is set to false all tracks from this release in the user's locker are no longer available for re-download. In these cases, properties that are irrelevant to unavailable content, such as download, downloadUrls and remainingDownloads will no longer be available on the release:

Example of a taken down release in XML:

<lockerRelease>
    <release id="662888">
        <title>Do You Want The Truth Or Something Beautiful?</title>
        <version>Live From BBC 1's Radio Live Lounge</version>
        <type>Single</type>
        <barcode>884977432688</barcode>
        <artist id="329482">
            <name>Paloma Faith</name>
            <appearsAs>Paloma Faith</appearsAs>
            <slug>paloma-faith</slug>
        </artist>
        <slug>do-you-want-the-truth-or-something-beautiful-2</slug>
        <image>http://artwork-cdn.7static.com/static/img/sleeveart/00/006/628/2888_50.jpg</image>
        <label id="1085">
            <name>Epic</name>
        </label>
        <licensor id="2">
            <name>Sony Music</name>
        </licensor>
    </release>
    <lockerTracks>
        <lockerTrack>
            <track id="7352778">
                <title>Do You Want The Truth Or Something Beautiful?</title>
                <version>Jonny L Remix</version>
                <artist id="329482">
                    <name>Paloma Faith</name>
                    <appearsAs>Paloma Faith</appearsAs>
                    <slug>paloma-faith</slug>
                </artist>
                <trackNumber>3</trackNumber>
                <duration>335</duration>
                <isrc>GBARL0901537</isrc>
                <discNumber>1</discNumber>
                <number>3</number>
            </track>
            <purchaseId>0</purchaseId>
            <purchaseDate>2010-01-13T21:19:58.81Z</purchaseDate>
            <completeAlbumPurchase>false</completeAlbumPurchase>
        </lockerTrack>
    </lockerTracks>
    <available>false</available>
</lockerRelease>

Example of a taken down release in JSON:

"lockerRelease": [
    {
        "release": {
            "id": 662888,
            "title": "Do You Want The Truth Or Something Beautiful?",
            "version": "Live From BBC 1's Radio Live Lounge",
            "type": "Single",
            "barcode": "884977432688",
            "artist": {
                "id": 329482,
                "name": "Paloma Faith",
                "appearsAs": "Paloma Faith",
                "slug": "paloma-faith"
                    },
            "slug": "do-you-want-the-truth-or-something-beautiful-2",
            "image": "http://artwork-cdn.7static.com/static/img/sleeveart/00/628/88_50.jpg",
            "label": {
                "id": 1085,
                "name": "Epic"
            },
            "licensor": {
                "id": 2,
                "name": "Sony Music"
            }
        },
        "lockerTracks": {
            "lockerTrack": [
                {
                    "track": {
                        "id": 7352778,
                        "title": "Do You Want The Truth Or Something Beautiful?",
                        "version": "Jonny L Remix",
                        "artist": {
                            "id": 329482,
                            "name": "Paloma Faith",
                            "appearsAs": "Paloma Faith",
                            "slug": "paloma-faith"
                        },
                        "trackNumber": 3,
                        "duration": 335,
                        "isrc": "GBARL0901537",
                        "disc": 1,
                        "number": 3
                    },
                    "purchaseId": 0,
                    "purchaseDate": "2010-01-13T21:19:58.81Z",
                    "completeAlbumPurchase": false,
                    "downloadUrls": null
                }
            ]
        },
        "available": false
    }
]

Any attempts to download (or stream) these tracks will result in an error page being returned by the relevant media delivery endpoint (instead of the actual media file). We recommend not to provide a download (or play) button in the end user interface (or disable/grey it out) for any releases with lockerRelease.available set to false.

Example request: http://api.7digital.com/1.2/user/locker?country=GB&sort=purchaseDate%20desc&oauth_token=...

Get editorial list GET /editorial/list

Returns a curated list of artists, albums or tracks. Available editorial lists are described in the table below. Please note that some lists might be empty for certain countries and/or at certain times in which case the list should not be displayed to users and we recommend to replace the empty list with the next editorial list in prominence order.

Currently, the curated lists accessible through this endpoint are put together with download services in mind, so the returned content might not be available for other business models.

The following lists are currently published by our team:

Example request:

GET http://api.7digital.com/1.2/editorial/list?key=new-albums&country=GB&oauth_consumer_key=YOUR_KEY_HERE

Method specific error codes:

1001 - Required parameter missing
Not all mandatory parameters have been provided.

2001 - The list was not found
List with given key has not been found.

Get editorial content for release GET /release/editorial

This method returns editorial content for the given release. This includes reviews written by our editorial team (~100 words) and recommendations suggested by employees of 7digital (~70 words).

Example request:

GET http://api.7digital.com/1.2/release/editorial?releaseid=1279755&oauth_consumer_key=YOUR_KEY_HERE&country=US&lang=en

Retrieve playlist GET /playlists/{playlistId}

Returns playlist details and track listing.

Access to private playlists is only allowed when an oauth_token or userId of the playlist owner is provided, or the partner owns the playlist.

Example request: http://api.7digital.com/1.2/playlists/51ed5cfec9021614f462bb7b?oauth_consumer_key=YOUR_KEY_HERE

Replace playlist POST /playlists/{playlistId}

Replaces a playlist at {playlistId} with the supplied playlist.

This method is intended to be used when multiple changes have been made to playlist off-line. If the user is online each individual change to playlist should be submitted as it happens, using the endpoints for modifying playlist details, adding and deleting individual tracks.

A status can be any custom string, that you can use to filter on at a later date using the ~/playlists request.

Example request: POST http://api.7digital.com/1.2/playlists/51ed5cfec9021614f462bb7b Authorization: OAuth realm="...", oauth_consumer_key="YOUR_KEY_HERE", oauth_token="..." Content-type: application/json { "name": "party time", "status": "published", "visibility": "Public", "imageUrl": "http://artwork-cdn.7static.com/static/img/sleeveart/00/004/963/0000496338_$size$.jpg", "description": "Hits to get the party started", "tracks" : [ { "trackId" : "5495893", "trackTitle" : "No You Girls", "trackVersion" : "Trentmoller Remix", "artistAppearsAs" : "Franz Ferdinand", "releaseId" : "496338", "releaseTitle" : "No You Girls Remixes Part 2", "releaseArtistAppearsAs" : "Franz Ferdinand", "releaseVersion" : "Digital Download", "source" : "7digital" }], "annotations" : { "key" : "value", "anotherkey" : "another value" } }

Delete playlist DELETE /playlists/{playlistId}

Deletes the playlist at {playlistId}.

This action is irreversible - deleted playlists can't be recovered. We advise you to ask users for confirmation or delay calling the API by couple of seconds whilst providing users with option to undo their action.

Example request: DELETE http://api.7digital.com/1.2/playlists/51ed5cfec9021614f462bb7b

Playlist details GET /playlists/{playlistId}/details

Returns details of given playlist without including all playlist tracks in the response.

Example request: http://api.7digital.com/1.2/playlists/51ed5cfec9021614f462bb7b/details?oauth_consumer_key=YOUR_KEY_HERE

Update playlist details POST /playlists/{playlistId}/details

Updates playlist details at {playlistId} with the supplied playlist details.

It does not affect playlist tracks. Use this method e.g. for changing visibility of the playlist from private to public.

Descriptions are limited to 500 characters. Descriptions over this length are truncated.

Example request: POST http://api.7digital.com/1.2/playlists/51ed5cfec9021614f462bb7b/details Authorization: OAuth realm="...", oauth_consumer_key="YOUR_KEY_HERE", oauth_token="..." Content-type: application/json { "name": "party time", "visibility": "Public", "imageUrl": "http://artwork-cdn.7static.com/static/img/sleeveart/00/004/963/0000496338_$size$.jpg", "description": "Laid back listening", "annotations": { "key": "value" } }

List playlist tracks GET /playlists/{playlistId}/tracks

Returns tracks of given playlist, and allows for pagination.

Example request: http://api.7digital.com/1.2/playlists/51ed5cfec9021614f462bb7b/tracks?page=1&pagesize=2&oauth_consumer_key=YOUR_KEY_HERE

Add tracks to playlist POST /playlists/{playlistId}/tracks

Adds an array of tracks to the playlist at {playlistId}.

All metadata (e.g. track title, artist, etc) for tracks needs to be provided in the API call.

The "source" property is optional, and defaults to 7digital. This relates to the audioUrl and image response and can be used to indicate a different source for the physical file, it can be any string you want as long as the application you use to add the track can understand it.

The "audioUrl" property is optional and allows you to specify a different source for the physical file e.g. source="local" and audioUrl="file://a.specific.file.location.mp3" could mean that the consuming application understands how to handle a file stored at the given audioUrl.

It is advisable that you only use these extra parameters if you need to use them. It's also advisable if you are accessing public playlists that some tracks may not be playable by your application, so we would advise including an option to hide, grey out non source=7digital tracks.

Example request: POST http://api.7digital.com/1.2/playlists/51ed5cfec9021614f462bb7b/tracks Authorization: OAuth realm="...", oauth_consumer_key="YOUR_KEY_HERE", oauth_token="..." Content-type: application/json [{ "trackId" : "5495893", "trackTitle" : "No You Girls", "trackVersion" : "Trentmoller Remix", "artistAppearsAs" : "Franz Ferdinand", "releaseId" : "496338", "releaseTitle" : "No You Girls Remixes Part 2", "releaseArtistAppearsAs" : "Franz Ferdinand", "releaseVersion" : "Digital Download", "source" : "7digital" }, { "trackId" : "3121833", "trackTitle" : "Kids", "trackVersion" : "", "artistAppearsAs" : "MGMT", "releaseId" : "280218", "releaseTitle" : "Oracula Spectacular", "releaseArtistAppearsAs" : "MGMT", "releaseVersion" : "", "source" : "local", "audioUrl" : "file://a.specific.file.location.mp3" }]

Remove tracks DELETE /playlists/{playlistId}/tracks/{playlisttrackid}

Removes the specified track {playlisttrackid} from the specified playlist at {playlistId}.

Example request: DELETE http://api.7digital.com/1.2/playlists/51ed5cfec9021614f462bb7b/tracks/52cd88c2c902161660aeab81?oauth_consumer_key=YOUR_KEY_HERE&oauth_token=...

Move tracks POST /playlists/{playlistId}/tracks/{playlisttrackid}/move

Moves the specified track {playlisttrackid} from the specified playlist at {playlistId}, to a location dictated by the "pos" parameter of the POST request data.

The "pos" parameter is the playlistTrackId of the track you wish your selected track to appear AFTER. A value of "0" indicates you wish to place the track at the front of the list.

NOTE: Tracks can also be rearranged at the client side and then posted back to the ~/playlists/{playlistId} endpoint, this offers a lightweight way of doing the same thing.

Example request: POST http://api.7digital.com/1.2/playlists/51ed5cfec9021614f462bb7b/tracks/524ae1a1c90216252c1837ab/move Authorization: OAuth realm="...", oauth_consumer_key="YOUR_KEY_HERE", oauth_token="..." Content-type: application/json {"pos" : "524ae1a1c90216252c1837cd"}

Example request: POST http://api.7digital.com/1.2/playlists/51ed5cfec9021614f462bb7b/tracks/524ae1a1c90216252c1837ab/move Authorization: OAuth realm="...", oauth_consumer_key="YOUR_KEY_HERE", oauth_token="..." Content-type: application/x-www-form-urlencoded pos=524ae1a1c90216252c1837cd

List playlists GET /playlists

Returns a list of the partner's playlists.

See /user/playlist API method for alternate way of listing only playlists owned by current user.

Query parameters when passed act as an AND rather than an OR

Create playlist POST /playlists

Creates a new playlist tied to your partner consumer key.

When creating a new playlist you can provide an inital track listing in the request or create an empty playlists by leaving the "tracks" array empty.

Descriptions are limited to 500 characters. Descriptions over this length are truncated.

A status can be any custom string, and can be used to filter playlists by a single status (e.g. ~/playlists?status=mycustomstatus)

When adding a track to a playlist there are certain properties you can specify, see playlists/{playlistId}/tracks for details

Example request: POST http://api.7digital.com/1.2/playlists Authorization: OAuth realm="...", oauth_consumer_key="YOUR_KEY_HERE" Content-type: application/json { "name" : "party time", "visibility" : "Public", "tracks" : [{ "trackId" : "5495893", "trackTitle" : "No You Girls", "trackVersion" : "Trentmoller Remix", "artistAppearsAs" : "Franz Ferdinand", "releaseId" : "496338", "releaseTitle" : "No You Girls Remixes Part 2", "releaseArtistAppearsAs" : "Franz Ferdinand", "releaseVersion" : "Digital Download", "imageUrl": "http://artwork-cdn.7static.com/static/img/sleeveart/00/003/865/0000386513_$size$.jpg", "description": "A chillout playlist for relaxing to", "source" : "7digital" }], "annotations" : { "key" : "value", "anotherkey" : "another value" } }

Retrieve playlist tags GET /playlists/tags

Return a list of unique tags that have been added to a partner's playlists.

Tags are returned ordered by the order saved in the ~/playlists/tags POST endpoint, or alphabetically if no order is saved.

Example request: http://api.7digital.com/1.2/playlists/tags?oauth_consumer_key=YOUR_KEY_HERE&oauth_token=...

Save playlist tags POST /playlists/tags

Saves the visibility and order of tags against each other for a shop and partner. Any previous order is overwritten.

Example request: POST http://api.7digital.com/1.2/playlists/tags Authorization: OAuth realm="...", oauth_consumer_key="YOUR_KEY_HERE" Content-type: application/json { "shopId" : 34, "tags" : [{ "name" : "tag1", "hidden" : true }, { "name" : "tag2", "hidden" : false }] }

Favourite playlist PUT /playlists/{playlistId}/favourites/{userId}

Favourite the playlist at {playlistId} for user at {userId}. Only partner playlists can be favourited.

Example request: PUT http://api.7digital.com/1.2/playlists/51ed5cfec9021614f462bb7b/favourites/123?oauth_consumer_key=YOUR_KEY_HERE&oauth_token=...

Unfavourite playlist DELETE /playlists/{playlistId}/favourites/{userId}

Unfavourite the playlist at {playlistId} for user at {userId}. Only partner playlists can be favourited.

Example request: DELETE http://api.7digital.com/1.2/playlists/51ed5cfec9021614f462bb7b/favourites/123?oauth_consumer_key=YOUR_KEY_HERE&oauth_token=...

Retrieve user's playlists GET /user/playlists

Return a list of playlists owned by current user (identified by the provided access token).

Example request: http://api.7digital.com/1.2/user/playlists?oauth_consumer_key=YOUR_KEY_HERE&oauth_token=...

Retrieve a user's playlist groups GET /user/playlists/groups

Returns a list of a users playlist groups

Example request: http://api.7digital.com/1.2/user/playlists/groups?oauth_consumer_key=YOUR_KEY_HERE&oauth_token=...

Create playlist group POST /user/playlists/groups

Generates a new playlist group by supplying the following example request payload

Example request: POST http://api.7digital.com/1.2/user/playlists/groups Authorization: OAuth realm="...", oauth_consumer_key="YOUR_KEY_HERE", oauth_token="..." Content-type: application/json { "name" : "My Mix A", "playlists" : [ "5891c01057abd1052cc2bf1b", "5891c01057abd1052cc2bf1b" ] }

Retrieve playlist group GET /user/playlists/groups/{playlistGroupId}

Retrieves a specific user playlist groups by playlistGroupId

Example request: http://api.7digital.com/1.2/user/playlists/groups/5891c01057abd1052cc2bf1b?oauth_consumer_key=YOUR_KEY_HERE&oauth_token=...

Add playlists to playlist group POST /user/playlists/groups/{playlistGroupId}

Adds a list of valid playlists to a a playlist group

Example request: POST http://api.7digital.com/1.2/user/playlists/groups/5891c01057abd1052cc2bf1b Authorization: OAuth realm="...", oauth_consumer_key="YOUR_KEY_HERE", oauth_token="..." Content-type: application/json { "playlists" : [ '5891c01057abd1052cc2bf1b', '5891c01057abd1052cc2bf1b' ] }

Replace playlist group PUT /user/playlists/groups/{playlistGroupId}

Update an entire playlist group

Example request: PUT http://api.7digital.com/1.2/user/playlists/groups/5891c01057abd1052cc2bf1b Authorization: OAuth realm="...", oauth_consumer_key="YOUR_KEY_HERE", oauth_token="..." Content-type: application/json { "name": "My Updated Mix A" "playlists" : [ '5891c01057abd1052cc2bf1c', '5891c01057abd1052cc2bf1d' ] }

Delete playlist group DELETE /user/playlists/groups/{playlistGroupId}

Deletes the users playlist group at {playlistGroupId}.

NOTE: This action is irreversible - deleted playlist groups can't be recovered. We advise you to ask users for confirmation or delay calling the API by couple of seconds whilst providing users with option to undo their action.

Example request: DELETE http://api.7digital.com/1.2/user/playlistsgroups/5891c01057abd1052cc2bf1b

Request token POST /oauth/requesttoken

Requests a new request token for 3-legged authentication. As per OAuth spec the default format of the response is "application/x-www-form-urlencoded" unless you explicitly specify "application/xml" or "application/json" in the request "Accept" header. NB: In order to avoid breaking changes for API consumers who integrated with this endpoint in the past if you invoke this API call with HTTP method "GET" an XML response is returned by default.

Example request: https://api.7digital.com/1.2/oauth/requesttoken?oauth_consumer_key=YOUR_KEY_HERE&oauth_nonce=ABCDEF&oauth_timestamp=1234567890&oauth_signature_method=HMAC-SHA1&oauth_signature=4KO5478ghJ49Olsp3kJ3L589Ssslg5o5

Method specific error codes:

1001 - Missing parameter "parameter name"
Not all mandatory parameters have been provided.

1002 - Value of parameter "parameter name" is not valid
Value for parameter in error message is not valid.

Authorising a request token GET /User authentication - authorising a request token

This is not an API method, but the URL that displays the form that a user will authenticate themselves to 7digital with. After authenticating the user, the request will be redirected back to the API consumer's website (if returnUrl has been supplied). The return url will contain two additional paramters - the original request token and a status paramater which can have the value 'Authorised' or 'InvalidToken'

Example request: https://account.7digital.com/YOUR_KEY_HERE/oauth/authorise?oauth_token=AAAAAAA&oauth_callback=http%3a%2f%2fapi-consumer.com%2fhandback%3fconsumerparam%3dvalue

Access token POST /oauth/accesstoken

Grants an access token in exchange for an authorised request token. This method must be OAuth signed, using your consumer secret and the request token secret.

As per OAuth spec the default format of the response is "application/x-www-form-urlencoded" unless you explicitly specify "application/xml" or "application/json" in the request "Accept" header. Although not expiring automatically after a certain period of time, access tokens (and also authorised request tokens) can be revoked by users at any time.

In the near future we will also enforce a limit of maximum of 3 access tokens that can be active at the same time per one 7digital user account, api consumer key and xoauth_client_identifier combination. If a user has already approved 3 access tokens for your service, the next time you acquire another access token for this same user the first access token will automatically expire.

If the nature of your service allows/requires users to maintain multiple connections to a single 7digital account you are advised to use a distinct xoauth_client_identifier for each connection.

E.g. if a user of your service has registered 5 different accounts ("joe_home", "joe_work", etc) and they want to link all these accounts to a single 7digital account you need to provide an xoauth_client_identifier (xoauth_client_identifier=joe_home, xoauth_client_identifier=joe_work, etc) at the stage of acquiring an oauth/requesttoken.

For device based integrations we recommend to use device names (if available) or serial numbers or IMEIs for mobiles as the identifier.

NB: In order to avoid breaking changes for API consumers who integrated with this endpoint in the past if you invoke this API call with HTTP method "GET" an XML response is returned by default.

Example request: https://api.7digital.com/1.2/oauth/accesstoken?oauth_consumer_key=YOUR_KEY_HERE&oauth_nonce=ABCDEF&oauth_timestamp=1234567890&oauth_signature_method=HMAC-SHA1&oauth_token=yu87230J29DT7tyuGslO98wrR43e39Of&oauth_signature=lth409pPr989rmMjaE9po3h34oKER89e

Create or update a subscription POST /user/unlimitedStreaming (post)

The API Consumer must notify us of new subscriptions or changes to existing ones. This is essential in granting streaming access for any given user.

Example request:

POST http://api.7digital.com/1.2/user/unlimitedStreaming planCode=trial-unlimited-streaming&status=active&currency=GBP&recurringFee=999&postcode=W1A%201AA&country=GB&activatedAt=2012-07-01T10:33:00Z&currentPeriodStartDate=2013-11-23T23:59:59Z&trialEndsAt=2013-12-23T23:59:59Z&expiryDate=2013-12-23T23:59:59Z&oauth_consumer_key=YOUR_KEY_HERE&oauth_token=...

Retrieve subscription status GET /user/unlimitedStreaming (get)

Provides information about whether a user has access to streaming services and at what date does the access expire. If expiryDate is in the future then user has access to stream.

Example request: GET http://api.7digital.com/1.2/user/unlimitedStreaming?country=GB&oauth_consumer_key=YOUR_KEY_HERE&oauth_token=...

Method specific error codes:

2001 - Resource not found The user was not found.

Create a 7digital user POST /user/signup

Creates a new 7digital user account. The user will be able to use the same credentials to log on to 7digital.com to buy music and view their locker online.

Note: Since OAuth protocol is particularly strict about parameter encoding we advise you to thoroughly test integration with this endpoint using passwords containing special characters (e.g. @, �, & etc)

Example request: POST https://api.7digital.com/1.2/user/signup emailAddress=test%40example.com&password=secret&country=GB

Method specific error codes:

1001 - Missing parameter
A required parameter is missing.

1002 - Parameter value out of allowable range
A parameter has been supplied with invalid value.

2003 - User with given email already exists
User with given email address already has a 7digital account.

Get 7digital user's details GET /user/details

Returns a user's email address. For consumers with access to internal services, the details of any user can be accessed given their userid. For normal consumers, only their own user details will be returned.

Example request: https://api.7digital.com/1.2/user/details?userid=1234userid

Method specific error codes:

2001 - Resource not found
The user was not found.

Check if a 7digital user exists GET /users

Checks if a 7digital user account exists for a particular email address. If a user account is not found for the provided email address then an empty list will be returned.

Example request: http://api.7digital.com/1.2/users?emailAddress=someone@example.com

Method specific error codes:

1001 - Missing or invalid parameter
One or more of the supplied parameters is missing or invalid.

Create a new partner user GET /user/create

Creates a new partner user account.

Example request: http://api.7digital.com/1.2/user/create?userId=123456&country=GB

Method specific error codes:

1001 - Missing parameter
A required parameter is missing.

1002 - Invalid parameter value
A parameter has been supplied with invalid value.

2003 - User already exists
A user with this user id has already been created.

Retrieve basket GET /basket

This method retrieves an existing basket and its contents.

Example request: http://api.7digital.com/1.2/basket?basketId=00000000-0000-0000-0000-000000000000&country=DE&oauth_consumer_key=YOUR_KEY_HERE

Method specific error codes:

1001 - Missing parameter "parameter name"
Not all mandatory parameters have been provided.

1002 - Value of parameter "parameter name" is not valid
Value for parameter in error message is not valid.

2001 - Basket with basketId not found.
Basket with given ID does not exist.

2002 - Basket with basketId is unavailable in this country / shop.
The basket has been created in different country and can only be accessed in the country where it was created.

Create basket GET /basket/create

This method creates an empty basket and returns the new basket with it's basketId.

Example request: http://api.7digital.com/1.2/basket/create?country=DE&oauth_consumer_key=YOUR_KEY_HERE

Add item to basket GET /basket/addItem

This method adds a track or release to a basket.

Example request: http://api.7digital.com/1.2/basket/additem?basketid=00000000-0000-0000-0000-000000000000&releaseid=160553&trackid=1693930&country=GB&oauth_consumer_key=YOUR_KEY_HERE

Add custom priced item to basket GET /basket/addpriceditem

This method allows an item to be added to a basket with a specified price. The specified price can be higher or lower than the 7digital catalogue price, including a price of 0.00 to make an item free. For a full description of the basket responses, please refer to the Basket API section in the 7digital public API documentation.

Example request: https://api.7digital.com/1.2/basket/addpriceditem?basketid=00000000-0000-0000-0000-000000000000&country=GB&releaseid=123&price=12.30

Remove item GET /basket/removeItem

This method removes an item from a basket.

Example request: http://api.7digital.com/1.2/basket/removeitem?basketid=00000000-0000-0000-0000-000000000000&itemid=15965085&country=DE&oauth_consumer_key=YOUR_KEY_HERE

Method specific error codes:

1001 - Missing parameter "parameter name"
Not all mandatory parameters have been provided.

1002 - Value of parameter "parameter name" is not valid
Value for parameter in error message is not valid.

2001 - Basket with basketId not found.
Basket with given ID does not exist.

2001 - Basket item with id not found.
Basket does not contain an item with given ID.

2002 - Basket with basketId is unavailable in this country / shop.
The basket has been created in different country and can only be accessed in the country where it was created.

Apply voucher POST /basket/applyVoucher

This method applies a voucher to a basket. If a valid voucher code has been applied the response will return an updated basket with the applied discount reflected in the amountDue element of the basket item the voucher has been applied to. The amountDue element of the basket total will be updated accordingly as well. The price element will remain unchanged and will reflect the original catalogue price of the item and basket. To finalize purchase the basket needs to be checked-out using user/purchase/basket method. If the voucher code cannot be redeemed against any items in the basket an error response will be returned.

Example request: POST https://api.7digital.com/1.2/basket/applyvoucher?basketid=00000000-0000-0000-0000-000000000000&vouchercode=ABC123&oauth_consumer_key=YOUR_KEY_HERE

Method specific error codes:

1001 - Missing parameter "parameter name"
Not all mandatory parameters have been provided.

1002 - Value of parameter "parameter name" is not valid
Value for parameter in error message is not valid.

2001 - Basket with basketId not found.
Basket with given ID does not exist.

2002 - Basket with basketId is unavailable in this country / shop.
The basket has been created in different country and can only be accessed in the country where it was created.

3012 - Voucher not applied
Voucher was not applied for any of the following reasons:

• the voucher code is not valid
• the voucher has expired
• it cannot be redeemed against any items in the basket
• it has been fully redeemed already

Check voucher status GET /payment/voucher/details

Checks validity of voucher and returns remaining allowance and expiry date.

Example request: https://api.7digital.com/1.2/payment/voucher/details?voucherCode=ABC&oauth_consumer_key...

Method specific error codes:

1001 - Missing parameter
A required parameter is missing.

1002 - Invalid parameter
A parameter has been supplied with invalid value.

2001 - Voucher does not exist
There is no voucher (valid or not) with this code.

Purchase single item GET /user/purchase/item

This method allows a user to purchase an item at the price as advertised on 7digital.com. It will return the download URL of each item purchased. For example, if a release consisting of multiple tracks was purchased, then the download URL of each item constituting the release will be returned.

For a user purchase to be processed, the user should already have a default debit or credit card set up for payments.

This method allows users to take advantage of 7digital.com promotional offers and is only available to selected partners building 7digital branded integrations. For white-label integrations please use user/purchase/rrpItem or user/purchase/pricedItem instead.

Example request: https://api.7digital.com/1.2/user/purchase/item?releaseid=786&country=GB&trackid=6598&price=0.99&oauth_token=...

Method specific error codes:

3001 - The user's card has expired
The user's default payment hard has expired.

3002 - The user has no card details saved
User did not register a payment method. Before making a purchase on user's behalf they need to register a payment card.

3003 - Payment for this purchase has failed
The payment with the default payment card have been declined by the bank (e.g. card details not valid, insufficient funds, etc). The card used will be automatically marked as inactive and user will have to re-enter new payment card.

3004 - Price supplied is out of date
The price displayed to the user and supplied in price parameter is no longer valid. The user has not been charged. You can retrieve the updated price, notify the user of the change and repeat the purchase request.

3005 - This card was issued in a country that is not valid for purchases in this shop. Please use another card.
For legal reasons, access to our catalogues is restricted by country. If you see this message, it means that the payment card is issued in a country that is not valid for this catalogue.

Purchase item at RRP GET /user/purchase/rrpItem

This method allows a user to purchase an item at 7digital recommended retail price (RRP). It will return the download URL of each item purchased. For example, if a release consisting of multiple tracks was purchased, then the download URL of each item constituting the release will be returned. For a user purchase to be processed, the user should already have a default debit or credit card set up for payments.

Example request: https://api.7digital.com/1.2/user/purchase/rrpItem?releaseid=786&country=GB&trackid=6598&price=0.99&oauth_token=...

Method specific error codes:

3001 - The user's card has expired
The user's default payment hard has expired.

3002 - The user has no card details saved
User did not register a payment method. Before making a purchase on user's behalf they need to register a payment card.

3003 - Payment for this purchase has failed
The payment with the default payment card have been declined by the bank (e.g. card details not valid, insufficient funds, etc). The card used will be automatically marked as inactive and user will have to re-enter new payment card.

3004 - Price supplied is out of date
The price displayed to the user and supplied in price parameter is no longer valid. The user has not been charged. You can retrieve the updated price, notify the user of the change and repeat the purchase request.

3005 - This card was issued in a country that is not valid for purchases in this shop. Please use another card.
For legal reasons, access to our catalogues is restricted by country. If you see this message, it means that the payment card is issued in a country that is not valid for this catalogue.

Purchase basket GET /user/purchase/basket

This method allows a user to purchase a basket with items that have been added via basket/additem or basket/addpriceditem. It will return the download URL of each item purchased. For example, if a release consisting of multiple tracks was purchased, then the download URL of each item constituting the release will be returned. If total amount due for a basket is greater than 0, the user will need to have a valid debit or credit card set up for payments otherwise a 300X error will be returned. Upon receiving a 300X error you should redirect the user to a new payment method registration screen (see Adding a payment card)

Example request: https://api.7digital.com/1.2/user/purchase/basket?country=GB&basketid=00000000-0000-0000-0000-000000000000&country=FR&oauth_token=...

Method specific error codes:

3001 - The user's card has expired
The user's default payment hard has expired.

3002 - The user has no card details saved
User did not register a payment method. Before making a purchase on user's behalf they need to register a payment card.

3003 - Payment for this purchase has failed
The payment with the default payment card have been declined by the bank (e.g. card details not valid, insufficient funds, etc). The card used will be automatically marked as inactive and user will have to re-enter new payment card.

3005 - This card was issued in a country that is not valid for purchases in this shop. Please use another card.
For legal reasons, access to our catalogues is restricted by country. If you see this message, it means that the payment card is issued in a country that is not valid for this catalogue.

Purchase custom priced item GET /user/purchase/priceditem

This method allows a user to purchase a product or track at a specified price. The specified price can be higher or lower than the 7digital catalogue price, including a price of 0.00 to make an item free. It will return the download URL of each item purchased. For example, if a release consisting of multiple tracks was purchased, then the download URL of each item constituting the release will be returned. The user should already have a default debit or credit card set up for payments.

Example request: https://api.7digital.com/1.2/user/purchase/priceditem?releaseid=10147&trackid=103818&price=2.00&country=FR&oauth_token=...

Credit item GET /user/deliveritem

This method will log a sale of a track or release for the specified user and add that track or release to the user's locker. It returns a purchase id identifying the transaction at 7digital's end.

Example request: https://api.7digital.com/1.2/user/deliveritem?country=US&trackId=4648051&releaseid=415019&transactionid=test4343&oauth_token=...

Report release refund DELETE /user/purchase/{purchaseid}/release/{releaseid}

This method allows a user to remove a purchase of a release from the sales report when the purchase has been refunded. It will return the purchase id and the release id of the item remvoved.

Example request: http://api.7digital.com/1.2/user/purchase/49193524/release/87654?oauth_token=...

Method specific error codes:

2001 - Cannot find sale with purchaseId {purchaseid} and releaseId {releaseid}
Specified sale could not be found in the sales log

2002 - Cannot exclude sale with purchaseId {purchaseid} and releaseId {releaseid}
Specified sale could not be removed because the sale does not fall within the current reporting period. (The reporting period being from the start of the current month to 5th of the succeeding month. e.g. In January the reporting period is 1st January to 4th February.

Report track refund DELETE /user/purchase/{purchaseid}/track/{trackid}

This method allows a user to remove a purchase of a track from the sales report when the purchase has been refunded. It will return the purchase id and the track id of the item remvoved.

Example request: http://api.7digital.com/1.2/user/purchase/49193524/track/87654?oauth_token=...

Method specific error codes:

2001 - Cannot find sale with purchaseId {purchaseid} and trackId {releaseid}
Specified sale could not be found in the sales log

2002 - Cannot exclude sale with purchaseId {purchaseid} and trackId {trackid}
Specified sale could not be removed because the sale does not fall within the current reporting period. (The reporting period being from the start of the current month to 5th of the succeeding month. e.g. In January the reporting period is 1st January to 4th February.

Get all active payment cards GET /user/payment/card

Lists all active payment cards stored on user's account. The first card listed is the user's default payment method.

Example request: https://api.7digital.com/1.2/user/payment/card?country=GB&oauth_token=xxxxxx&oauth_consumer_key...

Set default payment method POST /user/payment/card/select

Sets selected payment card as the default payment method for user.

Example request: https://api.7digital.com/1.2/user/payment/card/select?cardId=123456&oauth_token=xxxxxx&oauth_consumer_key...

Method specific error codes:

1001 - Missing parameter
A required parameter is missing.

1002 - Invalid parameter value
A parameter has been supplied with invalid value.

2001 - Card does not exist
User has not registerd card with given cardId or the card has been deleted.

Remove payment card POST /user/payment/card/delete

Remove payment card from user's account.

Example request: https://api.7digital.com/1.2/user/payment/card/delete?cardId=123456&oauth_token=xxxxxx&oauth_consumer_key...

Method specific error codes:

1001 - Missing parameter
A required parameter is missing.

1002 - Invalid parameter value
A parameter has been supplied with invalid value.

2001 - Card does not exist
User has not registerd card with given cardId or the card has been already deleted.

Lisy payment card types GET /payment/card/type

List payment card types accepted in given country.

Example request: http://api.7digital.com/1.2/payment/card/type?country=US&oauth_consumer_key...

Method specific error codes:

1001 - Missing parameter
A required parameter is missing.

1002 - Invalid parameter value
A parameter has been supplied with invalid value.

Mobile apps POST /card-api.7digital.com/card

Adds a new card to a user's account. This card will be automatically set as default payment option.

Before adding the card to user's account the card number is validated using Luhn alogrithm. Full card validation with the issuing bank (e.g. CVC number check, funds availability, etc.) is also performed.

This endpoint can be used by mobile applications, where the client's device communicates directly with the 7digital API.

Example request: POST https://card-api.7digital.com/card country=GB&cardNumber=4444333322221111&cardType=VISA&cardHolderName=Joe%20User&cardVerificationCode=123&cardExpiryDate=201611&cardCountry=GB&cardPostCode=W37NT&oauth_consumer_key=YOUR_KEY_HERE&oauth_token=...

Method specific error codes:

1001 - Missing parameter
A required parameter is missing.

1002 - Invalid parameter value
A parameter has been supplied with invalid value.

3100 - Payment Provider Connection Error
There was a problem processing the card action with the payment provider. Please retry your request.

3104 - Add Card declined
The card failed to pass validation checks or has been cancelled. Please try with another card.

7100 or 3103 - Add Card failed
The card failed to be added to the payment provider. This request can be resent without any side effects.

Web Step 1 - Create a card registration POST /api.7digital.com/1.2/user/payment/cardregistration

Creates a card registration which responds with a location header to which the browser can directly POST the users card details to.

Example request: POST http://api.7digital.com/1.2/user/payment/cardregistration redirecturl=http%3a%2f%2fredirect.me%2fhere&oauth_consumer_key=YOUR_KEY_HERE&oauth_token=...

Web Step 2 - Post card data POST /card-api.7digital.com/cardregistration/{id}

This URL is provided in the location header in the response from the POST to card registration above. You should POST to this URL directly from the client's browser.

Example request: POST https://card-api.7digital.com/cardregistration/3246a11b-cf71-4342-a1a4-691830eee2cf cardNumber=4444333322221111&cardType=VISA&cardHolderName=Joe%20User&cardVerificationCode=123&cardExpiryYear=2016&cardExpiryMonth=01&cardCountry=GB&cardPostCode=W37NT

Web Step 3 - Check the status of the card addition GET /api.7digital.com/1.2/user/payment/cardregistration/{id}

Use this endpoint to find out whether a card was added successfully or not.

Example request: GET http://api.7digital.com/1.2/user/payment/cardregistration/3246a11b-cf71-4342-a1a4-691830eee2cf

Artist - Full feed GET /feed/artist/full

This endpoint returns a file which is a data snaphot of all the artists contained in the catalogue. The data is contained in a gzipped CSV formatted text file.

Example request: http://feeds.api.7digital.com/1.2/feed/artist/full?country=WW&date=20160623&oauth_consumer_key=YOUR_KEY_HERE

Artist - Daily Updates feed GET /feed/artist/updates

This endpoint returns a file contains a data snaphot of the artists that have changed in the catalogue in the 24 hours prior to midnight on the date of the date parameter. The data is contained in a gzipped CSV formatted text file.

Example request: http://feeds.api.7digital.com/1.2/feed/artist/updates?country=WW&date=20160623&oauth_consumer_key=YOUR_KEY_HERE

Artist - Pre-release Full feed GET /feed/artist/prerelease/full

This endpoint returns a file which is a data snaphot of all the artists who's content is not yet saleable nor streamable in the catalogue. The data is contained in a gzipped CSV formatted text file.

Example request: http://feeds.api.7digital.com/1.2/feed/artist/prerelease/full?country=WW&date=20160623&oauth_consumer_key=YOUR_KEY_HERE

Artist - Pre-release Daily Updates feed GET /feed/artist/prerelease/updates

This endpoint returns a file contains a data snaphot of the artists who's content is not yet saleable nor streamable that have changed in the catalogue in the 24 hours prior to midnight on the date of the date parameter. The data is contained in a gzipped CSV formatted text file.

Example request: http://feeds.api.7digital.com/1.2/feed/artist/prelease/updates?country=WW&date=20160623&oauth_consumer_key=YOUR_KEY_HERE

Release - Full feed GET /feed/release/full

This endpoint returns a file which is a data snaphot of all the releases contained in the catalogue for a given country. The data is contained in a gzipped CSV formatted text file.

Example request: http://feeds.api.7digital.com/1.2/feed/release/full?country=WW&date=20160623&oauth_consumer_key=YOUR_KEY_HERE

Release - Daily Updates feed GET /feed/release/updates

This endpoint returns a file contains a data snaphot of the releases that have changed in the catalogue in the past 24 hours for a given country. The data is contained in a gzipped CSV formatted text file.

Example request: http://feeds.api.7digital.com/1.2/feed/release/updates?country=WW&date=20160623&oauth_consumer_key=YOUR_KEY_HERE

Release - Global Full feed GET /feed/release/global/full

This endpoint returns a file which is a data snaphot of all the releases contained in the catalogue for all countries. The data is contained in a gzipped CSV formatted text file.

Example request: http://feeds.api.7digital.com/1.2/feed/release/global/full?date=20160623&oauth_consumer_key=YOUR_KEY_HERE

Release - Global Daily Updates feed GET /feed/release/global/updates

This endpoint returns a file with all the releases contained in the catalogue for all countries that have changed in the 24 hours prior to midnight on the date of the date parameter. The data is contained in a gzipped CSV formatted text file.

Example request: http://feeds.api.7digital.com/1.2/feed/release/global/updates?date=20160623&oauth_consumer_key=YOUR_KEY_HERE

Release - Hi Res Full feed GET /feed/release/hi-res/bitrate/{bitrate}/full

This endpoint returns a file which is a data snaphot of all the hi res releases of a given bitrate contained in the catalogue for a given country. The data is contained in a gzipped CSV formatted text file.

Example request: http://feeds.api.7digital.com/1.2/feed/release/hi-res/bitrate/16/full?country=WW&date=20160623&oauth_consumer_key=YOUR_KEY_HERE

Release - Hi Res Daily updates feed GET /feed/release/hi-res/bitrate/{bitrate}/updates

This endpoint returns a file with all the hi res releases for a given country for a given bitrate that have changed in the catalogue in the past 24 hours. The data is contained in a gzipped CSV formatted text file.

Example request: http://feeds.api.7digital.com/1.2/feed/release/hi-res/bitrate/16/updates?country=WW&date=20160623&oauth_consumer_key=YOUR_KEY_HERE

Release - Pre-release Full feed GET /feed/release/prerelease/full

This endpoint returns a file which is a data snaphot of all the releases contained in the catalogue for a given country, which are not yet saleable nor streamable. The data is contained in a gzipped CSV formatted text file.

Example request: http://feeds.api.7digital.com/1.2/feed/release/prerelease/full?country=WW&date=20160623&oauth_consumer_key=YOUR_KEY_HERE

Release - Pre-release Daily Updates feed GET /feed/release/prerelease/updates

This endpoint returns a file contains a data snaphot of the releases which are not yet saleable nor streamable that have changed in the catalogue in the past 24 hours for a given country. The data is contained in a gzipped CSV formatted text file.

Example request: http://feeds.api.7digital.com/1.2/feed/release/prerelease/updates?country=WW&date=20160623&oauth_consumer_key=YOUR_KEY_HERE

Track - Full feed GET /feed/track/full

This endpoint returns a file which is a data snaphot of all the tracks contained in the catalogue for a given country. The data is contained in a gzipped CSV formatted text file.

Example request: http://feeds.api.7digital.com/1.2/feed/track/full?country=WW&date=20160623&oauth_consumer_key=YOUR_KEY_HERE

Track - Daily Updates feed GET /feed/track/updates

This endpoint returns a file contains a data snaphot of the tracks in the catalogue for a given country that have changed in the 24 hours prior to midnight on the date of the date parameter. The data is contained in a gzipped CSV formatted text file.

Example request: http://feeds.api.7digital.com/1.2/feed/track/updates?country=WW&date=20160623&oauth_consumer_key=YOUR_KEY_HERE

Track - Global Full feed GET /feed/track/global/full

This endpoint returns a file which is a data snaphot of all the tracks contained in the catalogue for all countries. The data is contained in a gzipped CSV formatted text file.

Example request: http://feeds.api.7digital.com/1.2/feed/track/global/full?date=20160623&oauth_consumer_key=YOUR_KEY_HERE

Track - Global Daily Updates feed GET /feed/track/global/updates

This endpoint returns a file with all the tracks contained in the catalogue for all countries that have changed in the 24 hours prior to midnight on the date of the date parameter. The data is contained in a gzipped CSV formatted text file.

Example request: http://feeds.api.7digital.com/1.2/feed/track/global/updates?date=20160623&oauth_consumer_key=YOUR_KEY_HERE

Track - Hi Res Full feed GET /feed/track/hi-res/bitrate/{bitrate}/full

This endpoint returns a file which is a data snaphot of all the hi res tracks of a given bitrate contained in the catalogue for a given country. The data is contained in a gzipped CSV formatted text file.

Example request: http://feeds.api.7digital.com/1.2/feed/track/hi-res/bitrate/16/full?country=WW&date=20160623&oauth_consumer_key=YOUR_KEY_HERE

Track - Hi Res Daily updates feed GET /feed/track/hi-res/bitrate/{bitrate}/updates

This endpoint returns a file with all the hi res tracks for a given country for a given bitrate that have changed in the 24 hours prior to midnight on the date of the date parameter. The data is contained in a gzipped CSV formatted text file.

Example request: http://feeds.api.7digital.com/1.2/feed/track/hi-res/bitrate/16/updates?country=WW&date=20160623&oauth_consumer_key=YOUR_KEY_HERE

Track - Pre-release Full feed GET /feed/track/prerelease/full

This endpoint returns a file which is a data snaphot of all the tracks contained in the catalogue for a given country, which are not yet saleable nor streamable. The data is contained in a gzipped CSV formatted text file.

Example request: http://feeds.api.7digital.com/1.2/feed/track/prerelease/full?country=WW&date=20160623&oauth_consumer_key=YOUR_KEY_HERE

Track - Pre-release Daily Updates feed GET /feed/track/prerelease/updates

This endpoint returns a file contains a data snaphot of the tracks in the catalogue for a given country which are not yet saleable nor streamable that have changed in the 24 hours prior to midnight on the date of the date parameter. The data is contained in a gzipped CSV formatted text file.

Example request: http://feeds.api.7digital.com/1.2/feed/track/prerelease/updates?country=WW&date=20160623&oauth_consumer_key=YOUR_KEY_HERE