API definition

The API definition for retrieving a Company Printout as a byte stream is

Flow Chart

The process of retrieving a copmany print out is outlined in the following flow chart

retrieving a company printout process


The URL for getting the company printout is:{company_num}?company_bus_ind={company_bus_ind}&key={key}

The verb used to call this URL must be Http GET. The value returned is a byte stream. This byte stream can then be saved as a PDF document.


Value Description
COMPANY_NUM This can mean a company or business number.
COMPANY_BUS_IND To retrieve a company print out set company_bus_ind=C. To retrieve a business names only print out, set company_bus_ind=B.
KEY This is the Authorization Key that is returned from the preceeding Http POST that was made to permissionrequest.

Response Status Codes

The following is the list of possible Status Codes returned in the Response. If 200 OK is not returned, the returned Status message will contain details of the error message.

Response Explanation
200 OK Success. A byte stream is returned. This can be displayed directly to the user and saved as a pdf.
400 Bad Request This can arise in a few situations, but most frequently it will be for one of the following reasons:
  • The value supplied for {KEY} is invalid. Most likely, characters in the Authorization Key have been changed or missing
  • There is a problem with one of the mandatory values encoded in the Authorization Key. The error message returned will specify exactly where the problem is.
  • The query string value {COMPANY_NUM} does not match the value "Company_Num" that was posted in the Request Body when calling permissionrequest. For example, the value requested in permissionrequest was 12345555, but the value supplied for {COMPANY_NUM} is 65413212. The value mismatch causes Status Code 400.
401 Unauthorized This can happen in any of the following situations:
  • The credentials in your Authentication Header are invalid (i.e. the Base64 encoded version of emailaddress:apikey)
  • The link has expired. If you specified a time_to_live in the preceeding permissionrequestof a few seconds, and tried to retrieve the account balance after the time has elapsed, you will get a 401
412 Precondition Failed This can occur in one of the following situations
  1. The {KEY} is missing from the URL.
  2. Insufficient balance in the Customer Account. The workaround is to deposit funds in your account using the Company Search website.

Example: Getting a Company Printout

The following is the sequence of steps to get a company printout PDF for company number 1234:

1. Get the Authorization Key with permission request

To get the Authorization Key, refer to Example 2 in the permission request help page.

For demonstration purposes, let's assume that the key returned is


2. Get the company printout

Using the key returned in step 1, we now execute an Http GET to the following URL:

A byte stream will be returned. This can be saved as a PDF.

At this point, the price of a company print will be deducted from your Account Balance. You can see these orders when you look at your Current Statement in the Company Search site.

Here is a sample of what the transactions would look like in your statement. The Customer Ref makes it clear that the order was placed through Open Services. The letters PO stand for company printout (if these letters don't appear then the order was for a submission document). The number appearing after "OPEN SERVICES PO/" is the number of the company for which a printout was ordered. The final letter indicated whether the printout was for a company (C) or a business name (B).

sample transactions

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