Step 2: Place Orders

Now that you’ve successfully used your sandbox keys to place your first request, we’re ready to start placing orders.

The process of placing orders is the same across all Rev service lines - it does not matter whether you’re placing an order for Transcription, Captions or Foreign Subtitles.

You specify the service line by using either caption_options or transcription_options in the body of the request. In the examples below, we are placing caption orders.

Below we cover different ways to place orders:

  1. Submitting an order using a public URL or URI
  2. Submitting an order using a local file

1. Submitting an order using a public URL or URI

Media that’s embedded on a webpage (YouTube, Vimeo, etc.) can be submitted directly to POST /orders using external_link

In the example below, we use a YouTube URL to create a caption order. We also specify that we would like the order optimized for the SubRip file format by using output_file_formats. Please note: specifying the output_file_formats is not the same as requesting those formats for download - we’ll cover that later in the Retrieve Completed Files step.

curl -i -X POST \
  https://api-sandbox.rev.com/api/v1/orders \
  -H 'Authorization: Rev [ClientApiKey]:[UserAPIKey]' \
  -H 'Content-Type: application/json' \
  -d '{
       "caption_options": {
          "inputs": [
             {
                "external_link": "https://www.youtube.com/watch?v=E0arJC0CJ7k"
             }
          ],
          "output_file_formats": [
             "SubRip"
          ]
       }
    }'
var https = require('https');

var post_data = JSON.stringify({
  caption_options: {
    inputs: [
        {
            external_link: 'https://www.youtube.com/watch?v=E0arJC0CJ7k'
        }
    ],
    output_file_formats: [
      'SubRip'
    ]
  }
});

var options = {
  host: 'api-sandbox.rev.com',
  path: '/api/v1/orders',
  method: 'POST',
  headers: {
    'Authorization': 'Rev [ClientApiKey]:[UserAPIKey]',
    'Content-Type': 'application/json'
  }
};

var post_req = https.request(options, (resp) => {
  console.log('Status Code:', resp.statusCode);
  console.log('Headers:', resp.headers);
});

post_req.write(post_data);
post_req.end();

You can also submit a S3 URI directly to POST /orders. You would use uri rather than external_link. The URI structure for a S3 URI is urn:s3:[bucket name]object, in the example below we use a publicly accessible URI from Rev’s S3 bucket.

Remember, your S3 URIs will need to be publicly accessible or have a policy that allows read access to the content. To enable our system to pull from your S3 bucket, see Setting up S3 Bucket Policy.

curl -i -X POST \
  https://api-sandbox.rev.com/api/v1/orders \
  -H 'Authorization: Rev [ClientApiKey]:[UserAPIKey]' \
  -H 'Content-Type: application/json' \
  -d '{
       "caption_options": {
          "inputs": [
             {
                "uri": "urn:s3:[public-rev]api-samples/Audio and Video Transcription with Rev.com.mp4"
             }
          ],
          "output_file_formats": [
             "SubRip"
          ]
       }
    }'
var https = require('https');

var post_data = JSON.stringify({
  caption_options: {
    inputs: [
        {
           uri: 'urn:s3:[public-rev]api-samples/Audio and Video Transcription with Rev.com.mp4'
        }
    ],
    output_file_formats: [
      'SubRip'
    ]
  }
});

var options = {
  host: 'api-sandbox.rev.com',
  path: '/api/v1/orders',
  method: 'POST',
  headers: {
    'Authorization': 'Rev [ClientApiKey]:[UserAPIKey]',
    'Content-Type': 'application/json'
  }
};

var post_req = https.request(options, (resp) => {
  console.log('Status Code:', resp.statusCode);
  console.log('Headers:', resp.headers);
});

post_req.write(post_data);
post_req.end();

2. Submitting a local file to POST /inputs

Submitting local media file is a two step process. First you use POST /inputs to send the file to Rev.

In the example below, replace [INSERT FILE PATH HERE], keeping the '@' sign. If you need a small sample video, you can download one here.

curl -i -X POST \
  https://api-sandbox.rev.com/api/v1/inputs \
  -H 'Authorization: Rev [ClientApiKey]:[UserAPIKey]' \
  -H 'Content-Type: video/mp4' \
  -H 'content-disposition: attachment; filename="filename.mp4"' \
  --data-binary '@[INSERT FILE PATH HERE]'
