Search API Overview

Financial Search API is exposed to search the global financial data of companies based on various search criteria’s . You can find details of using Search API below in this section.

Request

POST /searchfinancials

Details

Full path https://api.globalfinancials.com/searchfinancials
HTTP verb POST
Description Search the Financial statements globally with a variety of matched criteria’s .
Produces application/json

The main sections of the request are explained below:

HTTP Header
  • Security section
HTTP Body
  • Transaction section
  • Return Fields section
  • Match Criteria section
  • Pagination section
  • Sorting section

HTTP Header

Security section

All requests will be validated for authentication and authorization using the security token received through the Authentication process. If you want to know more about Authentication process, please refer Authentication API

Below parameters are required to be included in the request as a part of HTTP Headers:

Header Parameters
Name Data Type Required Example Description
Authorization string true TOKEN-VALUE The access token provided by authentication.
Content-Type string true application/json The content type must be "application/json".

HTTP Body

JSON schema of the request body is available here for your reference. Download - Search Request JSON

Transaction section

All requests should contain the below details in order to track each transaction unique to Global Financials application.

Name Data Type Required Example Description
documentID string true 28a89391-b15f-44fc-b764-91b8262c9ec5 Each json will be treated as a unique document and an unique identifier is expected.
sessionID string true user1@mail.com An user specific unique identifier e.g login id or email
creationTimestamp date-time false 2018-06-04 10:28:35 The timestamp of the time the request document is created.
requestType string true result A key identifying the type of the request, e.g., count (returns the count of search), result (returns the data packets on matched criteria).
Return Fields section

If you need to control the returned data with the set of limited input, use the return fields as explained below. By default, it returns the data the user is entitled to.

Name Data Type Required Example Description
returnFields array-enum false 
"returnFields":[
	"businessName", 
	"registrationNumbers",
	"totalCurrentAssets",
	"totalAssets", 
	"issuedCapital" ]


Click here to get the list of accepted enum values
Match Criteria section

In order to search any Financial or identification criteria, this section will help you understand how to filter the search with different filtering capability of the Search API. This is a mandatory section , and a mix and match of the below items can be provided in the request.

Name Data Type Required Example Description
matchCriteria.duns string array false 
"matchCriteria": { 
"duns":["111523689","600165450"]},
 Add the list of DUNS numbers to be searched.


Maximum 10,000 DUNS are allowed
matchCriteria.registrationNumbers objects array false 
"matchCriteria": { 
"registrationNumbers": [{ 
"registrationNumber":"CH29030022964", 
"typeDnBCode":13145
}]},
 Add the list of Registration numbers to be searched. typeDnBCode is not mandatory.


List of typeDnBCode
matchCriteria.name string array false 
"matchCriteria": { 
    "name": ["Barclays", "Tesco"]
},
 Add the list of Business names to be searched.


Min three characters needed to match the search.
matchCriteria.businessAddress object false 
"matchCriteria": { 
"businessAddress": { 
"town": ["Marlow","Reading"], 
"county": [ "Middlesex","Bucks"], 
"territory": ["SH"], 
"postalCode": ["8200", "123"], 
"countryCode": [1067]
}},
 The list of address texts for searching.


Town array of strings

County array of strings

Territory array of strings

Postal codes array of strings

Country codes array of codes - List of Country codes
matchCriteria.numberOfEmployees object false 
"matchCriteria": { 
"numberOfEmployees" : { 
    "fromValue": 5,
    "toValue": 100
}},
 Search using the From Value and/or To Value as numeric for number of employees parameter.
matchCriteria.industryCodes array false 
"matchCriteria": { 
"industryCodes" : {
    "typeDnbCode": "1015",
    "code" : ["4312321","323212"],
    "isOnlyPrimaryRequired": true,
    "isAvailable": false
}},
 Search for the list of Industry type codes.

typeDnbCode is the Industry type codes
and code is the Industry code.


List of Industry Type codes (typeDnbCode) and codes in each type


isOnlyPrimaryRequired true to search only the primary industry code.
isAvailable is to match if industry code is available.
matchCriteria.startDate date false 
"matchCriteria":  { 
"startDate" : {
    "fromValue" : "2001-01-01" ,
    "toValue":  "2019" 
}},
 Search the entities using start date of the company using the From Value and/or To Value parameters.


