Document

API definition

The API definition for retrieving a Document as a byte stream is https://services.cro.ie/cws/documentapi/help/operations/document

Flow Chart

The process of retrieving a document is outlined in the following flow chart

URL

The URL for getting the document is:

 https://services.cro.ie/cws/documentapi/document/{DOC_ID}?key={KEY}

The verb used to call this URL must be Http GET. The value returned is a byte stream. This byte stream can then be saved as a multi-page TIFF. Streaming in other file formats is not currently available. If you need the document as a PDF, this conversion must take place in your own application.

Variables

Value	Description
DOC_ID	The document id. This must be the doc_id that was supplied for "doc_id" in the Request Body of the preceeding call to permissionrequest. If it is not the same, a status code of 400 Bad Request will be returned. Remember that the "doc_id" is available when you grab the SubmissionDoc details. Please refer to the data dictionary and the submission help pages for more info.
KEY	This is the Authorization Key that is returned from the preceeding Http POST that was made to permissionrequest.

Response Status Codes

The following is the list of possible Status Codes returned in the Response. If 200 OK is not returned, the returned Status message will contain details of the error message.

Response	Explanation
200 OK	Success. A byte stream is returned. This can be displayed directly to the user and saved as a multi-page TIFF. It makes sense for you to perform your own archiving of documents which you order to prevent re-ordering the same document.
400 Bad Request	This can arise in a few situations, but most frequently it will be for one of the following reasons: The value supplied for {KEY} is invalid. Most likely, characters in the Authorization Key have been changed or missing There is a problem with one of the mandatory values encoded in the Authorization Key. The error message returned will specify exactly where the problem is. The query string value {DOC_ID} does not match the value "doc_id" that was posted in the Request Body when calling permissionrequest. For example, the value requested in permissionrequest was 12345555, but the value supplied for {DOC_ID} is 65413212. The value mismatch causes Status Code 400.
401 Unauthorized	This can happen in any of the following situations: The credentials in your Authentication Header are invalid (i.e. the Base64 encoded version of emailaddress:apikey) The link has expired. If you specified a time_to_live in the preceeding permissionrequestof a few seconds, and tried to retrieve the account balance after the time has elapsed, you will get a 401
412 Precondition Failed	This can occur in one of the following situations The {KEY} is missing from the URL. Insufficient balance in the Customer Account. The workaround is to deposit funds in your account using the Company Search website.

Example: Getting a Document

The following is the sequence of steps to get the multi-page TIFF for doc_id 56566674:

1. Get the Authorization Key with permission request

To get the Authorization Key, refer to Example 2 in the permission request help page.

For demonstration purposes, let's assume that the key returned is

"EAAAAMCJlm%2flJlEUMSwjULtRey8uAO%2fkZRMWcLrEaiukHAb0pksSnYOb4OMY%2f2ECi%2bISqKqN1Pm3d6dblxOjLbo7acUilodR
pmI%2bKuGTxqI6NGEXF8WmYWUSNQxbO8lXZzKvrg%3d%3d"

2. Get the document

Using the key returned in step 1, we now execute an Http GET to the following URL:

 https://services.cro.ie/cws/documentapi/document/56566674?key=EAAAAMCJlm%2flJlEUMSwjULtRey8uAO%2fkZRMWcLrEa
 iukHAb0pksSnYOb4OMY%2f2ECi%2bISqKqN1Pm3d6dblxOjLbo7acUilodRpmI%2bKuGTxqI6NGEXF8WmYWUSNQxbO8lXZzKvrg%3d%3d

A byte stream will be returned. This can be saved as a multi-page TIFF.

At this point, the price of a document will be deducted from your Account Balance. You can see these orders when you look at your Current Statement in the Company Search site.

Here is a sample of what the transactions would look like in your statement. The Customer Ref makes it clear that the order was placed through Open Services. The number appearing after "OPEN SERVICES" is the doc_id of the Document that was ordered.