Global Gateway API Interface -...

Creditsafe Group – Global Gateway Service v1.3

Global Gateway API

Interface V1.0.5


of 33

Document revisions

Date Description

2012-04-30 initial version.

2012-07-26 Updated status company search notes

2013-04-25 Company monitoring & Offline report orders interface description added

2013-07-11 Reportbox management section added

2013-09-20 Offline report orders section added + DE reason codes descriptions update

2013-10-01 ReportBox functionality extended. IT/CH/LI events added.

2014-02-26 Monitoring “HasChanges” flag description extended.

2014-09-12 Incorrect information in the Portfolio Creation section fixed.

2014-10-10 Default changes check period set up documentation added. Monitoring rules alteration documentation extended.

2014-11-21 Missing report retrieval parameter documentation added.

2015-04-17 Added Brazilian offline time and Spanish events

2015-10-28 AT & FI Monitoring Update

2016-02-26 US report redirects information added.

2016-05-16 NO events added.

2016-08-05 Updated Canada maintenance window notes in Appendix C.

2016-10-11 Added Custom Score related functionality description

2016-02-16 Added DK monitoring update

2017-06-02 Added monitoring event codes HO, BN, LG


of 33

Service Description

Fundamentals

Test service basicHTTP: service:

https://testwebservices.creditsafe.com/GlobalData/1.3/MainServiceBasic.svc metadata: https://testwebservices.creditsafe.com/GlobalData/1.3/MainServiceBasic.svc/meta?wsdl

Live service Please request the live Global API URLs from [email protected].

Note: the wsHTTP endpoint(s) should be used only by clients using the WSE 3.0 (web service extensions) compatible specification (WS-Security 1.1, SOAP 1.2, MTOM). Clients that are not using WS-* extensions should use the basicHTTP endpoint(s). For more information please visit Web Service Specifications Supported by WSE. For SOAP service access the ‘service’ endpoint should be used. For WSDL access (client proxy generation etc.) the ‘metadata’ endpoint should be used.

The purpose of the Global Gateway Service is to provide the ability to find companies and order their detailed information reports in multiple countries using a common strong typed interface. Its methods are designed to allow:

- Browsing available countries; - Discovery of company searching options that can be applied; - Performing criteria based search queries; - Ordering the reports.

Both the requests and responses of all interface’s methods have a strongly typed structure that ensures that a common client solution will be able to access all available countries’ searching options and data. A typical usage scenario consists of the following steps: 1) Listing available countries (with possible filtering) 2) Discovery of the search options that can be used to search desired country/countries 3) Selecting one of the searching options and performing a company search with it 4) Using the company Ids returned in the search results to order company reports All requests and responses conform to the SOAP standard of Web Service calls. The later examples of their structure are stripped of the standard SOAP call/response envelopes and present only the discussed parts for clarity. All responses also share a common possible field Messages which is always used to inform of any errors, warnings or important situations related to the request made: <response>

<Messages>

https://testwebservices.creditsafe.com/GlobalData/1.3/MainServiceBasic.svc

https://testwebservices.creditsafe.com/GlobalData/1.3/MainServiceBasic.svc/meta?wsdl

http://msdn.microsoft.com/en-us/library/aa529362.aspx

of 33

<Message Type=”Error” Code=”6”>

Invalid search criteria specified.

</Message>

<Message Type=”Information” Code=”16”>

Search criteria schemas for DE have recently changed.

</Message>

</Messages>

</response>

The “Type” attribute can have one of the following values: Error, Warning, Information.

Countries Listing Listing of available countries is done by calling the GetCountries service method. This method can take one optional parameter – filter. If this parameter is specified, only countries that meet this filter will be returned as the result; otherwise all countries available will be returned. Structure of the filter parameter is explained bellow: <filter>

<Codes> 

<Code/>

<Code/>

</Codes>

<OnlineReports /> 

<Monitoring /> 

</filter>

Element Name Optional Description

Codes yes A list of <Code/> elements specifing Country codes that limit the countries included in the results. The codes must be specified in the ISO 3166-1-alpha-2 standard.

OnlineReports yes Limits the listing to countries that either do or do not provide online report retrieval functionality.

Monitoring yes Limits the listing to countries that either do or do not provide changes monitoring functionality.

Response

The country listing response contains a list of countries along with their parameters like online report ordering availability, available report types and languages. The list of countries returned and their parameters will vary depending on users’ access rights (those countries/options that user can’t access won’t be listed).


of 33

<response>

<Countries>

<Country Code=”DE” OnlineReports=”true” Monitoring=”false”>

<AvailableReportTypes>

<AvailableReportType>Full</AvailableReportType>

</AvailableReportTypes>

<AvailableLanguages>

<AvailableLanguage>EN</AvailableLanguage>

</AvailableLanguages>

</Country>

<Country Code=”GB” OnlineReports=”true” Monitoring=”false”>







</Country>

</Countries>

</response>

Element/Attribute Name Description

Code The ISO 3166-1-alpha-2 country code f the specified country.

OnlineReports If “true”, then onlie reports are available for the companies in this

country. *

Monitoring If “true”, then changes monitoring is available for the companies in this country. *

AvailableReportTypes List of report types that are available for ordering for the companies in this country. *

AvailableLanguages List of languages (in ISO 639-1 notation) that reports are available in for the companies in this country. *

* Not all companies have to comply to this – to verify options on a company level company search results have to be used.

Search criteria schemas discovery Different countries offer different searching options and can have different restrictions on some of the search criteria and Custom Data. Search criteria discovery allows knowing the searching options available for specified country or set of countries. Performing the discovery is done by calling the GetPossibleSearchCriteria method and passing the desired set of countries to retrieve the search criteria schemas for (see the countries parameter below).

<countries>

<CountryCode>DE</CountryCode>

<CountryCode>GB</CountryCode>

<CountryCode>FR</CountryCode>

</countries>

Response

