D&B Direct+ API Documentation for IP Address Detail Lookup. Version 1, REST Interface. Intended for Early Adopter Program Participants

Transcription

1 DUN & BRADSTREET D&B Direct+ API Documentation for IP Address Detail Lookup Version 1, REST Interface Intended for Early Adopter Program Participants PREPARED ON THURSDAY, JUNE 11, 2015

2 Copyright 2015 by Dun & Bradstreet, Inc. All rights reserved. For purposes of this Dun & Bradstreet Documentation, "D&B" means The Dun & Bradstreet Corporation, its subsidiaries, affiliates, divisions, contractors and all of its and their data sources and suppliers. This Documentation is a work of authorship that belongs to Dun & Bradstreet, Inc. and is protected by United States and foreign copyright laws and international copyright treaties. D&B, Dun & Bradstreet, D-U-N-S Number, DUNSRight, WorldBase, and the D&B logo are registered marks in the U.S., and in other countries, of Dun & Bradstreet, International, Ltd. or its affiliates. Java is a trademark of Oracle Corporation. Other trademarks used herein are the trademarks, or registered trademarks, of their respective owners. Use of the D&B Direct+ software and this Documentation is governed by the D&B Business Information Solutions, Ltd. software license agreement. D&B Direct+ software is copyright D&B Business Information Solutions, Ltd., All rights reserved. For the most recent copy of these materials, please visit ABOUT DUN & BRADSTREET Dun & Bradstreet (NYSE: DNB) grows the most valuable relationships in business. By uncovering truth and meaning from data, we connect customers with the prospects, suppliers, clients and partners that matter most, and have since Nearly ninety percent of the Fortune 500, and companies of every size around the world, rely on our data, insights and analytics. For more about Dun & Bradstreet, visit DNB.com.

3 IP Address Detail Lookup Service D&B Direct+ Version 1.0 View(s) Options(s) Interface Method Format(s) basic, standard IPv4 REST GET JSON Released on March 31, 2015 This API provides one option for obtaining details about an IP (Internet Protocol) v4 address. Currently a REST interface is supported for all D&B Direct+ calls. IP v6 addresses are currently not supported by this function. NOTE: This release provides responses to API calls for both 'biz' and 'isp' domain type (ipdomaintype) values by default. All successful API calls to this operation will count against the number of calls for which Early Adopters are entitled per month. An optional parameter enables the selection of the ipdomaintype ('biz' [default], 'isp', or 'any'). Update History No modifications have been made to this data layer since the initial release. D&B DIRECT BY DUN & BRADSTREET, INC. IP ADDRESS DETAIL LOOKUP 1-1

4 Product Request Authenticating D&B Direct+ API calls utilize access tokens - generated from a key/secret combination - for authentication based on the Client Credentials Grant flow of the OAuth 2 specification. These access tokens expire after twenty-four hours. The error code indicates the current access token being used has expired. Contact your D&B representative to obtain your D&B Direct+ key/secret combination. These values, along with any access tokens generated, should be considered as sensitive as a password, and must be used only by authorized parties as stated in the D&B Direct+ API agreement. Refer to "Understanding the D&B Direct+ API Authentication Flow" for more details on the steps involved in authenticating. Specification The IP Address Lookup function can be invoked in the following manner. While the view parameter will default to standard, it is a good practice to always specify the level of service expected. All D&B Direct+ function calls require the use of a secured connection (i.e. https). Place the {IP} address into the following endpoint: isp any and then append one of the two view options. Sample BASIC Request GET Authorization: Bearer <yourtoken> (from Authentication call) Origin: Sample STANDARD Request GET Authorization: Bearer <yourtoken> (from Authentication call) Origin: Quick Start using Postman (Optional) Postman is a Google Chrome plug-in that allows you to make API calls and inspect responses from within a browser environment. A Postman collection is available for making calls to the IP Address Lookup function. Refer to "Interacting with the D&B Direct+ API Using Postman" for more details on how to quickly and easily make API calls. The consumer key/secret credentials will be required. D&B DIRECT BY DUN & BRADSTREET, INC. IP ADDRESS DETAIL LOOKUP 1-2

