Place Investigation (POST)
Products | D&B Direct 2.0, D&B Direct for Onboard |
Product Code(s) | Not Applicable |
Options(s) | D-U-N-S Number, Company Name |
Monitoring Available | No |
Interface | REST |
Method(s) | GET & POST |
Format(s) | JSON |
Service | Investigation |
{version} | 2.1 |
Initial Release | October 3, 2013 |
D&B Direct provides a service for requesting investigations in order to obtain the most recent information on a business. Successful investigations result in the creation (for companies not in the D&B database) or revision (for existing companies) of a D&B Business Information Report (BIR).
Update History
- Jaunary 28, 2022 (v2.1 SOAP & REST): Defect fix to enable Urgent Priority code for investigations place on Spain, Andorra and Portugal markets.
Feature Request
IMPORTANT: Please see the new Online Services Security Enhancement Release, effective November 09, 2020.
Overview
An investigation is appropriate under the following conditions: when the In Date status for a data or report product is Investigation Recommended or Out of Date; when a company search fails to return a suitable match; or when the most up-to-date information is required.
Investigations may be initiated either by providing the D-U-N-S Number of an organization or by providing its name and address. If both a D-U-N-S Number and name/address are submitted, an investigation will be performed based on the D-U-N-S Number
Optional telephone number and organization identification number (e.g. FEIN) parameters are available to provide additional information; however, these fields are not sufficient to initiate an investigation by themselves.
An option exists to request a "priority" investigation, which will typically be completed in less time than a regular investigation. Investigations requested using the priority setting will incur an additional charge, and are dependent on the accessibility of information for the organization being requested (which may be impacted by the responsiveness of the organization).
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 "Investigations" 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
The details in this section override the Optional/Required values listed in the specification table.
1. When submitting a request by D-U-N-S Number, a valid D-U-N-S Number is Required.
2. When submitting a request by Organization Name and Address, an Organization Name (or partial name) and a valid Country Code are Required.
Any additional details that are available should be included to assist the D&B Analyst.
Restriction: The sequence of Request Parameters submitted to POST/PUT operations currently MUST follow the order presented in this section. This applies to REST calls only.
POST http://direct.dnb.com/V2.1/organizations/081466849?investigate=true Accept-Encoding: gzip,deflate Content-Type: application/json Authorization: <MyToken> {"PlaceInvestigationRequest": { "TransactionDetail": {"ApplicationTransactionID": "ID_001"}, "PlaceInvestigationRequestDetail": { "InquiryDetail": { "DUNSNumber": "804735132", "Address": {"CountryISOAlpha2Code": "US"} }, "InvestigationSpecification": {"DNBProductID": "BIR"}, "RequestorDetail": { "RequestorName": "John", "EmailAddress": {"TelecommunicationAddress": "john@mycompany.com"} }, "DeliveryDetail": { "DeliveryMethodCode": "7795", "EmailAddress": [ {"TelecommunicationAddress": "john@mycompany.com"}, {"TelecommunicationAddress": "mike@mycompany.com"} ] }, "NotificationDetail": { "NotificationMethodCode": "7795", "EmailAddress": [ {"TelecommunicationAddress": "john@mycompany.com"} ] } } }}
POST https://direct.dnb.com/V2.1/organizations/name-Gorman?investigate=true HTTP/1.1 Accept-Encoding: gzip,deflate Content-Type: application/json Authorization: +YQplvYNTv86mFhkTXy4008aFnQBJAqq7EGM6KCrPIKLLM6RxaVuYxtftvcsMIAJdO17prwXvx0wa5xR/hvzE/UHUOtNLsz/RB80ZhUBuXYyK0eL48iMKBAxE1+2UYFmvhJOqRIRtDrn8OPf6xQGKlRnO5+c5A4r0FBa3XMU8Yw/OTDCO01zCQmgu9jQqH5Pj2ZxoESCAi1OgzInnxtBy5uavI2WM0NnFKV1Wfys2PUkmda8cCKgB7J1/WdW+CZ6xZwnjDZUspA3MzTqbOMn6ZxuSdwab1nX1Wu6iDPMYWchYhblRbIDmwHZ15nRZL0DORi76O+RC0hU+E+DF60zYQ== Content-Length: 1024 Host: direct.dnb.com Connection: Keep-Alive User-Agent: Apache-HttpClient/4.1.1 (java 1.5) {"PlaceInvestigationRequest": { "TransactionDetail": {"ApplicationTransactionID": "ID_001"}, "PlaceInvestigationRequestDetail": { "InquiryDetail": { "OrganizationName": "Gorman", "Address": { "StreetAddressLine":[ {"LineText":"492 KOLLER STREET"} ], "PrimaryTownName":"San Francisco", "CountryISOAlpha2Code": "US", "TerritoryName":"CA" } }, "InvestigationSpecification": {"DNBProductID": "BIR"}, "RequestorDetail": { "RequestorName": "John", "EmailAddress": {"TelecommunicationAddress": "john@mycompany.com"} }, "DeliveryDetail": { "DeliveryMethodCode": "7795", "EmailAddress": [ {"TelecommunicationAddress": "john@mycompany.com"}, {"TelecommunicationAddress": "mike@mycompany.com"} ] }, "NotificationDetail": { "NotificationMethodCode": "7795", "EmailAddress": [ {"TelecommunicationAddress": "john@mycompany.com"} ] } } }}
This operation is also available as a GET call.
Name | Characteristics |
---|---|
PlaceInvestigationRequest | Aggregate |
PlaceInvestigationRequest@ServiceVersionNumber | Attribute |
PlaceInvestigationRequest { TransactionDetail | Aggregate |
PlaceInvestigationRequest { TransactionDetail { ApplicationTransactionID | string up to 64 chars., Optional A number assigned by the calling application to uniquely identify this request. |
PlaceInvestigationRequest { TransactionDetail { TransactionTimestamp | DateTimestamp, Optional The date and time when this request was created. When the request is from an intermediary, such as a workflow manager or service bus, this is the date and time when the message was sent to the D&B function, i.e., the date and time when the xml document was created by the requesting intermediary. |
PlaceInvestigationRequest { TransactionDetail { SubmittingOfficeID | string up to 64 chars., Optional A number that identifies the system or the software application from where this request originated. / A number used to uniquely identfy the D&B business segment or delivery channel from where this request originated. |
END: PlaceInvestigationRequest } TransactionDetail | /Aggregate |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail | Aggregate, Required Records data provided by the Customer/User required to request D&B to research and obtain information on a subject when searching for the subject yielded no results or the Customer/User would like to have more current information on the subject. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InquiryDetail | Aggregate, Required Records data that allows the customer to specify identifying information about the subject being inquired, e.g., the DUNS Number, the address, the telephone number. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { 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). |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InquiryDetail { OrganizationName | string up to 240 chars., Optional Records the name of the inquired organization. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InquiryDetail { Address | Aggregate, Required Records the location information of the requested subject. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InquiryDetail { Address { StreetAddressLine | Aggregate, Optional(Up to 10x) An entry loop which can repeat multiple times to allow the recording of several lines where each address line contains one or more named address elements. Examples of named address elements are Street Name, Street Number, Building Name, Estate Name. They are called “lines” because an addres can be divided into multiple lines. When there are multiple lines the sequence of the lines must be preserved. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InquiryDetail { Address { StreetAddressLine { LineText | string up to 240 chars., Required Text that records the street address components as it would be presented on an address label. This includes, but is not limited to, details such as street name, street number, building name, estate name. |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail } InquiryDetail } Address } StreetAddressLine | /Aggregate |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InquiryDetail { Address { PrimaryTownName | string up to 64 chars., Required (US), Optional (other countries) The name of the town or city recognized by the Postal Authority for delivering mail. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InquiryDetail { Address { CountryISOAlpha2Code | string at least 2 chars. up to 2 chars., Required The two-letter country code, defined in the ISO 3166-1 scheme published by International Organization for Standardization (ISO), identifying the country for this address. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InquiryDetail { Address { TerritoryName | string up to 64 chars., Required (US & CA), Optional (other countries) The name of a locally governed area which forms part of a centrally governed nation. As a guiding principle this is a geographic area which could theoretically exist as a separate nation. In the U.S. this would be a State in the UK this would be one of the Home Nations. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InquiryDetail { Address { FullPostalCode | string up to 32 chars., Optional An identifier used by the local country Postal Authority to identify a particular geographic location and may include the identification of a street or building. When this data has been derived by concatenating the elements Postal Code and Postal Code Extension, a separator will be inserted between these two elements based on country rules. For example, when the address is a U.S. address, the separator that will be used is a hyphen '-'. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InquiryDetail { Address { CountyName | string up to 64 chars., Optional The name of a primary administrative division within a Territory or Country. As a guiding principle this is a geographic area which would be classified as a Province (except Canada) or a County. In the U.S. this would be a county within a State. In the UK this would be a county in one of the Home Nations. In Republic Of Ireland, this would be a county and there would be no Territory. |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail } InquiryDetail } Address | /Aggregate |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InquiryDetail { TelephoneNumber | Aggregate, Optional Records Telephone contact information used for voice communication with the inquired subject. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InquiryDetail { TelephoneNumber { TelecommunicationNumber | string at least 1 chars. up to 50 chars., Required A sequence of digits used by the subject for voice communication in a public switched telephone network. This sequence of digits includes the area code or city code. Note: This number does not include the International Dialing Code and Domestic Dialing Code. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InquiryDetail { TelephoneNumber { InternationalDialingCode | string up to 7 chars., Optional The country calling code assigned by the International Telecommunication Union (ITU) required to connect to this Telecommunication Number of the subject country when dialing from outside the subject country; e.g., '1' for the US, '44' for the UK, '91' for India. |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail } InquiryDetail } TelephoneNumber | /Aggregate |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InquiryDetail { OrganizationIdentificationNumberDetail | Aggregate, Optional An entry loop which can repeat multiple times to allow the recording of several different identifiers issued by organizations to uniquely identify subjects. The issuing organization may be a Registration Authority, Government Department or Commercial Enterprise, e.g., Chamber of Commerce numbers, VAT numbers, etc. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InquiryDetail { OrganizationIdentificationNumberDetail { OrganizationIdentificationNumber | string at least 1 chars. up to 40 chars., Required A number issued by an external official registry body, a government entity or a commercial enterprise to uniquely identify an organization. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InquiryDetail { OrganizationIdentificationNumberDetail { OrganizationIdentificationNumberTypeCode | integer up to 7 digits., Required A D&B code value which denotes the type of Organization Identification Number, e.g., Chamber of Commerce Number, Value Added Tax Number, Federal Taxpayer Identification Number, Companies Registry Office Number. |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail } InquiryDetail } OrganizationIdentificationNumberDetail | /Aggregate |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail } InquiryDetail | /Aggregate |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InvestigationSpecification | Aggregate, Required Records data that allows the customer to specify the details of the requested product. This may include details such as the identifier of the product, the language in which the product needs to be rendered, the format in which the product needs to be rendered. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InvestigationSpecification { DNBProductID | string up to 64 chars., Required An alphanumeric string that uniquely identifies the product being requested. Possible values: BIR |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InvestigationSpecification { LanguagePreferenceCode | integer up to 7 digits., Optional A D&B code value that defines the language in which the customer wants this product to be rendered. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InvestigationSpecification { CharacterSetPreferenceCode | integer up to 7 digits., Optional A D&B code value denoting the set of graphic symbols (e.g., alphabet letter, pictograph) in which the product is to be rendered, e.g., Unicode. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InvestigationSpecification { ProductFormatPreferenceCode | integer up to 7 digits., Optional A D&B code value that describes the defined structure in which the product is to be rendered, e.g., txt, xml, pdf. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InvestigationSpecification { OrderReasonCode | integer up to 7 digits., Optional A D&B code value that defines the grounds for the customer requesting the product, e.g., required to support a credit decision. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InvestigationSpecification { InvestigationPriorityCode | integer up to 7 digits., Optional A D&B code value representing the urgency of the investigation, e.g., Regular 3 Days, Priority 1 Way - 2 Days. PDQ 2 Way - 1 Day. Possible values: 6344 - Priority; 6347 - Routine |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InvestigationSpecification { InvestigationRemarksText | string up to 3000 chars., Optional Free form text for the customer to enter any special remarks for this investigation request. NOTE: For the US and CA, up to 3000 characters are supported. For GB, IE, IT, SM, BE, LU, NL, DE, PT, ES, AD, AT, CH, LI, HU, PL, CZ, SK, DK, FI, NO, SE, GL, FO, FR, MC, MQ, RE, GP, GF, 255 characters are supported. For the remaining countries, up to 280 characters are supported. Refer to the ISO Country Codes list. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InvestigationSpecification { InvestigationSubjectContact | Aggregate, Optional Records details about the individual associated with the subject organization that the user or purchaser of D&B data has as a contact at this subject organization. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InvestigationSpecification { InvestigationSubjectContact { ContactName | Aggregate, Optional Records the name of the individual associated with the subject organization that the user or purchaser of D&B data has as a contact. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InvestigationSpecification { InvestigationSubjectContact { ContactName { FirstName | string up to 64 chars., Optional The given name of the individual. If this is not known then an initial may be supplied. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InvestigationSpecification { InvestigationSubjectContact { ContactName { LastName | string up to 64 chars., Optional The portion of the individual's name usually presented at the end used to identify the members of a family. |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail } InvestigationSpecification } InvestigationSubjectContact } ContactName | /Aggregate |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InvestigationSpecification { InvestigationSubjectContact { TelephoneNumber | Aggregate, Optional Records the Telephone information of the individual associated with the subject organization that the user or purchaser of D&B data has as a contact. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InvestigationSpecification { InvestigationSubjectContact { TelephoneNumber { TelecommunicationNumber | string at least 1 chars. up to 50 chars., Required A sequence of digits used by the subject for voice communication in a public switched telephone network. This sequence of digits includes the area code or city code. Note: This number does not include the International Dialing Code and Domestic Dialing Code. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InvestigationSpecification { InvestigationSubjectContact { TelephoneNumber { InternationalDialingCode | string up to 7 chars., Optional The country calling code assigned by the International Telecommunication Union (ITU) required to connect to this Telecommunication Number of the subject country when dialing from outside the subject country; e.g., '1' for the US, '44' for the UK, '91' for India. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InvestigationSpecification { InvestigationSubjectContact { TelephoneNumber { DomesticDialingCode | string at least 1 chars. up to 16 chars., Optional The code used within a country or region which identifies the telephone exchange to which the Telecommmunication Number is connected. This is a standard dialing code and is unique to a Telephone exchange within a country; e.g., '1' for the US, '0' for the UK, '0' for India. This code should be used when dialing from the same country as the subject |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InvestigationSpecification { InvestigationSubjectContact { TelephoneNumber { MobileIndicator | boolean, Optional When the Mobile Indicator is turned ON (set to 1), it indicates that this telecom number is for a mobile (e.g., cellular) unit. When the Mobile Indicator is turned OFF (set to 0), it indicates that this is for a land line telecom number; however as this is the default condition there is no requirement to create this tag to represent this fact. |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail } InvestigationSpecification } InvestigationSubjectContact } TelephoneNumber | /Aggregate |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail } InvestigationSpecification } InvestigationSubjectContact | /Aggregate |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail } InvestigationSpecification | /Aggregate |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { RequestorDetail | Aggregate, Optional Records details regarding the placeer, who place the invstigation request such as his name and address. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { RequestorDetail { RequestorName | string up to 64 chars., Optional Text recording the name of the Customer/User who has placed this request. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { RequestorDetail { Address | Aggregate, Optional Records details about the designation of a place where the Customer/User who has placed this request can be located or may be communicated with. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { RequestorDetail { Address { StreetAddressLine | Aggregate, Optional(Up to 10x) An entry loop which can repeat multiple times to allow the recording of several lines where each address line contains one or more named address elements. Examples of named address elements are Street Name, Street Number, Building Name, Estate Name. They are called “lines” because an addres can be divided into multiple lines. When there are multiple lines the sequence of the lines must be preserved. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { RequestorDetail { Address { StreetAddressLine { LineText | string up to 240 chars., Required Text that records the street address components as it would be presented on an address label. This includes, but is not limited to, details such as street name, street number, building name, estate name. |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail } RequestorDetail } Address } StreetAddressLine | /Aggregate |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { RequestorDetail { Address { PrimaryTownName | string up to 64 chars., Optional The name of the town or city recognized by the Postal Authority for delivering mail. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { RequestorDetail { Address { CountryISOAlpha2Code | string at least 2 chars. up to 2 chars., Required The two-letter country code, defined in the ISO 3166-1 scheme published by International Organization for Standardization (ISO), identifying the country for this address. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { RequestorDetail { Address { TerritoryName | string up to 64 chars., Optional The name of a locally governed area which forms part of a centrally governed nation. As a guiding principle this is a geographic area which could theoretically exist as a separate nation. In the U.S. this would be a State in the UK this would be one of the Home Nations. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { RequestorDetail { Address { FullPostalCode | string up to 32 chars., Optional An identifier used by the local country Postal Authority to identify a particular geographic location and may include the identification of a street or building. When this data has been derived by concatenating the elements Postal Code and Postal Code Extension, a separator will be inserted between these two elements based on country rules. For example, when the address is a U.S. address, the separator that will be used is a hyphen '-'. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { RequestorDetail { Address { CountyName | string up to 64 chars., Optional The name of a primary administrative division within a Territory or Country. As a guiding principle this is a geographic area which would be classified as a Province (except Canada) or a County. In the U.S. this would be a county within a State. In the UK this would be a county in one of the Home Nations. In Republic Of Ireland, this would be a county and there would be no Territory. |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail } RequestorDetail } Address | /Aggregate |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { RequestorDetail { TelephoneNumber | Aggregate, Optional Records Telephone contact information used for voice communication with the Customer/User who has placed this request. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { RequestorDetail { TelephoneNumber { TelecommunicationNumber | string at least 1 chars. up to 50 chars., Required A sequence of digits used by the subject for voice communication in a public switched telephone network. This sequence of digits includes the area code or city code. Note: This number does not include the International Dialing Code and Domestic Dialing Code. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { RequestorDetail { TelephoneNumber { InternationalDialingCode | string up to 7 chars., Optional The country calling code assigned by the International Telecommunication Union (ITU) required to connect to this Telecommunication Number of the subject country when dialing from outside the subject country; e.g., '1' for the US, '44' for the UK, '91' for India. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { RequestorDetail { TelephoneNumber { DomesticDialingCode | string at least 1 chars. up to 16 chars., Optional The code used within a country or region which identifies the telephone exchange to which the Telecommmunication Number is connected. This is a standard dialing code and is unique to a Telephone exchange within a country; e.g., '1' for the US, '0' for the UK, '0' for India. This code should be used when dialing from the same country as the subject |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { RequestorDetail { TelephoneNumber { MobileIndicator | boolean, Optional When the Mobile Indicator is turned ON (set to 1), it indicates that this telecom number is for a mobile (e.g., cellular) unit. When the Mobile Indicator is turned OFF (set to 0), it indicates that this is for a land line telecom number; however as this is the default condition there is no requirement to create this tag to represent this fact. |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail } RequestorDetail } TelephoneNumber | /Aggregate |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { RequestorDetail { EmailAddress | Aggregate, Optional Records the electronic mail addresses used for electronic messaging communication with the Customer/User who has placed this request. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { RequestorDetail { EmailAddress { TelecommunicationAddress | string up to 240 chars., Required Text recording the electronic mail address used by a subject by which the subject can transmit and or receive text messages, links, and files electronically, typically via a network, like the Internet. |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail } RequestorDetail } EmailAddress | /Aggregate |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail } RequestorDetail | /Aggregate |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { DeliveryDetail | Aggregate, Optional Records the details about the mechanism by which the requested product or service is to be delivered. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { DeliveryDetail { DeliveryMethodCode | integer up to 7 digits., Required A D&B code value denoting the type of medium being supplied for sending the product(s)/service(s). Possible values: 7795 - Email NOTE: For Other Possible values: 6320 - ONLINE & 6318- Mail, customers need to check for the investigation status using list portfolio asset & retrieve report once fulfilled. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { DeliveryDetail { EmailAddress | Aggregate, Optional(Up to 5x) An entry loop which can repeat multiple times to allow the recording of the email addresses provided by the Customer/User to which the product(s)/service(s) have to be delivered. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { DeliveryDetail { EmailAddress { TelecommunicationAddress | string up to 240 chars., Required Text recording the electronic mail address used by a subject by which the subject can transmit and or receive text messages, links, and files electronically, typically via a network, like the Internet. |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail } DeliveryDetail } EmailAddress | /Aggregate |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail } DeliveryDetail | /Aggregate |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { NotificationDetail | Aggregate, Optional Records the details about the mechanism by which any notification is to be delivered when this investigation request is fulfilled. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { NotificationDetail { NotificationMethodCode | integer up to 7 digits., Required A D&B code value denoting the type of medium by which the Customer/User should be notified. Possible values: 7795 - Email |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { NotificationDetail { EmailAddress | Aggregate, Optional(Up to 5x) An entry loop which can repeat multiple times to allow the recording of the email addresses provided by the Customer/User to which the notification should be delivered. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { NotificationDetail { EmailAddress { TelecommunicationAddress | string up to 240 chars., Required Text recording the electronic mail address used by a subject by which the subject can transmit and or receive text messages, links, and files electronically, typically via a network, like the Internet. |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail } NotificationDetail } EmailAddress | /Aggregate |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail } NotificationDetail | /Aggregate |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { ArchiveDetail | Aggregate, Optional Records data that allows the customer to specify details about the archival of the product being requested. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { ArchiveDetail { ArchiveProductOptOutIndicator | boolean, Optional When true (set to 1), it indicates that the product being ordered is not to be stored. When false (set to 0), it indicates that the product being ordered is to be stored; however as this is the assumed condition there is no requirement to create this tag to represent this fact. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { ArchiveDetail { ExtendArchivePeriodIndicator | boolean, Optional When true (set to 1), the duration to archive the data is to be extended. Note: There is an additional cost for extending the archival period of the data purchased. When false (set to 0), the duration to archive the data is not to be extended. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { ArchiveDetail { PortfolioAssetContainerID | long, Optional |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail } ArchiveDetail | /Aggregate |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InquiryReferenceDetail | Aggregate, Optional Records data that allows the customer to specify information to be linked to the request in order to support subsequent order reconciliation. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InquiryReferenceDetail { CustomerReferenceText | string up to 240 chars., Optional(Up to 5x) A freeform reference string provided by the customer to be linked to the product in order to support subsequent order reconciliation. NOTE: Due to known limitation, only up to 100 characters are supported. Same will be increased up to 240 (Up to 5x) chars in future. |
PlaceInvestigationRequest { PlaceInvestigationRequestDetail { InquiryReferenceDetail { CustomerBillingEndorsementText | string at least 1 chars. up to 64 chars., Optional Text that is filled in by customer and commonly contains requesting individual or department name, or customer's own account/reference number and/or name for the case on which the product was provided.This text is a reference used during the billing process. NOTE: Due to known limitation, only up to 100 characters are supported. Same will be increased up to 240 chars in future. |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail } InquiryReferenceDetail | /Aggregate |
END: PlaceInvestigationRequest } PlaceInvestigationRequestDetail | /Aggregate |
END: PlaceInvestigationRequest | /Aggregate |
Endpoint
Use the following endpoint for requesting this feature. The {version} is dependent on the underlying service delivering the response.
Endpoint (Investigation) |
---|
GET|POST https://direct.dnb.com/V{version}/organizations/{DUNS}?investigate=true |
GET|POST https://direct.dnb.com/V{version}/organizations/name-{name}?investigate=true |
Testing
This operation is currently unavailable in the D&B Direct sandbox (test) environment.
Feature Response
NOTE: The D&B Direct REST implementation uses the BadgerFish approach for JSON with some minor variations.
Specification
The following is a list of the possible data fields returned by this operation in the JSON 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.
{"PlaceInvestigationResponse": { "@ServiceVersionNumber": "2.0", "TransactionDetail": { "ApplicationTransactionID": null, "ServiceTransactionID": "Id-5e83d5fd5256cced0bab742e-2", "TransactionTimestamp": "2013-10-10T11:51:11.738-04:00" }, "TransactionResult": { "SeverityText": "Information", "ResultID": "CM000", "ResultText": "Success" }, "PlaceInvestigationResponseDetail": { "InquiryDetail": { "DUNSNumber": "081466849", "OrganizationName": "MICROSOFT CORPORATION", "Address": { "StreetAddressLine": [{"LineText": null}], "PrimaryTownName": null, "CountryISOAlpha2Code": "US", "TerritoryName": null, "FullPostalCode": null } }, "InvestigationTrackingID": "M24578512171A1003058QH0", "ArchiveDetail": {"PortfolioAssetID": 4595541}, "InquiryReferenceDetail": { "CustomerReferenceText": ["Sandbox testing for name and address investigation"], "CustomerBillingEndorsementText": "Sandbox testing for name and address investigation" } } }}
{"PlaceInvestigationResponse": { "@ServiceVersionNumber": "2.1", "TransactionDetail": { "ApplicationTransactionID": null, "ServiceTransactionID": "Id-9e17a3065256ee2b162b742e-1", "TransactionTimestamp": "2013-10-10T14:13:02.212-04:00" }, "TransactionResult": { "SeverityText": "Information", "ResultID": "CM000", "ResultText": "Success" }, "PlaceInvestigationResponseDetail": { "InquiryDetail": { "DUNSNumber": null, "OrganizationName": "GORMAN", "Address": { "StreetAddressLine": [{"LineText": "492 KOLLER STREET"}], "PrimaryTownName": "San Francisco", "CountryISOAlpha2Code": "US", "TerritoryName": "CA", "FullPostalCode": null } }, "InvestigationTrackingID": "M24578512171A1003058S1L", "ArchiveDetail": {"PortfolioAssetID": 4595872}, "InquiryReferenceDetail": { "CustomerReferenceText": ["Sandbox testing for name and address investigation"], "CustomerBillingEndorsementText": "Sandbox testing for name and address investigation" } } }}
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: CM001, CM002, CM003, CM004, CM005, CM006, CM008, CM009, CM011, CM012, CM014, CP001, 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]).
Expected Response Times
A D&B Fulfillment Specialist will perform research on the organization and collect up-to-date information. The following table provides the expected number of days that a regular investigation will be completed for each country.
Country | Expected Days | Customer Service Center |
---|---|---|
Abu Dhabi - UAE | 6 | D&B SAME |
Admiralty Islands | 10 | Australia (Corre. Office) |
Afghanistan | 6 | D&B North Africa |
Ajman - UAE | 6 | D&B SAME |
Alain | 6 | D&B SAME |
Albania | 4 | Emerging Markets Center |
Algeria | 6 | D&B North Africa |
Andorra | 3 | Spain D&B |
Angola | 6 | D&B North Africa |
Anguilla | 10 | LABIC |
Antarctica | --- | Not reported on by D&B |
Antigua & Barbuda | 10 | LABIC |
Argentina | 7 | Argentina D&B |
Armenia | 4 | Emerging Markets Center |
Aruba | 10 | LABIC |
Ascension Islands | 6 | D&B North Africa |
Australia | 5 | Australia D&B |
Austria | 3 | Austria D&B |
Azerbaijan | 4 | Emerging Markets Center |
Azores | 7 | Portugal (Corre. Office) |
Bahamas | 10 | LABIC |
Bahrain | 6 | D&B SAME |
Bangladesh | 6 | D&B SAME |
Barbados | 10 | LABIC |
Belgium | 3 | Belgium D&B |
Belize | 10 | LABIC |
Belorussia | 4 | Emerging Markets Center |
Benin | 6 | D&B North Africa |
Bermuda | 10 | LABIC |
Bhutan | 6 | D&B SAME |
Bolivia | 10 | LABIC |
Bosnia Herzegovina | 4 | Emerging Markets Center |
Botswana | 5 | TU ITC |
Bouvet Island | --- | Not Reported on by D&B |
Brazil | 7 | Brazil D&B |
British Indian Ocean Territory | --- | Not Reported on by D&B |
Brunei | 10 | Singapore (Corre. Office) |
Bulgaria | 4 | Emerging Markets Center |
Burkina Faso | 6 | D&B North Africa |
Burma | 10 | Singapore (Corre. Office) |
Burundi | 6 | D&B North Africa |
Cambodia | --- | Not Reported on by D&B |
Cameroon | 6 | D&B North Africa |
Canada | 7-10 | Canada D&B |
Cape Verde | 6 | D&B North Africa |
Caroline Islands | 10 | Australia (Corre. Office) |
Cayman Islands | 10 | LABIC |
Central African Republic | 6 | D&B North Africa |
Ceuta | 7 | Spain D&B |
Chad | 6 | D&B North Africa |
Chile | 10 | LABIC |
China | 10 | China D&B |
Christmas Islands | 10 | Australia (Corre. Office) |
Colombia | 10 | LABIC |
Cocos & Keeling Island | --- | Not Reported on by D&B |
Comoros | 6 | D&B North Africa |
Congo | 6 | D&B North Africa |
Cook Islands | 10 | Australia (Corre. Office) |
Costa Rica | 10 | LABIC |
Croatia | 4 | Emerging Markets Center |
Cuba | --- | Not Reported on by D&B |
Cyprus | 4 | Emerging Markets Center |
Czech | 3 | Czech D&B |
Denmark | 3 | Denmark D&B |
Djibouti | 6 | D&B North Africa |
Dominica | 10 | LABIC |
Dominican Republic | 10 | LABIC |
Dubai | 6 | D&B SAME |
East Timor | 10 | Singapore (Corre. Office) |
Ecuador | 10 | LABIC |
Egypt | 6 | D&B North Africa |
El Salvador | 10 | LABIC |
England | 3 | United Kingdom D&B |
Equatorial Guinea | 6 | D&B North Africa |
Eritrea | 6 | D&B North Africa |
Estonia | 4 | Emerging Markets Center |
Ethiopia | 6 | D&B North Africa |
Falkland Islands | 6 | D&B North Africa |
Faroe Islands | 7 | Denmark (Correspondent) |
Fiji | 10 | Australia (Corre. Office) |
Finland | 3 | Finland |
Former Yugoslav Republic | 4 | Emerging Markets Center |
France | 3 | France |
French West Indies | 7 | France (Correspondent) |
French Guyana | 7 | France (Correspondent) |
French Southern Territory | 7 | France (Correspondent) |
Friendly Isles | 10 | Australia (Corre. Office) |
Furjairah - UAE | 6 | D&B SAME |
Gabon | 6 | D&B North Africa |
Gambia | 6 | D&B North Africa |
Georgia | 4 | Emerging Markets Center |
Germany | 3 | Germany D&B |
Ghana | 10 | Emerging Markets Center |
Gibraltar | 4 | Emerging Markets Center |
Greece | 7 | Greece Alpha Mi |
Greenland | 7 | Denmark (Correspondent) |
Grenada | 10 | LABIC |
Guadaloupe | 7 | France (Correspondent) |
Guam | 10 | Australia (Corre. Office) |
Guatemala | 10 | LABIC |
Guinea | 6 | D&B North Africa |
Guinea Bissau | 6 | D&B North Africa |
Guyana | 10 | LABIC |
Haiti | 10 | LABIC |
Heard & McDonald | --- | Not Reported on by D&B |
Honduras | 10 | LABIC |
Hong Kong | 7 | Hong Kong D&B |
Hungary | 3 | Hungary D&B |
Iceland | 4 | Emerging Markets Center |
India (356) | 14 | D&B SAME |
Indonesia | 10 | Singapore (Corre. Office) |
Iran | 8 | D&B SAME |
Iraq | 6 | D&B SAME |
Ireland Republic of | 3 | Ireland D&B |
Israel | 5 | Israel D&B |
Italy | 3 | Italy D&B |
Ivory Coast | 6 | D&B North Africa |
Jamaica | 10 | LABIC |
Japan | 5 | Japan D&B |
Jordan | 6 | D&B SAME |
Kazakhstan | 4 | Emerging Markets Center |
Kenya | 6 | D&B North Africa |
Kirghizia | 4 | Emerging Markets Center |
Kiribati | 10 | Australia (Corre. Office) |
Korea, Democratic Peoples Republic (North) | --- | Not Reported on by D&B |
Korea,Republic of (South) | 10 | Korea D&B |
Kuwait | 6 | D&B SAME |
Laos | --- | Not Reported on by D&B |
Latvia | 4 | Emerging Markets Center |
Lebanon | 6 | D&B SAME |
Leichtenstein | 3 | Switzerland D&B |
Lesotho | 10 | TU ITC |
Liberia | --- | Not Reported on by D&B |
Libya | --- | Not Reported on by D&B |
Lithuania | 4 | Emerging Markets Center |
Luxembourg | 3 | Belgium D&B |
Macau | 10 | Hong Kong (Corre. Office) |
Madagascar | 6 | D&B North Africa |
Madeira | 7 | Portugal (Corre Office) |
Malawi | 6 | D&B North Africa |
Malaysia | 7 | Malaysia D&B |
Maldives | 6 | D&B SAME |
Mali | 6 | D&B North Africa |
Malta | 4 | Emerging Markets Center |
Marianas Islands | 10 | Australia (Corre. Office) |
Marshall Islands | 10 | Australia (Corre. Office) |
Martinique | 7 | France (Correspondent) |
Mauritania | 6 | D&B North Africa |
Mauritius | 6 | D&B North Africa |
Mexico | 7 | Mexico D&B |
Micronesia | 10 | Australia (Corre. Office) |
Midway Islands(SX) | 10 | Australia (Corre. Office) |
Moldova | 4 | Emerging Markets Center |
Monaco | 3 | France D&B |
Mongolia | --- | Not Reported on by D&B |
Montserrat | 10 | LABIC |
Morocco | 6 | D&B North Africa |
Mozambique | 6 | D&B North Africa |
N. Ireland | 3 | Northern Ireland D&B |
Namibia | 10 | TU ITC |
Nauru | 10 | Australia (Corre. Office) |
Nepal | 6 | D&B SAME |
Netherlands | 3 | Netherlands D&B |
Netherlands Antilles | 10 | LABIC |
New Caledonia | 7 | France (Correspondent) |
New Zealand | 5 | New Zealand D&B |
Nicaragua | 10 | LABIC |
Niger | 6 | D&B North Africa |
Nigeria | 6 | D&B North Africa |
Norfolk Island | 10 | Australia (Corre. Office) |
Northern Mariana Island | 10 | Australia (Corre. Office) |
Norway | 3 | Norway D&B |
Nuie Island | --- | Not Reported on by D&B |
Oman | 6 | D&B SAME |
Pakistan | 14 | D&B SAME |
Palau Island | 10 | Australia (Corre. Office) |
Palestine | 10 | Israel D&B |
Panama | 10 | LABIC |
Papua New Guinea | 10 | Australia (Corre. Office) |
Paraguay | 10 | Argentina (Corre. Office) |
Peru | 7 | Peru D&B |
Philippines | 10 | Singapore (Corre. Office) |
Pitcairn Island | 10 | Australia (Corre. Office) |
Poland | 3 | Poland D&B |
French Polynesia | 7 | France (Correspondent) |
Portugal | 3 | Portugal D&B |
Puerto Rico | 3 | United States D&B |
Principe Sao Tome | 10 | Emerging Markets Center |
Qatar | 6 | D&B SAME |
Ras Al Khaimah - UAE | 6 | D&B SAME |
Reunion Island | 7 | France (Correspondent) |
Romania | 4 | Emerging Markets Center |
Russian Federation | 4 | Russia D&B |
Rwanda | 6 | D&B North Africa |
Saint Helena | 10 | Emerging Markets Center |
Saint Kitts & Nevis | 10 | LABIC |
Saint Lucia | 10 | LABIC |
Saint Pierre & Miquelon | 7 | France (Correspondent) |
Saint Vincent | 10 | LABIC |
American Samoa | 10 | Australia (Corre. Office) |
Western Samoa | 10 | Australia (Corre. Office) |
San Marino | 3 | Italy D&B |
Saudi Arabia | 6 | D&B SAME |
Scotland | 3 | United Kingdom D&B |
Senegal | 6 | D&B North Africa |
Serbia & Montenegro | 4 | Emerging Markets Center |
Seychelles | 6 | D&B North Africa |
Sharjah - UAE | 6 | D&B SAME |
Sierra Leone | 6 | D&B North Africa |
Singapore | 7 | Singapore D&B |
Slovakia | 7 | Czech Republic D&B |
Slovenia | 4 | Emerging Markets Center |
Society Isles | 10 | Australia (Corre. Office) |
Solomon Islands | 10 | Australia (Corre. Office) |
Somalia | 6 | D&B North Africa |
South Africa | 5 | South Africa ITC |
Spain | 6 | Spain D&B |
Sri Lanka | 6 | D&B SAME |
Sudan | 10 | Emerging Markets Center |
Suriname | 10 | LABIC |
Svalbard & Jan Mayen | 3 | Norway D&B |
Swaziland | 10 | TU ITC |
Sweden | 3 | Sweden D&B |
Switzerland | 3 | Switzerland D&B |
Syria | 6 | D&B SAME |
Tahiti | 10 | Australia (Corre. Office) |
Taiwan | 7 | Taiwan D&B |
Tajikistan | 4 | Emerging Markets Center |
Tanzania | 6 | D&B North Africa |
Thailand | 10 | Singapore (Corre. Office) |
Togo | 6 | D&B North Africa |
Tokelau Islands | 10 | Australia (Corre. Office) |
Tonga | 10 | Australia (Corre. Office) |
Trinidad & Tobago | 10 | LABIC |
Trust Territory | 10 | Australia (Corre. Office) |
Tunisia | 6 | D&B North Africa |
Turkiye | 4 | Emerging Markets Center |
Turkish Rep. of Cyprus | 4 | Emerging Markets Center |
Turkmenistan | 4 | Emerging Markets Center |
Turks & Caicos | 10 | LABIC |
Tuvalu | 10 | Australia (Corre. Office) |
Uganda | 6 | D&B North Africa |
United Kingdom | 3 | United Kingdom D&B |
Ukraine | 7 | Emerging Markets Center |
Umm-Al-Quwain - UAE | 6 | D&B SAME |
Uruguay | 10 | Argentina (Corre. Office) |
United States of America | 5 - 7 | USA D&B |
US Minor Outlying Islands, Baker/Howland | 10 | Australia (Corre. Office) |
Uzbekistan | 4 | Emerging Markets Center |
Vanuatu | 10 | Australia (Corre. Office) |
Vatican City | 3 | Italy D&B |
Venezuela | 10 | LABIC |
Vietnam | 10 | Singapore (Corre. Office) |
American Virgin Islands | 10 | USA D&B |
British Virgin Islands | 10 | LABIC |
Wake Islands | 10 | Australia (Corre. Office) |
Wales | 3 | United Kingdom D&B |
Wallis and Futuna Island | 7 | France (Correspondent) |
West Indies | 10 | LABIC |
Western Sahara | --- | Not Reported on by D&B |
Yemen | 6 | D&B SAME |
Zaire | 10 | Emerging Markets Center |
Zambia | 6 | D&B North Africa |
Zimbabwe | 10 | TU ITC |
Feature Notes
Investigations initiated using the D&B Direct API may only be requested for the Business Information Report, although when the investigation is completed any data updated in the BIR will also be available in D&B Direct products that provide similar information.
Additional questions may be submitted (in the comments field) with the initial investigation request. Responses to these questions will be appended to the Business Information Report provided upon completion of the investigation.
When an investigation is requested on an in date case, please provide an explanation in the comments section. This is an operational requirement that ensures the local D&B Customer Service Center understands the expectations of the request.
If D&B is unable to locate the organization based on the information provided in the request, an Unable To Locate (UTL) report will be prepared and delivered.
Multiple email addresses may be included with the request, and each will receive a notification email -- with the Business Information Report attached --when the investigation process is completed. A copy of the report is also stored in the Product Request Archive.
What to do Next
Check Investigation Status
Investigation status can be checked using the List Portfolio Asset with the below options:
Use Investigation Status Code and User Read Indicator query parameters:
- /V2/assets?UserReadIndicator=0&InvestigationStatusCode=1&SortBasisText=FulfillmentTimeStamp &SortDirectionText=Descending
The above REST URL will list all the Fulfilled Investigations records and records that have not been retrieved using Retrieve Portfolio. The response will be sorted by Fulfilled Timestamp in descending order.
Use Investigation Tracking ID query parameter:
- /V2/assets?InvestigationTrackingID={InvestigationTrackingID}
The above REST URL will provide the status of Investigation Status Text: Pending, Fulfilled or Cancelled.
NOTE: No action is required if Investigation Status Text is Pending or Cancelled.
Use time stamp fields Order From Timestamp, Order To Timestamp and Fulfillment From Timestamp, Fulfillment To Timestamp:
- /V2/assets?InvestigationStatusCode=1&OrderFromTimestamp=2018-10-01T00:00:00Z&OrderToTimestamp=2018-11-01T00:00:00Z
- /V2/assets?FulfillmentFromTimestamp=2018-10-01T00:00:00Z&FulfillmentToTimestamp=2018-11-01T00:00:00Z
The above REST URL will list all the Fulfilled Investigations records between the time period provided.
Retrieve Fulfilled Reports
Use the following REST URLs to retrieve the report stored for the Asset/ Investigation Tracking ID provided.
- /V2/assets/{PortfolioAssetID}?ApplicationTransactionID={PassUniqueNumber}
- /V2/assets?InvestigationTrackingID={InvestigationTrackingID}
NOTE: After retrieval, status of Investigation will be changed to 'Delivered' and User Read Indicator will be updated to ‘true’.