CompanyCheckAPIOutline

Important Note: The URLislikely tochangeoncethisgoesintoproduction.We willreissuethis documentationwiththeupdatedURLsonceyouresatisfiedthattheAPIworksasintended. The API contains three methods that can be used to search for companies by name, view a company(anditsdirectors)byID,andtoviewadirectorbyID. APIKey We provide you with an API key so that we can identify who is using the API and prevent unauthorised access.TheAPIkeywillbea64digithexadecimalnumberandshouldbeaddedto theURLofeveryrequestusingthea p i K e y urlvariable. CompanySearch The first of these is located at https://companycheck.co.uk/api/search and canbe queried with then a m e URLvariable: https://companycheck.co.uk/api/search?name=tesco&apiKey=xxxxxx returns XML in the followingformat:
<results xmlns="http://companycheck.co.uk/api/search" searchTerm="tesco" total="100"> <company id="03436754"> <name>TESCO (PARTNERSHIP) LIMITED</name> <number>03436754</number> <status>Active</status> <address>TESCO HOUSE, DELAMARE ROAD, WALTHAM CROSS, EN8 9SL</address> <country>GB</country> </company> <company id="00445790"> <name>TESCO PLC</name> <number>00445790</number> <status>Active</status> <address>TESCO HOUSE, DELAMARE ROAD, WALTHAM CROSS, EN8 9SL</address> <country>GB</country> </company> </results>

Each company node contains the basic informationaboutthecompaniesthatmatchthesearch term, including the unique number that companies househave assignedtoeachcompany.The i d attribute of the c o m p a n y node is the ID code that you can use to perform a more detailed queryonthatspecificcompany.

If the search is not particularly specific,the XML will only return a maximum of 100results.The number of results returned, along with the search term are returned as attributes of the root element. It is advisable tobe as specific in the query as possible, orthe correct result may not bewithinthat100. CompanyQuerybyID Once you have obtained a unique ID by using the search API, youmay then get more specific details about a company by using https://companycheck.co.uk/api/company with the id URL variable. Depending on the package that you have purchased you will see different XML structures: https://companycheck.co.uk/api/company?id=04905417&apiKey=xxxxxx returns the following XML: Basic
<company xmlns="http://companycheck.co.uk/api/company" id="04905417" package="basic"> <name>COMPANY CHECK LTD</name> <number>04905417</number> <sicCode>63110</sicCode> <registeredAddress>5 COLLEGE STREET, NOTTINGHAM, NG1 5AQ</registeredAddress> </company>

Financial
(The actual contents of the XML has been truncated, but the second level nodes are shown to indicate the types of data which comes with this package) <company xmlns="http://companycheck.co.uk/api/company" id="04905417" package="financial"> <CompanySummary>...</CompanySummary> <CompanyIdentification>...</CompanyIdentification> <ContactInformation>...</ContactInformation> <ShareCapitalStructure>...</ShareCapitalStructure> <Directors>...</Directors> <GroupStructure>...</GroupStructure> <FinancialStatements>...</FinancialStatements> <CompanyHistory>...</CompanyHistory> <Commentaries>...</Commentaries> <ShareDetails>...</ShareDetails> </company>

Full
(The actual contents of the XML has been truncated, but the second level nodes are shown to indicate the types of data which comes with this package) <company xmlns="http://companycheck.co.uk/api/company" id="04905417" package="full"> <CompanySummary>...</CompanySummary> <CompanyIdentification>...</CompanyIdentification> <CreditScore>...</CreditScore> <ContactInformation>...</ContactInformation> <ShareCapitalStructure>...</ShareCapitalStructure> <Directors>...</Directors> <GroupStructure>...</GroupStructure> <FinancialStatements>...</FinancialStatements> <CountyCourtJudgements>...</CountyCourtJudgements> <PaymentData>...</PaymentData> <CompanyHistory>...</CompanyHistory> <MortgageInformation>...</MortgageInformation> <Commentaries>...</Commentaries> <ShareDetails>...</ShareDetails> </company>

