Setting Up Legal Transcription API
Quick Start Introduction
The goal of this tutorial is to familiarize your team with the major components of the Legal Rev API. During this quick start, you’ll walk through the essential steps to use the API to:
- Authenticate and Send Request
- Place orders
- Retrieve Completed Files
There’s a lot more you can do with the API outside of these three simple tasks. Once you’ve implemented these successfully, you can learn more about the extended capabilities in our documentation resources portal.
Are you ready? Let’s go!
Step 1: Create a Rev Legal account
Before you can begin making API calls you’ll need an account that’s enabled to access Rev’s Legal Transcription services. You will first need to speak to one of our team members to ensure we are a good fit for your business. Once qualified, we can begin the account creation process to start ordering. https://www.rev.com/contact-sales
Step 2: Generate Your Client And User API keys
You’ll need to have API keys to begin the integration process. Authentication requires two keys: ‘Client’ and ‘User’
Client Key
Your Client API Key is user agnostic (can be paired with any of your Rev.com user keys) and enables your account for Rev user production access. Here are the steps to generate your Client API Key:
- Open https://www.rev.com/api/docs
- Click on the “START BUILDING” button
-
Fill out the information in the modal
- Select “START BUILDING”
- Your client key will be sent “Getting starting with the Rev API”
User API Key
Your User API key is specific to your Rev account and order placement. Here are the steps to generate your User API key:
- Open https://www.rev.com/account/settings
- Next the to V1 API User Key select “Regenerate”
- In the window select “REGENERATE API KEY”
- You will be presented with the API key in the window where you can copy/paste it to a secure location.
Note: Once the window is closed you are not able to view the same API key again and it cannot be retrieved at a later time by anyone. If you lose a user key, a new one will need to be generated.
Step 3: Authenticate And Send Your First Request
All operations with our API must be executed over HTTPS. The API endpoints start with:
https://api.rev.com/
Every API request must be authenticated via the Authorization header, where you paste in your client and user keys. If you don’t have them yet, refer to section Step 1: Generate your Client and User API keys.
Rev [Client API Key]:[User API Key]
Now let’s make our first request using the API. All examples in the Quick Start use cURL, a simple command line tool for transferring data. You can access cURL in the following ways:
- On PC, Mac, or Linux: Using Postman to interpret cURL commands- our recommended tool
- On a PC: by downloading cURL
- On a Mac or Linux: via Terminal, where cURL should be installed by default
Run the following GET /orders request; it returns all the orders you’ve placed.
cURL
|
curl -X GET \ https://api.rev.com/api/v1/orders \ -H 'Authorization: Rev [ClientApiKey]:[UserAPIKey]' |
Node.js
|
var https = require('https');
var options = { host: 'api.rev.com', path: '/api/v1/orders', method: 'GET', headers: { 'Authorization': 'Rev [ClientApiKey]:[UserAPIKey]' } };
var req = https.request(options, (resp) => { var data = [];
resp.on('data', (chunk) => { data.push(chunk); });
resp.on('end', function() { console.log('Status Code:', resp.statusCode); console.log(JSON.parse(data)); }); }); req.end(); |
What you see in response will depend on whether you've placed orders with Rev before.
- If you have placed orders with us, you'll see up to your last 25 orders.
- If you have not placed an order before, you should receive the result below. We’ll be placing an order in the next step.
|
{ "total_count": 0, "results_per_page": 25, "page": 0, "orders": [] } |
Voilá! You have now completed your first request with the Rev API.
Step 4: Get Template
cURL
|
curl -X GET \ https://api.rev.com/api/v1/templates \ -H 'Authorization: Rev [ClientApiKey]:[UserAPIKey]' |
Node.js
|
var https = require('https');
var options = { host: 'api.rev.com', path: '/api/v1/templates', method: 'GET', headers: { 'Authorization': 'Rev [ClientApiKey]:[UserAPIKey]' } };
var req = https.request(options, (resp) => { var data = [];
resp.on('data', (chunk) => { data.push(chunk); });
resp.on('end', function() { console.log('Status Code:', resp.statusCode); console.log(JSON.parse(data)); }); }); req.end(); |
The templates you see in response will depend on what templates have been created for your account. Select and store your ID to use in Step 4: Place Order.
|
{ "templates": [ { "id": 21904476, "proceeding_type": "deposition", "name": "Rev Standard Deposition NY", "jurisdiction": "NY", "rev_standard": true, "sample_url": "https://www.rev.com/sample-template-url" }, { "id": 527310255, "proceeding_type": "hearing", "name": "My Hearing Template GA", "jurisdiction": "GA", "rev_standard": false, "sample_url": "https://www.rev.com/sample-template-url" } ] } |
Step 5: Placing Orders
Now that you’ve successfully used your keys to retrieve your order history, we’re ready to start placing orders.
You’ll start by specifying the service line by using transcription_options in the body of the request.
Note: during this quick start process, you’ll be placing sandbox orders. You can perform all the operations on sandbox mode with orders that are available regularly, however, no real work is performed by our freelancers and you won’t be charged for the sandbox orders you place.
Submitting the Order
To submit an order you’ll need to provide a link to a file that is available for download. This can be a public, Pre-signed or Signed URL as long as the Rev system has access to download. The link to the media file is provided with the first external_link property in the inputs object.
To attach additional legal resources and backup audio to an order, provide download accessible URL links to the files.
Next, you’ll run the following POST /orders request; it places a sandbox order for a Ready to Certify transcript of a Deposition proceeding type.
cURL
|
curl -i -X POST \ https://api.rev.com/api/v1/orders \ -H 'Authorization: Rev [ClientApiKey]:[UserAPIKey]' \ -H 'Content-Type: application/json' \ -d '{ 'sandbox_mode': true, 'client_ref': 'Legal API test order', 'transcription_options': { 'inputs': [ { 'external_link': 'https://cf-public.rev.com/api-samples/audio.mp3', 'speakers': ['John', 'Jane', 'Sam Jones'], 'glossary': ['cryptography', 'MD5', 'SHA-1', 'bcrypt'], 'legal_resources': [ { 'type': 'notice', 'external_link':'https://cf-public.rev.com/api-samples/notice.pdf', 'name': 'Test notice 1.pdf' }, { 'type': 'reporter_notes', 'external_link': 'https://cf-public.rev.com/api-samples/reporter_notes.txt', 'name': 'test reporter notes 1.txt' }, { 'type': 'tag_file', 'external_link': 'https://cf-public.rev.com/api-samples/tag_file.txt', 'name': 'test tag file 1.txt' } ], 'backups':[ { 'external_link': 'https://cf-public.rev.com/api-samples/backup.mp3' } ] } ], 'legal_tc_types': ['ai_rough_draft', 'ready_to_certify'], 'rush': true, 'proceeding_type': 'deposition', 'template': 340540780 }, 'notification': { 'url': 'http://www.clientsite.com/orderupdate', 'level': 'Detailed', 'content_type': 'ApplicationJson' } }'
|
Node.js
|
var https = require('https');
var post_data = JSON.stringify({ sandbox_mode: true, client_ref: 'Legal API test order', transcription_options: { inputs: [ { external_link: 'https://cf-public.rev.com/api-samples/audio.mp3', speakers: ['John', 'Jane', 'Sam Jones'], glossary: ['cryptography', 'MD5', 'SHA-1', 'bcrypt'], legal_resources: [ { 'type': 'notice', 'external_link':'https://cf-public.rev.com/api-samples/notice.pdf', 'name': 'Test notice 1.pdf' }, { 'type': 'reporter_notes', 'external_link': 'https://cf-public.rev.com/api-samples/reporter_notes.txt', 'name': 'test reporter notes 1.txt' }, { 'type': 'tag_file', 'external_link': 'https://cf-public.rev.com/api-samples/tag_file.txt', 'name': 'test tag file 1.txt' } ], backups: [ { external_link: 'https://cf-public.rev.com/api-samples/backup.mp3' } ], legal_tc_types: ['ai_rough_draft', 'ready_to_certify'], rush: true, proceeding_type: 'deposition', template: 340540780 } ] }, notification: { url: 'http://www.clientsite.com/orderupdate', level: 'Detailed', content_type: 'ApplicationJson' } }); var options = { host: 'api.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(); |
The Response
All orders will receive a HTTP response similar to the one below. The location URL is used to retrieve the completed files. Save this for use in the next step.
|
Cache-Control: no-cache Content-Length: 0 Date: Wed, 16 March 2024 19:09:05 GMT Expires: -1 Location: https://api.rev.com/api/v1/orders/TC0938707965 Pragma: no-cache |
Step 6: Retrieve Completed Files
Once you’ve placed a sandbox mode 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 The Attachments ID
The Order ID that was returned in the Location 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.
cURL
|
curl -X GET \ https://api.rev.com/api/v1/orders/TC0938707965 \ -H 'Authorization: Rev [ClientApiKey]:[UserAPIKey]' |
Node.js
|
var https = require('https');
var options = { host: 'api.rev.com', path: '/api/v1/orders/TC0938707965', method: 'GET', headers: { 'Authorization': 'Rev [ClientApiKey]:[UserAPIKey]' } };
var req = https.request(options, (resp) => { var data = [];
resp.on('data', (chunk) => { data.push(chunk); });
resp.on('end', function() { console.log('Status Code:', resp.statusCode); console.log(JSON.parse(data)); }); }); req.end();
|
The body response will contain information you’ll need to pull down the attachment.
|
{ "order_number": "TC0948053481", "price": 2.85, "status": "Complete", "transcription": { "total_length_seconds": 300, "verbatim": true, "timestamps": false }, "attachments": [ { "kind": "media", "name": "FTC_Sample_1.mp3", "id": "1C4AA80F4000000001000000F2EED32A3DD4775B1B0", "audio_length_seconds": 48, "links": [ { "rel": "content", "href": "https://api.rev.com/api/v1/attachments/1C4AA/content" } ] }, { "kind": "transcript", "name": "FTC_Sample_1.docx", "id": "1C4AA80F4000000001000000F2EED32A3DD4775B1B0", "links": [ { "rel": "content", "href": "https://api.rev.com/api/v1/attachments/1B4AA/content", "content-type": "text/x-rev-transcription" } ] } ], "comments": [ { "by": "John S.", "timestamp": "2003-04-05T12:20:30.567", "text": "Please do it quickly" } ] }
|
The relevant parts of the response are bolded; they are all in the “attachments” section of the response. You’ll need the “transcript id,” not the media id, to retrieve the completed file.
Retrieve The Completed File
Now you’re ready to use GET /attachments/{id}/content to retrieve the completed file. The following example fetches the FTC_Sample_1.docx from the excerpt above.
There are two ways to request formats:
- Using the “Accept” header
- Appending an extension to the end of the URL (ie: adding .docx 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
|
curl -X GET \ https://api.rev.com/api/v1/attachments/6SWCOBmRAwAAAAAA/content \ -H 'Accept: application/vnd.openxmlformats-officedocument.wordprocessingml.document' \ -H 'Authorization: Rev [ClientApiKey]:[UserAPIKey]' |
Node.js
|
var https = require('https');
var options = { host: 'api.rev.com', path: '/api/v1/attachments/6SWCOBmRAwAAAAAA/content', method: 'GET', headers: { 'Authorization': 'Rev [ClientApiKey]:[UserAPIKey]', 'Accept': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' } };
var req = https.request(options, (resp) => { var data = [];
resp.on('data', (chunk) => { data.push(chunk); });
resp.on('end', function() { console.log('Status Code:', resp.statusCode); console.log(JSON.parse(data)); }); }); req.end(); |
Now that you’ve received a completed file, you’ve walked through all the major steps of using the Rev API.
Going Further with the API
You’ve now completed the most basic operations you can perform with the Rev API. We mentioned that there’s a lot more you can do with our API in the current state. A few other things you might be interested in:
Step 7: Moving to Production
If you feel ready to start placing production (real) orders, you’ll have to do a few things first:
- Enable your Client key for production - Email legalsupport@rev.com and we will enable access to place real, production orders.
- Set up payment - Ensure your Rev account is set up for invoicing or loaded with prepaid credit.
- Once we have notified you that your production access is live and your form of payment is configured, you can send orders without the sandbox_mode param.
Pre-Paid Set Up
To add prepaid credits: Go to your account Payment Settings and click "Add More" next to the Prepay Balance section. Make sure you load enough credit to place your first order.
Invoicing Set up
If you haven’t already, fill out this form to get started: https://www.rev.com/invoicing-form
If you’re an invoicing customer, you'll receive a bill at the end of the month and have 30 days to pay.
Sandbox Access
Even after you have API credentials for our production environment, you can continue placing sandbox mode orders. You may test with sandbox_mode=true at any time, even after starting to place real orders.