INSTANT ACCESS TO AUTHORITATIVE BUSINESS INFORMATION. 80 COUNTRIES & JURISDICTIONS. 1 API. brex.io API TECHNICAL INTERFACE DOCUMENTATION

Transcription

1 Image by Jason Hawkes - hayesdavidson.com a service of kompany INSTANT ACCESS TO AUTHORITATIVE BUSINESS INFORMATION. 80 COUNTRIES & JURISDICTIONS. 1 API. brex.io API TECHNICAL INTERFACE DOCUMENTATION

2 BREX API A SERVICE OF KOMPANY BREX Enterprise API your gateway to verified company information Imagine one neat and powerful API that gives you instant access to 1. Official Commercial Registers 2. Shareholder Information 3. Company Filings 4. Annual & Financial Accounts The next generation of company information trusted and authoritative data for your KYC, AML, AVS, CRM or ERP applications. With only one API to worry about, integration is easy and cost-effective. The BREX Enterprise API is your central gateway to verified business data from 80 countries & jurisdictions in Europe, the USA (beta) and select countries. Make sure to regularly check brex.io for updates. BREX Business Register Exchange GmbH Mariahilfer Strasse 93/2/20, A-1060 Vienna, Austria Page 2 of 12

3 Content BREX Enterprise API your gateway to verified company information... 2 Change Record of this Documentation... 4 BREX API Technical Interface... 4 Online Documentation... 4 Overview... 4 API Authentication... 4 User Key... 5 Regenerating an API Key... 5 API HOST... 5 Additional Headers... 5 Accept Header... 5 HTTP Status Codes... 5 API Objects... 5 Company... 6 See the current data model for each dataset online... 6 Product... 6 Product Order... 7 Product Notifier... 7 TEST COMPANY SET... 8 COUNTRIES CURRENTLY COVERED... 9 SKU LIST... 9 DESCRIPTION DATA SETS BREX Business Register Exchange GmbH Mariahilfer Strasse 93/2/20, A-1060 Vienna, Austria Page 3 of 12

4 CHANGE RECORD OF THIS DOCUMENTATION Version Date Reviewed by Change References 1 May 2 nd, 2014 P. Bainbridge-Clayton 2 September 18 th, 2014 A. Baumeier 3 October 21 st, 2014 P Bainbridge-Clayton 4 November 6 th 2014 R. Toifl-Dupin 5 December 1 st, 2014 R. Toifl-Dupin 6 February 6 th, 2015 R. Toifl-Dupin 7 April 23 rd, 2015 A. Baumeier 8 May 29 th, 2015 R. Toifl-Dupin 9 Jan 21th, 2016 A. Baumeier Corrected SKU for products from Ireland BREX API TECHNICAL INTERFACE The BREX Enterprise API is a lightweight RESTful webservice which can be used to search for corporate and related information, and to order and retrieve documents. Requests are sent through an HTTPS channel, the reply will be in JSON for data or PDF for report delivery further formats may be added in future. The content and format of a response varies with the request and chosen subscription model, examples are given online and in the appendix. ONLINE DOCUMENTATION BREX Enterprise API uses a 'live' online documentation method this allows readers to see the format of the request URLs, any parameters, the actual URLs called and the structure of the responses. It is also synchronized with the API code, so it is always correct, and even allows the API to be driven via the website, which makes testing a much simpler operation that conventional techniques. The information supplied by this live documentation can assist greatly in writing one's own interface to the BREX API. This documentation is available to anyone with an API key and can be accessed at: OVERVIEW The following overview is subject to changes. For a detailed description, please refer to the online documentation. The API is separated into logical functional groups which follow the general format of: version/object/method/parameter1/.../parameter It is important to note that parameter1 to parameterx may possibly include reserved URI characters, and must therefore be URL encoded to the current standard (RFC3986). Any components of the URL preceding the parameter sections will not require encoding, but will also be defined in such a way that encoding them would have no effect. The valid 'object' values at the time of writing are: company used to search for and access company data product used to list, order and retrieve products Valid 'method' values are: search used to return a list of 'objects' that match the parameters following availability used to check the actual availability of a product for a given company buy used to order a product status get the current status of an ordered product API AUTHENTICATION BREX Enterprise API uses API keys for authentication transferred as a separate header. This is safe because your API key is securely encrypted by the SSL channel. The easiest way to test the API is to use the online live documentation this is BREX Business Register Exchange GmbH Mariahilfer Strasse 93/2/20, A-1060 Vienna, Austria Page 4 of 12