5 Quick Start using Java TM (Optional) If you are an experienced Java developer, sample code is available to authenticate and invoke the IP Address Lookup function. The Java JDK version 1.7 or higher is required. A pom.xml file is included for users of Maven. Refer to "Getting Started with D&B Direct+ using Java" for more details. The consumer key/secret credentials will be required. Product Response Specification The following is a list of the data fields returned by this operation in the JSON response. [Y=always returned, O=optional, I=value from input] Basic Standard JSON Attribute name JSON Data Type Description Y Y transactiondetail object Records information used to process this request. Y Y transactionid string A number assigned by the D&B application to uniquely identify this request. Y Y transactiontimestamp string The date and time in ISO 8601 UTC Z standards when this response was created by the D&B application. Y Y inlanguage string A IETF BCP 47 code value that defines the language in which this product was rendered. Y Y productid string A key assigned by D&B which uniquely identifies the product ordered. For the list of products please refer to Y Y productversion string A number assigned by D&B which either uniquely identifies or helps to identify the state of this software deliverable. These numbers are generally assigned in increasing order and correspond to new releases in the software. O O additionaldetail array Records any further details used to process this request as key value pairs which cannot be recorded in other discrete elements. For the list of currently available key values please refer to O Y Key1 string A unique identifier assigned by D&B application to denote a specific information used to process this request. O Y Value1 string The value associated with the key. D&B DIRECT BY DUN & BRADSTREET, INC. IP ADDRESS DETAIL LOOKUP 1-3

6 Basic Standard JSON Attribute name JSON Data Type Description Y Y result object Records the outcome of this transaction. This section is created only when the customer request was not fulfilled due to system failures, incorrect or incomplete request parameters etc. Y Y errorcode string A number assigned by D&B which uniquely identifies the reason for failure of this request. Y Y errormessage string An explanatory text providing more details about the reason for failure of this request. Y Y errorinformationurl 1 string The D&B website URL which provides the complete list of possible errors with their error codes and any other related information. Y Y inquirydetail object Records data that allows the customer to specify identifying information about the subject being inquired upon, e.g., IP Address, address, Domain name. I I ipaddress string The IP Address which is a 32-bit number based on Internet Protocol Version 4 (IPv4) specified by the customer to find a matching company. I I ipdomaintype string Th IP Domain Type specified by the customer to find a matching Company. The permissible values are 'isp' internet service or access provider; 'biz' commercial business as well as other domains like.edu,.gov,.org,.mil, etc.; 'any' includes all types of IP domains available. Note: The values are not case-sensitive. Y Y inquirymatch object Records the data returned by the D&B data partner based on the inquiry details from the customer. Y Y duns string The D-U-N-S Number is D&B's identification number, which provides unique identification of the inquired entity, in accordance with the Data Universal Numbering System (D-U-N-S). Y Y countryisoalpha2code string The two-letter country code, defined by the International Organization for Standardization (ISO) ISO scheme identifying the country of the inquired entity's headquarters as published on their website. D&B DIRECT BY DUN & BRADSTREET, INC. IP ADDRESS DETAIL LOOKUP 1-4

7 Basic Standard JSON Attribute name JSON Data Type Description Y Y region string A textual value, representing the region of the inquired entity's domain name as per the Regional Internet Registry that manages the allocation and registration of Internet number resources within a particular region of the world. Possible values include: North America, South America, Asia, Europe, Oceania, Africa. Y Y ipaddress string A unique Internet Protocol (IP) address which identifies the website of the inquired entity. The IP address is defined as a 32-bit number based on Internet Protocol Version 4 (IPv4). The humanreadable notation is displayed as four numbers separated by periods. Each of the 4 numbers within the IP address can range from zero to 255. Y Y ipdomaintype string A classifier of the domain value returned for the IP address. There are 2 possible values: isp - internet service or access provider; biz - commercial businesses as well all other domains like.edu,.gov,.org.,.mil, etc. Y Y ipdomainname string A unique name used to identify the website of the inquired entity which serves as an address to access that website. Y Y url string The Primary Uniform Resource Locator (URL) for the homepage of the inquired entity's website. Y Y organization object Records data about an organization, a legal or commercial entity established to provide products and/or services in the marketplace or to the community. Y Y organization. duns string 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). Y Y organization. name string The single name by which the organization is primarily known / identified. N Y organization. primaryaddress object Records the single primary or physical address at which the organization is located. N Y organization. primaryaddress. addresscountry N Y organization. primaryaddress. addresscountry. name object string Records the details of the country in which the business is located. Text recording the name of the country in which the business is located. D&B DIRECT BY DUN & BRADSTREET, INC. IP ADDRESS DETAIL LOOKUP 1-5

