Links API Documentation
Here you will find detailed documentation on the request and response formats for Thumbplay’s Link API.This API returns the landing pages links for specific contentIds and artistIds as delivered by the Charts API. For the highest converting Web landing pages, we recommend using the titleLandingPageURL. If you are integrating into a mobile site or application, please use the mobilePurchaseURL. Note that you must have an activated pname in order to make requests. Your pname acts as both your partner ID for reporting and API key for authentication.
1.0 Request Format
If you are submitting the request programmatically, please be sure to URL-encode the parameters.
1.1 Example URL Pattern
http://api.hosted.thumbplay.com/api/rest/offers/partnerLinks?contentIds=527974,514518&pname=1003&plpFlow=atb3
1.2 Parameters
| Name | Expected Value | Required? | Example | Description |
|---|---|---|---|---|
| contentIds | Non-negative integer values separated by commas | Yes, if artistIds not provided | contentIds=527974,514518 | contentIds upon which lookup will be done |
| artistIds | Text string values separated by commas | Yes, if contentIds not provided | artistIds=25781,28082 | artistIds upon which lookup will be done |
| pname | Non-negative integer | Yes | pname=1003 | Partner ID and API key used for reporting and authentication. Will be included in the URLs returned within response XML |
| plpFlow | landing page name | No | plpFLow=atb3 | Determines the version of the artistLandingPageURL and titleLandingPageURL |
| plpParams | Name value pairs separated by “|”, multiple instances of this parameter is allowed | No | plpParams=thpcampid|artist-page | |
| clientRequestId | No | clientRequestId=myRequest01 | Returned in the response to allow partner tracking |
2.0 Response Format
2.1 Sample - Successful Response
<offerRequest>
<contentIds>527974,514518</contentIds>
<plpFlow>atb3</plpFlow>
<pname>1003</pname>
</offerRequest>
<partnerLinks>
<offerLinks>
<artistId>ANIMAL SOUNDS</artistId>
<artistLandingPageURL>http://offers.thumbplay.com/offers/1003/atb3?thpartist=Animal+Sounds</artistLandingPageURL>
<artistURL>http://ringtones.thumbplay.com/Animal+Sounds-ringtones</artistURL>
<contentId>514518</contentId>
<mobilePurchaseURL>http://m.thumbplay.com/tp/infomo?view=details2&cid=514518&pname=1003</mobilePurchaseURL>
<titleLandingPageURL>http://offers.thumbplay.com/offers/1003/atb3?thpartist=Animal+Sounds&thptitle=Rooster+Call&selectedContent=514518</titleLandingPageURL>
<webPurchaseURL>http://www.thumbplay.com/join/Animal+Sounds-artist-Rooster+Call-realtones-bonus?pname=1003</webPurchaseURL>
</offerLinks>
<offerLinks>
<artistId>29242</artistId>
<artistLandingPageURL>http://offers.thumbplay.com/offers/1003/atb3?thpartist=Rush</artistLandingPageURL>
<artistURL>http://ringtones.thumbplay.com/Rush-ringtones</artistURL>
<contentId>527974</contentId>
<mobilePurchaseURL>http://m.thumbplay.com/tp/infomo?view=details2&cid=527974&pname=1003</mobilePurchaseURL>
<titleLandingPageURL>http://offers.thumbplay.com/offers/1003/atb3?thpartist=Rush&thptitle=YYZ+%28Intro%29&selectedContent=527974</titleLandingPageURL>
<webPurchaseURL>http://www.thumbplay.com/join/Rush-artist-YYZ+%28Intro%29-realtones-bonus?pname=1003</webPurchaseURL>
</offerLinks>
</partnerLinks>
<queryDuration>0</queryDuration>
2.2 Successful Response - Field Description
| Name | Description |
|---|---|
| artistID | Unique identifier for the artist |
| artistLandingPageURL | URL for the best-converting artist-specific partner landing page (recommended) |
| artistURL | URL for the artist page on Thumbplay main site (not recommended) |
| contentId | Unique identifier for the content item |
| mobilePurchaseURL | URL for the purchase page for the content - suitable for WAP viewing |
| titleLandingPageURL | URL for the best-converting title-specific partner landing page (recommended) |
| webPurchaseURL | URL for the title page on Thumbplay main site (not recommended) |
2.3 Sample - Response With Errors
<errors>
<error>
<code>102</code>
<description>Unable To Parse Parameter: contentIds</description>
</error>
</errors>
<offerRequest>
<contentIds>abcdef</contentIds>
<plpFlow>atb3</plpFlow>
<pname>1003</pname>
</offerRequest>
<queryDuration>1</queryDuration>
2.4 Response with Errors - Field Description
| Name | Description |
|---|---|
| description | Printable description of the error |
| code | 101 - 300 is not success (error) codes. Possible values: 101 – Missing contentIds and artistIds, 102 – Unable to parse contentIds, 103 – Unknown Content Id, 104 – Unknown Artist Id, 105 – Unable to parse plpParams, 200 – A communication error has occurred, 201 – Generic error |
| debugInfo | Debugging information associated with the error. Generated in cases when there have been internal service problems. Should sent to Thumbplay with the bug report. |