Account Balance

API definition

The API definition for retrieving the Account Balance


The URL for getting the account balance is:{CUSTOMER_NUM}/balance?key={KEY}

The verb used to call this URL must be Http GET. The value returned is a double-precision number representing the account balance.


Value Description
CUSTOMER_NUM The Customer Number. This is the same Customer Number that you would use to log into the CRO Company Search website. The value that is supplied here MUST be the same value that was supplied in the preceeding call to permissionrequest for the "customer_num" in the Request Body.
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. In this case, the account balance is returned. This can then be cast as a double-precision number in your own code.
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. The error message returned will specify exactly where the problem is.
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
  • The customer number specified in the URL is not linked to the API key encoded in the Authorization Header
412 Precondition Failed If you leave the {KEY} out of the URL, you will get a 412

Example: Getting the Account Balance

The following is the sequence of steps to get the Account Balance:

1. Get the Authorization Key with permission request

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

For demonstration purposes, let's assume that the Customer Number is 1234 and that the key returned is


2. Get the account balance

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

The account balance will then be returned as a double-precision number.

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