Please note that documentation for v1.0 is still available HERE.

Basics
CoCredo services exchange XML over HTTP. Requests are submitted via the HTTP POST method, with a Content-Type of text/xml. The example XML shown in the schemas section illustrate typical requests and responses to and from the CoCredo Services XML Gateway. Requests must be submitted with a Content-Type of text/xml. A typical transaction looks like this.

Message Envelope
Service specific requests and responses are always encapsulated within a common envelope that carries the essential routing and authentication details. The envelope schema can be found here.

Service URL
Requests are submitted to a single service entry point.

https://xmlgw.cocredo.co.uk/v2-0/xmlservice.cfm

Requests sent to this URL will be logged and the relevant number of points deducted from your account. Under no circumstanses should any tests be carried out against this URL. It is a requirement that you test against our 'UAT' service before we enable you to use the live service. We have a seperate URL that can be used for testing and development of your requests. This URL is:

https://xmluat.cocredo.co.uk/v2-0/xmlservice.cfm

The 'UAT' service will only return reports for British Airways Plc or other pre-defined companies, regardless of what company data has been requested. However, using this service will not use any points from your account for XML requests. So for example, UAT searches can be on any business and will return true results; any product availability or product selection requests must be for British Airways Plc or another pre-defined business. Please contact technical@cocredo.com for a full list of test companies or if you would like to test against a particular company that is not in the list. Requesting browser reports, or PDF reports will subtract points from your account.

The content of the request document submitted to the service describes the information being requested. The service uses this information to route the request to the appropriate function once it has carried out some preliminary checks, such as authentication details.

Versioning
Any changes made to the XML service will be done under a new version number. The latest version of the service in use on the live server will be stated on the documentation at https://xmlgw.cocredo.co.uk.

New versions will utilise a new URL for calling the service e.g. https://xmlgw.cocredo.co.uk/v2-0/xmlservice.cfm, which enables users to continue using the previous version until they are ready to move onto the new version. Support will always be based upon the latest version of the service.

Error Handling
All errors are returned with the Class element in the XML envelope specified as Error. Error codes and descriptions will be provided in the XML document. The error schema can be found here.