var http = require("https");

var options = {
  host: 'api-sandbox.rev.com',
  path: '/api/v1/inputs',
  method: 'POST',
  headers: {
    'Authorization': 'Rev [ClientApiKey]:[UserAPIKey]',
    'Content-Type': 'video/mp4',
    'content-disposition': 'attachment; filename=filename.mp4'
  }
};

var req = http.request(options, (resp) => {

  resp.on("end", function () {
    console.log('Status Code:', resp.statusCode);
    console.log('Headers:', resp.headers);
  });
});

req.write("@[INSERT FILE PATH HERE]");
req.end();

After submitting to POST /inputs, you should receive a response similar to the one below.

HTTP/1.1 201 Created
Cache-Control: no-cache
Content-Length: 0
Date: Fri, 18 May 2018 17:23:45 GMT
Expires: -1
Location: urn:rev:inputmedia:RXVwbG9hZHMvMjAxOC0wNS0xNi8yY2UxYWFmNS04ZasdfQ4NzMtOGRmMC05Y2I2ZDkwN2ViNzIvbGVnb3ZpZGVvLm1wNA
Server: Microsoft-IIS/10.0
X-MiniProfiler-Ids: ["00109bf4-bcf5-41af-92e5-0150703b8a4f"]
X-Powered-By: ASP.NET

The relevant parts of the response are in bold above.

  • 201 Created tells us we posted the file to Rev successfully.
  • Location gives the URI for the file we just posted to Rev.

Now we’re ready for the second step — taking the URI and using it with POST /orders.

The command below places a Caption order with .srt as the file output type. Rev is usually (but not always) able to auto-detect length of the file. In this example, we added video_length_seconds to the body of the request.

curl -i -X POST \
  https://api-sandbox.rev.com/api/v1/orders \
  -H 'Authorization: Rev [ClientApiKey]:[UserAPIKey]' \
  -H 'Content-Type: application/json' \
  -d '{
       "caption_options": {
          "inputs": [
             {
                "video_length_seconds": 6,
                "uri": "urn:rev:inputmedia:RXVwbG9hZHMvMjAxOC0wNS0xNi8yY2UxYWFmNS04ZasdfQ4NzMtOGRmMC05Y2I2ZDkwN2ViNzIvbGVnb3ZpZGVvLm1wNA"
             }
          ],
          "output_file_formats": [
             "SubRip"
          ]
       }
    }'
var https = require('https');

var post_data = JSON.stringify({
  caption_options: {
    inputs: [
        {
            video_length_seconds: 6,
            uri: 'urn:rev:inputmedia:RXVwbG9hZHMvMjAxOC0wNS0xNi8yY2UxYWFmNS04ZasdfQ4NzMtOGRmMC05Y2I2ZDkwN2ViNzIvbGVnb3ZpZGVvLm1wNA'
        }
    ],
    output_file_formats: [
      'SubRip'
    ]
  }
});

var options = {
  host: 'api-sandbox.rev.com',
  path: '/api/v1/orders',
  method: 'POST',
  headers: {
    'Authorization': 'Rev [ClientApiKey]:[UserAPIKey]',
    'Content-Type': 'application/json'
  }
};

var post_req = https.request(options, (resp) => {
  console.log('Status Code:', resp.statusCode);
  console.log('Headers:', resp.headers);
});

post_req.write(post_data);
post_req.end();

Receiving a response from Rev

Regardless of what type of media you submit to Rev, all orders will receive a HTTP response similar to the one below:

Cache-Control: no-cache
Content-Length: 0
Date: Wed, 16 May 2018 19:09:05 GMT
Expires: -1
Location: https://api-sandbox.rev.com/api/v1/orders/CP0938707965 
Pragma: no-cache
Server: Microsoft-IIS/10.0
X-MiniProfiler-Ids: ["f38e8e42-e513-4c96-9bd7-a17f412593ad"]
X-Powered-By: ASP.NET

The Location response contains a URL to the order that was created in Rev. The last part of the URL CP0948053481 is the Order Number.

Congrats! You’ve placed your first order using the Rev API.

Having trouble? Email apisupport@rev.com and one of our engineers will reply.