The search criteria schemas discovery contains a list of <Schema> elements, from which every one represents a single searching option description, plus a set of country codes that describes the set of countries those search criteria schemas apply to. Each child element of the <Schema> element describes a single search criterion. If for a single <Schema> element any of its sub-elements don’t appear, it means that for this option the criteria they represent are not allowed. Child elements of the <Schema> elements are either of “value schema” or “query schema” type, with the later being an extension of the former with one additional parameter (see below). For countries which allow or require Custom Data to be specified

of 33

when executing a search request an additional <CustomData> node will be present in the response. The element can contain multiple <Entry> sub-elements with each one representing a separate required or allowed Custom Data that can or has to be passed when executing a search query.

<response>

<Schemas>

<Schema>

<Id /> 

<Name /> 

<Type /> 

<OfficeType /> 

<Status /> 

<RegistrationNumber /> 

<VatNumber /> 

<Address>

<SimpleValue /> 

<Street /> 

<HouseNumber /> 

<City /> 

<PostalCode /> 

<Province /> 

</Address>

<PhoneNumber /> 

</Schema>

<Schema>...</Schema>

</Schemas>

<CustomData>

<Entry Key=”example” Optional=”false”>

<AllowedValues>

<AllowedValue>example value</AllowedValue>

...

</AllowedValues>

<Description>This is an example Custom Data entry</Description>

</Entry>

</CustomData>

<Countries>

<Country>DE</Country>

</Countries>

</response>



<Name Optional=”false” MinLength=”5” MaxLength=”50”

MatchType=”MatchBeginning”> 

<AllowedValues>

<AllowedValue>Example</AllowedValue>

<AllowedValue>Sample</AllowedValue>

</AllowedValues>

<ValidationRegExp>^\w+$</ValidationRegExp>

</Name>

Element/Attribute Name Section Description

Id Schema If present, describes the company Id related searching part.

Name Schema If present, describes the company name related searching part.

Type Schema If present, describes the company type related searching part.

OfficeType Schema If present, describes the company office type related searching part.

Status Schema If present, describes the company status related searching


of 33

part.

RegistrationNumber Schema If present, describes the company registration number related searching part.

VatNumber Schema If present, describes the company VAT identification number related searching part.

PhoneNumber Schema If present, describes the company phone number related searching part.

Address Schema If present, describes the company address related searching part.

SimpleValue Schema->Address If present, describes the company simple value address (whole address as a single text string) related searching part.

Street Schema->Address If present, describes the company address street name related searching part.

HouseNumber Schema->Address If present, describes the company address house number related searching part.

City Schema->Address If present, describes the company address city name related searching part.

PostalCode Schema->Address If present, describes the company address postal code related searching part.

Province Schema->Address If present, describes the company address province name related searching part.

Optional value/query schema Specifies if the described search criterion can be ommited when forming the search criteria that conform to the schema.

MinLength value/query schema If present, specifies the minimal length of values that can be passed in the described search criterion when forming the search criteria that conform to the schema.

MaxLength value/query schema If present, specifies the maximal length of values that can be passed in the described search criterion when forming the search criteria that conform to the schema.

MatchType query schema Specifies the possible matching options for the query in the described search criterion when forming the search criteria that conform to the schema.

AllowedValues value/query schema If present, limits the values, that can be specified in the described search criterion when forming the search criteria that conform to the schema, only to one of those listed.

MinLength value/query schema If present, specifies reqular expresion validation string that must be matched by the value of the described search criterion when forming the search criteria that conform to the schema.

Key CustomData->Entry Identifies the Custom Data entry.

Optional CustomData->Entry Specifies if the described Custom Data entry can be ommited when executing the search operation.

AllowedValues CustomData->Entry If present, limits the values, that can be specified in the described Custom Data entry, only to one of those listed.

Description CustomData->Entry Free form text description of the Custom Data entry.

Company search FindCompanies method allows searching for companies, in a specified country or a set of countries (parameter countries), that meet criteria specified in the searchCriteria parameter. An additional chargeReference parameter can be specified containing a text reference to be logged for charging purposes. The criteria specified have to comply to one of the criteria schemas that the discovery returns for the same set of countries, otherwise an error informing about invalid search criteria will be returned. If any companies are found, their basic information is returned in the results. Structure of both parameters is presented below:

<countries>

of 33

<CountryCode>DE</CountryCode>

<CountryCode>GB</CountryCode>

<CountryCode>FR</CountryCode>

</countries>

 <searchCriteria>

<Id />

<Name MatchType=[one of allowed values] />

<Type />

<OfficeType />

<Status />

<RegistrationNumber />

<VatNumber />

<Address>

<SimpleValue MatchType=[one of allowed values] />

<Street />

<HouseNumber />

<City />

<PostalCode />

<Province />

</Address>

<PhoneNumber />

</searchCriteria>

 <searchCriteria>

<Name MatchType=”MatchBeginning”>Exmaple Company</Name>

<Address>

<Street>Example Street</Street>

</Address>

</searchCriteria>

<!-- Custom Data example

<customData>

<CustomDataEntry Key=”example>Example value</CustomDataEntry>

</customData>


Id If present, limits the search results to a single company which ID equals the one specified.

Name If present, limits the search results to companies which names match the given query (matching is specified by the MatchType value).

Type If present, limits the search results to companies which type equals the one specified.

OfficeType If present, limits the search results to companies which office type equals the one specified.

Status If present, limits the search results to companies which status is covered by the specified value. If omitted, the search will default to ‘Active’ only searches.

RegistrationNumber If present, limits the search results to companies which registration number equals the one specified.


of 33

VatNumber If present, limits the search results to companies which VAT identification number equals the one specified.

Address->SimpleValue If present, limits the search results to companies which addresses match the given query (matching is specified by the MatchType value).

Address->Street If present, limits the search results to companies which street name matches the one specified.

Address->HouseNumber If present, limits the search results to companies which house number equals the one specified.

