Operations

POST /orders

Summary Submit a new order
URL /api/v1/orders
Detailed Description

Use this method to submit a new order for legal transcription. The order will be placed in the user's default team.

Payment will be done by debiting the user's account balance.

Note: Placing Legal Transcription orders requires some additional set up by the Rev team. Please contact us at legalsupport@rev.com for support.
Request Headers
  • Authorization - contains client/user API keys
Request Body

JSON with the details about the order. See below for an example entity illustrating the fields used.

  • sandbox_mode (optional)
    Optionally, choose to submit the order in sandbox mode. For testing a new or changed client integration.

  • client_ref (optional)
    A reference number for the order meaningful for the client.
    Max Length: 256.

  • transcription_options (required)
    Provides information on what needs to be transcribed and allows for any transcription options to be set.

    • inputs (required)
      Contains a list of media to transcribe

      • external_link
        URL link to download media file that is to be transcribed.

        Using external_link is recommended over the uri method when possible. When using external_link, Rev will download the media from the provided URL shortly after the request is made. This allows for faster order placement and avoids timeout issues that may occur for clients when uploading files directly via the /inputs endpoint.

      • uri
        A uri returned from a POST to /inputs in the Location header.
        Use this if the media is either stored in your system, or is accessible at a URL where we can download it.
        First, make a POST to /inputs to send us the media. Next, you can use the returned uri to reference it in the order request.

        Important: For any input, you must provide either uri or external_link, but not both. If both or neither is provided, an error is returned.

      • audio_length_seconds (optional)
        Length of audio, in seconds rounded up.

        For each input, you may explicitly specify the audio length, in seconds, of the video referenced by the input. If you do not specify the audio length, we will attempt to determine it automatically from the input media; however we are not always able to do so. We can generally calculate audio length of files using common audio/video formats (e.g. mp3, aac, quicktime, etc) that are up to 10MB in size. If your files are larger than 10MB or are using an uncommon audio/video format, we strongly recommend you specify the audio length explicitly.

      • speakers (optional)
        List of speaker names.
        The speaker list may have up to 100 entries, and speaker names may be up to 50 characters long.

      • glossary (optional)
        List of glossary entries.
        The glossary may have up to 1000 entries, and glossary entries may be up to 255 characters long.

      • accents (optional)
        List of speaker accents.
        We currently support the following accents (case-sensitive) with your input file:

        • AmericanNeutral
        • AmericanSouthern
        • Asian
        • Australian
        • British
        • Indian
        • Other
        • Unknown

      • order_index (required only when combine_inputs is true)
        Indicates files sequential order in the concatenation of audio/video files.

      • legal_resources (optional)
        Additional legal resource files to be referenced for transcription.

        • type (required)
          The type of the legal resource. See Legal Resources section below for more information on the types of Legal resources that are supported along with limits on file types and amounts.

        • external_link (required)
          URL link to download resource file.

        • name (optional)
          Name of the resource file, including the file extension.

      • backups (optional)
        Backup recordings for reference.

        • external_link (required)
          URL link to download backup file.

    • combine_inputs (optional)
      Specifies if the audio files included need to be combined into a single transcript.
      When combining inputs, the following rules apply:

      • All input files must be of the same media type
      • Each input must include an order_index
      • Any backup files or legal resources must be associated with the first input

    • legal_tc_types (required)
      Specifies the transcription type being ordered. Multiple types can be ordered simultaneously.
      Supported types include:

      • ai_rough_draft
      • human_rough_draft
      • ready_to_certify

    • rush (optional)
      Should the order be rushed for faster delivery.

    • proceeding_type (required)
      Specifies the type of proceeding to be transcribed.
      Supported proceeding types include:

      • deposition
      • hearing
      • statement_on_record
      • examination_under_oath
      • other

    • template (required only for Ready to Certify orders)
      Specifies the ID of the ready to certify template to be used when generating the transcript.
      Template IDs are accessible via a GET request to /templates.

  • notification (optional)
    Optionally, you may request that an HTTP post be made to a url of your choice when the order enters a new status (e.g. being transcribed or reviewed) and when it is completed.

    • url (required)
      The url for notifications. Updates will be posted to this URL.

    • level (optional)
      specifies which notifications are sent. If "Detailed", then a notification is sent whenever the order is in a new status or has a new comment. If "FinalOnly" (the default), notification is sent only when the order is complete.

    • content_type (optional)
      Specifies the content-type that notifications will be transmitted with.
      If "FormUrlEncoded" (or omitted), they will be transmitted in application/x-www-form-urlencoded format.
      If "ApplicationJson", they will be transmitted in application/json format.

  • po_number (optional)
    Optionally, you may add a PO, Project, or Department to specify how the order should be paid. Only Valid if customer has invoicing.
    Max Length: 64.

  • workspace_id (optional)
    Optionally, you may add a workspace id to specify the workspace the order should be placed in.
    The user must be a member of the workspace with the provided id. If no id is provided, the order is placed in the user's default team.