ThesamebasicinformationwhichwasprovidedinthesearchresultsXMLisalsoprovidedhere, butalotofextrainformationisalsopresent. Within the D i r e c t o r subtreetherearelistedcurrentandpreviousdirectors. Thisalsocontains companysecretarieswhichareidentifiedfromdirectorsbycontentsoftheP o s i t i o n node.The i d attribute of theD i r e c t o r element is the uniqueIDthatyoucanusetoperformaqueryona specificdirector. Currently, shareholder data is limited. Currently it is structured as a text string with thenameof the shareholder. We have no way to distinguish between individual, companies, or any other entities atthistime.Inthenearfuture,wewillbeabletoprovide exactandclosematchesacross 50 million records from across Europe. We also will build up the group structure and better information about shareholders from this data.Whenwe havethisnewdata,wewillcontactyou toexplaintheupgradeprocess. Director(orSecretary)Query(AvailabletoallpackagesexceptBasic) Using the i d attribute attached to a d i r e c t o r or s e c r e t a r y element in the company details XML you can then perform a search to look at a particular director/secretary. This is locatedat https://companycheck.co.uk/api/director

https://companycheck.co.uk/api/director?id=915692370&apiKey=xxxxxx returns the following XML: <director xmlns="http://companycheck.co.uk/api/director" id="915692370">

<name>Mr Alastair Gordon Campbell</name> <number>915692370</number> <dateOfBirth>1972-07-31</dateOfBirth> <noOfApppointments>3</noOfApppointments> <appointments> <company id="04905417"> <number>04905417</number> <name>COMPANY CHECK LTD</name> <current>true</current> <type>Director</type> <appointmentDate>2011-09-01</appointmentDate> <directorAddress> <address1>145-157 St. John Street</address1> <address2/> <address3>London</address3> <address4/> <address5>United Kingdom</address5> <postcode>EC1V 4PW</postcode> <postalArea>EC1V</postalArea> </directorAddress> <companyAddress> <address1>5 COLLEGE STREET</address1> <address2>NOTTINGHAM</address2> <address3/> <postcode>NG1 5AQ</postcode> <countryCode>GB</countryCode> </companyAddress> </company>

</appointments> </director>

In this XML, you get the basic details which are provided in the company search XML. Youalso get a full list of all the known past and present director and secretary appointments for that director ID. We also have the address they registered when setting up the company, and the registeredaddressofthecompanyforeachappointment. The t y p e element can either beDirector or Secretary. c u r r e n t indicateswhethertheyare still registered as holding that appointment. c u r r e n t may be set to true for a dissolved company, but one wherethedirector/secretaryneverofficiallyresignedbeforethecompanywas dissolved.

Currently, we cannot display the status of the individual companies on this XML feed due tothe data structure. This will change in future and we will add in a s t a t u s element into each c o m p a n y element. Errors When there are errors, you will get an empty version of the standard root element, with some informationabouttheerror.Forexampledirectormightreturn:
<directorxmlns="http://companycheck.co.uk/api/director"errorCode="400"errorMessage="Nocompanyid wasprovided"/>

Or,therearesomekindsofmorecomplexerrorswhichmayoccur,suchas
<company xmlns="http://companycheck.co.uk/api/" errorCode="500" errorMessage="Could not contactget Results"/>

Could get Results is a complex issue with our systems which we would appreciate you reporting to bugs@companycheck.co.uk with some background information such as what companyordirectoryouweresearchingforandwewillinvestigate. Thisshould onlyhappenveryoccasionallyandweonlyseethisnowunderveryexcessiveuseof the Directorsearchduetothescaleofdataand thesheernumberofduplicatenamestheSOLR searchhastoworkthrough.inthefirstinstancewesuggestmakingtherequestagain. This shouldnt happen often in normal day to day running and it works 99.9% of the time on a second request.Once wehave completed the migration from SOLR to CloudSearchthisissue willbefinallyresolved.