Address->City If present, limits the search results to companies which city name matches the one specified.

Address->PostalCode If present, limits the search results to companies which postal code matches the one specified.

Address->Province If present, limits the search results to companies which province name matches the one specified.

PhoneNumber If present, limits the search results to companies which contact phone number equals the one specified.

Response

Search results contain a list of elements describing every found company. If too many companies match the specified search criteria, some of the results will be truncated. If such a situation occurs, TooManyResults code message will be returned as a part of the response (see Appendix B for message codes details). Here’s an example results structure:

<response ChargeReference=”example”>

<Companies>

<Company Id=”DE001/000001” Country=”DE” OnlineReports=”true” Monitoring=”false”>

<Name>Example Company 1</Name>

<Type>Ltd</Type>

<OfficeType>HeadOffice</OfficeType>

<Status>Active</Status>

<RegistrationNumber>123-456</RegistrationNumber>

<VatNumber>DE123456</VatNumber>

<Address>

<SimpleValue>Example Street 12, Some City</SimpleValue>

<Street>Example Street</Street>

<HouseNumber>12</HouseNumber>

<City>Some City</City>

<PostalCode>12345</PostalCode>

<Province>Somewhereland</Province>

</Address>







<AdditionalData>

<AdditionalDataItem key=”example”>Example value.</AdditionalDataItem>

</AdditionalData>

</Company>

</Companies>

</response>


Response->ChargeReference The same charge reference text that has been supplied using the chargeReference call parameter.

Id Company’s Id string.


of 33

Country The ISO 3166-1-alpha-2 country code of the company’s country.

Name Holds company’s name.

Type If present, holds company’s type information (Ltd, NonLtd etc.)

OfficeType If present, holds company’s office type information (Headoffice etc.)

Status If present, holds company’s status information (Active, Pending etc.)

RegistrationNumber If present, holds company’s registration number.

VatNumber If present, holds company’s VAT identification number.

Address->SimpleValue If present, holds a single string address.

Address->Street If present, holds the name of the street (some times includes the house number).

Address->HouseNumber If present, holds the house number.

Address->City If present, holds the name of the city.

Address->PostalCode If present, holds the postal/Zip code.

Address->Province If present, holds the name of a province, state etc.

DateOfLatestAccounts If present, holds information about company's latest accounts filling date.

OnlineReports If “true”, then onlie reports are available for this company.

Monitoring If “true”, then changes monitoring is available for this company.

AvailableReportTypes List of report types that are available for ordering for this company.

AvailableLanguages List of languages (in ISO 639-1 notation) that reports are available in for this company.

AdditionalData Text key/value collection field that can in the future hold company specific data not suitable for any other fields.


of 33

Online Company Report If a company has online reports available, one can be ordered using the RetrieveCompanyOnlineReport method. Company’s detailed information will be returned instantly in the common format requested. This method takes in a following set of single-value parameters:

Parameter Name Description

companyId Company’s Id string.

reportType One of the types from the list of report types that are available for ordering for this company – affects the contents and structure of the returned report.

language ISO 639-1 notation language that the report should be returned in (has to be available).

customData Custom Data allowed or required by selected country for report ordering calls.

chargeReference Text reference to be logged for charging purposes.

storeInReportbox If set to “true”, the report, if retreived successfully, will also be stored in the reportbox for future free of charge access..

portfolioIds Used for monitoring, one or more portfolio Ids can be passed, in which if valid, the requested company will be added to monitoring (optional).

monitoringReference If the company is to be added to monitoring using the above parameter, this parameter can be used to specify the reference string with which it will be added to the portfolios (optional).

Custom Data possibilities can be discovered using the GetReportCustomDataSchema method. This method returns a Custom Data schema description with identical structure as <CustomData> part of the search criteria discovery method. See GetPossibleSearchCriteria method’s response documentation for details (“Search criteria schemas discovery” section of this document).

Note: please view Appendix for DE based report requests.

Response

The responses will vary depending on the type of the report that was ordered. Detailed structure of those reports is covered in a separate document. However all types of reports will share the following basic company report information:

<response ChargeReference=”example”>

<Reports>

<Report CompanyId=”DE001/000001” OrderNumber=”1234” Language=”EN” />

</Reports>

</response>

Attribute Name Description


CompanyId Company’s Id string.

OrderNumber Unique number of the order that this report is result of.

Language ISO 639-1 notation language that the report is returned in.


of 33

In some cases the report unavailable information returned by the service can contain redirection

information. Please see Appendix F for details.

Try Online Company Report (direct report requests) It is possible to make a request to GGS which encapsulates the search input parameters and report response in one call to the GGS web service. The ‘TryRetrieveCompanyOnlineReport’ is the method whose input parameters replicate what is allowed through the ‘FindCompanies’ method call, so allowing all possible search criteria input parameters, and then, if a unique hit is found, the company report will be returned in the response. This method eliminates one request/response step for the end users and is ideally suited for clients whose integrations requires them to only load direct reports. You can view the company search page of this document to see all the allowed criteria. The method, since it returns a company report, and not search results, also has report related input parameters.


reportType One of the types from the list of report types that are available for ordering for this company – affects the contents and structure of the returned report.

language ISO 639-1 notation language that the report should be returned in (has to be available).

customData Custom Data allowed or required by selected country for report ordering calls.


storeInReportbox If set to “true”, the report, if retreived successfully, will also be stored in the reportbox for future free of charge access..

portfolioIds Used for monitoring, one or more portfolio Ids can be passed, in which if valid, the requested company will be added to monitoring (optional).

monitoringReference If the company is to be added to monitoring using the above parameter, this parameter can be used to specify the reference string with which it will be added to the portfolios (optional).

It is important to know that if the search parameters provided to the method ‘TryRetrieveCompanyOnlineReport’ returns more than one company, then an error is returned back to the user/client. For the method to return a company instance the provided search criteria needs to generate a unique search results hit, from which the GGS will then take this single search result and generate a report from it.


