NAV Navbar
Python Shell
  • Introduction
  • Authentication
  • Batch Endpoint
  • API fields
  • Credits Left
  • Rate Limits
  • Errors
  • 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
    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 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 [{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
    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