Response On success, 201 Created.
On error, 400 Bad Request.
Response Headers
  • Location – URI identifying the newly created order. This URI can be used to request details (such as status) of the order. Only present if a 201 response code is returned.
Response Body On success, empty. On error, will contain an <error/> entity with more details.
Error Codes
  • 10001 Missing Inputs - if the order request did not contain any input media
  • 10002 Invalid Input - if one of the input media URIs is invalid, eg does not identify a valid media uploaded via a POST to /inputs
  • 10003 Multiple Service Options Specified - currently, an order can be made for only one of the three services we offer (transcription and caption). The service is specified by including a transcription_options, automated_transcription_options, or caption_options element. If more than one such element is included in the request, this error is returned.
  • 10004 Service type is not specified - you must include exactly one of transcription_options, automated_transcription_options, or caption_options elements. If none of these are included, this error is returned.
  • 10005 External Link and URI specified - only External Link or URI should be set for input media
  • 10006 Input Location is not specified - neither of External Link and URI set for input media
  • 10007 Cannot connect to the External Link provided
  • 10008 S3 buckets are not supported, consider using a signed S3 URL instead
  • 10009 One of media inputs has an invalid order_index. Values must be populated and sequential, starting with index 1
  • 10010 One of media inputs has invalid data. With combine_inputs=true, any Backup Files or Legal Resources must be associated with the first input
  • 10011 Backup media is only valid for transcription orders with transcription_options.legal_tc_types that includes ready_to_certify
  • 10012 Legal template is only valid for transcription orders with transcription_options.legal_tc_types that includes ready_to_certify
  • 10013 The provided legal template is not valid
  • 10014 Legal template is required for transcription orders with legal_tc_types that include ready_to_certify and proceeding_type that is not Other
  • 10015 Legal details can only be provided for orders with transcription_options.legal_tc_types
  • 10016 Legal orders can only be placed by legal customers
  • 10017 Using both LegalTcTypes and LegalTcType is not supported, consider only using transcription_options.legal_tc_types
  • 10018 ProceedingType is required for orders with transcription_options.legal_tc_types
  • 20001 Invalid Media Length - If one of the input medias has a specified audio length that is not a positive integer. This will also be returned if you do not provide the audio length and we are unable to calculate it automatically
  • 20010 Reference Number Too Long Code - the reference number provided longer than 256 characters
  • 20020 Speaker list may not exceed 100 speakers
  • 20021 Speaker names may not exceed 50 characters
  • 20030 Glossary may not exceed 1000 entries
  • 20031 Glossary entries must not be null nor exceed 255 characters
  • 20040 Number of provided accents may not exceed 8
  • 20041 One or more provided accents are not supported
  • 20042 Legal resources have exceeded the maximum number of allowed resources
  • 20043 Legal resource file type is not valid
  • 20050 User does not have authorization to add a Workspace Id
  • 30010 Ineligible For Balance Payments - if the user on whose behalf the order request was made is not eligible for paying using account balance
  • 30011 Account Balance Limit Exceeded - if the order request specified payment using account balance, but doing so would exceed the user's balance limit
  • 40010 PO Number Too Long - The PO, Project, or Department provided exceeded the max length
  • 40011 User Unauthorized For PO Number - User does not have invoicing set up or cannot set PO at checkout
  • 40012 Invalid Order Type For PO Number - PO, Project, or Department provided for an unsupported order type
  • 50000 Field Validation Errors - One or more of the fields are in the wrong format
  • 50002 Sandbox Mode Required - your keys are not set up to place real orders. Read about sandbox mode and getting production credentials.
Legal Resources

The following types of legal resources are supported:

