TwentyThree Developer APIAPI Method: /api/photo/get-replace-token

API Method: /api/photo/get-replace-token

Last updated on May 17, 2016.

Pre-authenticate a replacement upload of either a video, a thumbnail for a video or a photo. This allows the client to upload directly to TwentyThree's servers from a web browser.

This method can be used to pre-authenticated uploads to a site without proxying them through your servers and the API. The flow is the same as the one described in detail in the Browser-based uploads section of the API documentation, but in general terms this method will return a token which can be included in a standard HTML form to upload files for replacement.

Parameters

ParameterDescription
return_urlThe URL where the user is return after both replacement success and failure. The callback is a GET request when permitted (when the return data is less than 1500 chars) and a POST in all other cases; so your callback handler needs to accept both GET and POST. If return_url is empty or omitted, the request will return a simple HTTP 200 OK mesage.
background_return_pReturn to the callback url in the background. If this parameter is set to 1 the replace request will not redirect the client directly back to return_url. Instead, a request is made to return_url from the TwentyThree servers and a plain text document in returned containing status information. This option is design for replacing through clients such as Adobe Flash, where a client-side redirected might not be honoured. (The background callback takes the form of a HTTP GET request with a maximum length of 1500 chars.)
photo_idThe photo object to be replaced.
valid_minutesHow many minutes should the replace token be valid for. The default is 180 minutes (or 3 hours). The minimum value is 15 minutes and the maximum is 24 hours.
max_uploadsHow many files can be uploaded using the returned token. The default is 1 upload; the maximum is 100

Permission level

The minimum required permission level is:

write

Example XML Response

<response status="ok" permission_level="write" 
  message="The replace token is ready to use" cached="0">
  <replace_token>022fe6e3fb42758d6147c539727c5358af3524b1</replace_token>
  <photo_id>123456</photo_id>
  <max_uploads>1</max_uploads>
  <valid_minutes>180</valid_minutes>
  <valid_until>1266711372</valid_until>
  <return_url>http://www.example.com/upload/callback?theme=green</return_url>
</response>

Example JSON Response

{
  "status": "ok", 
  "message":"The upload token is ready to use",
  "permission_level":"write",
  "cached":"0",
  "replacetoken":{
    "valid_minutes": "180", 
    "replace_token": "022fe6e3fb42758d6147c539727c5358af3524b1", 
    "max_uploads": "1", 
    "return_url": "http://www.example.com/upload/callback?theme=green", 
    "valid_until": "1266713254", 
    "photo_id": "123456"
  },
  "p": "1",
  "size": "1",
  "site": { ... },
  "endpoint": "/api/photo/get-replace-token"
}