If a Customer was to check their Account Balance, and purchase documents through the Company Search website, they would log into the website using a Customer Number and PIN.

A permission request can be viewed similarly. Getting the balance on a customer account, or purchasing a document using Open Services, requires a Customer Number and PIN. The permission request ensures that a Customer is providing valid credentials. It also checks that the Customer is in fact linked to an API Key issued through Open Services.

If a permission request is successfully executed, an authorization key is returned. This key is then appended as a query string parameter to the subsequent request.

URL

The URL for a permission request is:

 https://services.cro.ie/cws/customerapi/account/permissionrequest

The verb used to call this URL must be Http POST.

Request Body

In addition to supplying an Authorization Header, the Request Body in the Http POST must contain a number of values supplied in JSON format. Values can be supplied in any order. The values are explained as follows:

Value	Description
customer_num	The Customer Number (mandatory). This is the same Customer Number that you would use to log into the CRO Company Search website
customer_pin	The Customer PIN (mandatory). The matching PIN for the Customer Number entered above
time_to_live	The "time to live" for the request (mandatory). The value must be an integer, representing the number of seconds that the authorization key will be valid for. 60 seconds is a practical minimum, although you can use a shorter time if you wish. Note that high latency could cause authorization keys to expire, so it is not practcal to set it too short. The maximum allowed value is 3600 seconds (i.e. 1 hour).
requested_method	This is where you will indicate what you are looking for permission to do next. Only two values are currently acceptable here: balance - if you intend to get the account balance, supply the word "balance" document - if you intend to purchase a document, supply the word "document" printout - if you intend to purchase a company printout cdocument, supply the word "printout"
doc_id	Only necesssary if requested_method is set to "document". 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. (If Bulk Data Customers are using this service, this may be called "Filenet Doc Id" in your specification.)

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. You should check the contents of the status message in the event of any return code other than "200 OK".

Response	Explanation
200 OK	Success. An Authorization Key is returned.
400 Bad Request	This can happen in any of the following situations: One of the required values in the Request Header is missing The time_to_live is not a valid integer representing a number of seconds If "document" was specified as the requested_method, a value for doc_id must also be specified. It is possible that the doc_id was ommitted
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 customer number specified in the Request Body is not linked to the API Key encoded in the Authorization Header. You must specifically request from the CRO for the API Key to be linked to your Customer Account Number The customer_num and customer_pin specified in the Request Body are not correct. The same credentials should be usable on the Account Login page in the Company Search Site
404 Not Found	This occurs when the "requested_method" is set to "document", but the "doc_id" specified does not actually exist. In other words, a request was made for permission to get a document which does not exist
412 Precondition Failed	Two possible reasons: Permission was requested to get an Authorization Key to stream a document, but there is an insufficient balance on the account to go ahead with the purchase. The workaround is to deposit funds in your account using the Company Search website. The value specified for "time_to_live" is too high. A maximum of 3600 is allowed (this is equal to 1 hour).

Example 1: Permission Request for Account Balance

Let's assume that an Open Services user has the following credentials:

[email protected]:0903f484-1db9-4245-a542-737e0ec2a548

When we Base64 encode this and include in the Authorization Header, the full Authorizaton Header becomes:

Authorization: Basic dGVzdEB0ZXN0aW5nLmNvbTowOTAzZjQ4NC0xZGI5LTQyNDUtYTU0Mi03MzdlMGVjMmE1NDg=

You must also specify the Content-type as JSON:

Content-Type: application/json;charset=UTF-8

Now, assume that the Customer Number is 1234. The Customer PIN is ABC123. And finally, the Customer wants the Authorization Key to be valid for 5 minutes.

Here is the JSON that must be supplied in the Request Body:

{"customer_num":"1234","customer_pin":"ABC123","requested_method":"balance","time_to_live":"300"}

Assuming the call returns a 200: SUCCESS, an Authorization Key is returned as a string. A sample Authorization Key might look something like this:

"EAAAAGQl%2bp42SfKXBTUfyh48320KHgBzxpur6%2fMrWYuWd2x9ZpUpSlezmdaPlAlHGDED3fEBOMF3SjW6biZFkazgp0hieB75C1T3pXPRgOoLGSFF"

The above key can then be used in a query string to request the Account Balance.

Example 2: Permission Request to retrieve a Document

Assume that the Open Services user has the following credentials:

[email protected]:0903f484-1db9-4245-a542-737e0ec2a548

When we Base64 encode this and include in the Authorization Header, the full Authorizaton Header becomes:

Authorization: Basic dGVzdEB0ZXN0aW5nLmNvbTowOTAzZjQ4NC0xZGI5LTQyNDUtYTU0Mi03MzdlMGVjMmE1NDg=

You must also specify the Content-type as JSON:

Content-Type: application/json;charset=UTF-8

The Customer Number is 1234. The Customer PIN is ABC123. The Customer wants the Authorization Key to be valid for 1 minute. This Customer wants to retrieve doc_id 56566674.

Here is the JSON that must be supplied in the Request Body:

{"customer_num":"1234","customer_pin":"ABC123","time_to_live":"60","requested_method":"document","doc_id":"56566674"}

Assuming the call returns a 200: SUCCESS, an Authorization Key is returned as a string. A sample Authorization Key might look something like this:

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

The above key can then be used in a query string to retrieve the document as a byte stream.