of 33

Offline Company Report If a company is not available online, it is not found in the search results or the country is not searchable at all, a report can still be ordered using the OrderCompanyOfflineReport method. A report order confirmation will be returned and order processing will begin instantly. This method takes in a following set of single-value parameters:


country The country code of the country for which the report order is made.

searchCriteria Company search criteria to match. This parameter’s structure is identical to the criteria used in Company Searching method described earlier – please refer to that section for detailed description.

reportType Desired report type – affects the contents and structure of the returned report. Currently only Full is avaialble. Please be aware that the format of the returned report type may not be in the common report structure which you would have for online reports.

language ISO 639-1 notation language that the report should be returned in (has to be available). Only EN or the language of the requested Country are currently available.

customData Custom Data allowed for offline report ordering calls.


Offline report orders’ search criteria, unlike standard company searching, are not restricted by any searching schema sets and all combinations can be used. The more company data is available the easier it will be to find the correct company. The interface does not provide any means of Custom Data discovery for the offline ordering method. Here’s a full list of acceptable entries (all are optional):

Key Allowed values Description

notes (any) Additional order related notes. If there are any questions to ask with the fresh investigation order they should be asked here. Please see section below on how questions are answered and returned to the client.

deliveryEmails (any valid e-mail addresses)

";" separated list of email addresses to which the report is to be delivered. If not specified, the addresses configured by the account manager as default for offline orders will be used for delivery.

reportFormat pdf | word Desired file format for the report to be delivered in.

serviceType* Normal | Express | Urgent Service type selection.

* Available for selected customers only.

Returned Answered Questions

Any questions asked with a fresh investigation request, where the fresh investigation response is returned via the online GGS reportbox interface (in the common XML format), will have the answers returned in a fixed area of the XML report, within the <AdditionalInformation> section. An example of the XML that will be output, containing answers is below… <AdditionalInformation>

<Notes>

<Note>This is an answer to a customer question.</Note>

<Note>This is the second answer to a customer question.</Note>

</Notes>

</AdditionalInformation>


of 33

Response

The response contains order confirmation along with a unique order number that can be used for reference:

<response OrderNumber=”123” ChargeReference=”example”>

<ReportType>Full</ReportType>

<Language>EN</Language>

<PlacementDate>2013-01-01T00:00:00.0000000Z</PlacementDate>

</response>


Response->OrderNumber Unique order number that can be used for reference.


ReportType Ordered report type.

Language ISO 639-1 notation language that the report has been ordered in.

PlacementDate Date and time of order placement (UTC).

of 33

Reportbox management

Reportbox listing Reportbox listing provides basic information about all or selected reports available in the reportbox, and for selected countries, along with the realisation status of offline report orders. The ‘realisation’ flag against a company in the report box is to indicate whether a offline company request has been successful and is loaded into the customers reportbox. The reportbox listing can be achieved by calling the GetReportboxContents service method. The method can take an optional filter parameter that alters the returned list. All of the sub-elements of the filter work as if there was an “AND” relationship between them and only those entries that meet all of the submitted conditions will be included in the results. The structure of the filter parameter is explained below: <filter>

<Id />

<OrderNumber />

<CompanyId />

<ReportType />

<OrderedAfter /> 

<OrderedBefore /> 

<CompanyName />

<Country />

<Realised /> 

</filter>

Element Name Optional Description

Id yes The reportbox Id of the report to include. Providing this parameter will result in a single or no hits being returned depending on other fields and validity of the Id.

OrderNumber yes The order number of the report to include. Providing this parameter will result in a single or no hits being returned depending on other fields and validity of the order number.

CompanyId yes Limits the results to those that exactly match the company Id specified.

ReportType yes Limits the results to those that were ordered with the specified type of the report.

OrderedAfter yes Limits the results to those that were ordered on a date later than the one specified.

OrderedBefore yes Limits the results to those that were ordered on a date earlier than the one specified.

CompanyName yes Limits the results to those with the company name containing the specified text.

Country yes Only reports for companies from the specified country will be listed.

Realised yes If specified, will filter the results to those that have the realisation flag equal to the one specified.

Response

The portfolio listing response will contain a set of reportbox entry nodes. Those nodes will contain basic company and report information along with order date and status. All the dates will include UTC times.

<response>

<Entries>

<Entry Id="123" OrderNumber="321" Realised="true">

<ReportType>Full</ReportType>

<OrderedOn>2013-01-01T01:10:20.0000000Z</OrderedOn>

<Company Country="DE" Id="DE001/0/1234">

<Name>Some company</Name>

<Type>Ltd</Type>


<RegistrationNumber>1234</RegistrationNumber>


of 33

<Address>

<Street>Some street</Street>

<City>Some city</City>

<PostalCode>123456</PostalCode>

</Address>

</Company>

</Entry>

...

</Entries>

</response>


Id Unique reportbox Id of the entry.

OrderNumber Number of the report order that resulted in this reportbox entry creation.

Realised Indicates if the order has been realised and can be retrieved from the reportbox.

ReportType Type of the report (Full only).

OrderedOn UTC date and time of the order.

Company Basic company information. It is the same information that is returned within the company search results. Please refer to company searching description section for details.

Failed offline report orders note

For the offline orders that are reportbox based (please see Appendix E for list of offline supported Countries within the reportbox), the reportbox will contain those orders’ entries throughout all their processing and in all the states they can be in (in processing, realised and failed). For failed orders the Realised flag will still be set to true, but the company name will be prefixed with order failed information plus the listing response will contain messages for each of such companies being listed. Those messages will contain the reason of failure plus the reportbox/order number information. Trying to retrieve the report for such an entry will result in a failure in the same way it does for retrieving unrealised orders.

