Resolve Company Information by D-U-N-S number

Resolves company information (official name, postal address, annual turnover, number of employees, ...) based on the company's D-U-N-S number. In order to get the company information each request requires a reason.

Request Url: https://api.datamill.solutions/business-data/duns/resolve
Request Method: POST

Table of Contents

Request Parameters

The API uses the POST request method to send data in the HTTP message body to avoid data being stored in the cache of the web server. A request is valid if all parameters are provided as described below (data type, minimum and maximum length). Please note that all data must be UTF-8 and URL encoded.

POST /business-data/duns/resolve HTTP/1.1
Host: https://api.datamill.solutions

name1=value1&name2=value2
Parameter Mandatory Data Type Min. Max. Description
license required string 29 29 Your license key used for authentication - keep this key secret!
guid required string 30 40 Your GUID used for authentication - keep this key secret!
duns_number required string 9 9 D-U-N-S number representing the company you like to get detailed information about.
reason_code required integer 1 8 Unique code describing the reason why you like to get detailed information about the specified company. Possible codes are:
  • 1: Credit decisions
  • 2: Credit check (intended business connection)
  • 3: Credit check (ongoing business connection)
  • 4: Debt collections
  • 5: Commercial credit insurance
  • 6: Insurance contract
  • 7: Leasing agreement
  • 8: Rental agreement

Response

The API returns all data in valid JSON. A few programming languages include native support for JSON. For those that don't, you can find a suitable library at http://www.json.org. Valid requests always returns all response keys listed below. Depending on the request parameters some response keys may be empty.

HTTP/1.1 200 OK

Server: Apache
Content-Type: application/json; charset=UTF-8
Date: Mon, 19 Aug 2019 18:51:26 GMT
Content-Length: 33
Access-Control-Allow-Origin: *

{"key1":"value1","key2":"value2"}
Name Data Type Description
status string Flag if a company was found by its D-U-N-S number or not [0,1]
status_description string Describes if a company was found or if the specified D-U-N-S number could not be resolved.
  • company not found
  • company found
  • invalid duns number
company_name string The company's official name
company_name_2 string The company's second name or "doing business as"
continent_name string Continent name of the company's headquarters
country_code string ISO 3166-1 alpha-2 country code of the company's headquarters
country_code_3 string ISO 3166-1 alpha-3 country code of the company's headquarters
zip string Postal code of the company's headquarters
city string City of the company's headquarters
street string Street name of the company's headquarters
house_number string House number of the company's headquarters
state_name string State name of the company's headquarters
state_code string ISO 3166-2 state code of the company's headquarters
phone_number string Phone number of the company's headquarters
fax_number string Fax number of the company's headquarters
ceo_name string Name of the company's CEO (Chief Executive Officer)
ceo_title string Position / Business title of the company's CEO
ceo_secondary array Collection of names of further CEOs
year_started string Year of establishment
sic_code string The company's international SIC (Standard Industrial Classification) code
sic_description string Description of the SIC code
annual_turnover_usd integer The company's annual turnover in US Dollar (may be NULL if unset)
annual_turnover_local_currency integer The company's annual turnover in its local currency (may be NULL if unset)
annual_turnover_indicator_code string Indicator if the annual turnover is an approximated or exact value
  • <empty value>: not available
  • 0: exact value
  • 1: low end of range
  • 2: approximated
  • 3: modeled value
annual_turnover_indicator_description string Description of the annual turnover indicator
net_income integer The company's net income in its local currency (may be NULL if unset)
net_income_usd integer The company's net income in US Dollar (may be NULL if unset)
net_worth integer The company's net worth (net value) in its local currency (may be NULL if unset)
net_worth_usd integer The company's net worth (net value) in US Dollar (may be NULL if unset)
currency_code string The local currency code of the company's headquarters country (3-letter ISO 4217 currency code)
currency_name string The local currency name of the company's headquarters country
marketability_code string Indicator if the company / branch can be used for marketing purposes
  • 1: not marketable, but listed
  • 2: not marketable and not listed
  • 3: marketable and listed
marketability_description string Description of the marketable indicator value
total_employees integer The total number of employees (may be NULL if unset)
total_employees_indicator string Indicator if the total number of employees is an approximated or exact value
  • 0: exact value
  • 1: low end of range
  • 2: approximated