5 a web page which allows you to test the various API methods and handles all the communications for you, whilst showing you the appropriate URLs. BREX will provide client code in php and java in due course. USER KEY Header: User_key {your API key} REGENERATING AN API KEY Your API key can be regenerated by clicking on the Regenerate button on your dashboard page (login with address and password will be required). Note: Only one API key may be active on an application at a time. If you choose to regenerate your API key, your services will not work until you ve updated all references to your API key. There is only one API key per application, though your account can manage multiple applications. Regenerating the key will regenerate it for all users. API HOST API HOST: api.brex.io ADDITIONAL HEADERS ACCEPT HEADER BREX Enterprise API currently returns results only JSON. If the accept header is specified it should be application/json, but will be ignored. Including this header, however, will future proof your client code. Accept: application/json If your JSON or XML request is invalid, the API will respond with a status code 400 Bad Request. This commonly occurs when ampersands are not correctly encoded in the text of your request. Please inspect the body of the response for more details regarding the error. However, please note that at the time of writing there are no API methods that correspond to a 'create' or 'update' request -therefore this is for future reference only. HTTP STATUS CODES Every request includes an HTTP status code with the result. The status code should examined before the response. The online documentation provides up to date status code information, however in general the response codes can be interpreted as: as success as client request errors as server errors API OBJECTS The API method calls are documented in the online system, but the general object structure and sequence is as described below: BREX Business Register Exchange GmbH Mariahilfer Strasse 93/2/20, A-1060 Vienna, Austria Page 5 of 12

6 At the time of writing there are 4 basic objects Company, Product, ProductOrder and ProductOrderNotifier. A typical use case would be: COMPANY Search for a company by name: /company/search/name/{country code}/{name} Search by registration number: /company/search/number/{country code}/{registration number} Select the appropriate Company from the returned array and get more details returns a populated Company object. The level of information in the object is determined by the request, but there may be pricing differences and availability differences depending on your API plan: /company/{company id}?dataset=mini/master/full (defaults to mini) SEE THE CURRENT DATA MODEL FOR EACH DATASET ONLINE PRODUCT Search for possible Product available for that Company returns an array of Product objects which includes the BREX SKU /product/search/{company id} Check the actual availability for the selected Product returns an updated Product object with availability status and whether there are options available (e.g. accounts year) /product/availability/{sku}/{company id} BREX Business Register Exchange GmbH Mariahilfer Strasse 93/2/20, A-1060 Vienna, Austria Page 6 of 12

7 PRODUCT ORDER Place an order for that product returns a ProductOrder object /product/order/{sku}/{company id} POST Or when there are options available, e.g. a specific year for a document. /product/order/{sku}/{option}/{company id} POST Check the status of the ProductOrder object to see when it is ready. Loop here every 60 seconds until ready or the product is marked as failed for some reason. /product/status/{product order id} Retrieve the ordered Product will return a byte stream containing the product in an appropriate format as per the response content-type header. /product/{product order id} Note the status checking here is done via polling. There is an alternative method by using a ProductNotifier. PRODUCT NOTIFIER This allows BREX to notify you when a product is ready. To use a ProductNotifier, replace step heck the status of the ProductOrder with the following: Create a ProductOrderNotifier passing in a URL which will be called using HTTP. Note the callback URL MUST have any forward slashes (/) converted to tilde characters (~) /product/notifier/{product order id}//{callback url} Wait for the callback from BREX to the URL you supplied. The URL will be called with added parameters of orderid={product order id} and notifierid={the id of the product order notifier as created in this step). The use of a notifier does not preclude the polling method but is more efficient for everybody. BREX Business Register Exchange GmbH Mariahilfer Strasse 93/2/20, A-1060 Vienna, Austria Page 7 of 12

