NAV
python shell

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 business email address based on its name, surname and company.

Otherwise, 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.com
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, /all, which process contacts and organizations in batches. You can use the /all endpoint to process either a single contact or a batch of contacts.


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:

Copy to Clipboard
import requests

r = requests.post("https://api.dropcontact.com/v1/enrich/all",
                 headers={'X-Access-Token': apiKey})

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.

Enrich 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 endpoint you can process up to 250 contacts with a single request. One contact data must be less than 15 kB.

To launch the process POST /all, and to recover the output GET /all/{your_request_id}.

POST request

Copy to Clipboard
import requests

r = requests.post(
  "https://api.dropcontact.com/v1/enrich/all",
  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
  }
)

This request returns the following JSON:

Copy to Clipboard
{
  "error": false,
  "request_id": "your-request-id",
  "success": true,
  "credits_left": <int>
}

HTTP Request

POST https://api.dropcontact.com/v1/enrich/all

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 built 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 decoding and checking the data instead of performing a direct string comparison.

GET request

Copy to Clipboard
import requests

r = requests.get("https://api.dropcontact.com/v1/enrich/all/{}".format('your-request-id'),
                 headers={'X-Access-Token': apiKey})

This request returns this JSON if we are still processing your contacts:

Copy to Clipboard
{
  "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:

Copy to Clipboard
{
  "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.com/v1/enrich/all/your-request-id

Using the request id obtained in the POST call, 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 (it means you will receive your input data for those contacts).

We advise you to use the webhook system (explained below) if you don't want to use the GET endpoint.

API fields

Request fields

Copy to Clipboard
import requests

r = requests.post(
  "https://api.dropcontact.com/v1/enrich/all",
  json = {
    'data': [
      {
        'email': 'example_email@email.com',
        'first_name': 'Denis',
        'last_name': 'Dupont',
        'full_name': 'Denis Dupont',
        'phone': '0707070707',
        'company': 'Dropcontact',
        'website': 'https://dropcontact.com',
        "num_siren": "01010101",
        "country": "france",
        "job": "CEO"
      }
    ],
    'siren': True,
    'language': 'en'
  },
  headers={
    'Content-Type': 'application/json',
    'X-Access-Token': apiKey
  }
)

HTTP Request

POST https://api.dropcontact.com/v1/enrich/all

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
email 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
linkedin string Contact linkedin
siret string Company's siret
country string Specify the country code (e.g., ‘US’ for the United States) to base the data enrichment on that country >> more here about country codes
job string Job title
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:

Copy to Clipboard
{
  "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 :

Copy to Clipboard
{
  "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 [{email: string, qualification: string}] Yes
phone string Yes
mobile_phone string Yes
company string Yes
website string Yes
linkedin 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
country string Yes
company_linkedin string Yes
company_turnover string Yes
company_results string Yes
job string Yes
custom_fields dictionary of strings Yes

Webhooks

Instead of polling the API every 30 seconds, you can use webhooks to get notified when your data is ready. Webhooks allow you to subscribe to different types of events by specifying the event_type that interests you.

You can create multiple subscriptions to cover various event types, depending on your needs. For now, only event "enrich_api_result" is available. By default, the webhook notifications will be sent to the callback_url you specified during the subscription creation.

However, if you want to receive webhooks with a different URL "per POST request", you can include the field "custom_callback_url" in the POST request payload. This allows you to dynamically set a custom URL for specific POST requests, giving you more flexibility (especially for n8n or zapier integrations).

Note that you still need to create an active subscription with a "default" callback URL to receive webhooks on a custom_callback_url.

Create a subscription

Copy to Clipboard
# create subscription

import requests

r = requests.post(
  "https://api.dropcontact.com/v1/webhooks/subscriptions",
  json={
    "event_type": "enrich_api_result",
    "active": True,
    "callback_url": "http://your-domain.com/callback",
    "period_s": 5,
    "max_webhooks_per_period": 30
  },
  headers={
    'Content-Type': 'application/json',
    'X-Access-Token': apiKey
  }
)

If you want to receive webhooks with an URL different from the subscription one, you can include the field "custom_callback_url" in the POST request payload.

Copy to Clipboard
# optional: specify custom callback URL per POST request

import requests

r = requests.post(
  "https://api.dropcontact.com/v1/enrich/all",
  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',
    'custom_callback_url': 'http://your-domain.com/callback/my-custom-path'
  },
  headers={
    'Content-Type': 'application/json',
    'X-Access-Token': apiKey
  }
)

Send a POST request. This will create a subscription for the event type you specified and return its ID (id field), which can be used later to edit or delete it.

Explanation of the fields you must provide:

Field Type Description
event_type string The type of event you want to subscribe to. Here, it's "enrich_api_result".
active bool Indicates whether the subscription is active (true) or inactive (false).
callback_url string The URL where you want to receive webhooks for this event.
period_s int The time interval, in seconds, between consecutive webhook dispatches. This defines how often you will receive webhook batches. Must be between 1 and 60 seconds. Recommended: 5 seconds.
max_webhooks_per_period int The maximum number of webhooks to receive per period. Those webhooks can be split in multiple HTTP requests. Must be between 1 and 100. Recommended: 30.

Receive a webhook

Webhook received example :

Copy to Clipboard
[
    {
        "id": "<unique-webhook-id>",  # unique id of the webhook - this is not the request id returned by the POST request
        "version": 1,
        "event_type": "enrich_api_result",
        "occurred_at": 1623153600,
        "data": {
            "data": [{
                "first_name": "Peter",
                "last_name": "Jackson",
                ...
            }],
            "request_id": "<your-POST-request-id>",
        }
    },
    {
        ...
    }
]

The payload will contain a list of JSON webhooks. Each webhook will contain the following fields:

Field Type Description
id str Unique ID of the webhook.
version int Version of the webhook (set to 1 everytime for now).
event_type string The type of event you subscribed to.
occurred_at int Timestamp in seconds since EPOCH of the event occurrence.
data dict/list/str Data of the webhook. Here, it contains the request_id and the processed data.

See your subscriptions

Copy to Clipboard
import requests

r = requests.get(
  "https://api.dropcontact.com/v1/webhooks/subscriptions",
  headers={
    'X-Access-Token': apiKey
  }
)

You can see all your subscriptions by sending a GET request.

Edit a subscription

Copy to Clipboard
import requests

r = requests.put(
  "https://api.dropcontact.com/v1/webhooks/subscriptions/<subscription_id>",
  json={  # edit as many fields as you want in a single request
    "callback_url": "http://your-domain.com/callback"
  },
  headers={
    'Content-Type': 'application/json',
    'X-Access-Token': apiKey
  }
)

You can edit a subscription by sending a PUT request. You can change the callback URL, the period_s, the max_webhooks_per_period, or set it active/inactive.

Note that the field event_type cannot be changed. In this case, you must delete the subscription and create a new one.

Delete a subscription

Copy to Clipboard
import requests

r = requests.delete(
  "https://api.dropcontact.com/v1/webhooks/subscriptions/<subscription_id>",
  headers={
    'X-Access-Token': apiKey
  }
)

You can delete a subscription by sending a DELETE request.

You can also "pause" it using the PUT endpoint above.

Credits Policy

Credits Count

From now on, you'll only pay on success, in other word one email found or verified = 1 email charged. New pricing are thus related to new email-found model.

However, if you're an old customer, you may still have an old "enrichment-request" subscription, which means every request will cost you 1 credit.

To be upgraded on new email-found model, you don't have to do anything. You'll be switched seamlessly on next renew. You'll then enjoy the NEW V2 Boost Algo with OLD pricing conditions during 6 months. We recommend visiting www.dropcontact.com to discover the latest algorithm upgrades 🪄.

Credits Roll Over / Carry Over option

Dropcontact Carry Over option allows you to keep your credit unlimitedly in time when not fully used during a month.

Please note that a specific condition may apply on customers that were switched from old Aldo to V2 Boost in case you had a Carry Over option, former credits left will be halved on renew, since 1 OLD enrichment credit = 1/2 new email-found credit.

Credits Left

Copy to Clipboard
import requests

r = requests.post(
  "https://api.dropcontact.com/v1/enrich/all",
  json={
    'data': [
      {}
    ],
  },
  headers={
    'Content-Type': 'application/json',
    'X-Access-Token': apiKey
  }
)

This request returns the following JSON:

Copy to Clipboard
{
  "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
python shell