Getting started

Service interface help page

To understand the structure of the API requests and responses, you should visit the service interface help at https://services.cro.ie/cws/help.

To begin using the service:

Step 1 - Get an API Key

To access Open Services, you will need to sign up, input your details and complete and sign a copy of the Open Services Terms and Conditions. The signed copy of the Terms and Conditions can be scanned and Emailed to CRO. When the CRO receives this, you will be given an API Key and granted full access.

Step 2 - Use your Email Address and API Key when making a service call

Once your API Key is activated, you will be able to start using the service. You may create your client application using whatever coding platform you wish. A few code examples are available to help you to get started. There are also some code samples available on the downloads page. Links to live working examples (with restricted functionality) are on the examples page.

How to use the API Key

Your email address and API Key must be included in the Authorization header of your request. These credentials must be base64 encoded.

For example, if we have a user whose email address is [email protected], and the API Key for the user is da093a04-c9d7-46d7-9c83-9c9f8630d5e0, the Authorization header would be formed in your code as follows

1. Combine the email address and API key together, separated by a colon. In this case,

   [email protected]:da093a04-c9d7-46d7-9c83-9c9f8630d5e0

2. Encode the above value using Base64 encoding. This will give the following result:

   dGVzdEBjcm8uaWU6ZGEwOTNhMDQtYzlkNy00NmQ3LTljODMtOWM5Zjg2MzBkNWUw

3. Add the Authorizaton Header to your call using Basic access authentication. The complete value will now be

   Authorization: Basic dGVzdEBjcm8uaWU6ZGEwOTNhMDQtYzlkNy00NmQ3LTljODMtOWM5Zjg2MzBkNWUw

The REST call can now be executed using GET as the Http request method.

A simple example

Let's take the example of retrieving details for a company. The company number is 83740, and the company/business indicator is C (meaning it is a company).

The URL for this call would be:

 https://services.cro.ie/cws/company/83740/c

Without valid Authorizaion credentials, this would return a 401:Unauthorized response. Now modify the request header by adding

 Authorization: Basic dGVzdEBjcm8uaWU6ZGEwOTNhMDQtYzlkNy00NmQ3LTljODMtOWM5Zjg2MzBkNWUw

Assuming that the credentials are set correctly, the above call will return the data for the specified Company with a 200:Success response.

Response format

The default response format for all service calls is XML. However, if you prefer to receive a JSON response, you can specify "json" as format in the query string as follows:

 https://services.cro.ie/cws/company/83740/c?format=json

...or by specifying application/json in the Content-type Header:

 Content-type: application/json

Error handling

Implement your own preferred approach to error handling using normal try/catch logic.

You can also preceed lookups with a quick call to the status service. This returns a simple structure containing two pieces of information: ServicesRunning, and Message. If ServicesRunning is false, then you should display a message indicating that the search service is not currently available. Alternatively, you can display the Message returned from the status call, which will contain the CRO's explanation for the downtime, and will often give an idea of when the service will be back running again. The Message will be kept short, and will typically say something like "The service is currently down. We hope to be back at 2.30pm" .