Introduction
Welcome to the Dropcontact API!
You can enjoy our service’s features with the Dropcontact API to find and enrich all your B2B contacts.
Email Addresses
If there is no email address specified for your contact, we add the buisness email adress based on its name, surname and company.
Else, we verify and qualify any email address, and find business email addresses.
For each email address we qualify the local part and the domain to form a string such as: local_qualification@domain_qualification.
Local Part Qualification | Description |
---|---|
nominative | belongs to one individual, e.g.: dave.smith@domain.com |
catch_all | catch-all email address |
generic | e.g.: support@domain.com, contact@domain.com |
random | random email address |
invalid | this email address does not exist |
Domain Qualification | Description |
---|---|
pro | this domain belongs to a company, e.g.: @dropcontact.io |
perso | e.g.: @gmail.com, @hotmail.com, etc. |
invalid | this domain is not a valid domain |
Company
Find information about companies.
Person
Correct first names and find the gender.
Phone
Find the phone number of the company.
We currently offer one endpoint, /batch, which process contacts in batches. You can use the /batch endpoint, even if you're looking to process only one contact.
In the dark area on the right, you can see code examples. You can switch the programming language in the upper right menu.
Feel free to contact us if you have any question!
Authentication
Example of a request with the access token:
import requests
r = requests.post("https://api.dropcontact.io/batch",
headers={'X-Access-Token': apiKey})
curl -X POST -H "X-Access-Token: apiKey" https://api.dropcontact.io/batch
Make sure to replace
apikey
with your access token.
Dropcontact uses access tokens to allow access to the API. Subscribe here to get your access token.
Our API authenticates requests with an access token that must be passed on the request's header.
Include 'X-Access-Token': apiKey
in your header for authentication.
Batch Endpoint
This request retrieves the civility, the company, the validity of the email, the first name, the full name and a lot of information for all contacts in the request.
Using our batch endpoint you can process up to 250 contacts with a single request. One contact data must be less than 10 kB.
To launch the process POST /batch, and to recover the output GET /batch/{your_request_id}.
POST request
import requests
r = requests.post(
"https://api.dropcontact.io/batch",
json={
'data': [
{'email': 'peter.jackson@company.com'},
{'first_name': 'John', 'last_name': 'Smith', 'website': 'corporation.com'},
{'first_name': 'Samuel', 'last_name': 'Jones', 'email': 'contact@bigcorp.com'}
],
'siren': True,
'language': 'en'
},
headers={
'Content-Type': 'application/json',
'X-Access-Token': apiKey
}
)
curl -X POST
-H "Content-Type: application/json"
-H "X-Access-Token: apiKey"
-d '{"data": [{"email": "name@company.com"}, {"first_name": "John", "last_name": "Smith", "website": "corporation.com"}, {"first_name": "Samuel", "last_name": "Jones", "email": "contact@bigcorp.com"}]}'
'https://api.dropcontact.io/batch'
This request returns the following JSON:
{
"error": false,
"request_id": "your-request-id",
"success": true,
"credits_left": <int>
}
HTTP Request
POST https://api.dropcontact.io/batch
You can add the parameter :
hashedInputs=true
to get in the body of the response a list called hashedInputs containing a hash for each object received. The hash is buit with the jwt encryption, using HS256 algorithm. The security key to decode the data is your api key. All the allowed fields will be in the object, even the empty one. We recommend to decode and check your data instead of comparing the strings.
GET request
import requests
r = requests.get("https://api.dropcontact.io/batch/{}".format('your-request-id'),
headers={'X-Access-Token': apiKey})
curl -X GET
-H "X-Access-Token: apiKey"
'https://api.dropcontact.io/batch/your-request-id'
This request returns this JSON if we are still processing your contacts:
{
"error": false,
"reason": "Request not ready yet, try again in 30 seconds",
"success": false
}
This request returns a JSON structured like this if the process is over:
{
"data": [
{
"first_name": "Peter",
"last_name": "Jackson",
"email": [
{"email": "peter.jackson@company.com", "qualification": "nominative@pro"}
],
"company": "Company",
"website": "www.company.com",
},
{
"first_name": "John",
"last_name": "Smith",
"email": [
{"email": "johnsmith@corporation.com", "qualification": "nominative@pro"}
],
"company": "corporation",
"website": "www.corporation.com",
},
{
"first_name": "Samuel",
"last_name": "Jones",
"email": [
{"email": "samuel_jones@bigcorp.com", "qualification": "nominative@pro"},
{"email": "contact@bigcorp.com", "qualification": "generic@pro"}
],
"company": "Big Corp",
"website": "www.bigcorp.com",
},
],
"error": false,
"success": true
}
HTTP Request
GET https://api.dropcontact.io/batch/your-request-id
Using the request id obtained in the POST call to batch, you can check if all of your contacts have already been processed, and recover the processed contacts once they're ready.
You can also retrieve your data even if all your contacts haven't been processed yet. To do this, just add
forceResults=true
as a parameter to your GET request.
Contacts that are not already processed will be unchanged.
API fields
Request fields
import requests
r = requests.post(
"https://api.dropcontact.io/batch",
json = {
'data': [
{
'email': 'example_email@email.com',
'first_name': 'Denis',
'last_name': 'Dupont',
'full_name': 'Denis Dupont',
'phone': '0707070707',
'company': 'Dropcontact',
'website': 'https://dropcontact.io',
"num_siren": "01010101",
"country": "france"
}
],
'siren': True,
'language': 'en'
},
headers={
'Content-Type': 'application/json',
'X-Access-Token': apiKey
}
)
curl -X POST
-H "Content-Type: application/json"
-H "X-Access-Token: apiKey"
-d '{
"data": [
{
"email": "example_email@email.com",
"first_name": "Denis",
"last_name": "Dupont",
"full_name": "Denis Dupont",
"phone": "0707070707",
"company": "Dropcontact",
"website": "https://dropcontact.io",
"num_siren": "01010101",
"country": "france"
}
],
"siren": True,
"language": "en"
}'
'https://api.dropcontact.io/batch'
HTTP Request
POST https://api.dropcontact.io/batch
Request body
Parameter | Type | Description |
---|---|---|
siren | boolean | True if you want the SIREN number, NAF code, TVA number, company address and informations about the company leader. |
language | string | 'en' if you want result in English, if this not specified the results will be in French. |
You must send an array "data", contaning one or multiple objects with datas you want to clean and enrich.
Data Object Optionnal Parameters
Those are the fields describing objects to treat.
Parameter | Type | Description |
---|---|---|
string | The email that you want to verify | |
first_name | string | First name |
last_name | string | Last name |
full_name | string | Full name |
phone | string | Phone number |
company | string | Company's name |
website | string | Website URL of a company |
num_siren | string | Company's siren |
string | Contact linkedin | |
siret | string | Company's siret |
country | string | Add the country-related code you want to base on for data enrichment, eg country : US if you want 'United States' as reference country >> more here about country codes |
company_linkedin | string | Company linkedin |
custom_fields | dictionary of strings | Custom fields you can give in the request input. Those fields will be kept but not modified or enriched during the process. You will find them back in the output of the request. |
Response fields
POST body example:
{
"first_name": "Denis",
"last_name": "Dupont",
"company": "companyTest",
"website": "www.companyTest.fr",
"custom_fields": {
"your_custom_id": "18181818181818",
"some_key": "some_value"
}
}
GET Response example :
{
"civility": "M",
"first_name": "Denis",
"last_name": "Dupont",
"full_name": "Denis Dupont",
"email": [
{"email": "denis@companyTest.com", "qualification": "nominative@pro"},
{"email": "contact@companyTest.com", "qualification": "generic@pro"}
],
"phone": "0707070707",
"company": "companyTest",
"website": "www.companyTest.fr",
"linkedin": "https://fr.linkedin.com/in/denis.dupont",
"siren": "500 500 500",
"siret": "222 222 222 00022",
"siret_address": "2 Rue Rotland, 67140 Mittelbergheim",
"vat": "79",
"nb_employees": "202",
"naf5_code": "01.22E",
"naf5_des":"Culture de la vigne",
"company_linkedin": "https://www.linkedin.com/company/companyTest/",
"company_turnover": "12345",
"company_results": "6789",
"custom_fields": {
"your_custom_id": "18181818181818",
"some_key": "some_value"
}
}
The following fields can be returned by our API:
Information | Type | Available |
---|---|---|
civility | string | Yes |
first_name | string | Yes |
last_name | string | Yes |
full_name | string | Yes |
[{email: string, qualification: string}] | Yes | |
phone | string | Yes |
mobile_phone | string | Yes |
company | string | Yes |
website | string | Yes |
string | Yes | |
siren | string | Yes |
siret | string | Yes |
siret_address | string | Yes |
vat | string | Yes |
nb_employees | string | Yes |
naf5_code | string | Yes |
naf5_des | string | Yes |
siret_address | string | Yes |
siret_zip | string | Yes |
siret_city | string | Yes |
company_linkedin | string | Yes |
company_turnover | string | Yes |
company_results | string | Yes |
job | string | Yes |
custom_fields | dictionary of strings | Yes |
Credits Left
import requests
r = requests.post(
"https://api.dropcontact.io/batch",
json={
'data': [
{}
],
},
headers={
'Content-Type': 'application/json',
'X-Access-Token': apiKey
}
)
curl -X POST
-H "Content-Type: application/json"
-H "X-Access-Token: apiKey"
-d '{"data": [{}]}'
'https://api.dropcontact.io/batch'
This request returns the following JSON:
{
"error": false,
"request_id": "your-request-id",
"success": true,
"credits_left": <int>
}
Credits left are always in the POST and GET requests.
If you want to know how much credit you have left, use POST request with one empty object in data.
It will return your remaining credits whithout consuming any.
Rate Limits
If you hit the API with too many requests in a given amount of time, subsequent requests will temporarily fail.
If your client gets rate-limited, you will start receiving 429 Too Many Requests
HTTP errors in response to your requests.
Errors
Http Status codes
Error Code | Title | Description |
---|---|---|
400 | Bad Request | Your request is invalid. |
401 | Unauthorized | Your access token is wrong. |
403 | Unauthorized | API call Token exceeded quota. |
404 | Not Found | The specified resource could not be found. |
429 | Too Many Requests | Too many requests in a given slot of time. |
500 | Internal Server Error | We have been informed of this and will solve it as soon as possible. |
503 | Service Unavailable | We're temporarily offline for maintenance. Please try again later. |
504 | Service Unavailable | Gateway timeout. Please try again later. |
524 | Timeout | A timeout occured. |
Error type
Type | Value | Desctiption |
---|---|---|
email qualificiation | 'invalid' | The email you provide to the API is invalid |