Step 3: Retrieve Completed Files

Once you’ve placed a sandbox order, the status will be “In Progress” for five minutes. Then, the order status will move to “Complete”, now you’re ready to pull down your completed file.

Retrieve Attachment IDs

The Order ID that was returned in the header of the POST /orders request will be used to get the ID associated with the file for that order. We’ll do this using the GET /orders/{ordernum} operation. In this example, we pasted in the order number from the YouTube video in step 2.

curl -X GET \
  https://api-sandbox.rev.com/api/v1/orders/CP0938707965 \
  -H 'Authorization: Rev [ClientApiKey]:[UserAPIKey]'

The body response will contain information you’ll need to pull down the attachment.

{
    "order_number": "CP0948053481",
    "price": 2.85,
    "status": "Complete",
    "priority": "Normal",
    "non_standard_tat_guarantee": false,
    "caption": {
        "total_length": 2,
        "total_length_seconds": 171
    },
    "comments": [
        {
            "by": "Rev I.",
            "timestamp": "2018-05-16T03:52:36.91Z"
        },
        {
            "timestamp": "2018-05-16T03:59:05.617Z",
            "text": "Order delivered"
        }
    ],
    "attachments": [
        {
            "kind": "media",
            "name": "Work From Home Transcription & Translation Jobs with Rev.com.mp4",
            "id": "6SWCOBeRAwAAAAAA",
            "video_length_seconds": 170,
            "links": [
                {
                    "rel": "content",
                    "href": "https://api-sandbox.rev.com/api/v1/attachments/6SWCOBeRAwAAAAAA/content"
                }
            ]
        },
        {
            "kind": "caption",
            "name": "Work From Home Transcription & Translation Jobs with Rev.com.srt",
            "id": "6SWCOBmRAwAAAAAA",
            "links": [
                {
                    "rel": "content",
                    "href": "https://api-sandbox.rev.com/api/v1/attachments/6SWCOBmRAwAAAAAA/content" ,
                    "content-type": "application/x-subrip"
                }
            ]
        }
    ]
}

Again, the relevant parts of the response are bolded; they are all in the Attachments section of the response.

  • kind: this tells you what the ID pertains to
    • media: a source file you provided
    • caption: a completed caption file
    • transcription: a completed transcript
  • name: the name of the file
  • id: a unique string needed for you to fetch the files
  • href: the command needed to retrieve the media for that file

Please note: You’ll need the caption id, not the media id, to retrieve the completed file. In the example above, the caption id is in bold.

Retrieve Completed File

Now you’re ready to use GET /attachments/{id}/content to retrieve the completed file. The following example fetches the sample.srt from the excerpt above.

When we used POST /orders to create the order, we specified that the file should be optimized for the SubRip format. However, you can specify up to 12 different formats when you retrieve the file. A full list of potential file formats is available here.

There are two ways to request formats:

  1. Using the Accept header
  2. Appending an extension to the end of the URL (i.e., adding .srt to the URL below)

The example below uses the Accept header. You can only request one format per call; multiple calls are needed to retrieve multiple formats.

curl -X GET \
  https://api-sandbox.rev.com/api/v1/attachments/6SWCOBmRAwAAAAAA/content \
  -H 'Accept: application/x-subrip' \
  -H 'Authorization: Rev [ClientApiKey]:[UserAPIKey]'

And this example appends the extension to the end of the URL:

curl -X GET \
  https://api-sandbox.rev.com/api/v1/attachments/6SWCOBmRAwAAAAAA/content.srt \
  -H 'Authorization: Rev [ClientApiKey]:[UserAPIKey]'

Regardless of how you specify the file type, the contents of the file are printed in the console, and every sandbox order will return the same result.

1
00:00:00,000 --> 00:00:05,000
Rebecca: This is a sample
first line with a speaker

2
00:00:10,500 --> 00:00:15,500
and this is the second line with
the same speaker, shown at top

It’s also possible to download the file rather than retrieve the data. You can learn how to do so cURL using -o.

Now that you’ve received a completed file, you’ve walked through all the major steps of using the Rev API.

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