Response Formats

All requests to the API that do not result in an error condition will return a response document. The format of this response document will depend on whether the request was for a single document or for more than one document, which is paginated.

Single Document Object

Any requests for a single document, such as the details of a specific job or a single result bucket, will return the result embedded in a Single Document Object. This response object will have the properties detailed in the table below:

documentId:

The requested document ID.

Type: String

type:

The document type one of job, bucket or record.

Type: String

exists:

true if the requested document was found, otherwise false and the document field will be empty.

Type: Boolean

document:

The requested document.

Type: Object

Pagination Response

If the request is for more than one document, rather than return all the documents at once, the API will return a page of results inside a Pagination Object.

Queries for the results are always returned wrapped in a pagination object, regardless of the actual number of results.

The pagination object provides convenient URL links to the next and previous pages of results so that your API client does not have to construct them itself. However you can construct these URLs manually using skip and take query parameters as detailed in the Pagination section.

The pagination object will have the following properties:

hitCount:

The total number of documents found by the request. This may not equal the number of documents returned if pagination is in affect.

Type: Integer

skip:

The position in the list of matched documents of the first item in this page.

Type: Integer

take:

true The number of documents requested. This may not equal the actual number of elements in the documents array depending on the position of the page in the total set of results.

Type: Integer

nextPage:

The URI of the next page of results, or empty if there is no next page.

Type: URL

previousPage:

The URI of the previous page of results, or empty if this is the first page.

Type: URL

documents:

The list of documents in this page.

Type: Array of Objects

Warning

Pagination is designed to allow memory efficient access to the results. The skip and take parameters can be increased to reduce the code required to handle pagination. However take care to not to use a huge value for skip and take. With very large numbers of results, the memory required for the JSON documents could exceed the available machine resources, leading to performance degradation and potential system instability.