Find Competitors
| Product | D&B Direct 2.0, D&B Direct Onboard |
| Product Code(s) | Not Applicable |
| Option(s) | None |
| Monitoring Available | No |
| Interface | SOAP |
| WSDL | download |
| Format(s) | XML |
| Service | EntityList |
| Operation | FindCompetitor |
| {version} | 6.2 |
| 6.2 Released On | January 29, 2016 |
Returns all the competitors for a given company.
Update History
- January 29, 2016 (v6.2 SOAP & REST): The UnitofSize attribute is added to SalesRevenueAmount for Find Competitor.
Feature Request
IMPORTANT: Please see the new Online Services Security Enhancement Release, effective November 09, 2020.
Overview
When requesting this feature, a valid D-U-N-S Number for a company will be required. An option exists to request only the top competitors.
A top competitor designation is assigned by D&B based on analysis of the company and industry in which it operates. Public companies frequently identify top competitors in their public filings, which is also taken into consideration.
Pagination: This feature does not offer any pagination options, and will return an unlimited number of results (typically fewer than one hundred).
Data Layer Entitlement
For customers in U.S. and Canadian markets, the API is provisioned for specific collections of products, reports, and/or features (collectively referred to as data layers) for production and trial usage. Entitlement is not required for testing in the sandbox environment.
- This feature is entitled as "Search/Lookup for Companies" for D&B Direct 2.0 customers.
For customers in the UK, Ireland, Belgium, Netherlands and Luxembourg markets, the API is provisioned as a specific set of data layers for production, trial, and sandbox usage.
- This particular data layer is included in the D&B Direct Onboard 2.0 suite.
Specification
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ent="http://services.dnb.com/EntityListServiceV2.0">
<soapenv:Header>
<wsse:Security soapenv:mustUnderstand="0" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsse:UsernameToken wsu:Id="UsernameToken-11">
<wsse:Username>MyUserName</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">MyPassword</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
<ent:FindCompetitorRequest>
<FindCompetitorRequestDetail>
<InquiryDetail>
<DUNSNumber>804735132</DUNSNumber>
</InquiryDetail>
</FindCompetitorRequestDetail>
</ent:FindCompetitorRequest>
</soapenv:Body>
</soapenv:Envelope>
| Name | Characteristics |
|---|---|
| FindCompetitorRequest | Aggregate |
| FindCompetitorRequest. FindCompetitorRequestDetail | Aggregate, Required Records the search criteria provided by the Customer/User to find the list of business competitors for the subject organization. |
| FindCompetitorRequest. FindCompetitorRequestDetail. InquiryDetail | Aggregate, Required Records data that allows the customer to specify identifying information about the subject being inquired, e.g., the DUNS Number. |
| FindCompetitorRequest. FindCompetitorRequestDetail. InquiryDetail. DUNSNumber | string up to 15 chars. Pattern: {([0-9a-zA-Z]*)}., Required The D-U-N-S Number is D&B's identification number, which provides unique identification of this organization, in accordance with the Data Universal Numbering System (D-U-N-S). |
| END: FindCompetitorRequest. FindCompetitorRequestDetail. InquiryDetail | /Aggregate |
| FindCompetitorRequest. FindCompetitorRequestDetail. FindCompetitorSpecification | Aggregate, Optional Records the parameters for refining the search result. |
| FindCompetitorRequest. FindCompetitorRequestDetail. FindCompetitorSpecification. ReturnOnlyTopCompetitorIndicator | boolean, Optional When true (set to 1), only the organizations classified as a top competitor for the subject organization have to be listed in the search response. When false (set to 0), all the organizations identified as a competitor for the subject organization have to be listed in the search response. |
| END: FindCompetitorRequest. FindCompetitorRequestDetail. FindCompetitorSpecification | /Aggregate |
| END: FindCompetitorRequest. FindCompetitorRequestDetail | /Aggregate |
| END: FindCompetitorRequest | /Aggregate |
Endpoint
Use the following endpoint with the downloadable WSDL to request this feature.
| SOAP (EntityList) |
|---|
| https://direct.dnb.com/EntityList/V{version} |
Testing
This operation will return a static set of results in the D&B Direct test environment (sandbox), regardless of the request parameters.
Feature Response
Specification
The following is a list of the possible data fields returned by this operation in the XML response. Samples are provided for testing successful and failed retrieval, and to demonstrate the basic layout of a response. The data returned in samples may not represent actual values that this feature will deliver.
NOTE: The D-U-N-S Number returned in the response will be a nine-digit zero-padded, numeric value.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body xmlns:ent="http://services.dnb.com/EntityListServiceV2.0">
<ent:FindCompetitorResponse ServiceVersionNumber="6.0">
<TransactionDetail>
<ServiceTransactionID>Id-3f7f3f1552729f5002db742e-1</ServiceTransactionID>
<TransactionTimestamp>2013-10-31T14:20:00</TransactionTimestamp>
</TransactionDetail>
<TransactionResult>
<SeverityText>Information</SeverityText>
<ResultID>CM000</ResultID>
<ResultText>Success</ResultText>
</TransactionResult>
<FindCompetitorResponseDetail>
<Competitor>
<DUNSNumber>985015354</DUNSNumber>
<OrganizationPrimaryName>
<OrganizationName>Accenture plc</OrganizationName>
</OrganizationPrimaryName>
<PrimaryAddress>
<PrimaryTownName>Dublin</PrimaryTownName>
<CountryISOAlpha2Code>IE</CountryISOAlpha2Code>
<CountryOfficialName>Ireland</CountryOfficialName>
</PrimaryAddress>
<GlobalUltimateDUNSNumber>985015354</GlobalUltimateDUNSNumber>
<ParentDUNSNumber>985015354</ParentDUNSNumber>
<SalesRevenueAmount>30394.285</SalesRevenueAmount>
<TopCompetitorIndicator>true</TopCompetitorIndicator>
</Competitor>
<InquiryReferenceDetail>
<CustomerReferenceText>Order placed by Joe</CustomerReferenceText>
<CustomerBillingEndorsementText>Order placed by Joe</CustomerBillingEndorsementText>
</InquiryReferenceDetail>
</FindCompetitorResponseDetail>
</ent:FindCompetitorResponse>
</soapenv:Body>
</soapenv:Envelope>
NOTE: There may be additional request and/or response elements specified in the WSDL that are not applicable for D&B Direct customers. Data elements that are not listed on this page are currently unused by this operation.
Response Codes & Error Handling
Successful service requests will return a CM000 response code in the TransactionResult ResultID field. Otherwise, one of the D&B Direct standard response codes will be returned.
This operation may return the following response codes: CM002, CM004, CM005, CM012, CM017, and SC001-SC009.
D&B Direct 2.0 API requests are provided on a metered basis; and may require entitlement prior to use in the production environment. In addition, a concurrency limit (QPS) is monitored to ensure that it is not exceeded. An error code will be returned in the event that a transaction is throttled.
Qualified usage (e.g., a successful response) is tracked and billed according to the terms & conditions of the customer's contract. The response codes CM000, CM010, PD002 and PD015 are considered successful. A built-in feature exists to prevent duplicate billing when multiple successful requests with the same criteria are submitted on the same calendar day (which is based on Eastern Standard Time [GMT-5]).
Business Elements
While D&B Direct uses a product canonical naming model in the request/response, many customers may be more familiar with the following business element labels.
| Name | Description |
|---|---|
| Competitor Organization Business Name | Primary Company Name of the competitor PCM XPath: //Competitor/ OrganizationPrimaryName/ OrganizationName |
| Competitor Organization Country Code | Country Code of the competitor PCM XPath: //Competitor/ PrimaryAddress/ CountryISOAlpha2Code |
| Competitor Organization Country Name | Country Name of the competitor PCM XPath: //Competitor/ PrimaryAddress/ CountryOfficialName |
| Competitor Organization D-U-N-S number | DUNS Number of the competitor PCM XPath: //Competitor/ DUNSNumber |
| Competitor Organization Global Ultimate DUNS Number | global ultimate Organization DUNS Number of the Competitor PCM XPath: //Competitor/ GlobalUltimateDUNSNumber |
| Competitor Organization Parent D-U-N-S Number | parent Organization DUNS Number of the Competitor PCM XPath: //Competitor/ ParentDUNSNumber |
| Competitor Organization Sales Revenue | The sales number in millions (USD) for this competitor PCM XPath: //Competitor/ SalesRevenueAmount |
| Competitor Organization Territory Abbreviated Name | Territory Name of the Competitor PCM XPath: //Competitor/ PrimaryAddress/ TerritoryAbbreviatedName |
| Competitor Organization Town Name | City name of the competitor PCM XPath: //Competitor/ PrimaryAddress/ PrimaryTownName |
| Top Competitor Organization Indicator | Indicates if the competitor is a top competitor or not PCM XPath: //Competitor/ TopCompetitorIndicator |
The preceding list is not presented in the order, nor manner, in which the information is packaged and delivered via the D&B Direct API. Legend: [C] = may be included in a Custom Data product; [M] = may be referenced by the Monitoring process; [M+] = Monitored using an aggregate or attribute XPath.
Feature Notes
For each competitor, this feature will return the D-U-N-S Number, organization name, city, state, country, sales revenue, parent and global ultimate D-U-N-S Numbers, and the top competitor indicator.
- © Dun & Bradstreet, Inc. 2019 – 2024. All rights reserved.