8 Basic Standard JSON Attribute name JSON Data Type Description Y Y organization. primaryaddress. addresscountry. isoalpha2code N Y organization. primaryaddress. addresslocality N Y organization. primaryaddress. addressregion N Y organization. primaryaddress. postalcode N Y organization. primaryaddress. streetaddress N Y organization. primaryaddress. streetaddress. line1 N Y organization. primaryaddress. streetaddress. line2 string string string string object string string The two-letter country code, defined by the International Organization for Standardization (ISO) ISO scheme identifying the country of the business entity. Text recording the name of a city, town, township, village, borough, etc. where the business is located. Text recording the name of the locally governed area which forms part of a centrally governed nation to identify where the business is located. An identifier used by the local country Postal Authority to identify where the business is located. Records the details such as address number, or post office box number and street name where the business is located. Text recording the address number, or post office box number and street name where the business is located. Text recording the address parts of the business entity that cannot be recorded in 1st address line. number The angular distance of the organization's primary N Y organization. primaryaddress. latitude 4 physical address north or south from the Earth's equator expressed in decimal numbers. Positive numbers indicate degrees north. Negative numbers indicate degrees south. number The angular distance of the organization's primary N Y organization. primaryaddress. longitude 4 physical address east or west from an imaginary line (called the prime meridian) that goes from the North Pole to the South Pole expressed in decimal numbers. Positive numbers indicate degrees east. Negative numbers indicate degrees west. N Y organization. isfortune1000listed boolean When set to "true" it indicates that the business entity has ever been listed as one of the 1000 largest American companies, ranked on revenues alone by the American business magazine Fortune. The value will be NULL when D&B is not aware of this fact. N Y organization. isforbeslargestprivatecompanieslisted boolean When set to "true" it indicates that the business entity has ever been listed as one of the annual list of largest private companies in the United States, compiled and published by Forbes magazine The value will be NULL when D&B is not aware of this fact. D&B DIRECT BY DUN & BRADSTREET, INC. IP ADDRESS DETAIL LOOKUP 1-6

9 Basic Standard JSON Attribute name JSON Data Type Description N Y organization. numberofemployees array Records details of the people engaged by an organization to perform its business operations. number The total number of people engaged by an N Y organization. numberofemployees. value 3 organization to perform its business operations.several different Employee Figures for a subject could be recorded, e.g., consolidated, individual entity, headquarters only. N Y organization. yearlyrevenue array Records the details of income received from customers from the sale of the business' goods and/or services. N Y organization. yearlyrevenue. value 3 number The monetary value of income received from customers from the sale of the business' goods and/or services. This means it is the gross sales minus any returns, rebates/discounts, allowances for damages or shortages, shipping expenses passed on to the customer, and amounts due where there is not a reasonable expectation of collection. This figure will be the latest sales revenue amount available for the business entity and will always be in US Dollars and Single units N Y organization. telephone object Records details on the telephone number of the business entity. N Y organization. telephone. number string The telephone number of the business entity. 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. N Y organization. telephone. isdcode string 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. N Y organization. tickersymbol 2 string Text that identifies the subject for share trading purposes at the Stock Exchange where the business entity does most of the trading. For example "NYSE: DNB" which is the ticker symbol for D&B in New York Stock Exchange. D&B DIRECT BY DUN & BRADSTREET, INC. IP ADDRESS DETAIL LOOKUP 1-7

10 Basic Standard JSON Attribute name JSON Data Type Description N Y organization. primaryindustrycode object Records the primary business activity in which an organization is actively engaged using standardized coding schemes such as European NACE and U.S. Standard Industry Classifications (SIC). N Y organization. primaryindustrycode. ussicv4 string The 1987 version of a 4 digit numeric coding system developed by the US Government for the classification of industrial activities to denote the industry in which the business entity does most of it's business. 1 Known issue: Not available in the current implementation. 2 Known issue: The current implementation is not returning the trading exchange part of this element. 3 Known issue: When values are unavailable for employee quantity and sales revenue amount, the field value is returned as 0 in JSON instead of null. 4 Primary address latitude/longitude values are available for US, Germany, Canada, Australia, UK, Mexico, Belgium, Netherlands, South Korea, and Vietnam. Response Codes Successful requests will return an HTTP 200 response. Otherwise, one of the D&B Direct+ standard response codes will be returned. Early Adopter Support For any Early Adopter Program support requests, please reach out to D&B Direct Early Adopter Support by sending an to DirectEASupport@dnb.com or contact your assigned Support Specialist directly. D&B DIRECT BY DUN & BRADSTREET, INC. IP ADDRESS DETAIL LOOKUP 1-8