Date pattern "YYYY-MM-DD Or YYYY-MM Or YYYY"
matchCriteria.dateOfRegistration date false 
"matchCriteria": { 
"dateOfRegistration" :  {
    "fromValue": "2001-01-01" ,
    "toValue": "2019"  
}},
 Search the entities using registered date of the company with the From Value and/or To Value parameters.


Date pattern "YYYY-MM-DD Or YYYY-MM Or YYYY"
matchCriteria.legalFormClassDnBCode object false 
"matchCriteria": { 
"legalFormClassDnBCode" : { 
	"value":  [452, 455]  
}},
 Search for the Legal Form codes to match the entities.


List of Legal form codes
matchCriteria.status string array false 
"matchCriteria": { 
	"status": ["Active", "Dormant"] 
},
 Search using the company status.


List of Company status codes
matchCriteria.informationSourceDnBCode integer array false 
"matchCriteria": { 
	"informationSourceDnBCode": [ 25863 ] 
},
 There are two types of source: 25863 is MorningStar or 3891 is D&B source data through GSRL.

To search Public Quoted companies, it's easy to search MorningStar source entities as it is the complete source of public quoted companies.
matchCriteria.statementToDate dates false 
"matchCriteria": { 
"statementToDate" : {
	"fromValue" : "2001-01-01",
	"toValue" : "2019"
}},
 Search on the date when the accounting period ended using the From Value and/or To Value parameters.


Date pattern "YYYY-MM-DD Or YYYY-MM Or YYYY"
matchCriteria.informationScopeDnBCode integer false 
"matchCriteria": { 
	"informationScopeDnBCode":[0, 9066, 9067, 9068, 13173] },
 Search on the organizational scope of the financial statement. E.g. Individual (Organization including any branches), Consolidated (Organization including any branches and subsidiaries).


List of Information Scope codes
matchCriteria.currency string false 
"matchCriteria": { 
	"currency" : "USD"
},
 An ISO code that identifies the currency in which the financial values are represented for searching and returning. If there is no currency input, then the default currency will be EURO.


List of supported currencies
matchCriteria
[Search on Balance Sheet financial fields]		 objects false 
"matchCriteria": {
	"tangibleFixedAssets" { 
	"fromValue" : 1, 
	"toValue" : 100000, 
	}, "totalAssets" { 
	"fromValue" : 500000, 
}},
Search the Balance sheet financial fields using the From and/or to as numeric values in search criteria.


List of Balance Sheet fields
matchCriteria
[Search on Profit & Loss financial fields]		 objects false 
"matchCriteria": {
	"grossProfit" { 
	"fromValue" : 1000000, 
	"toValue" : 10000000, 
	}, 
	"profitBeforeTaxes" {
	"fromValue" :1000000, 
}},
 Search the Profit and Loss financial fields using the From and/or to numeric search criteria.


List of Profit& Loss fields
matchCriteria
[Search on Derived financial fields]		 objects false 
"matchCriteria": {
	"quickRatio" { 
	"fromValue" :1000000, 
	"toValue" : 10000000, 
	},"EBITDA" { 
	"toValue" : 10000000, 
	},"netDebt" { 
	"fromValue" : 9000000, 
}},
 Search the derived financial fields using the From and/or to value as numeric for search criteria.


List of Derived fields
matchCriteria
[isAvailable check on financial fields]		 objects false 
"matchCriteria": {
	"stockOrInventories" { 
	""isAvailable":true, 
}},
 Search any financial fields in IS Available or NOT Available criteria with boolean input.


List of all Financial elements covered
matchCriteria.parentDuns string array 
"matchCriteria":{ 
"parentDuns":["762479538", 
"370003568"]},
 Search Corporate Linkages to find the Parent of the company.

Parent DUNS Numbers are used as input to evaluate the candidates.
matchCriteria.parentName string array 
"matchCriteria":{ 
"parentName":["google" ,
"apple"]},
 Search Corporate Linkages to find the Parent of the company.

Parent company names are used as input to evaluate the candidates.
matchCriteria.parentCountryCode integer array 
"matchCriteria":{ 
"parentCountryCode":[1067, 1073]},
 List of Parent countries where the entity is physically located and expressed as a D&B Geographic Reference Identifier.

