BizInsights API Documentation v3.5
BizInsights API Service provides a programmatic access via REST API to allow users to tap into BizInsights' database.
Users are able to acquire data of a corporate entity or an individual that is registered with Accounting and Corporate Regulatory Authority (ACRA) of Singapore by using our Search API. Users are also able to tap on our Report API to generate report, be it for filing purposes or KYC.
The REST API identifies the users via a token and the format of the results are in JSON.
Entity Search
Our Entity Search API provides access to our search engine to obtain basic information of people and corporate entities. You can do a search using part of the name of the entity that you would like to search for. Alternatively, you can provide the full ID or Unique Entity Number (UEN) of the entity as a search query. The search will only return first 100 records available for each result set. If you did not get the result you desire, you would need to refine your search query.
Request
To search for entities, you will need to provide the url as per below:
https://api.bizinsights.net/api/search?[token=]&[entity=]&[query=]
e.g. https://api.bizinsights.net/api/search?token=123456&entity=corporate&query=test
The definition of each parameter is explained in the table below.
Parameter | Description | Option | Mandatory |
---|---|---|---|
token | The token to use for authentication. | Yes | |
entity | Determines the index to search Note: If 'all' is provided, the result has a minor difference. Please see the result section below. |
corporate person all |
Yes |
query | The query to use for search. The search will return better results if more keywords are provided |
Yes |
Response
The search response is returned in json format.
{
"category": "corporate",
"message": "Got 1 results in 40ms. Showing only top 100 results",
"timestamp": 1519095833037,
"results": [
{
"id": "123",
"name": "ABC",
"formername": "DEF",
"status": "LIVE",
"address": "30 PASIR PANJANG ROAD #10-31/32 SINGAPORE 117440",
"reports": [
"BPF",
"EBPF",
"CBPF"
]
}
]
}
The definition of each key is explained in the table below
Key | Description | Datatype |
---|---|---|
category | The category that is searched | String |
message | Statistical message which contains the amount of results and the time taken for the search to complete | String |
timestamp | The date and time of search in linux epoch format | Long |
results | The search result depending on the search type: All search: Object Corporate/Person search: Array[Results] |
Object or Array[Results] |
The result of 'all' entity search is as below
{
"results": {
"corporate": [
{
"id": 123,
"name": "ABC",
"formername": "DEF",
"status": "LIVE",
"address": "30 PASIR PANJANG ROAD #10-31/32 SINGAPORE 117440",
"reports": [
"BPF",
"EBPF",
"CBPF"
]
}
],
"person": [
{
"uin": "1A2S3D4F",
"id": "****111A",
"name": "DANIEL",
"appointments": 1,
"reports": [
"PPF"
]
}
]
}
}
As 'all' entity type search returns result from both indices, and the format of each result is different, the result of both search is wrapped in an object. Please see the respective result section for the breakdown.
The result of 'corporate' entity search is as below
{
"id": 123,
"name": "ABC",
"formername": "DEF",
"status": "LIVE",
"address": "30 PASIR PANJANG ROAD #10-31/32 SINGAPORE 117440",
"reports": [
"BPF",
"EBPF",
"CBPF"
]
}
The definition of each key is explained in the table below
Key | Description | Datatype |
---|---|---|
id | The ID of the corporate entity | String |
name | The name of the corporate entity | String |
formername | The former name of the corporate entity | String |
status | The status of the corporate entity | String |
address | The address of the corporate entity | String |
reports | The reports available for this entity. The period of the financial information that it was filed in will be appended in format FSH-YYYY-MM (e.g. FSH-2013-12). For more information on the type of reports available, please visit this page. |
Array[String] |
The result of 'person' entity search is as below
{
"uin": "1A2S3D4F",
"id": "****111A",
"name": "DANIEL",
"appointments": 1,
"reports": [
"PPF"
]
}
The definition of each key is explained in the table below
Key | Description | Datatype |
---|---|---|
uin | Unique Identifier | String |
id | The masked ID of the person | String |
name | The name of the person | String |
appointments | The amount of appointments the person holds | Int |
reports | The reports available for this entity For more information on the type of reports available, please visit this page. |
Array[String] |
Report Generation
The Report Generation API provides a way to purchase the reports of corporate entity or person without any UI. The reports provided are the same with those reports that are purchased through our web portal. For more information on the reports we provide, please click here.
Request
To generate reports, you will need to provide the url as per below:
https://api.bizinsights.net/api/generate?[token=]&[type=]&[id=]&[year=]&[mime-type=]&[remarks=]
e.g. https://api.bizinsights.net/api/generate?token=123456&type=fsh&id=123456R&year=2016&mime-type=application/pdf&remarks=abc
The definition of each parameter is explained in the table below.
Parameter | Description | Option | Mandatory |
---|---|---|---|
token | The token to use for authentication | Yes | |
type | The desired report type for purchase. Reports are categorised as below: Standard Reports: BPF, ECI, SCI, PPF Enhanced Reports: EBPF, EECI, ESCI Comprehensive Reports: CBPF, CCI Statements: FSH |
BPF, ECI, SCI, PPF EBPF, EECI, ESCI CBPF, CCI FSH |
Yes |
id | The ID of the person or the Unique Entity Number (UEN) of a corporate entity Please ensure that the ID/UEN is correct. Incorrect ID/UEN will return an error |
Yes | |
year | The year of the financial statement you wish to purchase. This parameter is only required if the report type is FSH. Other report type will ignore this parameter. Note: If this parameter is not provided when the requested report is FSH, the system will return an error |
Varies | |
mime-type | The file format of the report. If undefined, it will default to application/pdf text/xml and application/x-pdfx mime-type are only available for BPF, ECI, SCI & PPF reports Note: application/x-pdfx is a custom mime-type that returns a zip file. |
application/pdf text/xml application/json application/x-pdfx |
No |
remarks | Remarks field that appears in the usage report for identification purpose. | No |
Response
The report generation response is returned in JSON format.
{
"referenceID": "XXXX-XXXX-XXXX-XXXX",
"username": "testuser",
"timestamp": 1499520492353,
"remarks": "abc",
"link": "http://this.is.a.download.link"
}
The definition of each key is explained in the table below
Key | Description | Datatype |
---|---|---|
referenceID | The purchase reference number | String |
username | The user account that purchased the report | String |
timestamp | The date and time of purchase in linux epoch format | Long |
remarks | Remarks that are passed when calling this API | String |
link | The download link for the report | String |
Data Generation
The Data Generation API provides a way to retrieve your pre-configured data packets via API to be integrated into your own system. Return Format will be in JSON.
Request
To pull your customised data packet, you will need to provide the url as per below:
https://api.bizinsights.net/api/extract/data/[token]/[packetID]/[regno]
e.g. https://api.bizinsights.net/api/extract/123456789/DATA-PACKET-001/202012345A
The definition of each parameter is explained in the table below.
Parameter | Description | Mandatory | token | The API token provided to our customers for authentication | Yes |
---|---|---|
packetID | Each self-customised data packet will be given a unique data packet ID to be used during the API call | Yes |
regno | UEN number of the company for the data requested | Yes |
Response
The data API response is returned in JSON format.
{
"transactionDetail" : {
"referenceID": "2021-0101-ABCD-123A",
"username": "testUser",
"timestamp": "1611306401187"
},
"data" : {
[packetID] : {
"companyName" : "ABC PTE LTD",
"companyAddress" : "123A YISHUN AVE 99 #01-234 SINGAPORE 123456"
.
.
"companySSICCode" : "54321"
}
}
}
The definition of each key is explained in the table below
Key | Description | Datatype |
---|---|---|
referenceID | The purchase reference number | String |
username | The user account that purchased the report | String |
timestamp | The date and time of purchase in linux epoch format | Long |
packetID | Packet ID in relation to the data provided (Examples: profileInfo, officerInfo, etc.) |
String |
datafield | Key value for the data field included in each data packet | String |
Profile
The Profile API allows user to access the information of the account registered with BizInsights. The development of this API is always ongoing, which means that new endpoints/functionalities will be available in the future.
When you register with BizInsights, we have requested some information from you which helps us identify you better. These information can be retrieved and updated, should there be a need for it. No sensitive information can be retrieved from this API.
Below are the currently available functionalities
Retrieval
To retrieve the profile information, send a GET request to the url with the parameters as per below:
https://api.bizinsights.net/profile/details?[token=]
e.g. https://api.bizinsights.net/profile/details?token=12345A
The search result is returned in json format
{
"userID": "apitest",
"firstName": "A Test Account",
"lastName": "This Is",
"email": "test@example.com",
"dateCreated": "2016-06-30",
"companyName": "Test Example Pte Ltd",
"credit": 0,
"products": [
{
"code": "BPF",
"name": "Business Profile",
"price": {
"pdf": 360,
"xml": 360,
"json": 360,
"pdfx": 360
}
},
{
"code": "FSH",
"name": "Financial Statement",
"price": {
"pdf": 2140
}
}
]
}
The definition of each key is explained in the table below
Key | Description | Datatype | Modifiable |
---|---|---|---|
userID | The identification of the user | String | No |
firstName | First name of the user registered | String | Yes |
lastName | Last name of the user registered | String | Yes |
Email address of the user registered | String | Yes | |
dateCreated | Created date of this user ID | String | No |
companyName | Name of the company the user belongs to | String | Yes |
credit | Amount of credits left | Int | No |
products | Information of products that can be retrieved by the querying user | Array[Products] | No |
code | Product code | String | No |
name | Name of the product | String | No |
price | Price of the product corresponding to the format Price are in cents and are Int datatype |
Array[Price] | No |
Update
To update your profile information, send a POST request to the below url:
https://api.bizinsights.net/profile/details?[token=]
e.g. https://api.bizinsights.net/profile/details?token=12345A
The body of the request should only contain the fields you wish to update. You would need to set the Content-Type header to application/json.
Example of the request body:
{
"email": "test@example.com",
"companyName": "Test Pte Ltd"
}
The above is a request to only update the email and the companyName of your profile. You are only able to modify the fields that are marked modifiable in the previous table.
You will receive a message to inform you if the request is successful
Exceptions
There are times when mistakes were made, like when parameters are passed incorrectly, or invalid links. Exceptions will be returned with the cause of the error.
The different exceptions are listed in the table below
Code | Description |
---|---|
204 | Request is processed, but content is unable to be returned. Please contact us if this exception is encountered. |
400 | Incorrect/missing parameters. Affected parameter will be listed in the response message. |
401 | Unable to identify user due to missing token parameter or incorrect token. |
403 | Unable to process request due to throttle settings or not enough balance. |
404 | Requested resource not found. |