/v2/radkey

GET

Sending a GET request to /v2/redeem is simply to validate the status of a key and will only provide you with a true or false repsonse. It is informational only and does not produce any actions on a network such as removing claims, allowing monetization, etc. If the response is True, then the RADKey™ is valid for given media and has not yet been redeemed on the given network. If the response is False, then RADKey is not valid and the reason will be included. The POST method will almost always be used, but this method is available to check the validity of a RADkey without redeeming it.

Parameter Options
token Unique key that authenticates/identifies the API requester.
rad_key The RADKey™ you wish to validate.
media_id The Media ID said RADKey™ corresponds to.
network_id The unique Identifier of the network on which you wish to check if the RADKey is valid. Remember it is possible for a RADKey to have already been redeemed on one network and not another. See the list of network Id's here.

Usage

This method requires you to submit a token, rad_key, media_id, and network_id. Below are the possible responses.


This key is valid with the given media on the given network

      { 
        "rad_key_valid": 1,
        "rad_key": "3XLGMSO-CUQFKI6-E170NXG-445FOHY-22Z1"
      }
    

The RADKey was previously redeemed for this song on the given network, or the RADKey given doesn't match the given song, or the RADkey itself is not valid.

      { 
        "rad_key_valid": 0.
        "rad_key": "HSIEH4S-C2Q5KI6-E5706XG-40AHDFD-85DG"
      }
    

Try It

Inline Action Responses Vs. Post-Hoc Action Responses

This RADKey method supports two different use cases for which different types of responses should be expected. In the 'Inline Action' use case, the requester is typically a network (or a service working on behalf of a network), which is attempting to determine which action to take with a video which has not yet been published. An appropriate success status for this type of user would be Status ID 6003, and they should never see Status ID 6002.

The 'Post-Hoc' use case involves a requester who would like a particular action or business policy to be implemented on a video which is already published. This is typically the case with Youtube videos. Therefore, this use case can expect a successful message to be a Status ID 6002, which infoms that the action has been fully completed (e.g., A video claim has been released). If there is some confusion about which use case you fall into, please contact your Rumblefish Tech support representative.

POST

Usage

Sending a POST request to /v2/redeem with valid information will register the usage of the RADKey and inform the network to complete the approriate actions given the business rules behind the license.

Parameter Options
token Unique key that authenticates/identifies the API requester.
rad_key Unique key associated with the license.
video_reference The unique video id of the video which contains the licensed music. If it is a youtube video, then the video id or an entire video link may be used.
network_id A unique identifier for the network on which the RADKey redeem request is being made.
media_id The Rumblefish media_id for which the RADKey was issued.
request_id The request_id is used to do a re-lookup of the status of requested redeem process.

Initial use of the POST method requires you to submit a token, rad_key, video_reference, network_id and media_id. In "Post-Hoc" use cases, the application is dependent on external systems, so the first response from the API will typicaly be a 'retry' message with a request ID which you may use to check the status of your request, like so:

    { 
      "status": 6001,
      "message": "Waiting for the network to complete this action."
      "retry_in": 0.1,
      "request_id": 342341
    }
    

This means your request has been validated, is in the Rumblefish system and we are currently in contact with the network. You are now able to request the status of this communication by POSTing to /v2/redeem with your token and request_id. Although the request usually happens instantaneously, this method may rely on factors outside of our infrastructure, therefore it is recommended that this request be done in a polling manner until a conclusive answer is recieved. Examples of possible conclusive responses (status codes greater than 6001) follow:

Success Responses (6002-6003)

    { 
      "status": 6002,
      "message": "key validated and redeemed on network",
      "recommended_action": "Inform user that the action has been completed",
      "network_id": 1,
      "rad_key": "3XLGMSO-CUQFKI6-E170NXG-445FOHY-22Z1",
      "video_reference" : "http://www.youtube.com/watch?v=9ib3lD_VZYU",
      "request_id": 342341
    }
    
    { 
      "status": 6003,
      "message": "the key is validated and the business rule is monetize",
      "recommended_action": "monetize",
      "network_id": 2,
      "rad_key": "3XLGMSO-CUQFKI6-E170NXG-445FOHY-22Z1",
      "video_reference" : "d831HDAS30",
      "request_id": 414214
    }
    

Failure Responses (7001-7003)

    { 
      "status": 7001,
      "message": "That is not a valid rad key",
      "recommended_action": "Inform user that the entered key is invalid, redirect 
to store-front for new license." "request_id": 123625 }
    { 
      "status": 7002,
      "message": "RAD Key previously redeemed for this song on this network.",
      "recommended_action": "Inform user that the key has already been validated for this 
network. User should a) check again if the business rules have already been implemented
b)find the correct RAD key or c) contact support.", "network_id": 1, "rad_key": "3XLGMSO-CUQFKI6-E170NXG-445FOHY-22Z1", "video_reference" : "http://www.youtube.com/watch?v=9ib3lD_VZYU", "request_id": 435667 }
    { 
      "status": 7003,
      "message": "the key is valid but publishing is blocked on this network",
      "recommended_action": "block",
      "network_id": 3,
      "rad_key": "3XLGMSO-CUQFKI6-E170NXG-445FOHY-22Z1",
      "video_reference" : "d831HDAS30",
      "request_id": 414214
    }
    

Network ID's

Network Name Network ID
Youtube 1
Daily Motion 2
Vimeo 3

Try It

First Request


Polling for response