Country codes as array of codes - List of Country codes
matchCriteria.domesticUltimateDuns string array 
"matchCriteria":{ 
"domesticUltimateDuns":[
"762479538","370003568"]},
 Search Corporate Linkages to find the Domestic Parent of the company.

Domestic Parent DUNS Numbers are used as input to evaluate the candidates.
matchCriteria.domesticUltimateName string array 
"matchCriteria":{ 
"domesticUltimateName":[
"google","apple"]},
 Search Corporate Linkages to find the Domestic Parent of the company.

Domestic Parent company names are used as input to evaluate the candidates.
matchCriteria.domesticUltimateCountryCode integer array 
"matchCriteria":{ 
"domesticUltimateCountryCode":[1067, 1073]},
 List of Domestic Ultimate countries where the entity is physically located and expressed as a D&B Geographic Reference Identifier.

Country codes as array of codes - List of Country codes
matchCriteria.globalUltimateDuns string array 
"matchCriteria":{ 
"globalUltimateDuns":[
"762479538","370003568"]},
 Search Corporate Linkages to find the Global Ultimate Parent of the company.

Global Ultimate Parent DUNS Numbers are used as input to evaluate the candidates.
matchCriteria.globalUltimateName string array 
"matchCriteria":{ 
"globalUltimateName":[
"google","apple"] },
 Search Corporate Linkages to find the Global Ultimate Parent of the company.

Global Ultimate Parent company names are used as input to evaluate the candidates.
matchCriteria.globalUltimateCountryCode integer array 
"matchCriteria":{ 
"globalUltimateCountryCode":[1067, 888]},
 List of Global Ultimate countries where the entity is physically located and expressed as a D&B Geographic Reference Identifier.

Country codes array of codes - List of Country codes
matchCriteria.excludeCriteriaFields object 
"matchCriteria":{ 
"excludeCriteriaFields":{
"duns":["123123123", "456456433"]},
"town":["london", "marlow"]}
}},
 Exclude criteria will help to exclude any search fields from the other match criteria. e.g. Exclude all companies of London from the above matched criteria.

Here is the list of fields which can be excluded
  • "duns"
  • "town"
  • "country"
  • "territory"
  • "postalCode"
  • "countryCode"
  • "industryCodes
Pagination section

This section will help you to control the response data in a pagination process. The maximum entities (DUNS) returned is 50. This field is not required for the count request type.
Please note that maximum entities that can be returned from Global Financials API using pagination is limited to 10,000. Please reach out to support team if there is a requirement to get more data -

Name Data Type Required Example Description
startRecordNumber integer true 1 
"pagination": {
"startRecordNumber": 1,
"numberOfRecords": 20
}
 The start of the record number. In case you are getting 20 records in each page, and you need to retrieve the third page, then the start number is 21.
numberOfRecords integer true 20 The number of records per page requested. The maximum value which can be given is 50.
Sorting section

This section will help you to sort the response data in a pagination process. This is not required for count request type. :-

To retain the search engine ranking do not input the sort elements

Name Data Type Required Example Description
sortKey String false totalAssets
"orderBy": {
"sortKey": "totalAssets",
"sortDirection":"desc"
}
 The sorting column or key. List of sorting keys
sortDirection String false desc Sorting logic asc or desc is used. Default is asc.

Response

Below are the main sections of the response HTTP Body: -
  • Transaction section
  • Match Criteria section
  • Matched Records count section
  • Matched Record section

JSON schema of the request body is available here for your reference. Download - Search Response JSON

Transaction section

All response will contain the below details to track each transactions uniquely to Global Financials application.

Name Data Type Required Example Description
documentID string true 44r89671-b67t-31fc-b5627-91b8262c9ec5 Each json will be treated as a unique document, an unique identifier is expected for the response.
requestID string true 28a89391-b15f-44fc-b764-91b8262c9ec5 This field value is the document ID shared in the request to match the transaction for the calling application.
creationTimestamp date-time false 2018-06-04 10:28:35.384Z The timestamp of the time the response document is created.
requestType string true result A key identifying the type of the request, e.g., count (returns the count of search), result (returns the data packets on matched criteria)
transactionStatus.isfailure boolean true false This will help to identify whether this is a failure or success flow
transactionStatus.statusCode boolean true 200 This will return the status codes. 200 is success. For other error codes please check Error codes and messages page
transactionStatus.statusMessage boolean false 200 This will return the status message of the request. "success" will be returned for a successful transaction. For other error messages please check Error codes and messages page