Reportbox report retrieval This operation allows retrieval of multiple reports from the reportbox. It is done by calling the GetReportboxReports service method. The method takes an obligatory ids parameter which is a list of reportbox Ids of the entries to be retrieved. From the supplied identifiers, only those entries that are valid and flagged as “realised” in the reportbox will be returned. Additionally the entries count may be reduced if the total size of the message would exceed the maximal message size of the system.

Response

The response of this operation is identical to the response of online company report retrieval method with the only difference being the possibility of multiple report entries being included in it. Please refer to the online report retrieval section documentation for details.

Reportbox entries removal This operation allows old or unwanted entries to be removed from the reportbox. It is done by calling the RemoveReportboxReports service method. The method takes an obligatory ids parameter which is a list of reportbox Ids of the entries to be removed. If any of the entries is invalid or it points to a report order still in process of realisation the removal will not be carried out at all and a message describing the reason will be returned in the response.


of 33

Response

The response of this operation does not include any additional details apart from the shared messages container. In case of successful removal, no messages will be returned – otherwise error messages describing the source of the problem will be attached.

Portfolios management

Portfolio listing Portfolio listing provides summary information about all or selected portfolios available. It is done by calling the GetPortfolios service method. The method can take two optional parameters that alter the returned list. Specifying an XML date string using the changedSince parameter will override the system default (30-days) or, if defined, user default (set up using the SetDefaultChangesCheckPeriod call) for changes flagging. A set of portfolio identifiers can be passed using the portfolioIds parameter, which will cause the method only to return those portfolio’s summaries. Below is an example of this parameter’s proper structure: <portfolioIds>

<unsignedInt>5</unsignedInt>

<unsignedInt>12</unsignedInt>

...

</portfolioIds>

Response

The portfolio listing response will contain a set of portfolio description nodes. Those nodes will contain basic portfolio information along with changed and total company counts. All the dates will include UTC times.

<response>

<Portfolios>

<Portfolio Id=”1” Enabled=”true” Name=”Example” CreationDate=”[date]”

LastSettingsChangeDate=”[date]”>

<ChangedCompanies>3</ChangedCompanies>

<MonitoredCompanies>12</MonitoredCompanies>

</Portfolio>

...

</Portfolios>

</response>


Id Portfolio identifier.

Enabled Indicates if portfolio is being updated with new data (settings based).

Name If set up with any value, contains the assigned portfolio text name.

CreationDate UTC date and time of portfolio creation.

LastSettingsChangeDate UTC date and time of last portfolio settings change.

ChangedCompanies Number of companies that have changes registered within the specified period of time.

MonitoredCompanies Total count of companies being monitored using this portfolio.


of 33

Portfolio creation Operation used for creating a new portfolio instance that will be used to group monitored companies. Portfolio is created by calling the CreatePortfolio service method. It takes a single parameter (settings) as its input data. The structure of the parameter is explained below: <settings Enabled=”true” Name=”Example” />

Attribute Name Optional Description

Enabled no Specifies if the portfolio should be included in changes information processing.

Name no A non unique free form text that can be used for easier portfolio identification.

Response

Response has structure identical to the one of “Portfolio listing” operation. The only difference is the fact that it will only contain the summary of the newly created portfolio.

Portfolio removal Portfolios can be removed (along with the companies assigned to be monitored within them) by calling the RemovePortfolios service method. The sole input parameter (portfolioIds) is a list of portfolio identifiers of the portfolios to be removed. Its structure is identical to the once described for “Portfolio listing” operation. A simple response object is returned as the operation output. It will only contain error messages if any problems occur during the call processing.

Portfolio settings retrieval Portfolio settings retrieval is done by calling the GetPortfolioSettings method with passing the portfolio identifier as the portfolioId parameter’s value. The response is described below:

<response PortfolioId=”1” CreationDate=”[date]” LastSettingsChangeDate=”[date]”>

<Settings Enabled=”true” Name=”Example” />

</response>


Enabled Indicates if portfolio is being updated with new data (settings based).

Name If set up with any value, contains the assigned portfolio text name.

Portfolio settings alteration Alters selected portfolio’s basic settings. Operation is carried out by making a call to the SetPortfolioSettings service method. The portfolio to alter is selected by providing its identifier using the portfolioId parameter. New settings to be applied are passed using the newSettings parameter which has the same structure as the parameter used in “Portfolio creation” operation (see for structure and description).

A simple response object is returned as the operation output. It will only contain error messages if any problems occur during the call processing.


of 33

Default changes check period control Alters the default changes check period, which will be used for all portfolio and companies listing calls that do not explicitly define it. Operation is carried out by making a call to the SetDefaultChangesCheckPeriod service method. The default number of days back to check is set using the days parameter. If the parameter is not specified or specified with no value, the system default value will be used.


Monitoring rules management

Monitoring rules control the conditions under which companies in a portfolio will be treated as

changed or not by the company listing calls. Rules are set per portfolio and apply to all

companies in the portfolio they have been set in. All rules are treated as if there was an “OR”

relationship between them meaning that at least one of them has to be met for the monitoring

event to be taken into account.

Rules for events that carry values with them can also have value conditions specified, for

example to match events with changes higher than some value, in range of values etc. If multiple

such conditions are specified, it’s possible to select their coexistence character. Either At least

one of them has to be matched (like in an “OR” relationship) or all of them (“AND”

relationship). In order not to filter out important information if value conditions are set and the

event lacks any values, it will still be matched regardless of the value conditions.

Monitoring rules retrieval Portfolio monitoring rules retrieval is done by calling the GetPortfolioMonitoringRules method with passing the portfolio identifier as the portfolioId parameter’s value. The response is described below:

<response PortfolioId="1">

<Rules>

<Rule Enabled="true" EventCode="CR" MatchAllConditions="true">

<Conditions>

<Condition xsi:type="NumericValueRangeCondition" MinValue="100" MaxValue="200"/>

<Condition xsi:type="ChangeRangeCondition" MinChange="10" MaxChange="20"/>

</Conditions>

</Rule>

<Rule Enabled="false" EventCode="PR" MatchAllConditions="false">