8 TEST COMPANY SET Make sure to regularly check online for updates. Country Registration Number Company Name Register Report Register Check Shareholder List Articles of Association Annual Accounts Historical Accounts DE HRB42243 MÜNCHEN BAYERISCHE MOTOREN WERKE AKTIENGESELLSCHAFT X X X live DE HRB MÜNCHEN FLOOR 13 GMBH X X X live DE HRA50136 BERLIN ARENGO IMMOBILIEN BERLIN E.K. X live/new incorporation DE HRB 2185 FREIBURG FAMILIE FISCHER GMBH X dissolved AT 60562M SIEMENS AKTIENGESELLSCHAFT ÖSTERREICH X X live AT X 360KOMPANY GMBH X X live AT B ARLTROC SCHADENSANIERUNG GMBH X X live/new incorporation AT W YLINE INTERNET BUSINESS SERVICES AG X dissolved UK GENERAL MOTORS EUROPE LIMITED X X X X live UK MASS MEDIA DESIGN LTD X X X X live UK CHESLEY PROFESSIONAL SERVICES LIMITED X X live/new incorporation UK UIMANAGEMENT LTD X X X X dissolved IE TERRY MCGUINNESS LIMITED X X X X live IE RYANAIR LIMITED X X X live IE KILLEEN ENGINEERING FABRICATION LIMITED X X live/new incorporation IE IRISH NURSERIES LIMITED dissolved CH THE SWATCH GROUP EUROPA AG X live CH NEUE ZÜRCHER ZEITUNG AG X live CH NOONEE AG X live/new incorporation CH CABLECOM SA X dissolved DK/EBR DANSKE UNIPOL A/S X X X registered FR/EBR CARREFOUR HYPERMARCHES X registered GG/EBR CHANNEL ISLANDS AIRCRAFT SALES LTD X registered IT/EBR BS GIANNI VERSACE SPA X X X X registered JE/EBR RCP17 THE JERSEY RECREATION GROUNDS COMPANY LIMITED X X X registered LV/EBR SIA "BOOM MEDIA" X X X X registered LU/EBR B QIAGEN US FINANCE HOLDING (LUXEMBOURG) S.À R.L. X X X X registered NO/EBR NORSKE SKOG CANADA HOLDING AS X X X registered ES/EBR A SEAT MOTOR ESPAÑA SA X X X registered SE/EBR IBM SVENSKA AKTIEBOLAG X X X X X registered Status BREX Business Register Exchange GmbH Mariahilfer Strasse 93/2/20, A-1060 Vienna, Austria Page 8 of 12