type description accepted file types limit
topsheet Cover/Top Sheet Text, Word, PDF, JSON 1
worksheet Agency Worksheet Text, Word, PDF, JSON 1
tag_file Annotations/Tag File
Log Notes/Metadata Sheet
Text, Word, PDF, JSON 1
notice Notice Text, Word, PDF, JSON 1
reporter_notes Reporter Notes Text, Word, PDF, JSON 1
exhibit Exhibit Text, Word, PDF, JSON, Audio, Video 150
other Other Text, Word, PDF, JSON, Audio, Video 10 *

* When proceeding_type is other, the limit for this type of legal resource is increased to 20.

Annotated sample request
{
    /* 
        Optional, whether to place a sandbox mode or real order 
    */
    "sandbox_mode": true,
    /* 
        Optional, a reference number for the order meaningful for the client 
    */
    "client_ref": "Legal API test order",
    /*
       Mandatory, provides information on what needs to be transcribed and
       allows for any transcription options to be set.
    */
    "transcription_options": {
        /*
           Mandatory, contains list of media to transcribe.
           Must have at least one element
        */
        "inputs": [
            {
                /*
                    URL link to download media file that is to be transcribed.
                */
                "external_link": "https://www.rev.ai/FTC_Sample_1.mp3",
                /*
                    Optional, list of speaker names.
                    Compatible with any input format.
                */
                "speakers": ["John", "Jane", "Sam Jones"],
                /*
                    Optional, list of glossary entries.
                    Compatible with any input format.
                */
                "glossary": ["cryptography", "MD5", "SHA-1", "bcrypt"],
                /*
                    Additional legal resource files to be referenced for transcription.
                    See table above for a full list of supported legal resource types.
                */
                "legal_resources": [
                    /*
                        Topsheet resource document link and file name.
                    */
                    {
                        "type": "top_sheet",
                        "external_link":"https://www.rev.com/top_sheet.txt",
                        "name": "Test topsheet 1.txt"
                    },
                    /*
                        Worksheet resource document link and file name.
                    */
                    {
                        "type": "worksheet",
                        "external_link": "https://www.rev.com/worksheet.txt",
                        "name": "test worksheet 1.txt"
                    },
                    /*
                        Tag file resource document link and file name.
                    */
                    {
                        "type": "tag_file",
                        "external_link": "https://www.rev.com/tag_file.txt",
                        "name": "test tag file 1.txt"
                    }
                ],               
                /*
                    Backup recordings for reference
                */
                "backups":[
                    {
                        "external_link": "https://www.rev.com/backup_audio1.mp3"
                    },
                    {
                        "external_link": "https://www.rev.com/backup_audio2.mp3"
                    }
                ]
            }
        ],
        /*
            Specifies the transcription types being ordered. Supported types:
            ai_rough_draft, human_rough_draft, ready_to_certify
        */
        "legal_tc_types": ["ai_rough_draft", "ready_to_certify"],
        /*
            Optional, should we rush this order?
            Rush will deliver your files up to 5x faster.
            Requesting Rush adds $1.25 per audio minute to the cost of your orders.
            We expect a high degree of accuracy with these files.
            However, speaker names may be inconsistent for files over 30 minutes.
        */
        "rush": true,
        /*
            Mandatory, specifies the type of proceeding to be transcribed. Supported proceeding types:  
            deposition, hearing, statement_on_record, examination_under_oath, other
        */
        "proceeding_type": "deposition",
        /*
            Mandatory when ordering a ready_to_certify transcript.  
            Specifies the ID of the ready to certify template to be used when generating the transcript.
            Template IDs are accessible via a GET request to the /templates endpoint.
        */
        "template": 123456
    },
    /*
      Optional, enables receiving notifications about the order status
    */
    "notification": {
        /*
            The url for notifications.
            Mandatory if the notifications element is used.
            Updates will be posted to this URL
        */
        "url": "http://www.clientsite.com/orderupdate",
        /*
           Optional, specifies which notifications are sent. If "Detailed",
           then a notification is sent whenever the order is in a new status
           or has a new comment. If "FinalOnly" (the default), notification is
           sent only when the order is complete.
        */
        "level": "Detailed",
        /*
            Optional, specifies the content-type that notifications will be transmitted with.  
            - If "FormUrlEncoded" (or omitted), they will be transmitted in application/x-www-form-urlencoded format. 
            - If "ApplicationJson", they will be transmitted in application/json format.
        */
        "content_type": "FormUrlEncoded"
    },
    /*
      Optional- customer must have invoicing, it links order to PO, Project, or Department for billing
    */
    "ponumber": "SamplePoNumber01",
    /*
      Optional- id of the workspace the order should be placed in
    */
    "workspace_id": 123456789
}
                    