<Conditions>

<Condition xsi:type="TextValueRangeCondition" MinValue="C" MaxValue="A"/>

</Conditions>

</Rule>

</Rules>

</response>


of 33


Rule->Enabled Indicates if the rule is taken into account when the portfolio is being updated with new data.

Rule->EventCode Code of the event the rule applies to.

Rule->MatchAllConditions If “true” all of the conditions have to be met by the event to be counted as a change, otherwise at least one of the conditions has to be met.

Condition->xsi:type Condition type – supported values are: NumericValueRangeCondition – absolute new/old value guard for numeric value events; ChangeRangeCondition – old/new values change range (absolute) guard for numeric value events; TextValueRangeCondition – absolute new/old value guard for text value events;

Condition->MinValue (does not apply to ChangeRangeCondition) If set, the condition will only match those events which new or old value is not less than the set parameter.

Condition->MaxValue (does not apply to ChangeRangeCondition) If set, the condition will only match those events which new or old value is not greater than the set parameter.

Condition->MinChange (applies only to ChangeRangeCondition) If set, the condition will only match those events which new and old value differ by no less than the set parameter.

Condition->MaxChange (applies only to ChangeRangeCondition) If set, the condition will only match those events which new and old value differ by no more than the set parameter.

Monitoring rules alteration Alters selected portfolio’s monitoring rules. Operation is carried out by making a call to the SetPortfolioMonitoringRules service method. The portfolio is selected by providing its identifier using the portfolioId parameter. New monitoring rules to be applied are passed using the newRules parameter which has the same structure as the return value of “Monitoring rules retrieval” operation:

<newRules>

<Rule Enabled="true" EventCode="CR" MatchAllConditions="true">

<Conditions>

<Condition xsi:type="NumericValueRangeCondition" MinValue="100" MaxValue="200"/>

<Condition xsi:type="ChangeRangeCondition" MinChange="10" MaxChange="20"/>

</Conditions>

</Rule>

<Rule Enabled="false" EventCode="PR" MatchAllConditions="false">

<Conditions>

<Condition xsi:type="TextValueRangeCondition" MinValue="C" MaxValue="A"/>

</Conditions>

</Rule>

</newRules>



of 33

Monitored companies management

Monitored companies listing Companies listing provides basic company data along with change events’ details companies monitored in all or selected portfolios. It is done by calling the ListMonitoredCompanies service method in a results paging manner. Below is a description of the input parameters:

Parameter Optional Description

portfolioIds yes If set, filters the results to those that are assigned to specified portfolios. Structure is identical to the one described in “Portfolio listing” operation’s description.

changedOnly no If set to “true” the results will be filtered only to those companies which have changed registered within the checked period.

changedSince yes Can be set to override the system default changes check period (30 days) or one set up using SetDefaultChangesCheckPeriod call.

firstPosition no First result’s index that should be returned for this call.

pageSize no How many results should be returned in the response.

Response

Monitored companies listing response contains a paged set of portfolio-assigned companies information. Each company will contain a list of registered changes apart from basic company date (which has the same structure as company search results do). Companies that have any events in the event data base will always contain a full list of those events regardless of the parameters and/or monitoring rules. To determine companies’ events matching monitoring rules the flags HasChanges and LastChangeDate should be used (see response structure description below).

<response Results=”12” TotalResults=”112” FirstPosition=”100” PageSize=”50”>

<Portfolios>

<Portfolio Id=”1” Name=”Example”>

<Companies>

<Company Id=”[id]” Country=”GB” HasChanged=”true” LastChangeDate=”[date]”>

<Name>Example Company</Name>

<Type>Ltd</Type>

<OfficeType>HeadOffice</OfficeType>


<RegistrationNumber>123</RegistrationNumber>

<VatNumber>567</VatNumber>

<Address>

...

</Address>

<PhoneNumber>890</PhoneNumber>

<Reference>Some text.</Reference>

<Changes>

<Change Code=”CL” Date=”[date]” />

...

</Changes>

</Company>

...

</Companies>

</Portfolio>

...

</Portfolios>

</response>


Portfolio->Id Portfolio identifier.


of 33

Portfolio->Name If set up with any value, contains the assigned portfolio text name.

Company->Id Company’s Id string.

Company->Country The ISO 3166-1-alpha-2 country code of the company’s country.

Company->HasChanges Indicates if the company has changes any changes (if “changedSince” parameter has not been set) or changes after the date specified using “changedSince” parameter.

Company->LastChangeDate If present, holds the date of last company event that matched portfolio’s monitoring rules.

Company->Name Holds company’s name.

Company->Type If present, holds company’s type information (Ltd, NonLtd etc.)

Company->OfficeType If present, holds company’s office type information (Headoffice etc.)

Company->Status If present, holds company’s status information (Active, Pending etc.)

Company->RegistrationNumber If present, holds company’s registration number.

Company->VatNumber If present, holds company’s VAT identification number.

Company->Address If present, holds company’s address data structure.

Company->PhoneNumber If present, holds comapny’s phone number.

Company->Reference If present, holds the reference text assigned to the company.

Change->Code Code of the change that took place.

Change->Date Date on which the change took place.

Adding companies to monitoring Companies can be added to a portfolio or a set of portfolios using the AddCompaniesToPortfolios service method. A list of portfolio identifiers to which companies are to be added should be passed as the portfolioIds value (structure identical to “Portfolio listing” operation). Companies along with text references to assign to them are passed using the companies parameter. Structure of this parameter is explained below: <companies>

<Company key=”[company identifier]”>[reference text]</Company>

<Company key=”[company identifier]”>[reference text]</Company>

...

</companies>

Node Optional Description

“key” attribute no Company identifier of the company to be added to monitoring.

”Company” inner text yes A free form text to be asigned to the company entry in the portfolio.

Response

Company addition results contain summary counts of added companies plus all errors detailed using the standard messages system.

