A Ruby client for working with the CRO API

Vinny | about 3 years ago | ruby, rails, cro, fintech, companies registrations office

We had to do some work recently for a client that involved an integration with the CRO, that's the Company Registrations Office here in Ireland. They have an API, that allows you to search for companies by company number, company name, etc and you can download company documents as well. Most of the stuff that you can do manually through the CRO site.

This is useful stuff if you're a company working in some aspect of the burgeoning fintech sector in Dublin.. loan financing, credit checking.. anything really where you're looking up lots of companies and you want to build that directly into your workflow and not have to rely on an external tool.

You need to apply for an API key, which is pretty straightforward, which you can do here and if you're going to be using some of the paid features, you'll have to go the extra bit and set up an account with payments and a customer PIN. They have some sample code for PHP, C#, Python and Java but none for Ruby so here's a bit to get you started.

Initialise your class instance with your email address and your API key.

  # Initialize and generate the authenication key.
  def initialize email, key
    @email = email
    @API_KEY = key
    @AUTH = get_auth_token unless ( @email.nil? or @API_KEY.nil? )
  end

Then, this code here will generate your authentication token according to the CRO guidelines

  # Generate your auth token using Base64 encoding, following the guidelines here.
  # https://services.cro.ie/overview.aspx
  def get_auth_token
    base_string = @email+":"+@API_KEY
    @AUTH = Base64.strict_encode64(base_string)
  end

Then put that to token to use by looking up the API. In this method here, we're going to lookup a company using the company number. I'm specifying the response format as json, but others are available I believe.

  #Look up a company by company id
  def get_company_by_number num    
    uri = URI("https://services.cro.ie/cws/companies")
    query={
      :company_num => "#{num}",
      :format => "json"      
    }
    
    uri.query = URI.encode_www_form(query)    
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_PEER
    
    begin      
      req = Net::HTTP::Get.new(uri)
      # Set your auth token in the header request for the query.
      req['authorization'] = @AUTH
      response = http.request(req)  
      response
    rescue SocketError => se # No connection
      puts "Got socket error: #{se}"
    end

  end

And that's it you're ready to go. Invoke your code with with something like this.

cro_client = CRO_client.new("YOUR_EMAIL", "YOUR_CRO_ASSIGNED_API_KEY")
response = cro_client.get_company_by_number company_id_number
unless response.nil?
  result = JSON.parse(response.body)
end

There's a working example of this code here.

Does your company work frequently with company documents? Do you spend unnecessary time manually searching for documents or retrieving company information? If you feel that there are opportunities to improve your companies workflow and optimise your service then get in touch and maybe we can help.