9 COUNTRIES CURRENTLY COVERED Germany, Austria, Switzerland, United Kingdom, Ireland, Belgium, Denmark, Estonia, Finland, France Greece, Guernsey, Italy, Jersey, Latvia, Lithuania, Luxembourg, Macedonia, Malta, Netherlands, Norway, Slovenia, Spain, Sweden Bulgaria*, Croatia, Czech Republic, Hungary*, Moldova*, Montenegro*, Poland, Romania*, Serbia*, Slovakia*, USA (beta) * Implementation in progress SKU LIST Make sure to regularly check online for updates. Product Name Result of a nationwide company search without specific parameters Result of a company search with specified parameters like commercial court, legal form, legal nature or domicile, or result of a person search Current business register extract Current business register extract with historical (deleted) data Current business register extract with Trade Register data Current business register extract with historical (deleted) data and with Trade Register data Abridged extract with company name, domicile, registered office address, legal form) Abridged extract with maximal 2 persons or alphabetical person list Result of a search for documents of a company (eg articles of association, specimen of signatures, minutes, etc.) Documents (PDF format) Result of a search for annual accounts of a company Annual accounts (PDF format) Result of a search for changes in the business register (new entries, dissolutions, changes); price per hit Result of a search for changes in the business register (filing of annual accounts); price per hit Annual Subscription Register Report Austria Register Report Denmark (EBR) Register Report Estonia (EBR) Register Report Finland (EBR) Register Report Germany Register Report Greece (EBR) Register Report Ireland Register Report Italy (EBR) Register Report Latvia (EBR) Register Report Lithuania (EBR) Register Report Luxembourg (EBR) Register Report Malta (EBR) Register Report Norway (EBR) Register Report Serbia (EBR) Register Report Slovenia (EBR) Register Report Spain (EBR) Register Report Sweden (EBR) Register Report Switzerland Register Report United Kingdom Shareholder List Germany SKU SER01BXAT SER02BXAT REP01BXAT REP02BXAT REP03BXAT REP04BXAT REP05BXAT REP06BXAT SER03BXAT REP07BXAT SER04BXAT REP08BXAT SER05BXAT SER06BXAT SUB12BXAT REPOFHFAT REPOFEBDK REPOFEBEE REPOFEBFI REPOFHRDE REPOFEBGR REPOFCRIE REPOFEBIT REPOFEBLV REPOFEBLT REPOFEBLU REPOFEBMT REPOFEBNO REPOFEBRS REPOFEBSI REPOFEBES REPOFEBSE REPOFZECH REPOFCHUK ADDSLHRDE BREX Business Register Exchange GmbH Mariahilfer Strasse 93/2/20, A-1060 Vienna, Austria Page 9 of 12

10 Register Check Belgium (EBR) Register Check Denmark (EBR) Register Check Estonia (EBR) Register Check Finland (EBR) Register Check France (EBR) Register Check Greece (EBR) Register Check Guernsey (EBR) Register Check Ireland (EBR) Register Check Italy (EBR) Register Check Jersey (EBR) Register Check Latvia (EBR) Register Check Lithuania (EBR) Register Check Luxembourg (EBR) Register Check Macedonia (EBR) Register Check Malta (EBR) Register Check Netherlands (EBR) Register Check Norway (EBR) Register Check Serbia (EBR) Register Check Slovenia (EBR) Register Check Spain (EBR) Register Check Sweden (EBR) Articles of Association Austria Articles of Association Estonia (EBR) Articles of Association Finland (EBR) Articles of Association Germany Articles of Association Ireland Articles of Association Italy (EBR) Articles of Association Jersey (EBR) Articles of Association Latvia (EBR) Articles of Association Luxembourg (EBR) Articles of Association Sweden (EBR) Articles of Association United Kingdom Annual Accounts Austria Annual Accounts Denmark (EBR) Annual Accounts Estonia (EBR) Annual Accounts Finland (EBR) Annual Accounts Ireland Annual Accounts Italy (EBR) Annual Accounts Jersey (EBR) Annual Accounts Latvia (EBR) Annual Accounts Luxembourg (EBR) Annual Accounts Norway (EBR) Annual Accounts Slovenia (EBR) Annual Accounts Spain (EBR) Annual Accounts Sweden (EBR) Annual Accounts United Kingdom ADDOFEBBE ADDOFEBDK ADDOFEBEE ADDOFEBFI ADDOFEBFR ADDOFEBGR ADDOFEBGG ADDOFEBIE ADDOFEBIT ADDOFEBJE ADDOFEBLV ADDOFEBLT ADDOFEBLU ADDOFEBMK ADDOFEBMT ADDOFEBNL ADDOFEBNO ADDOFEBRS ADDOFEBSI ADDOFEBES ADDOFEBSE ADDASHFAT ADDASEBEE ADDASEBFI ADDASEBDE ADDASCRIE ADDASEBIT ADDASEBJE ADDASEBLV ADDASEBLU ADDASEBSE ADDASEBUK ADDAAHFAT ADDAAEBDK ADDAAEBEE ADDAAEBFI ADDAACRIE ADDAAEBIT ADDAAEBJE ADDAAEBLV ADDAAEBLU ADDAAEBNO ADDAAEBSI ADDAAEBES ADDAAEBSE ADDAAEBUK BREX Business Register Exchange GmbH Mariahilfer Strasse 93/2/20, A-1060 Vienna, Austria Page 10 of 12