<response TotalCompanies=”12” SuccessfullyAddedCompanies=”10” NewCompanies=”2”>


TotalCompanies Total count of company identifiers passed in the parameter.

SuccessfullyAddedCompanies Number of companies that were succesfully added to the portfolio(s)..

NewCompanies Companies that were not previously monitored in any portfolios..


of 33

Removing companies from monitoring Companies can be removed from a portfolio or a set of portfolios using the RemoveCompaniesFromPortfolios service method. The list of portfolios should be passed as the portfolioIds parameter’s value (structure identical to “Portfolio listing” operation). The set of company identifiers for removal should be passed as companyIds with the following structure: <companyIds>

<string>[company identifier]</string>

<string>[company identifier]</string>

...

</companyIds>

Response

Removal result contains a per-portfolio list of removed companies’ identifiers. Any errors are signalised using the standard messages system..

<response>

<Portfolios>

<Portfolio Id=”1” Name=”Example”>

<CompanyIds>

<Id>[id]</Id>

...

</CompanyIds>

</Portfolio>

...

</Portfolios>

</response>

Monitored companies reference text alteration Company assigned reference text can be altered using a call to the ChangeCompaniesReferenceStrings service method. It takes identical parameters as the “Adding companies to monitoring” operation, but instead of adding new entries to portfolios it only alters the reference text of existing ones.



of 33

Additional operations

Supported events information retrieval A list of supported event types along with their text description can be obtained by calling the GetSupportedChangeEvents service method. Currently the list serves only for informational purposes. It takes the following parameters:

Parameter Optional Description

country yes If set, only the events supported by the specified country will be returned along with the information specific for that country. Otherwise a system-wide list of events is returned.

language no Desired language of text descriptions. Currently only EN is supported.

Response

Supported events listing contains a set of entries, each one describing a single event code.

<response>

<Events>

<Event Code=”CL” CarriesValues=”false” Category=”SimpleEvent” CanBeMonitored=”true”>

<Description>Example event’s description text.</Description>

</Event>

...

</Events>

</response>


Code Unique event code string.

CarriesValues Indicates if event can have the new or old value included in returned event details..

Category Indicates event category (simple change, numeric value change, text value change etc.).

CanBeMonitored If “false” no monitoring rules can be set up for this event type as it is only kept for legacy events support and will soon be removed..

Description Text description of the event.


of 33

Company Custom Score calculation This functionality provides methods for calculating company credit score using custom algorithms. Such algorithms are manually entered into our system and provided to use as score cards. This way numerous algorithms can be made available and each one can be selected per call.

Available score cards information retrieval GetCustomScoreCards is the method that can be used to retrieve all the information about available score cards that can be used for custom credit score retrieval operations. The method takes no parameters and always lists all available score cards.

Response <response>

<ScoreCards>

<ScoreCard Id="1.1" Notes="Example score card"/>

<ScoreCard Id="2.45" Notes="Another score card"/>

</ScoreCards>

</response>

Company Custom Score retrieval Any company that has online report functionality available, can be requested for custom score calculation using the method RetrieveCompanyCustomScore. Company’s calculated credit score details will be returned instantly. This method takes in a following set of single value parameters:


companyId Company’s Id string.

scoreCardId Score card Id string (in the format returned by the listing method).

customData Custom Data allowed or required by selected country for custom score retrieval calls.


Apart from the above, there is one complex parameter parameters, which allows to pass additional data to the custom score calculation algorithm. It consists of 4 sections, each for one variable type: <parameters>

<Numeric>

<Parameter key="1">123</Parameter>

<Parameter key="2">0</Parameter>

</Numeric>

<Boolean>

<Parameter key="1">true</Parameter>

<Parameter key="2">false</Parameter>

</Boolean>

<Text>

<Parameter key="1">A</Parameter>

<Parameter key="2">Once a week</Parameter>

</Text>

<Date>

<Parameter key="1">2012-01-01T12:30:45Z</Parameter>

<Parameter key="2">2015-02-15T00:00:00Z</Parameter>

</Date>

</parameters>


of 33

Custom Data possibilities can be discovered using the GetCustomScoreCustomDataSchema method. This method

returns a Custom Data schema description with identical structure as <CustomData> part of the search criteria discovery method. See GetPossibleSearchCriteria method’s response documentation for details (“Search criteria

schemas discovery” section of this document).

Response <response CompanyId="AA/1234" OrderNumber="123" ScoreCardId="1.1" ChargeReference=" example">

<Result>

<Score>1790</Score>

<CreditLimit Currency="GBP">5815800.00000</CreditLimit>

</Result>

<ParameterValues>

<ParameterValue Name="Acid Test" Value="1.51" Points="160" Type="Numeric"/>

<ParameterValue Name="Gearing" Value="10.77" Points="80.00" Type="Numeric"/>

<ParameterValue Name="Credit Rating" Value="A" Points="100.00" Type="Text"/>

<ParameterValue Name="Payment Behaviour" Value="0.00" Points="150.00" Type="Numeric"/>

<ParameterValue Name="Payment Trend" Value="Improving" Points="50.00" Type="Text"/>

…

<ParameterValue Name="Years with Brand" Value="10.00" Points="100.00" Type="Numeric"/>

<ParameterValue Name="How Profitable" Value="700.00" Points="150.00" Type="Numeric"/>

</ParameterValues>

</response>


Response->CompanyId Company’s Id string.

Response->OrderNumber Unique number of the order that this report is result of.

Response->ScoreCardId The score card identifier that has been supplied using the scoreCardId call parameter.


Result->Score Calculated custom company score value.

Result->ScoreDescription Optional text description of the calculated custom score.

