NAV Navbar
Python Shell
  • Introduction
  • Authentication
  • Batch Endpoint
  • API fields
  • 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
    non_confirm 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 authentification.

    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.

    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
      },
      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"
          }
        ],
        'siren': True
      },
      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"
          }
        ],
        "siren": True
      }'
      'https://api.dropcontact.io/batch'
    

    HTTP Request

    POST https://api.dropcontact.io/batch

    Request body

    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

    Response fields

    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"
    }
    

    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
    company_infogreffe 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

    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