11 Interacting with the D&B Direct+ API Using Postman Postman is a Google Chrome plug-in that allows you to make API calls and inspect responses from within a browser environment. A Postman collection is available for making calls to the IP Address Lookup function. Prerequisites 1. Install Postman Plug-in Before proceeding any further in this document please open the Google Chrome browser and install the latest version of Postman For more detailed introductions and documentation for Postman see mentions and the project s web site at 2. Obtain Credentials & Authenticate D&B Direct+ API calls utilize access tokens - generated from a key/secret combination - for authentication. These access tokens expire after twenty-four hours. The error code indicates the current access token being used has expired. Refer to "Understanding the D&B Direct+ API Authentication Flow" for more details on the steps involved in authenticating. 3. Download the Sample Postman Collection Click on the link Plus.dnb.com.json.postman_collection to download a Postman collection that can be imported into Postman. The collection contains the necessary URLs and requests for accessing and testing the D&B Direct+ API. D&B DIRECT BY DUN & BRADSTREET, INC. INTERACTING WITH THE D&B DIRECT+ API USING POSTMAN 1-9

12 Generating an Access Token In order to call any of the D&B Direct+ APIs you are going to first need to make a call to the Authorization Server to generate an access token. Once you have downloaded and imported the Postman Collection locate the "Generate Access Token" request in the left navigation list. Click on the Basic Auth tab if it's not already open and then replace the username value with your own Consumer Key and the password with your Consumer Secret Click on the refresh headers button. Click Save. Click the send button. You will receive a response like: {"access_ token":"z5opwikcew0ujxoek1dmjsgjxvxg","expiresin":604800} Copy the token from the response (eg. Z5ZzzIKcew0ujxOEk1dmjsgjXvxg) and save it somewhere as you will need it for the actual API requests in the following sections. D&B DIRECT BY DUN & BRADSTREET, INC. INTERACTING WITH THE D&B DIRECT+ API USING POSTMAN 1-10

13 Determine IP Address Type Open Postman and find the "Determine IP Resource Type" request. Click on the Normal tab. Replace the value of the Authorization header with Bearer {Access Token} For example if we were to use the token we obtained in the "Generate an Access Token" step above then it would look like: Bearer Z5OpwIKcew0ujxOEk1dmjsgjXvxg Change the ipresource to whatever you want to test (or skip this step to use the one already in the query " " ). The part to change is highlighted in green below: NOTE: This release provides responses to API calls for both 'biz' and 'isp' domain type (ipdomaintype) values by default. All successful API calls to this operation will count against the number of calls for which Early Adopters are entitled per month. An optional parameter to enables the selection of the ipdomaintype ('biz' [default], 'isp', or 'any'). NOTE: Request parameters are case-sensitive. Click Save. Click the send button. D&B DIRECT BY DUN & BRADSTREET, INC. INTERACTING WITH THE D&B DIRECT+ API USING POSTMAN 1-11

14 Getting Started with D&B Direct+ using Java If you are an experienced Java developer, sample code is available to authenticate and invoke the Website Visitor Identification function. The Java JDK version 1.7 or higher is required. A pom.xml file is included for users of Maven. Prerequisites 1. Software Requirements Java JDK (1.7 or higher) The sample code has dependencies on the following third party software, and has been tested with the indicated versions: o Apache HTTP Components Client o Apache HTTP Components Core 4.3 o Apache Commons Codec 1.9 o Jettison Obtain Credentials & Authenticate D&B Direct+ API calls utilize access tokens - generated from a key/secret combination - for authentication. These access tokens expire after twenty-four hours. The error code indicates the current access token being used has expired. Refer to "Understanding the D&B Direct+ API Authentication Flow" for more details on the steps involved in authenticating. 3. Download the Java Client Sample Code Click on the link, DnB-Direct-Plus-WebVI-API-sample-Java.zip, to download a Java sample that can be used to call the D&B Direct+ API. 4. Additional Notes D&B DIRECT BY DUN & BRADSTREET, INC. GETTING STARTED WITH D&B DIRECT+ USING JAVA 1-12