Annotated sample request for audio concatenation
{  
    /* 
        Optional, whether to place a sandbox mode or real order 
    */
    "sandbox_mode": true,
    /* 
        Optional, a reference number for the order meaningful for the client 
    */
    "client_ref": "Legal API test order",
    /*
        Mandatory, provides information on what needs to be transcribed and
        allows for any transcription options to be set.
    */
    "transcription_options": {
        /*
           Mandatory, contains list of media to transcribe.
           Must have at least one element
        */
        "inputs": [
            {
                /*
                    URL link to download media file that is to be transcribed.
                */
                "external_link": "https://www.rev.ai/FTC_Sample_1.mp3",
                /*
                    Optional, use only when combine_inputs is true
                    Indicates files sequential order in the concatenation of
                    audio/video files
                */
                "order_index": 1,
                /*
                    Optional, list of speaker names.
                    Compatible with any input format.
                */
                "speakers": ["John", "Jane", "Sam Jones"],
                /*
                    Optional, list of glossary entries.
                    Compatible with any input format.
                */
                "glossary": ["cryptography", "MD5", "SHA-1", "bcrypt"],
                /*
                    Additional legal resource files to be referenced for transcription.
                    See table above for a full list of supported legal resource types.
                    When combining inputs, it is important to associate the legal resources with the first input.
                */
                "legal_resources": [
                    /*
                        Topsheet resource document link and file name.
                    */
                    {
                        "type": "top_sheet",
                        "external_link":"https://www.rev.com/top_sheet.txt",
                        "name": "Test topsheet 1.txt"
                    },
                    /*
                        Worksheet resource document link and file name.
                    */
                    {
                        "type": "worksheet",
                        "external_link": "https://www.rev.com/worksheet.txt",
                        "name": "test worksheet 1.txt"
                    },
                    /*
                        Tag file resource document link and file name.
                    */
                    {
                        "type": "tag_file",
                        "external_link": "https://www.reg.com/tag_file.txt",
                        "name": "test tag file 1.txt"
                    }
                ],   
                /*
                    Backup recordings for reference.
                    When combining inputs, it is important to associate the backups with the first input.
                */
                "backups":[
                    {
                        "external_link": "https://www.rev.com/backup_audio1.mp3"
                    },
                    {
                        "external_link": "https://www.rev.com/backup_audio2.mp3"
                    }
                ]
            },
            {
                /*
                    URL link to the second media file that is to be combined with the 
                    first.
                */
                "external_link": "https://www.rev.ai/FTC_Sample_1.mp3",
                /*
                    Optional, use only when combine_inputs is true
                    Indicates files sequential order in the concatenation of
                    audio/video files
                */
                "order_index": 2
            }
        ],
        /*
            Optional, specifies if the audio files included need to be combined
        */
        "combine_inputs": true,
        /*
            Specifies the transcription types being ordered. Supported types:
            ai_rough_draft, human_rough_draft, ready_to_certify
        */
        "legal_tc_types": ["ai_rough_draft", "ready_to_certify"],
        /*
            Optional, should we rush this order?
            Rush will deliver your files up to 5x faster.
            Requesting Rush adds $1.25 per audio minute to the cost of your orders.
            We expect a high degree of accuracy with these files.
            However, speaker names may be inconsistent for files over 30 minutes.
        */
        "rush": true,
        /*
            Mandatory, specifies the type of proceeding to be transcribed. Supported proceeding types:  
            deposition, hearing, statement_on_record, examination_under_oath, other
        */
        "proceeding_type": "deposition",
        /*
            Mandatory when ordering a ready_to_certify transcript.  
            Specifies the ID of the ready to certify template to be used when generating the transcript.
            Template IDs are accessible via a GET request to the /templates endpoint.
        */
        "template": 123456
    },
    /*
        Optional, enables receiving notifications about the order status.
    */
    "notification": {
        /*
            The url for notifications.
            Mandatory if the notifications element is used.
            Updates will be posted to this URL.
        */
        "url": "https://webhook.site/example",
        /*
            Optional, specifies which notifications are sent. If "Detailed",
            then a notification is sent whenever the order is in a new status
            or has a new comment. If "FinalOnly" (the default), notification is
            sent only when the order is complete.
        */
        "level": "Detailed"
    }
}