total_employees_indicator_description string Description of the total number of employees indicator
total_employees_physical_address integer The total number of employees working at the company's headquarters (may be NULL if unset)
total_employees_physical_address_indicator string Indicator if the total number of employees (working at the company's headquarters) is an approximated or exact value
  • <empty value>: not available
  • 0: exact value
  • 1: low end of range
  • 2: approximated or not available if the number of employees at this location is zero
  • 3: modeled value
import_export_indicator string Indicator if the company has an import and/or export trade
  • <empty value>: not available
  • A: import / export / agent
  • B: imports and exports
  • C: imports
  • D: imports and agents
  • E: exports and agents
  • F: agents, keeps no inventory, does not take title goods
  • G: not available or none
  • H: exports
import_export_indicator_description string Description of the import/export indicator
legal_form_code integer Code of the company's legal form (may be NULL if unset)
legal_form_description string Description of the legal form code
business_structure_code string Code of the company's business structure
  • <empty value>: not available
  • 0: single location
  • 1: headquarter
  • 2: branch
  • 4: division
business_structure_description string Description of the business structure code
undeliverable_indicator string Indicator if any of the company's information are undeliverable
  • B: both addresses are undeliverable
  • M: mail address is undeliverable
  • N: no nixie indication
  • P: physical address undeliverable
  • Y: one of the addresses is undeliverable
undeliverable_description string Description of the undeliverable indicator
financial_statement_date string Timestamp when the financial information were updated the last time (may be full year only or full date with day, month and year)
report_date string Timestamp when the company's information were updated the last time (may be full year only or full date with day, month and year)
is_only_available_address boolean Flag if this postal address is the only address available for the company
is_subsidiary boolean Flag if this postal address is a subsidiary of the company
total_employees_including_principals_indicator boolean Flag if the total number of employees includes principals
is_out_of_business boolean Flag if the company is already out of business
business_registration_number_code string Unique code describing the national registration id
business_registration_number_code_description string Friendly name of the business registration number code

Response Errors

If the request fails the API returns a HTTP status code according to the reason. A reason may be a missing mandatory request parameter, invalid parameter credentials (minimum/maximum length) or invalid API keys. The response body is a valid JSON containing detail information about the reason (except for status code 500).

HTTP/1.1 404 Not Found

Server: Apache
Content-Type: application/json; charset=UTF-8
Date: Mon, 19 Aug 2019 18:51:26 GMT
Content-Length: 71
Access-Control-Allow-Origin: *

{"errorcode":404,"errormessage":"transformation function name invalid"}
HTTP Status Code Reason
401 Unauthorized
The license key and/or GUID key is missing, invalid or inactive.
402 Payment Required
Your /data.mill credit quota is exceeded. You need to get more credits.
403 Forbidden
You need to accept all required agreements of this function to be able to use it.
404 Not Found
The request path in combination with the request method does not exist.
405 Method Not Allowed
The request method is not allowed for the requested path.
412 Precondition Failed
At least one of the given request parameter has invalid credentials (e.g. data type, length).
428 Precondition Required
At least one of the mandatory request parameter is missing or has an empty value.
500 Internal Server Error
An unexpected condition terminated the request.
503 Service Unavailable
The service is currently in maintenance mode and will be alive later.

Batch Mode

The batch mode allows the execution of thousands of records (limited to 5,000) combined in a single request. This API endpoint as described above uses the single mode execution of records. To use the batch mode you need to combine all request parameters above (excluding license and guid) as array, where each array element represents a single record. This array is converted to a valid JSON string and set as value of the new request parameter called batch. The response of the batch mode is a valid JSON which contains the result for each record set in the request. The response keys of each result element are the same as for the single request mode described above.

Batch Request

license=...
&guid=...
&batch=[{"duns_number":"...","reason_code":"..."},{"duns_number":"...","reason_code":"..."}]

Batch Response

[{"status":"...","status_description":"...","company_name":"...","company_name_2":"...","continent_name":"...","country_code":"...","country_code_3":"...","zip":"...","city":"...","street":"...","house_number":"...","state_name":"...","state_code":"...","phone_number":"...","fax_number":"...","ceo_name":"...","ceo_title":"...","ceo_secondary":[],"year_started":"...","sic_code":"...","sic_description":"...","annual_turnover_usd":"...","annual_turnover_local_currency":"...","annual_turnover_indicator_code":"...","annual_turnover_indicator_description":"...","net_income":"...","net_income_usd":"...","net_worth":"...","net_worth_usd":"...","currency_code":"...","currency_name":"...","marketability_code":"...","marketability_description":"...","total_employees":"...","total_employees_indicator":"...","total_employees_indicator_description":"...","total_employees_physical_address":"...","total_employees_physical_address_indicator":"...","import_export_indicator":"...","import_export_indicator_description":"...","legal_form_code":"...","legal_form_description":"...","business_structure_code":"...","business_structure_description":"...","undeliverable_indicator":"...","undeliverable_description":"...","financial_statement_date":"...","report_date":"...","is_only_available_address":"...","is_subsidiary":"...","total_employees_including_principals_indicator":"...","is_out_of_business":"...","business_registration_number_code":"...","business_registration_number_code_description":"..."},{"status":"...","status_description":"...","company_name":"...","company_name_2":"...","continent_name":"...","country_code":"...","country_code_3":"...","zip":"...","city":"...","street":"...","house_number":"...","state_name":"...","state_code":"...","phone_number":"...","fax_number":"...","ceo_name":"...","ceo_title":"...","ceo_secondary":[],"year_started":"...","sic_code":"...","sic_description":"...","annual_turnover_usd":"...","annual_turnover_local_currency":"...","annual_turnover_indicator_code":"...","annual_turnover_indicator_description":"...","net_income":"...","net_income_usd":"...","net_worth":"...","net_worth_usd":"...","currency_code":"...","currency_name":"...","marketability_code":"...","marketability_description":"...","total_employees":"...","total_employees_indicator":"...","total_employees_indicator_description":"...","total_employees_physical_address":"...","total_employees_physical_address_indicator":"...","import_export_indicator":"...","import_export_indicator_description":"...","legal_form_code":"...","legal_form_description":"...","business_structure_code":"...","business_structure_description":"...","undeliverable_indicator":"...","undeliverable_description":"...","financial_statement_date":"...","report_date":"...","is_only_available_address":"...","is_subsidiary":"...","total_employees_including_principals_indicator":"...","is_out_of_business":"...","business_registration_number_code":"...","business_registration_number_code_description":"..."}]

Pricing

In order to enable the payment of different currencies, we have introduced a system based on credit balance as payment for the individual functions. The currency of the account is called /data.mill credits. To use the functions, the account must be charged in advance. If the credit price of a function is higher than the current balance, the function can not be executed. The credits will be deducted from your balance after executing the function. Your credits have no expiration date.

This functions costs 2300 /data.mill credits for each record set in the request.
1 record (single mode): 2300
2 records (batch mode): 4600
3 records (batch mode): 6900

Code Snippets

We provide some code snippets for multiple programming languages to easily implement this function in your own application. The code snippets below uses the single request mode. If you want to use the batch mode instead of the single mode you need to modify the snippet. Feel free to copy the code snippets for your preferred programming language.

// the following code requires cURL php extension installed on your server (http://php.net/manual/en/book.curl.php) // initialize a new cURL session and store the cURL handler object $curl = curl_init(); // set the url to which the request will be sent curl_setopt($curl, CURLOPT_URL, "https://api.datamill.solutions/business-data/duns/resolve"); // set the HTTP method to use for the request curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST"); // set the number of parameters to be sent to the server curl_setopt($curl, CURLOPT_POST, 4); // data to be sent to the server // TODO: append your API keys and value(s) and don't forget to urlencode() them curl_setopt($curl, CURLOPT_POSTFIELDS, "license=&guid=&duns_number=&reason_code="); // set a timeout in seconds for the request curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 10); curl_setopt($curl, CURLOPT_TIMEOUT, 10); // return the raw data from the server curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); // execute the previously created cURL session $responseString = curl_exec($curl); // close the cURL session after execution curl_close($curl); // convert the response (string) to an array $responseArray = json_decode($responseString, true); // TODO: process the data in the response array (you may process the data in the response string too)
/* Note: We highly recommend to NOT use this code as it is written here. If you choose JavaScript as your preferred programming language, please change the following code to request your own server (without API keys) and further redirect the request from your own server to the API including your API keys. Otherwise everyone will be able to read your API keys and use them for their own purpose! */ // the following code requires jQuery JavaScript library (minimum version 1.8.1) added to your website (http://jquery.com/download/) // perform an asynchronous HTTP (Ajax) request jQuery.ajax({
// set the url to which the request is sent url : "https://api.datamill.solutions/business-data/duns/resolve", // set the HTTP method to use for the request type: "POST", // data to be sent to the server (you may use a JavaScript object instead of a string) // TODO: append your API keys and value(s) and don't forget to urlencode() them data : "license=&guid=&duns_number=&reason_code=", // type of data that we are expecting back from the server dataType: "JSON", // set a timeout in milliseconds for the request timeout: 10000, // function to be called if the request succeeds success:function(data, textStatus, jqXHR) {
// {object} data The data returned from the server, formatted according to the dataType parameter. // {string} textStatus String describing the status. // {object} jqXHR A XMLHttpRequest object describing the response. // TODO: process the data in the 'data' JavaScript object
}, // function to be called if the request fails error: function(jqXHR, textStatus, errorThrown) {
// {object} jqXHR A XMLHttpRequest object describing the response. // {string} textStatus String describing the type of error occurred. // {string} errorThrown Text portion of the HTTP status, such as "Not Found" or "Internal Server Error". // TODO: process the error occurred
}
});
// the following code uses standard libraries included in Microsoft Visual Studio 2013 or higher using System.IO; using System.Web; using System.Net;
// create an array of bytes representing the data to be sent to the server // TODO: append your API keys and value(s) and don't forget to urlencode() them byte[] Data = Encoding.ASCII.GetBytes("license=&guid=&duns_number=&reason_code="); // create a new web request resource and set the url to which the request is sent HttpWebRequest Request = (HttpWebRequest)WebRequest.Create("https://api.datamill.solutions/business-data/duns/resolve"); // set the HTTP method to use for the request Request.Method = "POST"; // set the request content type Request.ContentType = "application/x-www-form-urlencoded"; // set the number of bytes being sent to the server Request.ContentLength = Data.Length; // set a timeout in milliseconds for the request Request.Timeout = 10000; // try to send all data to the newly created web request resource try {
using(var Stream = Request.GetRequestStream()) {
Stream.Write(Data, 0, Data.Length);
}
} catch (Exception ex) {
// TODO: process the exception thrown (e.g. url not found) return;
} // try to read the response from the web resource try {
HttpWebResponse ResponseObject = (HttpWebResponse)Request.GetResponse(); StreamReader Reader = new StreamReader(ResponseObject.GetResponseStream()); // read the whole response as string and store it String ResponseMessage = System.Net.WebUtility.HtmlDecode(Reader.ReadToEnd()); // TODO: process the data in 'ResponseMessage'
} catch (WebException ex) {
// error occurred, http status code != 200 (e.g. timeout or parameter invalid) if(ex.Status == WebExceptionStatus.Timeout) {
// TODO: process the timeout reached
} else {
// read the response from the web exception HttpWebResponse ResponseObject = (HttpWebResponse)ex.Response; StreamReader Reader = new StreamReader(ResponseObject.GetResponseStream()); // read the whole response as string and store it String ResponseMessage = System.Net.WebUtility.HtmlDecode(Reader.ReadToEnd()); // TODO: process the error response received from the server (stored in 'ResponseMessage')
}
}
// the following code requires at least Android API version 10 // import standard Java and Android libraries import java.util.List; import org.apache.http.NameValuePair; import java.util.ArrayList; import org.apache.http.message.BasicNameValuePair; import java.net.URLDecoder; import org.apache.http.client.methods.HttpPost; import org.apache.http.client.entity.UrlEncodedFormEntity; import org.apache.http.client.HttpClient; import org.apache.http.impl.client.DefaultHttpClient;
// create a list of key-value-pairs to store the data which will be sent to the server List<NameValuePair> dataPairs = new ArrayList<NameValuePair>(); // add each parameter to the key-value-pair list (value is decoded to UTF-8 standard) // TODO: append your API keys and value(s) dataPairs.add(new BasicNameValuePair("license", URLDecoder.decode("enter value here", "UTF-8"))); dataPairs.add(new BasicNameValuePair("guid", URLDecoder.decode("enter value here", "UTF-8"))); dataPairs.add(new BasicNameValuePair("duns_number", URLDecoder.decode("enter value here", "UTF-8"))); dataPairs.add(new BasicNameValuePair("reason_code", URLDecoder.decode("enter value here", "UTF-8"))); // create the web resource with pre-defined POST method and set the url to which the request is sent HttpPost request = new HttpPost("https://api.datamill.solutions/business-data/duns/resolve"); // append the parameters to the web resource request.setEntity(new UrlEncodedFormEntity(dataPairs)); try {
// execute the request and read the response string HttpClient client = new DefaultHttpClient(); String response = client.execute(request); // TODO: process the data in 'response'
} catch (IOException ex) {
// TODO: process the exception thrown
}

Need help?

If you have any questions about the implementation of this API or found an error please don't hesitate to contact our support team.