15 If you choose to use Maven, a pom.xml file is included with the sample code for your convenience. If you choose to use Gradle, these are the corresponding dependencies: dependencies { compile(group: 'org.apache.httpcomponents', name: 'httpclient', version: '4.3.2') compile(group: 'org.apache.httpcomponents', name: 'httpcore', version: '4.3') compile(group: 'commons-codec', name: 'commons-codec', version: '1.9') compile(group: 'org.codehaus.jettison', name: ' jettison', version: '1.3.6') } Sample Code The sample Java code provided with this document provides an example to demonstrate authorization and service invocation. It includes the following classes: Class Name Purpose Class Name Purpose WebVIClientExample Provides sample methods for authorization and invocation of the Direct+ services. This code is purely for demonstration purposes and does not handle any of the exception conditions that can be normally expected WebVIClientRunner ProxyConfig To run the sample code: Runnable Java class that invokes the methods exposed by WebVIClientExample Simple holder of proxy server information that may be required to access the D&B Direct+ service from within a corporate network First, please refer to the Software Requirements section above to ensure that you obtain all required software dependencies Modify WebVIClientRunner to provide values for the following variables: o consumerkey o consumersecret If you do not possess these values then please contact the D&B Direct+ Customer Support Team to obtain them Proxy Configuration: If you need to use a proxy server to connect to the internet, then uncomment the proxy configuration line and provide the necessary host, port, username and password to the ProxyConfig constructor call Compile the code and then run WebVIClientRunner. If it runs correctly, then you will see the JSON output of the calls to each of the Get DUNS for Domain, Get DUNS for Address, Get DUNS for IP Address and Get DUNS for IP Resource services made by WebVIClientRunner. If the output is not as expected, then using a Java IDE with debugging features is recommended. D&B DIRECT BY DUN & BRADSTREET, INC. GETTING STARTED WITH D&B DIRECT+ USING JAVA 1-13

16 Understanding the D&B Direct+ API Authentication Flow Before you can start using thed&b Direct+ API, you will need to understand the authorization flow of the API. D&B Direct+ API calls utilize access tokens - generated from a key/secret combination - for authentication based on the Client Credentials Grant flow of the OAuth 2 specification. These access tokens expire after twenty-four hours. The error code indicates the current access token being used has expired. NOTE: Contact your D&B representative to obtain your D&B Direct+ key/secret combination. These values, along with any access tokens generated, should be considered as sensitive as a password, and must used only by authorized parties as stated in the D&B Direct+ API agreement. Here is a sample of a Consumer Key and Consumer Secret. Note: these are not valid credentials. Consumer Key: r1bkfi9irgl0fp8vxmxxm6yhy2msm3dw Consumer Secret: VH4HIUipabqqAcO7 The application-only auth flow follows these steps: 1. An application developer base 64 encodes the combination of Consumer Key plus ":" plus Consumer Secret into a credential value that can be submitted for a token. For example, the sample values would yield the following encoded credential value: UXQ2WUdZcFh2R2Z4V0FsUkhoNVdNNDZNc2I3NldLTnc6Y25oOFRDOVNlemxkM 2M4NA== 2. An application makes a request to the POST endpoint to exchange these credentials for a bearer token. Token Request D&B DIRECT BY DUN & BRADSTREET, INC. UNDERSTANDING THE D&B DIRECT+ API AUTHENTICATION FLOW A-1

17 POST Content-Type: application/json Authorization: Basic <base 64 encoded(yourkey:yoursecret)> Origin: { "grant_type" : "client_credentials" } Token Response { } "access_token": "<yourtoken>", "expiresin": When accessing the D&B Direct+ API, the application uses the bearer token to authenticate the API requests. Without the bearer token these calls will fail. Sample Request (by IP) GET Authorization: Bearer <yourtoken> Origin: Process The following diagram shows a standard Auth flow, where Authorization Server is ( and Resource Server is the D&B Direct+ API. D&B DIRECT BY DUN & BRADSTREET, INC. UNDERSTANDING THE D&B DIRECT+ API AUTHENTICATION FLOW A-2

18 D&B DIRECT BY DUN & BRADSTREET, INC. UNDERSTANDING THE D&B DIRECT+ API AUTHENTICATION FLOW A-3

19 Error Codes The following error codes may be returned by D&B Direct+ API functions: HTTP Status Code errormessage Values errorcode Values 200 Success! n/a 503 Request timeout One or more parameters are invalid or missing This request was issued outside the contract start/end date User credentials are not allowed on this request User credentials are required in payload Malformed payload Bad Request Origin header is required Contract data not found Unauthorized Internal Server Error Internal Server Error Not Found Not Found Unauthorized Unauthorized Unauthorized D&B DIRECT BY DUN & BRADSTREET, INC. ERROR CODES B-1

20 HTTP Status Code errormessage Values errorcode Values 429 Too Many Requests Too Many Requests Supplied IP address not found Supplied not found Supplied domain not found Resource type not found for supplied IP address External resource offline/not contactable External resource timeout External resource service error External resource authorization error DUNS not found DUNS resource service error DUNS resource authorization error DUNS resource has changed Unexpected data type in datastore Runtime error Request timeout Your request must contain one query parameter, please fix your request and try again The request URI was not valid as it was missing a valid query parameter, please fix your request and try again D&B DIRECT BY DUN & BRADSTREET, INC. ERROR CODES B-2

21 Dun & Bradstreet 103 JFK Parkway Short Hills, N. J Dun & Bradstreet, Inc All rights reserved.