Coface ICON Business Information API
V1 - Report API
Report API is a service offered by ICON, Coface Business Information offer. It allows you to request informations about a company.
Products
This API allows you to order and monitor :
| Publication | Available format ( and samples) |
|---|---|
| Full Reports | XML, JSON, HTML, PDF |
| Snapshot Reports | XML, PDF |
| Credit opinion Reports | XML, JSON, HTML, PDF |
| Advanced opinion Reports | XML, JSON, HTML, PDF |
| Score Report | XML, JSON, HTML, PDF |
Notes: In picture below you can see the standard list of product codes. Of course, other specific products can be available depending on your contract with ICON.
Please check How to / FAQ section below for more details about how to use API for ordering a product
Access & Security
Follow the process described in the main page
On the dev portal, you should subscribe to "ICON Report API Sandbox" for testing purposes or "ICON Report API" when you switch to Production environment
Pagination
The API uses its specific paging based on offset and limit parameters for paged operations. Pagination size will always be maxim 20.
The request can have input parameters offset and limit. More details can be found in Swagger file
The response header will have the following fields added:
- Accept-Range -{ressourceName} ${maxPageSize}
- Content-Range - ${offset}–${limit} / total count of search results
- X-Total-Count - total count of search results
An X-Total-Count header is added to responses to indicate the total number of items in a paged response.
Process
To order monitoring or report, you need to follow 5 steps :
- Find the company
- Check if the publication is available
- Order the publication with or without monitoring
- Verify that the order is finished
- Retrieve the publication
In case you have ordered a monitoring, during the next year, you can receive notifications. Once you get one, you can retrieve its content.
To order monitoring or report, you need to find on which company you want the data.
You always need to check if the company is still available because
- companies are a living entity, it can disappear following a bankruptcy for example
- Coface relies on partners to get the information for some countries. It happens that we decide to change partner if we find one with better information. In this case the company id can change.
Retrieving a company depends on the accuracy of your input :
- if you know an unique identifier for this company (like icon number or use an unique id from a national referential, like VAT number), you can call directly the GET /company endpoint to retrieve the company AND the available products.
- if you don't then use the GET /companies endpoint to search a company with its name and address. You will receive a summary of matching companies. When you find the one you want, you can retrieve the full details about this company by calling the GET /company with the external id provided in the summary.
- Coface will try its best to answer you quickly. But in some countries, it can't be possible and Coface will need time to make an investigation. When you order you report, you will have the possibility to specify if you want immediate result or not. If we can't provide you data, you will of course not be charged.
- You have to possibility to request a report even if you don't find the company in our database. A Coface agent will do an investigation and create a report if he find the company or cancel the order if not. In this case, you will not be charged.
- The time to process an order varies by country and provider. For immediate order, it takes maximum few seconds
- Sames indications as Ordering a report.
- A monitoring is placed for 1 year.
Notification
Once your monitoring is placed, you will receive notifications when changes are made. If you have set a callback url in your monitoring order, we will ping you as soon as something changed, if not it's up to you to check any change.
Technical documentation
Swagger
Public available here
Also available on our dev portal. NOTE : you need to be logged otherwise you will see an empty page.
Postman collection
You can test our API without any developpment using Postman.
You have to
- Download Postman
- Download our
- demo environment setting, using a demo user
- prod environment setting
- collection with all the steps to order report
- Modify the credentials in the environment settings
How To / FAQ
- Import the files
- Click on "Environments" tab
- Select the environment you want to modify
- Change the initial value of credentials
- Click on "Persist All" to copy Initial value to Current value
- Save
research_delivery_speed : It's an indication of when you need this information.
| Value | Meaning |
|---|---|
| immediate_no_research | I don't want to wait. So if you can not give the answer immediately don't do it. |
| immediate_if_available_research_otherwise | Give me what data you have, if you have any, request it, I can wait a little. |
| research_no_immediate | Even if you have data in your database, please check if the data are up-to-date. I can wait. |
research_delivery_speed : It's an indication of when you need this information.
| Value | Meaning |
|---|---|
| normal | Few days |
| express | One day |
| flash | Few hours, less than a day |