Result->CreditLimit Calculated credit limit value (in currency described by the Currency attribute.

Result->CreditLimitDescription Optional text description of the calculated credit limit.

ParameterValues->ParameterValue Represents a single custom score calculation parameter value used.

ParamererValue->Name Name of the parameter.

ParamererValue->Value Actual value of the parameter for the selected company.

ParamererValue->Points Calculation points of the parameter.

ParamererValue->Type Type of the parater – can be: Numeric, Boolean, Text, Date or Unknown

Direct custom score retrieval Similar to company report, custom score retrievals can be made without first knowing a company ID. The TryRetrieveCompanyCustomScore is the method whose input parameters replicate what is allowed through the FindCompanies method call, so allowing all possible search criteria input parameters, and then, if a unique hit is found, the custom score calculation will be made and its results returned in the response. You can view the company search page of this document to see all the allowed criteria. The rest of the parameters are identical to their counterparts in the standard custom score retrieval method described in the previous section. It is important to know that if the search parameters provided to the method TryRetrieveCompanyCustomScore return more than one company, then an error is returned back to the user/client. For the method to return a score calculation the provided search criteria needs to generate a unique search results hit.


of 33


of 33

Appendix A

DE report request reason code

Due to legal reasons all report requests of German companies must be accompanied with a reason code. Those codes are required by DE report order calls to be passed as Custom Data entries. The list of possible reason codes are given below...

Reason Code Description

1 Credit Decisioning

2 Credit Assessment - Future business connection (with credit risk)

3 Credit Assessment - Existing business connection (with credit risk)

4 Realisation check receivables collection

5 Purchase Contract - Intention of signature of purchase contract (with credit risk)

6 Goods Credit Insurance (with credit risk)

7 Contract - Intention of signature of leasing or rent contract (with credit risk)

8 Insurance Contract - Intention of signature of a insurance contract (with credit risk)


of 33

Appendix B

Message codes

Numeric code values are divided in such a way that 2 least significant digits represent an in-group number, 2 more significant represent a sub-group number and the most significant pair represents a group number.

Group Value mask

Data availability 0101xx

User account related 02xxxx

Access rights 0201xx

User resources 0202xx

Call related 03xxxx

Operation call 0301xx

System changes notifications 0302xx

Processing related 0401xx

Message Code Value

No results 010101

Too many results 010102

Report unavailable 010103

Report unavailable due to legal causes 010104

Report unavailable online 010105

Legal notice 010106

Invalid credentials 020101

Access restricted 020102

Access limits nearing 020103

Reportbox almost full 020201

Reportbox full 020202

Invalid request XML 030101

Invalid operation parameters 030102

Operation not supported 030103

Change notification 030201

Temporary system problem 030202

Endpoint shutdown 030203

Unexpected internal error 040101

Other 040102

Data service access problems 040103

Data service invalid response 040104


of 33

Appendix C

Country dependant service availability

Italy is unavailable at the times/dates below

Monday – Sunday: 20:00 – 07:00 (BST/GMT), 21.00 - 08.00 (CET)

Last working day of each month: 18:00 – 07:00 (BST/GMT), 19.00 - 08.00 (CET) Italy is also unavailable during bank holidays but with no support. Bank holidays in Italy are:

January, 1st

January, 6th

Easter

April, 25th

May, 1st

June, 2nd

August, 15th

November, 1st

December, 8th

December, 25th

December, 26th Canada’s availability is below

Canada has a maintenance window posted every day (Mon – Mon) between 01:30 & 06:30 EST – customers can potentially have no access. Our supplier may not go offline at this time but they have the ability to take the service down at this time. It is also possible the service will be unavailable for a time shorter than this time given. This will be 06:30 – 11:30 (BST/GMT) & 07:30 – 12:30 (CET).

Spain’s availability is below

Spain can be unavailable on Tuesdays between 18:00 & 21:00 GMT. Not every Tuesday will be unavailable, but if Spain is unavailable between these times it is likely due to a supplier maintenance window.

Brazil’s availability is below

Brazil is unavailable every day between the following times: o North American (EST) – 03:00 – 05:00 o UK Time (GMT) – 08:00 – 10:00 o Central European Time (CET) – 09:00 – 11:00


of 33

Appendix D

Country events

Below are listed the available events per Country

Monitoring Event Legend

Event Code Event Description

AC Address change (including telephone number)

CL Credit Limit

CR Credit Score

DN Director change

EC No. Of Employees

FN New accounts/financials filed

IC Change to total issued capital

NC Company name change

PR Negative data

UC Change to ultimate holding company

HO Headoffice activity

BN Branch/Establishment activity

LG Legal Event

Event Code/Country Code

BE DE FI FR GB IE LU NL SE US

IT

CH

LI

ES

AT NO DK

AC / / / / / / / / / / / / / / /

CL / / / / / / / / / / / / / /

CR / / / / / / / / / / / / / / /

DN / / / / / / / / / EC / / / / / /

FN / / / / / / / / / / / / /

IC / / / / / / / /

NC / / / / / / / / / / / / / / / PR / / / / / / / / / / / / / /

UC / / / / / /

HO /

BN /

LG /


of 33

Appendix E

List of online/offline Countries supported in the ReportBox

Below lists the offline Countries which are available to be used in the ReportBox

Offline supported companies within ReportBox

Country Code Country Name

DE Germany

Below lists the online Countries which are available to be used in the ReportBox

Online supported companies within ReportBox

Country Code Country Name

{ALL} All online Countries within the GGS service is supported on the


of 33

Appendix F

Company ID change report messages

When there are changes in company IDs made for some reason (eg. multiple IDs are merged to one) and a company is no longer available for report retrieval using the stored company ID, there RetrieveCompanyOnlineReport call will contain information regarding valid company ID if available. Here is an example of a message returned for US company report retrieval using an ID that is no longer valid as it has been merged to another entry: <response>

<Messages>

<Message Code="10103" Type="Information">

Specified company ID has been changed and the report is now available under Safe

Number: US12345678.

</Message>

</Messages>

</response>

The message contains indicator (SafeNumber) to the valid company entry which can be used to obtain the report.

Global Gateway API Interface -...

Documents

Transcript of Global Gateway API Interface -...