Operations

GET /orders

Summary Get paged list of orders for user
URL /api/v1/orders?page={pagenum}&pageSize={pageSize}&ids={orderNumber1}&ids={orderNumber2}..&ids={orderNumberN}
/api/v1/orders?page={pagenum}&pageSize={pageSize}&clientRef={referenceId}
Request Query Parameters
  • pagenum - the number of the page of orders to return. Optional, by default returns the first page
  • pageSize - the number of orders per page to return. Optional, by default returns 25 orders per page. Page size has to be between 5 and 100
  • orderNumber - you can retrieve specific orders by specifying their order numbers. Optional, by default returns all orders. Must not be specified if clientRef is specified - otherwise returns 403 Forbidden response.
  • referenceId - you can retrieve orders associated with the given reference id as used in your application. Optional, by default returns all orders. Must not be specified if ids is specified - otherwise returns 403 Forbidden response.
Detailed Description

Use this method to retrieve the list of orders for a user. The data will be returned as JSON or XML, depending on Accept header and/or URL extension.

The list is returned in a paged manner. The returned result will indicate the total number of orders, as well as number of orders per page and the number of orders in the requested page, which enables a client to iteratively retrieve all orders for the user if desired. The results are ordered in reverse chronological order by placed on date.

Each order entity in the list contains summary information for the order - it omits comments and attachments. To get those, perform a GET /orders/{ordernum} with the appropriate order number.

See below for an annotated example of a response orders entity.

Request Headers
  • Authorization - contains client/user API keys
  • Accept - indicates the format in which the response should be delivered. Must be application/json, application/xml, or text/xml
Response On success, 200 OK
Response Headers None
Response Body An <orders/> entity with a list of orders for the user. This includes information about how many total orders there are, to enable fully paging through the result set.
Error Codes None
Annotated sample response 
/*
    total_count is the total number of orders
    results_per_page shows how may results are returned in each page
    page is the number of the page returned (0-based)
*/
{
    "total_count": 28,
    "results_per_page": 8,
    "page": 0,
    "orders": [
        {
            /* Rev assigned order number */
            "order_number": "TC432432",
            /* 
                Client reference order number 
                provided with the order request 
            */
            "client_ref": "6",
            /* Total cost of the order */
            "price": 56,
            /* Status of the order */
            "status": "Transcribing",
            /* 
                Total length of the audio (in seconds) of media attachments 
                for the order and additional services.
            */
            "transcription": {
               "total_length_seconds": "300",
               "verbatim": true,
               "timestamps": false
            }
            /*
               Attachments and comments are not shown 
               in orders that are returned in this list. 
               Do a GET on orders/{ordernum} to get order attachments.
            */
        }
        /* the rest of the orders in the list */
    ]
}
                
<!--
    total_count is the total number of orders
    results_per_page shows how may results are returned in each page
    page is the number of the page returned (0-based)
-->
<orders total_count="28" results_per_page="8" page="0">
    <order>
        <!-- Rev assigned order number -->
        <order_number>TC432432</order_number>
        <!-- Client reference order number provided with the order request -->
        <client_ref>6</client_ref>
        <!-- Total cost of the order -->
        <price>56</price>
        <!-- Status of the order -->
        <status>Transcribing</status>
        <!-- 
            total length of the audio (in seconds) 
            in media attachments for the order and additional services 
        -->
        <transcription>
           <total_length_seconds>300</total_length_seconds>
           <verbatim>true</verbatim>
           <timestamps>false</timestamps>
        </transcription>
        <!--
           Attachments and comments are not shown in orders that are returned
           in the list. You can GET orders/{ordernum} to get order attachments.
        -->
    </order>
    <!-- the rest of the matches -->
</orders>