NAV Navbar
Python Shell
  • Introduction
  • Authentication
  • Batch Endpoint
  • API fields
  • Rate Limits
  • Errors
  • Introduction

    Welcome to the Dropcontact API!

    Among other things, you can use our API to:

    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'}]},
                     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

    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.

    API fields

    Request fields

    import requests
    
    r = requests.post("https://api.dropcontact.io/batch",
                     json={
                     'email': 'example_email@email.com',
                     'siren': True
                     'first_name': 'Denis',
                     'last_name': 'Dupont',
                     'full_name': 'Denis Dupont',
                     'phone': '0707070707',
                     'company': 'Dropcontact',
                     'website': 'https://dropcontact.io'
                     },
                     headers={
                     'Content-Type': 'application/json',
                     'X-Access-Token': apiKey
                     })
    
    curl -X POST
      -H "Content-Type: application/json"
      -H "X-Access-Token: apiKey"
      -d '{
        "email": "example_email@email.com",
        "siren": true,
        "first_name": "Denis",
        "last_name": "Dupont",
        "full_name": "Denis Dupont",
        "phone": "0707070707",
        "company": "Dropcontact",
        "website": "https://dropcontact.io"}'
      'https://api.dropcontact.io/batch'
    

    HTTP Request

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

    URL Optionnal Parameters

    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
    siren boolean True if you want the SIREN number

    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",
      "facebook": "https://www.facebook.com/denis.dupont",
      "twitter": "https://twitter.com/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",
    }
    

    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
    company string Yes
    website string Yes
    linkedin string Yes
    facebook string Yes
    twitter 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

    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