Matching Criteria section

This section will return back the matching criteria section placed in the request

Name Data Type Required Example Description
matchCriteria object 
"matchCriteria": { 
"duns":["111523689","600165450"]},
 The will be matching criteria given in the request and for which the response is matched.

Matched Records count section

This section will return back the count matched for the request.

Name Data Type Required Example Description
matchCandidatesCount integer 7682 The count of total records matched for the criteria in the request will be shared here.

Matched Candidates

This section will return back the matched searched entities, below are the elements inside it

Identification

This section will contains the details to identify the company or entity.

Name Data Type Required Example Description
duns string true 789567456 A number assigned by an external body or by D&B which either uniquely identifies or helps to identify an organization.
registrationNumbers array true 
"registrationNumbers": [
{
"registrationNumber":"04083914",
"typeDnBCode": 2541,
"priority": 1
}],
 Add the list of Registration numbers to be searched. typeDnBCode is not mandatory.


List of typeDnBCode
businessName object true 
"businessName": {
"languageDnBCode":39,
"name":"PORT 2 LTD"
}
 name - A name by which the business is known / identified
tradeStyleNames object 
"tradeStyleNames": {
"languageDnBCode":39,
"name":"PORT-2"
}
 Array of Trade style names for the company name - A name by which the business is known / identified
businessAddress object 
"businessAddress": {
"town": "CHERTSEY",
"streetAddress": {
	"line1":"Comtass House"
	},
"languageDnBCode":39,
"countryCode": 1067,
"postalCode":"KT1 9BQ",
"county":"Surrey",
"postalCodePositionDnBCode":1011
}
 The list of address lines.


Town array of strings

County array of strings

Territory array of strings

Postal codes array of strings

Country codes array of codes - List of Country codes
industryCodes object 
"industryCodes": {
"industryCodeTypes": [ {
"typeDnBCode":19295,
"industryCode": [ {
     "code":"46390",
     "priority": 1
    }, {
	"code":"56100",
	"priority":2
}] }, {
	"typeDnBCode":3599,
    "industryCode": [ {
    "code":"51410000",
    "priority": 1
    }, {
	"code": "58120000",
	"priority": 2
}] }, {
	"typeDnBCode":1016,
	"industryCode": [ {
	"code":"5141",
	"priority":1
	}, {
	"code":"5812",
	"priority":2
}]}]}
 List of all Industry type codes of the company.

typeDnbCode is the Industry type codes
and code is the Industry code.


List of Industry Type codes (typeDnbCode) and codes in each type
startDate date 1990-12-22 The date(YYYY-MM-DD) when the subject actively took control of the business activities. This would only be used when the subject is continuing a business started by an earlier founder. If a company registered on 25th August 1930 remained inactive until 2nd October 1965 at which time it acquired and continued business activities originally established on 18th June 1815 then the Subject Start Date is the 1965 date.
dateOfRegistration date 1990-12-22 The date when the subject is registered with official body..
numberOfEmployees array 
"numberOfEmployees": [ {
	"date":"2017-09-30",
	"informationScopeDnBCode":9067,
	"reliabilityDnBCode":9092,
	"value":588112
} ],
 Records several different Employee Figures for the subject. (E.g. Group/Consolidated and Individual figures).
telephoneNumber string 
"telephoneNumber":"+44 1932 373000"
 The subject's Telecom Number within the telephone exchange.
website string 
"website":"www.compass-3.co.uk"
 The subject's web addrees.
legalForm object false 
"legalForm": {
	"legalFormClassDnBCode":451,
	"startDate":"2000-09-29",
	"legalFormDnBCode":2549
}
 Records the current legal form of the subject.
status string false 
"status":"Active"
 The company's operating status.


List of Company status codes
informationSourceDnBCode integer false 
"informationSourceDnBCode":25863
 A code value identifying the source from which the Financial Statement data was extracted for inclusion in this record.

Latest Financials

This section will contains the latest financial details of the subject.

