Searching for submissions

API definition

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

URL

The URL for searching for submissions is:

https://services.cro.ie/cws/submissions?subNum={SUBNUM}&companyNum={COMPANYNUM}&companyBusInd={COMPANYBUSIND}
&sortBy1={SORTBY1}&sortDir1={SORTDIR1}&sortBy2={SORTBY2}&sortDir2={SORTDIR2}&skip={SKIP}&max={MAX}
&format={FORMAT}&htmlEnc={HTMLENC}

Searching for a submission returns an array of SubmissionDoc objects. Note that a single SubmissionDoc object represents a one single document relating to a submission. A submission in the CRO can have multiple documents attached to it. For example, an "Annual Return" submission will often be accompanied by a set of Accounts. This means two documents would be returned if you searched using only the submission number, namely the "B1 Annual Return", and "Account Details".

When searching for all submissions for a particular company, it may be a good idea to precede the search with a similar call to submission count. This will then help you to come up with a way of paging your results by specifying values for skip and max.

A special note on dates

The CRO has many records where no "effective date" or "accounts to date" was obtained. This is often the case with very old submissions, and many submissions received up to the mid 1980s. In almost all submissions, the "received date" is available. Please keep this in mind when looking at dates for some submissions. In such cases, you will see a value of 0001-01-01T00:00:00Z. This means that the CRO does not have the correct date stored on the live database.

Query string values

The following values may be included in the query string

Value Description
sub_num The submission number. If you supply the submission number in your search criteria, you will receive very few SubmissionDoc records back. Only use this if you are confident that you have the correct submission number.
doc_num This is the number to identify the document within the submission. See the above note concerning the concept of a SubmissionDoc to understand how documents form part of a submission. It often makes sense not include the doc_num in your query, unless you want to receive just one document back relating to the sub_num that you supplied.
company_num This can mean a company or business name number. Include the company_num in your query string if you want to list the submissions for the company. If you include the company_num, then you must include the company_bus_ind in the query string.
company_bus_ind Only include this if you included company_num. This should be set to C for company, or B for a business name.
sortBy1 If no sort column is specified, the default order will start at the highest sub_num, followed by the most recent sub_received_date. To sort by a different column, you may chose one of the following:

	sub_num
	doc_num
	sub_type_desc
	doc_type_desc
	sub_status_desc
	sub_received_date
	sub_effective_date
	acc_year_to_date

Note that an incorrect spelling will cause an error in the service call.

Important: If specifying a date in the sort expression, note that unpredictable sort results may occur especially for sub_effective_date, and acc_year_to_date. If in doubt, sorting by sub_num gives the most predictable results. For most cases, the highest submission numbers will be for the most recent submissions. See the note on dates above this section to understand the potential problems with dates.

sortDir1 This is the sort direction, and should be used in conjunction with sortBy1. 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 sub_num starting with highest numbers first, your query string would include the following:

		&sortBy1=sub_num&sortDir1=DESC
sortBy2 If you wish to specify a further sort expression, do so by including sortBy2 in the query string. The same rules apply as with sortBy1 concerning allowed columns.
sortDir2 This is the sort direction for sortBy2 clause. As an example, if you wanted to list the highest sub_num values first, followed by the lowest doc_num values, your sort expression in the query string will be:

		&sortBy1=sub_num&sortDir1=DESC&sortBy2=doc_num&sortDir2=ASC
Note that if you do not include sortDir2, even though you did supply sortBy2, ASC will be assumed. That means the lowest numbers would be listed first.
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 submissions at a time (this is done by setting max=5), and you are trying to list the rows on the 2nd page of results, then skip would be set to 5 [page 1 = 0->5; page 2 = rows 6->10, therefore for page 2 set skip=5].
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 submissions at a time. This would mean including &max=5 in the query string. It will often make sense to call submission count before setting this value, as there is no point in restricting the results if you know that a maximum of only 1 or 2 rows will be returned in the search.
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 submission search is either a company_num and company_bus_ind, OR, the sub_num.

For example, if we wanted to list all documents for sub_num 5445465, the call will be

 https://services.cro.ie/cws/submissions?sub_num=5445465

If we want to list all documents for submissions for company number 54512, the call will be

 https://services.cro.ie/cws/submissions?company_bus_ind=c&company_num=54512

Note that the same results can be acheived by tagging on /submissions to the call to get the details for one specific company. The URL in that case would be

 https://services.cro.ie/cws/company/54512/c/submissions

Please refer to https://services.cro.ie/cws/help/operations/submissionsForCompany for the service API help if you wish to use this approach. The query string parameters are the exact same as for the normal submission search method.

Paging your search results

By calling submission 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.

© 2022 - Companies Registration Office, Bloom House, Gloucester Place Lower, Dublin 1, Ireland.