Searching for a company

API definition

The API definition for company search is available at https://services.cro.ie/cws/help/operations/companies

URL

The URL for searching for a company or business name is:

https://services.cro.ie/cws/companies?company_num={COMPANY_NUM}&company_name={COMPANY_NAME}&alpha={ALPHA}
&company_bus_ind={COMPANY_BUS_IND}&searchType={SEARCHTYPE}&address={ADDRESS}&skip={SKIP}&max={MAX}&sortBy={SORTBY}
&sortDir={SORTDIR}&format={FORMAT}&htmlEnc={HTMLENC}

Searching for a company returns an array of Company objects. When searching for a company using name only, it is often wise to precede the search with a similar call to company count. This will then help you to come up with a way of paging your results by specifying values for skip and max.

Query string values

The following values may be included in the query string

Value Description
company_num This can mean a company or business number. For name searches, it is wiser to leave this out of your query string. Including this value is useful when trying to ascertain if the number is for a company or business name.
company_name This can be part of the company or business name. The less specific your search, the more results will be brought back. At least three characters should be included. The 'type' of search will impact how the name is used in the search.
alpha This is an alternive search which ignores words like "Ireland", "Company", "Limited", and all punctuation such as ampersand, commas, quotes etc. Note that you can only use alpha if you do not supply a company_name. Both company_name and alpha cannot be used in the same call.
company_bus_ind An optional value which helps to refine your search to list only companies or business names. To restrict to companies only, set company_bus_ind=C. To restrict to business names only, set company_bus_ind=B. To include both companies and business names, set to company_bus_ind=E. If you do not supply company_bus_ind, only companies will be returned.
searchType Values allowed are:

		1 = Exact match (will give very few results usually)
		2 = Starts with this phrase (default)
		3 = Contains this phrase (slowest, but more results) 
If no value is specified, option 2 will be assumed. Option 2 gives the fastest set of search results.
address Any part of the address. This can help narrow down your search results. For example, a search for all companies with the name "john" in the title would return hundreds, possibly thousands of rows. Narrow down the search results by including for example, the town. As an example, &address=maynooth would help narrow down the results so only companies with the word "john" in the name with the word "maynooth" in the address would be returned.
skip This is the number of rows to skip, and is really intended for use in conjunction with the max value. Skip is defaulted to 0. This means that no rows are skipped in the results returned. However, let's say you wanted to implement a paging mechanism so list only 5 companies at a time (this is done by setting max=5), and you are trying to list the rows on the 3rd page of results, then skip would be set to 10 [page 1 = 0->5; page 2 = rows 6->10; page 3 = rows 11->15, therefore for page 3 set skip=10].
max This is the maximum number of rows to return. If no value is specified, a default of 10 rows is returned. You will want to set this if you wish to paginate your results, listing say 5 companies at a time. This would mean including &max=5 in the query string. It will often make sense to call company count before setting this value, as there is no point in restricting the results if you know that a maximum of 1 or 2 rows will be returned in the search.
sortBy If no sortBy column is specified, the search results will automatically be ordered by company_name, in ascending order (i.e. alphabetical). To sort by another column, you may chose one of the following:

	company_num
	company_bus_ind
	company_name
	company_addr_1
	company_addr_2
	company_addr_3
	company_addr_4
	company_reg_date
	company_status_desc
	company_status_date
	last_ar_date
	next_ar_date
	last_acc_date
	comp_type_desc
Note that an incorrect spelling will cause an error in the service call.
sortDir This is the sort direction. If left blank, "ASC" will be assumed. ASC means alphabetical order for alphanumeric columns, lowest numbers first for numeric data, or earliest date first for dates. To sort starting with highest values first, specify "DESC". For example, to sort results by company_num starting with highest numbers first, your query string would include &sortBy=company_num&sortDir=DESC
format Optional parameter allowing you to specify JSON as the return format. Include &format=json in the query string to receive JSON data. Alternatively set a Header value Content-type: application/json.
htmlEnc Optional parameter allowing you to specify html codes for certain characters. For example, & would be returned instead of &. Include &htmlEnc=1 in the query string to receive html encoding.

Minimum requirements

The minumum requirement for a company search is part of the company name or company number.

For example, if we want to search for all companies that start with the word "Ryanair", the call will be

 https://services.cro.ie/cws/companies?company_name=ryanair

Special note on certain date fields

There are three date fields that are part of Company data which necessitate the calling of a function to calculate the date in question. These dates are last_ar_date, next_ar_date and last_acc_date. To reduce overall latency and prioritise the speed of a company search, these dates are deliberately left null when calling the this service. To retrieve these dates for a specific company, call the method which will retrieve the details for one company only.

Paging your search results

By calling company count method, you will get the number of rows returned using the exact same query string. This allows you to predict how many results you should show.

Eircodes

Around mid-August 2015 (date to be confirmed), any eircodes being recorded by the CRO against companies on the register will be made available through the https://services.cro.ie/cws/companies and https://services.cro.ie/cws/company. A new eircode field will be added to the Company object returned by these queries. To allow users to prepare for this change, a new Company test object is available to download via the test api's https://services.cro.ie/cws/companiestest (multiple company search) and https://services.cro.ie/cws/companytest (single company search). The company test object is the same as the company object except it also includes an eircode field.

© 2017 - Companies Registration Office, Bloom House, Gloucester Place Lower, Dublin 1, Ireland. Developed by Enterprise Registry Solutions