Authentication
On receiving any post we will go through several stages of checking what is being sent and authenticating the sender. In all cases an XML response will be sent (even if the initial post wasn't XML). Authentication will be performed through a combination of a SenderCompany, SenderID, Password and TransactionID. You will send your SenderCompany (e.g. CoCredo), your SenderID (e.g. CoCredoSenderID), a TransactionID (1-32 digits, Numeric) and an UTF8 hash of the concatenation of your SenderCompany, SenderID, Password and TransactionID. The hash should be created SHA-512. The algorithm used should be stated in the Method element as SHA-512.

For example, if we setup a SenderCompany of CoCredo, a SenderID of CoCredoSenderID and a Password of CoCredoPassword, and your TransactionID is 1 you would require a hash of CoCredoCoCredoSenderIDCoCredoPassword1 to be authenticated, which (using the SHA-512 alogrithm) is 4446D4CA6DC32819B4D74064055F3196DA4D5A20D108785C3C98C9990FF793792B44E0C16B7E5CBEBF9456A472AB2345256EBD7832D4C2CC59E9D042EF929AA2.

Please note that the Transaction ID used must increment for each request made to this service.

Monitoring
A business can be added to monitoring when using the productSelection service. Simply set the monitorAdd element to true.

Data formats

Data Type	Description	Format	Example
date	The date data type is used to specify a date.	The date is specified in the following form "YYYY-MM-DD" where: YYYY indicates the year MM indicates the month DD indicates the day Note: All components are required!	Example schema declaration: <xsd:element name="start" type="xsd:date"/> Example xml element: <start>2005-07-24</start>
dateTime	The dateTime data type is used to specify a date and a time.	The dateTime is specified in the following form "YYYY-MM-DDThh:mm:ss" where: YYYY indicates the year MM indicates the month DD indicates the day T indicates the start of the required time section hh indicates the hour mm indicates the minute ss indicates the second Note: All components are required!	Example schema declaration: <xsd:element name="start" type="xsd:dateTime"/> Example xml element: <start>2005-07-24T14:00:00</start>
time	The time data type is used to specify a time.	The time is specified in the following form "hh:mm:ss" where: hh indicates the hour mm indicates the minute ss indicates the second Note: All components are required!	Example schema declaration: <xsd:element name="start" type="xsd:time"/> Example xml element: <start>14:00:00</start>

Schemas
Provided below are details of the services provided by CoCredo.

Example requests and responses will be published soon.

	Company Search This component provides a search of incorporated and unincorporated companies. Searches can be done using company name, registration number, postcode or phone number. The message envelope class to use when invoking this component is companySearch. Company Search Schema Example Request Company Search Response Schema Example Response
	Product Availability This component will return a list of available reports and documents that are available for download. A Cocredo ID is required in this request. The ID number can be found from the response to the company search. Each product will have a request code which can be used to request that particular report or document.The message envelope class to use when invoking this component is productAvailability. Product Availability Schema Example Request Product Availability Reponse Schema Example Response
	Product Selection This component will return either report data. The message envelope class to use when invoking this component is productSelection. Product Selection Schema Example Request Product Selection Reponse Schema Example Response
	Director Search This component provides a search of company directors. Searches can be done using director name and post town. Director types are DIS - Disqualified directors, CUR - All other directors. The message envelope class to use when invoking this component is directorSearch. Director Search Schema Example Request Director Search Response Schema Example Response
	Director Report This component provides a report on a particular company director. The message envelope class to use when invoking this component is directorReport. Director Report Schema Example Request Director Report Response Schema Example Response
	Usage Statement This component will return a list of reports that the user has run in the specified time period. The message envelope class to use when invoking this component is usageStatement. Usage Statement Schema Example Request Usage Statement Reponse Schema Example Response
	Monitor Status This component allows the user to request either to add/remove a business from monitoring or just to request the current monitoring status of a business. The message envelope class to use when invoking this component is monitorStatus. Usage Statement Schema Example Request Usage Statement Reponse Schema Example Response
	Monitoring Notices This component will return a list of change notices in the specified time period. The user can optionally request change notices for one particular business. The message envelope class to use when invoking this component is monitorNotices. Note that when setting time periods in a request that change notices can take several hours to be available in the CoCredo database. It is therefore recommended that the requested period end date/time is at least 12 hours prior to the current time. Requested time periods must not exceed a length of 7 days - it is recommended that time periods should be about 12-48 hours. Usage Statement Schema Example Request Usage Statement Reponse Schema Example Response
	Errors Whenever an error is detected in a request to the service an error response is returned. This includes all caught errors, such as missing data elements, invalid data and any processing errors. In this case the message envelope class to used when for this reponse is Error. Error Schema Response Example Response Full list of all errors

Fair Use
We ask that requests made to the CoCredo XML services are limited to no more than 80 per minute. We do reserve the right to temporarily suspend any account that exceeds this limit.

Change Log
It should be noted that on every version change the URL of the service changes to reflect the latest version. As a result the schema namespaces used also change to reflect this change. This means that all schema documents are changed in this respect even if the XML data they are being used to describe has not changed.

Previous version: v1.0

Changes made since last version:

• API: v2.0 is significant update over v1.0 and is not backwards compatible to requests made in v1.0 specifications.
• Company search: Added ability to search by VAT, CocredoID, customer references.
• Company search: Reponse now returns a cocredo Id for the business.
• Company search: Extended to accommodate international searches.
• Product availability: Update request codes for reports provided. Added Monitoring not available status where it is not possible to add a company to monitoring.
• Product selection: Data returned in the response has had a full overhaul to accomodate new data not previously provided. New data includes:
  • ability to provide UK Dual Reports with credit recommendations from two independant opinions
  • payment experiences data
  • corporate event histories
  • affiliates
  • group structure
  • UK gender pay gap details
  • sanctions data