Searching for submissions
The API definition for submission search is available at
The URL for searching for submissions is:
Searching for a submission returns an array of
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
||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.
||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.
||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.
||Only include this if you included company_num. This should be set to C for company, or B for a business name.
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:
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.
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
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.
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:
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.
||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
||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.
||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
||Optional parameter allowing you to specify html codes for certain characters.
& would be returned instead of
Include &htmlEnc=1 in the query string to receive html encoding.
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
If we want to list all documents for submissions for company number 54512, the call will be
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
Please refer to
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.