Operations

POST /orders

Summary Submit a new order
URL /api/v1/orders
Detailed Description Submit a new order for AI transcription. The order request contains two main elements:
  • AI transcription options. This section contains references to the input media to be transcribed. There are three options for specifying input media:
    • 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.
    • external_link - this should be used if you have a link to a web page where the media is embedded, but not a link to the media file. We do not attempt to do anything with the link specified this way at the time the API call is made. This is done in contrast to when you post to /inputs with a link to a media file - in that case we do download the file.
      The external_link should only be used when you can't link to the media file directly.
      If the external_link points to a YouTube page, we can determine the duration of the video on that page automatically. Otherwise, you will need to specify the media duration explicitly.

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

    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.

  • Notification Info. 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), when a file is ready for download, and when the order is completed. See notifications for more information.

  • PO, Project, or Department. 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. 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.

  • Inputs Language. Optionally, you may specify an inputs_language if you need a Transcription for a non-English source. You can order transcriptions for these language codes: ar, bg, ca, hr, cs, da, nl, en, fa, fi, fr, de, el, he, hi, hu, id, it, ja, ko, lt, lv, ms, cmn, no, pl, pt, ro, ru, sk, sl, es, sv, ta, te, and tr.

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

Request Headers
  • Authorization - contains client/user API keys
Request Body XML or JSON with the details about the order. See below for an example entity illustrating the fields used.
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, AI transcription, 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
  • 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
  • 20003 Invalid Language Code - the inputs_language specified is not supported
  • 20010 Reference Number Too Long Code - the reference number provided longer than 256 characters
  • 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
  • 30029 External URL Not Support - if the organization does not support placing orders with external URLs
  • 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.
Annotated sample request 
{
    /* Optional, a reference number for the order meaningful for the client */
    "client_ref": "XB432423",
    /*
        Mandatory, provides information on what needs to be transcribed and
        allows for any AI transcription options to be set
    */
    "automated_transcription_options": {
        /*
            Mandatory, contains list of media to transcribe.
            Must have at least one element.
        */
        "inputs": [
            {
                /* Length of audio, in seconds rounded up */
                "audio_length_seconds": 60,
                /* URI of the media, as returned from the call to POST /inputs */
                "uri": "urn:rev:inputmedia:467432fds"
            },
            {
                /* YouTube URL, audio length determined automatically */
                "external_link": "http://www.youtube.com/watch?v=UF8uR6Z6KLc"
            },
            {
                /* For any other external link URL audio length is mandatory */
                "audio_length_seconds": 300,
                "external_link": "https://vimeo.com/7976699"
            }
        ],
        /* Optional, source language of the input to be processed */
        "inputs_language": "en"
    },
    /* 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,
            has a completed file ready for download, or has a new comment.
            - If "FileComplete", then a notification is sent whenever work on a file has been completed
            and is ready for download.
            - If "FinalOnly" (the default), a 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
}
                    
<order_request>
    <!--
        Optional, a reference number for the order meaningful for the client
    -->
    <client_ref>XB432423</client_ref>
    <!--
        Mandatory, provides information on what needs to be transcribed and
        allows for any AI transcription options to be set
    -->
    <automated_transcription_options>
        <!--
            Mandatory, contains list of media to transcribe.
            Must have at least one element.
        -->
        <inputs>
            <input>
                <!--
                    Length of audio, in seconds rounded up
                -->
                <audio_length_seconds>600</audio_length_seconds>
                <!--
                    Mandatory, URI of the media, as returned from the call to POST /inputs
                -->
                <uri>urn:rev:inputmedia:467432fds</uri>
            </input>
            <input>
                <!--
                    YouTube URL, audio length determined automatically
                -->
                <external_link>http://www.youtube.com/watch?v=UF8uR6Z6KLc</external_link>
            </input>
            <input>
                <!--
                    For any other external URL audio length is mandatory
                -->
                <audio_length_seconds>300</audio_length_seconds>
                <external_link>https://vimeo.com/7976699</external_link>
            </input>
        </inputs>
        <!--
            Optional, source language of the input to be processed
        -->
        <inputs_language>en</inputs_language>
    </automated_transcription_options>
    <!--
        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</url>
        <!--
            Optional, specifies which notifications are sent. 
            - If "Detailed", then a notification is sent whenever the order is in a new status,
            has a completed file ready for download, or has a new comment.
            - If "FileComplete", then a notification is sent whenever work on a file has been completed
            and is ready for download.
            - If "FinalOnly" (the default), a notification is sent only when the order is complete.
        -->
        <level>Detailed</level>
        <!--
            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</content_type>
    </notification>
    <!--
        Optional, customer must have invoicing, it links order to PO, Project, or Department for billing
    -->
    <ponumber>SamplePoNumber01</ponumber>
    <!--
        Optional, id of the workspace the order should be placed in
    -->
    <workspace_id>123456789</workspace_id>
</order_request>