Name Data Type Required Example Description
statementToDate date true 2108-12-31 Records the most recent financial statement. Format- YYYY-MM-DD
statementFromDate date 2108-12-31 The date on which the accounting period commenced. Format - YYYY-MM-DD
informationScopeDnBCode integer "informationScopeDnBCode": 9067 A code which describes the organizational scope of the financial statement. E.g. Individual (Organization including any branches), Consolidated (Organization including any branches and subsidiaries).
reliabilityDnBCode integer "reliabilityDnBCode": 9092 A code which describes the reliability of the figures in the financial statement. E.g. Actual, Estimated, Projected, Modeled.
statementSizeUnitDnBCode integer "statementSizeUnitDnBCode": 7964, A code which identifies the unit of size in which the financial statement is provided. E.g. In 1,000s; In 1,000,000s. The financial figures should be populated to the record with the 000's or 000,000's omitted.

STANDARD VIEW LOCAL CURRENCY

Records the standardized view array of the financial statement in local currency.

Name Data Type Required Example Description
currency string true EUR An ISO code that identifies the currency in which the financial statement is provided.


List of Industry Type codes (typeDnbCode) and codes in each type
balanceSheet object 
"balanceSheet":  {
"totalAssets":50067,
"totalCurrentAssets":49036,
"longTermDebt":0,
"totalLiabilities":33770,
"otherCurrentAssets":0,
"issuedCapital":100,
"otherCapitalAndReserves":16197,
"stockOrInventories":0,
"otherLongTermLiabilities":26428,
"currentLiabilities":7342,
"accountsReceivable":48931,
"shortTermDebt":0,
"totalLiabilitiesAndEquity":50067,
"intangibleAssets":0,
"totalLongTermLiabilities":26428,
"totalEquityOrNetworth":16297,
"otherCurrentLiabilities":7342,
"totalFixedAssets":1031,
"accountsPayable":0,
"tangibleFixedAssets":1031,
"investmentsAndOtherAssets":0,
"cashAndCashEquivalents":105
},
 Records the financial items present in the Balance Sheet section.


Balance sheet elements
profitAndLoss object 
"profitAndLoss": {
"netSales":22109808,
"directCosts":18072150,
"grossProfit":4037658,
"netOperatingIncome":105275,
"profitBeforeTaxes":410178,
"depreciationOrAmortisationCharge":533834,
"netIndirectCosts":3932383,
"netNonOperatingIncomeAndExpenses":304903,
"taxCharge":30464,
"profitAfterTaxes":379714,
"extraordinaryAndSimilarItems":0,
"totalPayrollCosts":1962815,
"numberOfEmployees":75,
"netProfitOrLoss":379714
},
 Records the financial items present in the Profit and Loss section.


Profit and Loss elements
derivedFinancialItems object 
"derivedFinancialItems": {
"workingCapital":41694,
"tangibleNetworth":16297,
"currentRatio":6.7,
"quickRatio":6.7,
"totalDebt":0,
"netDebt":-105,
"solvencyRatio":32.6,
"totalLiabilitiesToTotalEquity":207.2
},
Records the financial items present in the Balance Sheet section.


Derived elements

STANDARD VIEW REFERENCE CURRENCY

Records the standardized view array of the financial statement in reference currency, e.g.,EUR, USD.

Name Data Type Required Example Description
currency string true EUR An ISO code the identifies the currency in which the financial statement is provided.


List of Industry Type codes (typeDnbCode) and codes in each type
balanceSheet object 
"balanceSheet": {
"totalAssets":50067,
"totalCurrentAssets":49036,
"longTermDebt":0,
"totalLiabilities":33770,
"otherCurrentAssets":0,
"issuedCapital":100,
"otherCapitalAndReserves":16197,
"stockOrInventories":0,
"otherLongTermLiabilities":26428,
"currentLiabilities":7342,
"accountsReceivable":48931,
"shortTermDebt":0,
"totalLiabilitiesAndEquity":50067,
"intangibleAssets":0,
"totalLongTermLiabilities":26428,
"totalEquityOrNetworth":16297,
"otherCurrentLiabilities":7342,
"totalFixedAssets":1031,
"accountsPayable":0,
"tangibleFixedAssets":1031,
"investmentsAndOtherAssets":0,
"cashAndCashEquivalents":105
}
 Records the financial items present in the Balance Sheet section.