11 VAT N Check Austria VAT N Check Germany VAT N Check Switzerland Credit Report Austria * Credit Report Germany * Credit Report Ireland * Credit Report United Kingdom * Credit Check Austria Provider 1 * Credit Check Austria Provider 2 * Credit Check Germany * Credit Check Switzerland * kreport United Kingdom ADDVCBIAT ADDVCBIDE ADDVCBICH ADDCRKSAT ADDCRCSDE ADDCRCSIE ADDCRCSUK ADDCCKSAT ADDCCBIAT ADDCCBIDE ADDCCBICH REPKR36UK * Credit Reports & Checks: please contact us for more details The list of available products will be continuously updated with register filings & documents from US Secretaries of State. DESCRIPTION DATA SETS Make sure to regularly check online for updates. Call Result Data Set All Countries Master Data Set All Countries Full Data Set - Germany Full Data Set - Austria Full Data Set - Switzerland Full Data Set - United Kingdom Full Data Set - Ireland Full Data Set - Belgium (EBR) Full Data Set - Denmark (EBR) Full Data Set - Estonia (EBR) Full Data Set - Finland (EBR) Full Data Set - France (EBR) kompany ID ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü Company Name ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü Company Registration Number Full Data Set - Greece (EBR) Full Data Set - Guernsey (EBR) Full Data Set - Italy (EBR) ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü Company Status ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü Registered Address ü ü ü ü ü ü 1) 1) 1) 1) ü 1) 1) 1) 1) ü 1) 1) 1) 1) 1) 1) 1) 1) 1) ü ü ü Registration Court ü ü * ü ü * * ü ü * ü Incorporated (date) ü ü ü ü ü * ü ü * * ü ü * ü ü ü Age of Company ü ü ü ü ü * ü ü * * ü ü * ü ü ü Type of Business / Legal Form Activity Description Full Data Set - Jersey (EBR) ü ü ü ü ü * * * * ü ü ü ü SIC/NACE ü ü * * * * ü ü ü Share Capital ü ü VAT Number ü Shareholders * * * * Managing Directors ü ü ü Company Directors ü Company Secretaries ü ü * * * * Number of Charges / Mortgages Filing of Accounts (date) ü ü Filing of Annual Return (date) ü ü Previous Company Names ü ü * * * * Trade Names ü ü * * * * ü ü ü Brand Names ü * * * * Previous Address * * * * Domicile Address Website ü ü ü ü ü ü ü * ü ü ü ü * * ü ü ü ü ü * ü ü ü ü ü Full Data Set - Latvia (EBR) Full Data Set - Lithuania (EBR) Full Data Set - Luxembourg (EBR) Full Data Set - Macedonia (EBR) Full Data Set - Malta (EBR) Full Data Set - Netherlands (EBR) Full Data Set - Norway (EBR) Full Data Set - Slovenia (EBR) Full Data Set - Spain (EBR) Full Data Set - Sweden (EBR) Full Data Set - Croatia Full Data Set - Czech Republic Full Data Set - Poland BREX Business Register Exchange GmbH Mariahilfer Strasse 93/2/20, A-1060 Vienna, Austria Page 11 of 12

12 ü ü ü ü ü ü ü * ü ü ü ü * * ü ü ü ü ü * ü ü ü ü ü Phone ü ü ü ü ü ü ü * ü ü ü ü * * ü ü ü ü ü * ü ü ü ü ü Fax ü ü ü ü ü ü ü * ü ü ü ü * * ü ü ü ü ü * ü ü ü ü ü * Scheduled for ) City Call Result Data & Master Data Sets also apply to the US, which is currently operated as beta version. BREX Business Register Exchange GmbH Mariahilfer Strasse 93/2/20, A-1060 Vienna, Austria Page 12 of 12