Balance sheet elements
profitAndLoss object 
"profitAndLoss":{
"netSales":22109808,
"directCosts":18072150,
"grossProfit":4037658,
"netOperatingIncome":105275,
"profitBeforeTaxes":410178,
"depreciationOrAmortisationCharge":533834,
"netIndirectCosts":3932383,
"netNonOperatingIncomeAndExpenses":304903,
"taxCharge":30464,
"profitAfterTaxes":379714,
"extraordinaryAndSimilarItems":0,
"totalPayrollCosts":1962815,
"numberOfEmployees":75,
"netProfitOrLoss":379714
},
 Records the financial items present in the Profit and Loss section.


Profit and Loss elements
derivedFinancialItems object 
"derivedFinancialItems":  {
"workingCapital":41694,
"tangibleNetworth":16297,
"currentRatio":6.7,
"quickRatio":6.7,
"totalDebt":0,
"netDebt":-105,
"solvencyRatio":32.6,
"totalLiabilitiesToTotalEquity":207.2
}
 Records the financial items present in the Balance Sheet section.


Derived elements

LOCAL VIEW

The local view of the financial statement. (Accessible only if subscribed and entitled for this section.)

Name Data Type Required Example Description
currency string true EUR An ISO code the identifies the currency in which the financial statement is provided.


List of Industry Type codes (typeDnbCode) and codes in each type
financialStatementSchedules object array 
"financialStatementSchedules": [ {
"typeDnBCode":11596,
"financialStatementItems": [ {
"itemAmount":317319,
"typeDnBCode":3008,
"displaySequence":12
   }, {
"itemAmount":1146439,
"typeDnBCode":3009,
"displaySequence":14
   }, {
"itemAmount":639181,
"typeDnBCode":7153,
"displaySequence":20
}] },
 An entry loop which can repeat multiple times to allow the Financial Statement to be sub-divided into it's components parts or schedules such as Current Assets, Current Liabilities, Profit and Loss Account, Derived Ratios etc.


typeDnBCode - Contains a code describing the subdivision of a financial statement into which the Financial Statement Item can be categorizedFinancial Schedules codes


financialStatementItems.itemAmount - Records the monetary value of a Financial Statement Item.


financialStatementItems.typeDnBCode -A code that describes the account for the monetary amount recorded in 'Item Amount'Financial Item codes


financialStatementItems.displaySequence - Contains the order number in which items should be presented within the Financial Statement Schedule where the lower the number the earlier the data is presented.
derivedFinancialItems object array 
"localView": {
"derivedFinancialItems": [ {
"financialRatio":6304792,
"typeDnBCode":6363,
"displaySequence":1
    }, {
"financialRatio":1.3,
"typeDnBCode":11908,
"displaySequence":2
    },
 Records the financial ratios relating to the stated financial period.


typeDnBCode - A code value that describes the type of derived result recorded in 'Financial Ratio' Statistical Norm Type Codes


financialRatio - Records the monetary value of a Financial Statement Item.


displaySequence - Contains the order number in which items should be presented within the Financial Statement Schedule where the lower the number the earlier the data is presented.

Previous Financials

This section will contains the maximun of 9 years previous financial details of the subject.

Name Data Type Required Example Description
previousFinancials array Array of maximum of 9 year previous financial structure. This section needs to be treated as an array of statements matching like previous Financial Statement section

Corporate Linkage

The details of the relationship between the entity and other entities in the legal family tree.

Name Data Type Required Example Description
parent object 
"corporateLinkage": {
"parent" {
"duns": "302776257" ,
"primaryName": "IMMOFINANZ AG",
"countryCode": 869
},
 The details of the entity that owns more than 50% of the subject entity.
domesticUltimate object 
"corporateLinkage": {
"domesticUltimate" {
"duns": "302776257" ,
"primaryName": "IMMOFINANZ AG",
"countryCode": 869
},
 The details of the Domestic Ultimate which is the last entity in the tree, when reviewing upwards, that is in the same country as the entity.
globalUltimate object 
"corporateLinkage": {
"globalUltimate" {
"duns": "302776257" ,
"primaryName": "IMMOFINANZ AG",
"countryCode": 869
},
 The details of the top most entity in the family tree, tracing each parent up to its own parent.


Global Financials | © Dun & Bradstreet, Inc. | World Wide Networks . All Rights Reserved. | Need Help ? DNB WWN Full Logo