VoilaNorbert API Reference

API Endpoint

Our API follows the REST principle.

All API requests must be made over HTTPS. Call made otherwise will fail.

API Endpoint

The API endpoint is https://api.voilanorbert.com/2018-01-08/.

Authentication

Authentication against our API is performed via HTTP Basic Auth.

Use the API key in show in Integrations[link] or that we also send you by email as the password. You can pass any string you want as the username (it’s ignored).

any_string:{secure_token}

An Python example:

requests.get('https://api.voilanorbert.com/2018-01-08/contacts/', auth=('any_string', '{secure_token}'))

How do we determine your credits

Prospecting Service

We only deduct 1 credit each time we return a successful result from a search, i.e. when we find at least one email.

Every time you lookup an email, a contact is created. If you search a second time for that same contact, we won’t deduct a second credits, except if you removed that contact from your account.

Enrich & Verify Services

You are charged for each email you want to enrich or verify by this service. Please check pricing page for the details. https://www.voilanorbert.com/pricing/

API Rate Limit

By default, we limit the number of requests to 120 requests per minutes. Some endpoints allow for less requests, like the search engine, to avoid overage.

The number of requests available and the time it will reset are given in the response of each requests. We use the standard X-RateLimit headers as follows:

X-RateLimit-Remaining: 100
X-RateLimit-Limit: 120
X-RateLimit-Reset: 1466368960

The 120 requests/minute is the default. We tell you if it is not in each endpoint. If you need something faster ask us.

HTTP Status Code

We use the traditional HTTP status codes to indicate the state of your request.

Codes in the 2xx range indicate success
Codes in the 4xx range indicate an error from your side
Codes in the 5xx range indicate a fatal error on our side

Some of the more often used status codes are:

For success :

200 : Everything is good, with data provided
202 : Processing the data submitted
204 : No content (often returned with DELETE requests)

For errors :

400 : Bad request, often along with a form submission
401 : Account not found, when authenticating
402 : No credits left, returned on the search page
429 : Too many requets made in the timeframe indicated

Errors

We do our best to provide you with more informations whenever possible.

When we return additional details the content will be a JSON message with the following elements:

code: integer
It's the same value as the HTTP Status Code
error: string
Contains a more advanced message for the corresponding error.
For example : Too many requests in the allowed time frame (120 requests per minutes).

{
  "code": 429,
  "error": "Too many requests in the allowed time frame (120 requests per minutes)"
}

When you submit a form (POST), if there are errors with the data submitted the JSON response will be more detailed:

{
  "email": [
    "Invalid password or account does not exists."
  ]
}

Search Endpoint ¶

Resource ¶

POST /search/name

RequestsDefinitionPythonCurl

Headers

Content-Type: application/x-www-form-urlencoded

Body

name = "Cyril Nicodeme" &
domain = "reflectiv.net"

Responses200400

Headers

Content-Type: application/json

Body

{
  "company": {
    "description": null,
    "is_done": true,
    "keywords": [
      "Some",
      "Keywords",
      "For",
      "This",
      "Domain"
    ],
    "logo": "https://logo.clearbit.com/example.com",
    "name": "Example Website",
    "raw_url": "example.com",
    "title": "Example.com super website !",
    "url": "http://www.example.com"
  },
  "created": 1465371124000,
  "email": {
    "avatar_url": "https://secure.gravatar.com/avatar/abcde&s=128",
    "email": "email@example.com",
    "is_done": true,
    "score": 100
  },
  "id": 12345,
  "lists": [],
  "name": "Fake User",
  "owner": {
    "admin": true,
    "avatar_url": "https://secure.gravatar.com/avatar/54321?d=mm&s=128",
    "email": "user@voilanorbert.com",
    "firstname": "Cyril",
    "language": "en",
    "name": "Cyril"
  },
  "searching": false,
  "status": "LEAD"
}

Headers

Content-Type: application/json

Body

{
  "name": [
    "This field is required."
  ]
}

Body

import requests, time

# Here's a quick sample Python code that implements the algorithm :

API_TOKEN = 'abcde'

req = requests.post(
  'https://api.voilanorbert.com/2018-01-08/search/name',
  auth=('any_string', API_TOKEN),
  data = {
      'name': 'Cyril Nicodeme',
      'domain': 'reflectiv.net'
  },
  headers={'Content-Type': 'application/x-www-form-urlencoded'}
  )

  if req.status_code != 200:
    return None

  result = req.json()

  while True:
    contact_r = requests.get('https://api.voilanorbert.com/2018-01-08/contacts/{0}'.format(result['id']), auth=('any_string', API_TOKEN))
    if contact_r.status_code == 200:
        contact = contact_r.json()

        if contact['searching'] is False:
            # TODO : Update your database here
            if contact['email']:
                # Email found !
                print "Found email : {0} with score : {1}".format(contact['email']['email'], contact['email']['score'])
            else:
                print "Email not found!"

            break

    time.sleep(10)

Responses200400

Headers

Content-Type: application/json

Body

{
  "company": {
    "description": null,
    "is_done": true,
    "keywords": [
      "Some",
      "Keywords",
      "For",
      "This",
      "Domain"
    ],
    "logo": "https://logo.clearbit.com/example.com",
    "name": "Example Website",
    "raw_url": "example.com",
    "title": "Example.com super website !",
    "url": "http://www.example.com"
  },
  "created": 1465371124000,
  "email": {
    "avatar_url": "https://secure.gravatar.com/avatar/abcde&s=128",
    "email": "email@example.com",
    "is_done": true,
    "score": 100
  },
  "id": 12345,
  "lists": [],
  "name": "Fake User",
  "owner": {
    "admin": true,
    "avatar_url": "https://secure.gravatar.com/avatar/54321?d=mm&s=128",
    "email": "user@voilanorbert.com",
    "firstname": "Cyril",
    "language": "en",
    "name": "Cyril"
  },
  "searching": false,
  "status": "LEAD"
}

Headers

Content-Type: application/json

Body

{
  "name": [
    "This field is required."
  ]
}

Body

curl -X POST https://api.voilanorbert.com/2018-01-08/search/name \
 -u any_string:{secure_token} \
 -d domain="example.com" \
 -d name="Fake User"

Responses200400

Headers

Content-Type: application/json

Body

{
  "company": {
    "description": null,
    "is_done": true,
    "keywords": [
      "Some",
      "Keywords",
      "For",
      "This",
      "Domain"
    ],
    "logo": "https://logo.clearbit.com/example.com",
    "name": "Example Website",
    "raw_url": "example.com",
    "title": "Example.com super website !",
    "url": "http://www.example.com"
  },
  "created": 1465371124000,
  "email": {
    "avatar_url": "https://secure.gravatar.com/avatar/abcde&s=128",
    "email": "email@example.com",
    "is_done": true,
    "score": 100
  },
  "id": 12345,
  "lists": [],
  "name": "Fake User",
  "owner": {
    "admin": true,
    "avatar_url": "https://secure.gravatar.com/avatar/54321?d=mm&s=128",
    "email": "user@voilanorbert.com",
    "firstname": "Cyril",
    "language": "en",
    "name": "Cyril"
  },
  "searching": false,
  "status": "LEAD"
}

Headers

Content-Type: application/json

Body

{
  "name": [
    "This field is required."
  ]
}

POST`/search/name`

Search emails are based on the full name plus the domain or company name.

When your account does not have sufficient credits an HTTP status code of 402 is returned.

Also, take into consideration that we check the domain for its validity. So even if you provide a correct name+domain set, we may return a HTTP status code of 400 for the domain if we can’t locate it.

Due to the complex work involved, this endpoint is limited to 300 requests per minutes, and up to 100,000 requests per day max.

You can provide a callback url using a webhook parameter. We will send a POST request to this URL and expect a status code of 2xx. If we get something else, we will try again 2 more times incrementing the interval 30 seconds between each of the requests. After the third request, the server will stop trying.

The searching boolean returned by the server will let you know if the server is searching for that contact of it has already been found. You can then try to send a GET request to the contact (GET /contact/{id}) to get the same response as this request, and wait for the searching parameter to be true.

The contact object returned also includes email data. When searching, this data is set to null. Once the search is done, if we found the corresponding email, the email becomes an object containing information including the email value and the score related to this email.

The score value can have multiple values :

100 : We found the email and checked it against the mail server and it appears to be valid
80 : We found the email but we were unable to validate it against the mail server.
5 : We found the email using outside services but we can’t verify its validity.

A good rule of thumb is to send the POST request to the search endpoint, then do a while true to request GET /contacts/{id} until searching is true.

URI Parameters

HideShow

name: string (required) Example: "Larry Page"
Full name of the person to search.
domain: string (required) Example: "Google.com"
The domain of the company. (Either domain or company is required)
company: string (required) Example: "Google"
The name of the company. (Either domain or company is required)
webhook: string (optional) Example: "http://requestb.in/aaaaaa"
URL where the result will be POSTed
list_id: integer (optional) Example: 1
A List ID the contact will affected to.

Resource ¶

POST /search/domain

RequestsDefinitionPythonCurl

Headers

Content-Type: application/x-www-form-urlencoded

Body

domain = "reflectiv.net"

Responses200400

Headers

Content-Type: application/json

Body

{
  "has_next": true,
  "result": [
    {
      "company": {
        "description": null,
        "is_done": true,
        "keywords": [
          "Some",
          "Keywords",
          "For",
          "This",
          "Domain"
        ],
        "logo": "https://logo.clearbit.com/example.com",
        "name": "Example Website",
        "raw_url": "example.com",
        "title": "Example.com super website !",
        "url": "http://www.example.com"
      },
      "created": 1465371124000,
      "email": {
        "avatar_url": "https://secure.gravatar.com/avatar/abcde&s=128",
        "email": "second@example.com",
        "is_done": true,
        "score": 100
      },
      "id": 12345,
      "lists": [],
      "name": "Second User",
      "owner": {
        "admin": true,
        "avatar_url": "https://secure.gravatar.com/avatar/54321?d=mm&s=128",
        "email": "user@voilanorbert.com",
        "firstname": "Cyril",
        "language": "en",
        "name": "Cyril"
      },
      "is_new": false,
      "searching": false,
      "status": "LEAD"
    },
    {
      "company": {
        "description": null,
        "is_done": true,
        "keywords": [
          "Some",
          "Keywords",
          "For",
          "This",
          "Domain"
        ],
        "logo": "https://logo.clearbit.com/example.com",
        "name": "Example Website",
        "raw_url": "example.com",
        "title": "Example.com super website !",
        "url": "http://www.example.com"
      },
      "created": 1465371184000,
      "email": null,
      "id": 12346,
      "lists": [],
      "name": "Fake User",
      "owner": {
        "admin": true,
        "avatar_url": "https://secure.gravatar.com/avatar/987654?d=mm&s=128",
        "email": "user@voilanorbert.com",
        "firstname": "Cyril",
        "language": "en",
        "name": "Cyril"
      },
      "is_new": true,
      "searching": false,
      "status": "CONTACTED"
    }
  ],
  "credits_available": true,
  "total": 2
}

Headers

Content-Type: application/json

Body

{
  "name": [
    "This field is required."
  ]
}

Body

import requests, time

# Here's a quick sample Python code that implements the algorithm :

API_TOKEN = 'abcde'

req = requests.post(
  'https://api.voilanorbert.com/2018-01-08/search/domain',
  auth=('any_string', API_TOKEN),
  data = {
      'domain': 'reflectiv.net'
  },
  headers={'Content-Type': 'application/x-www-form-urlencoded'}
)

Responses200400

Headers

Content-Type: application/json

Body

{
  "has_next": true,
  "result": [
    {
      "company": {
        "description": null,
        "is_done": true,
        "keywords": [
          "Some",
          "Keywords",
          "For",
          "This",
          "Domain"
        ],
        "logo": "https://logo.clearbit.com/example.com",
        "name": "Example Website",
        "raw_url": "example.com",
        "title": "Example.com super website !",
        "url": "http://www.example.com"
      },
      "created": 1465371124000,
      "email": {
        "avatar_url": "https://secure.gravatar.com/avatar/abcde&s=128",
        "email": "second@example.com",
        "is_done": true,
        "score": 100
      },
      "id": 12345,
      "lists": [],
      "name": "Second User",
      "owner": {
        "admin": true,
        "avatar_url": "https://secure.gravatar.com/avatar/54321?d=mm&s=128",
        "email": "user@voilanorbert.com",
        "firstname": "Cyril",
        "language": "en",
        "name": "Cyril"
      },
      "is_new": false,
      "searching": false,
      "status": "LEAD"
    },
    {
      "company": {
        "description": null,
        "is_done": true,
        "keywords": [
          "Some",
          "Keywords",
          "For",
          "This",
          "Domain"
        ],
        "logo": "https://logo.clearbit.com/example.com",
        "name": "Example Website",
        "raw_url": "example.com",
        "title": "Example.com super website !",
        "url": "http://www.example.com"
      },
      "created": 1465371184000,
      "email": null,
      "id": 12346,
      "lists": [],
      "name": "Fake User",
      "owner": {
        "admin": true,
        "avatar_url": "https://secure.gravatar.com/avatar/987654?d=mm&s=128",
        "email": "user@voilanorbert.com",
        "firstname": "Cyril",
        "language": "en",
        "name": "Cyril"
      },
      "is_new": true,
      "searching": false,
      "status": "CONTACTED"
    }
  ],
  "credits_available": true,
  "total": 2
}

Headers

Content-Type: application/json

Body

{
  "name": [
    "This field is required."
  ]
}

Body

curl -X POST https://api.voilanorbert.com/2018-01-08/search/domain \
 -u any_string:{secure_token} \
 -d domain="example.com"

Responses200400

Headers

Content-Type: application/json

Body

{
  "has_next": true,
  "result": [
    {
      "company": {
        "description": null,
        "is_done": true,
        "keywords": [
          "Some",
          "Keywords",
          "For",
          "This",
          "Domain"
        ],
        "logo": "https://logo.clearbit.com/example.com",
        "name": "Example Website",
        "raw_url": "example.com",
        "title": "Example.com super website !",
        "url": "http://www.example.com"
      },
      "created": 1465371124000,
      "email": {
        "avatar_url": "https://secure.gravatar.com/avatar/abcde&s=128",
        "email": "second@example.com",
        "is_done": true,
        "score": 100
      },
      "id": 12345,
      "lists": [],
      "name": "Second User",
      "owner": {
        "admin": true,
        "avatar_url": "https://secure.gravatar.com/avatar/54321?d=mm&s=128",
        "email": "user@voilanorbert.com",
        "firstname": "Cyril",
        "language": "en",
        "name": "Cyril"
      },
      "is_new": false,
      "searching": false,
      "status": "LEAD"
    },
    {
      "company": {
        "description": null,
        "is_done": true,
        "keywords": [
          "Some",
          "Keywords",
          "For",
          "This",
          "Domain"
        ],
        "logo": "https://logo.clearbit.com/example.com",
        "name": "Example Website",
        "raw_url": "example.com",
        "title": "Example.com super website !",
        "url": "http://www.example.com"
      },
      "created": 1465371184000,
      "email": null,
      "id": 12346,
      "lists": [],
      "name": "Fake User",
      "owner": {
        "admin": true,
        "avatar_url": "https://secure.gravatar.com/avatar/987654?d=mm&s=128",
        "email": "user@voilanorbert.com",
        "firstname": "Cyril",
        "language": "en",
        "name": "Cyril"
      },
      "is_new": true,
      "searching": false,
      "status": "CONTACTED"
    }
  ],
  "credits_available": true,
  "total": 2
}

Headers

Content-Type: application/json

Body

{
  "name": [
    "This field is required."
  ]
}

POST`/search/domain`

Search emails are based on the domain or company name.

When your account does not have sufficient credits an HTTP status code of 402 is returned.

Also, take into consideration that we check the domain for its validity. So even if you provide a correct domain, we may return a HTTP status code of 400 for the domain if we can’t locate it.

The field is_new indicates that if the contact is recently found or already in your contact list.

Due to the complex work involved, this endpoint is limited to 60 requests per minutes, and up to 50,000 requests per day max.

URI Parameters

HideShow

domain: string (required) Example: "Google.com"
The domain of the company. (Either domain or company is required)
company: string (required) Example: "Google"
The name of the company. (Either domain or company is required)
list_id: integer (optional) Example: 1
A List ID the contact will attached to.
page: integer (optional) Example: 1
Current page to retrieve

Bulk Search Endpoint ¶

Bulk operations ¶

POST /massives/

RequestsDefinitionPythonCurl

Headers

Content-Type: application/x-www-form-urlencoded

Body

col_name = "0,1" &
col_company = "3" &
content = "Ned,Stark,voilanorbert.com,VoilaNorbert" &
file_url = "https://mybucket.s3.amazonaws.com/mycsvfile.csv" &
webhook = "http://requestb.in/aaaaaa" &
rerun_frequency = 0 &
webhook_file_retention_time = 3

Responses200400

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "created": 1545721762000,
  "enrich": false,
  "enrich_token": null,
  "filename": "upload.csv",
  "rerun_frequency": 720,
  "rerun_lasttime": 1545721762000,
  "webhook": "your webhook url",
  "id": 779,
  "list_id": 787,
  "quantity": 0,
  "status": "QUEUED",
  "success": 0,
  "treated": 0,
  "updated": 1545721762000
}

Headers

Content-Type: application/json

Body

{
  "col_name": [
    "This field is required."
  ]
}

Body

import requests, time

# Here's a quick sample Python code that implements the algorithm :

API_TOKEN = 'abcde'

req = requests.post(
  'https://api.voilanorbert.com/2018-01-08/massives/',
  auth=('any_string', API_TOKEN),
  data = {
      'col_name': '0,1',
      'col_company': '3',
      'content': 'Ned,Stark,voilanorbert.com,VoilaNorbert
      Arya,Stark,voilanorbert.com,VoilaNorbert',
      'webhook': 'your webhook url',
      'rerun_frequency': 720 # For a reprocess request every month,
      'webhook_file_retention_time' : 3 # 3 hours
  },
  headers={'Content-Type': 'application/x-www-form-urlencoded'}
)

Responses200400

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "created": 1545721762000,
  "enrich": false,
  "enrich_token": null,
  "filename": "upload.csv",
  "rerun_frequency": 720,
  "rerun_lasttime": 1545721762000,
  "webhook": "your webhook url",
  "id": 779,
  "list_id": 787,
  "quantity": 0,
  "status": "QUEUED",
  "success": 0,
  "treated": 0,
  "updated": 1545721762000
}

Headers

Content-Type: application/json

Body

{
  "col_name": [
    "This field is required."
  ]
}

Body

curl -X POST https://api.voilanorbert.com/2018-01-08/massives/ \
 -u any_string:{secure_token} \
 -d col_name="0,1" \
 -d col_company="3" \
 -d content="Ned,Stark,voilanorbert.com,VoilaNorbert \
          Arya,Stark,voilanorbert.com,VoilaNorbert" \
 -d webhook="your webhook url" \
 -d rerun_frequency=720 \
 -d webhook_file_retention_time=3

Responses200400

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "created": 1545721762000,
  "enrich": false,
  "enrich_token": null,
  "filename": "upload.csv",
  "rerun_frequency": 720,
  "rerun_lasttime": 1545721762000,
  "webhook": "your webhook url",
  "id": 779,
  "list_id": 787,
  "quantity": 0,
  "status": "QUEUED",
  "success": 0,
  "treated": 0,
  "updated": 1545721762000
}

Headers

Content-Type: application/json

Body

{
  "col_name": [
    "This field is required."
  ]
}

Submit a bulk file
POST`/massives/`

Search emails for the given bulk content based on the full name plus the domain or company name provided as line separated.

When your account does not have sufficient credits an HTTP status code of 402 is returned.

Also, take into consideration that we check each domain for its validity.

Due to the complex work involved, this endpoint is limited to 5 requests per minutes, and up to 1,000 requests per day max.

You need provide a callback url using a webhook parameter. We will send a POST request to this URL and expect a status code of 2xx. If we get something else, we will try again 2 more times incrementing the interval 30 seconds between each of the requests. After the third request, the server will stop trying. For the safety of resulted bulk file, you can provide optional retention time as webhook_file_retention_time. It is an integer value that will be evaluated as hour. File won’t be available after webhook_file_retention_time passes. The json content of the webhook result will be in a structure like:

{“success”: 6, “origin_id”: null, “result_file”: "https://api.voilanorbert.com/2018-01-08/massives/download/019ba731-result.csv", “treated”: 10, “id”: 778, “quantity”: 10}

There are two ways to provide the content. For a successful request, you need to provide one of these two POST parameters.

file_url: You may prefer to send a link to a csv file.
content: You may prefer to send the content of a csv file directly.

GET /massives/?offset=0&limit=100

RequestsPythonCurl

Body

import requests, time

# Here's a quick sample Python code that implements the algorithm :

API_TOKEN = 'abcde'

req = requests.post(
  'https://api.voilanorbert.com/2018-01-08/massives/?offset=0&limit=100',
  auth=('any_string', API_TOKEN)
)

Responses200

Headers

Content-Type: application/json

Body

{
  "result": [
    {
      "account": {
        "email": "account email",
        "firstname": "account firstname",
        "name": "account name",
        "plan": null
      },
      "created": 1629100703000,
      "enrich": false,
      "enrich_token": null,
      "filename": "test3.csv",
      "id": 1,
      "list_id": 1,
      "quantity": 2,
      "rerun_frequency": null,
      "rerun_last_time": 1629100703000,
      "status": "ENDED",
      "success": 1,
      "treated": 2,
      "updated": 1629100791000,
      "webhook": null
    },
    {
      "account": {
        "email": "account email",
        "firstname": "account firstname",
        "name": "account name",
        "plan": null
      },
      "created": 1629096845000,
      "enrich": false,
      "enrich_token": null,
      "filename": "test1.csv",
      "id": 2,
      "list_id": 1,
      "quantity": 2,
      "rerun_frequency": null,
      "rerun_last_time": 1629096845000,
      "status": "ENDED",
      "success": 1,
      "treated": 2,
      "updated": 1629096885000,
      "webhook": null
    },
    {
      "account": {
        "email": "account email",
        "firstname": "account firstname",
        "name": "account name",
        "plan": null
      },
      "created": 1629096804000,
      "enrich": false,
      "enrich_token": null,
      "filename": "test2.csv",
      "id": 3,
      "list_id": 1,
      "quantity": 2,
      "rerun_frequency": null,
      "rerun_last_time": 1629096804000,
      "status": "ENDED",
      "success": 1,
      "treated": 2,
      "updated": 1629096878000,
      "webhook": null
    }
  ]
}

Body

curl -X PUT https://api.voilanorbert.com/2018-01-08/massives/?offset=0&limit=100 \
 -u any_string:{secure_token}

Responses200

Headers

Content-Type: application/json

Body

{
  "result": [
    {
      "account": {
        "email": "account email",
        "firstname": "account firstname",
        "name": "account name",
        "plan": null
      },
      "created": 1629100703000,
      "enrich": false,
      "enrich_token": null,
      "filename": "test3.csv",
      "id": 1,
      "list_id": 1,
      "quantity": 2,
      "rerun_frequency": null,
      "rerun_last_time": 1629100703000,
      "status": "ENDED",
      "success": 1,
      "treated": 2,
      "updated": 1629100791000,
      "webhook": null
    },
    {
      "account": {
        "email": "account email",
        "firstname": "account firstname",
        "name": "account name",
        "plan": null
      },
      "created": 1629096845000,
      "enrich": false,
      "enrich_token": null,
      "filename": "test1.csv",
      "id": 2,
      "list_id": 1,
      "quantity": 2,
      "rerun_frequency": null,
      "rerun_last_time": 1629096845000,
      "status": "ENDED",
      "success": 1,
      "treated": 2,
      "updated": 1629096885000,
      "webhook": null
    },
    {
      "account": {
        "email": "account email",
        "firstname": "account firstname",
        "name": "account name",
        "plan": null
      },
      "created": 1629096804000,
      "enrich": false,
      "enrich_token": null,
      "filename": "test2.csv",
      "id": 3,
      "list_id": 1,
      "quantity": 2,
      "rerun_frequency": null,
      "rerun_last_time": 1629096804000,
      "status": "ENDED",
      "success": 1,
      "treated": 2,
      "updated": 1629096878000,
      "webhook": null
    }
  ]
}

List bulk files
GET`/massives/{?offset,limit}`

Retrieves the uploaded bulk files by chronological order.

URI Parameters

HideShow

offset: number (optional) Example: 0
Offset to start the search from
limit: number (optional) Example: 100
Maximum number of items to return

Bulk item operations ¶

GET /massives/MassiveId

RequestsCurl

Body

curl https://api.voilanorbert.com/2018-01-08/massives/1001 \
 -u any_string:{secure_token}

Responses200

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "created": 1545721762000,
  "enrich": false,
  "enrich_token": null,
  "filename": "upload.csv",
  "rerun_frequency": 720,
  "rerun_lasttime": 1545721762000,
  "webhook": "your webhook url",
  "id": 779,
  "list_id": 787,
  "quantity": 0,
  "status": "QUEUED",
  "success": 0,
  "treated": 0,
  "updated": 1545721762000
}

Retrieve
GET`/massives/{id}`

Returns the latest status of the massive with given id. If massive is not found or API key does not have admin permission you will receive a 400 error.

URI Parameters

HideShow

id: number (required) Example: MassiveId
The massive’s id

DELETE /massives/MassiveId

RequestsDefinitionCurl

Headers

Content-Type: application/x-www-form-urlencoded

Body

recursive = false

Responses200

Headers

Content-Type: application/json

Body

{
  "result": "success"
}

Body

curl -X DELETE https://api.voilanorbert.com/2018-01-08/massives/<id> \
 -u any_string:{secure_token}

Responses200

Headers

Content-Type: application/json

Body

{
  "result": "success"
}

Remove
DELETE`/massives/{id}`

Removes the massive from the account. If recursive boolean form parameter is provided as true, it removes all the related data including lists, and contacts.

URI Parameters

HideShow

id: number (required) Example: MassiveId
The massive’s id

POST /massives/MassiveId/resume

RequestsPythonCurl

Body

import requests, time

# Here's a quick sample Python code that implements the algorithm :

API_TOKEN = 'abcde'

req = requests.post(
  'https://api.voilanorbert.com/2018-01-08/massives/779/resume',
  auth=('any_string', API_TOKEN)
)

Responses200

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "created": 1545721762000,
  "enrich": false,
  "enrich_token": null,
  "filename": "upload.csv",
  "rerun_frequency": 720,
  "rerun_lasttime": 1545721762000,
  "webhook": "your webhook url",
  "id": 779,
  "list_id": 787,
  "quantity": 0,
  "status": "PROCESSING",
  "success": 0,
  "treated": 0,
  "updated": 1545721762000
}

Body

curl -X PUT https://api.voilanorbert.com/2018-01-08/massives/779/resume \
 -u any_string:{secure_token}

Responses200

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "created": 1545721762000,
  "enrich": false,
  "enrich_token": null,
  "filename": "upload.csv",
  "rerun_frequency": 720,
  "rerun_lasttime": 1545721762000,
  "webhook": "your webhook url",
  "id": 779,
  "list_id": 787,
  "quantity": 0,
  "status": "PROCESSING",
  "success": 0,
  "treated": 0,
  "updated": 1545721762000
}

Resume
POST`/massives/{id}/resume`

Resumes the paused massive with given id.

URI Parameters

HideShow

id: number (required) Example: MassiveId
The massive’s id

POST /massives/massiveId/pause

RequestsPythonCurl

Body

import requests, time

# Here's a quick sample Python code that implements the algorithm :

API_TOKEN = 'abcde'

req = requests.post(
  'https://api.voilanorbert.com/2018-01-08/massives/779/pause',
  auth=('any_string', API_TOKEN)
)

Responses200

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "created": 1545721762000,
  "enrich": false,
  "enrich_token": null,
  "filename": "upload.csv",
  "rerun_frequency": 720,
  "rerun_lasttime": 1545721762000,
  "webhook": "your webhook url",
  "id": 779,
  "list_id": 787,
  "quantity": 0,
  "status": "PAUSED",
  "success": 0,
  "treated": 0,
  "updated": 1545721762000
}

Body

curl -X PUT https://api.voilanorbert.com/2018-01-08/massives/779/pause \
 -u any_string:{secure_token}

Responses200

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "created": 1545721762000,
  "enrich": false,
  "enrich_token": null,
  "filename": "upload.csv",
  "rerun_frequency": 720,
  "rerun_lasttime": 1545721762000,
  "webhook": "your webhook url",
  "id": 779,
  "list_id": 787,
  "quantity": 0,
  "status": "PAUSED",
  "success": 0,
  "treated": 0,
  "updated": 1545721762000
}

Pause
POST`/massives/{id}/pause`

Pauses an active massive with given id.

URI Parameters

HideShow

id: number (required) Example: massiveId
The massive’s id

PUT /massives/massiveId/rerun

RequestsDefinitionPythonCurl

Headers

Content-Type: application/x-www-form-urlencoded

Body

rerun_frequency = 720

Responses200400

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "created": 1545721762000,
  "enrich": false,
  "enrich_token": null,
  "filename": "upload.csv",
  "rerun_frequency": 720,
  "rerun_lasttime": 1545721762000,
  "webhook": "your webhook url",
  "id": 779,
  "list_id": 787,
  "quantity": 0,
  "status": "QUEUED",
  "success": 0,
  "treated": 0,
  "updated": 1545721762000
}

Headers

Content-Type: application/json

Body

{
  "rerun_frequency": [
    "This field is required."
  ]
}

Body

import requests, time

# Here's a quick sample Python code that implements the algorithm :

API_TOKEN = 'abcde'

req = requests.put(
  'https://api.voilanorbert.com/2018-01-08/massives/779/rerun',
  auth=('any_string', API_TOKEN),
  data = {
      'rerun_frequency': 720 # For a reprocess request every month
  },
  headers={'Content-Type': 'application/x-www-form-urlencoded'}
)

Responses200400

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "created": 1545721762000,
  "enrich": false,
  "enrich_token": null,
  "filename": "upload.csv",
  "rerun_frequency": 720,
  "rerun_lasttime": 1545721762000,
  "webhook": "your webhook url",
  "id": 779,
  "list_id": 787,
  "quantity": 0,
  "status": "QUEUED",
  "success": 0,
  "treated": 0,
  "updated": 1545721762000
}

Headers

Content-Type: application/json

Body

{
  "rerun_frequency": [
    "This field is required."
  ]
}

Body

curl -X PUT https://api.voilanorbert.com/2018-01-08/massives/779/rerun \
 -u any_string:{secure_token} \
 -d rerun_frequency=720

Responses200400

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "created": 1545721762000,
  "enrich": false,
  "enrich_token": null,
  "filename": "upload.csv",
  "rerun_frequency": 720,
  "rerun_lasttime": 1545721762000,
  "webhook": "your webhook url",
  "id": 779,
  "list_id": 787,
  "quantity": 0,
  "status": "QUEUED",
  "success": 0,
  "treated": 0,
  "updated": 1545721762000
}

Headers

Content-Type: application/json

Body

{
  "rerun_frequency": [
    "This field is required."
  ]
}

Set rerun
PUT`/massives/{id}/rerun`

Updates the rerun frequency of the given massive to the provided rerun_frequency post data

URI Parameters

HideShow

id: number (required) Example: massiveId
The massive’s id

DELETE /massives/massiveId/rerun

RequestsPythonCurl

Body

import requests, time

# Here's a quick sample Python code that implements the algorithm :

API_TOKEN = 'abcde'

req = requests.delete(
  'https://api.voilanorbert.com/2018-01-08/massives/779/rerun',
  auth=('any_string', API_TOKEN)
)

Responses200

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "created": 1545721762000,
  "enrich": false,
  "enrich_token": null,
  "filename": "upload.csv",
  "rerun_frequency": null,
  "rerun_lasttime": 1545721762000,
  "webhook": "your webhook url",
  "id": 779,
  "list_id": 787,
  "quantity": 0,
  "status": "QUEUED",
  "success": 0,
  "treated": 0,
  "updated": 1545721762000
}

Body

curl -X DELETE https://api.voilanorbert.com/2018-01-08/massives/779/rerun \
 -u any_string:{secure_token}

Responses200

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "created": 1545721762000,
  "enrich": false,
  "enrich_token": null,
  "filename": "upload.csv",
  "rerun_frequency": null,
  "rerun_lasttime": 1545721762000,
  "webhook": "your webhook url",
  "id": 779,
  "list_id": 787,
  "quantity": 0,
  "status": "QUEUED",
  "success": 0,
  "treated": 0,
  "updated": 1545721762000
}

Reset rerun
DELETE`/massives/{id}/rerun`

Cancels reruning of the given massiveata.

URI Parameters

HideShow

id: number (required) Example: massiveId
The massive’s id

Account ¶

Resource ¶

GET /account/

RequestsCurl

Body

curl https://api.voilanorbert.com/2018-01-08/account/ \
 -u any_string:{secure_token}

Responses200

Headers

Content-Type: application/json

Body

{
  "admin": true,
  "api_token": "48da1831-dfeb-4e09-a0d8-d2d0ed11637f",
  "avatar_url": "https://secure.gravatar.com/avatar/b58d13722f80bead69d9a4f9ae208020?d=mm&s=128",
  "balance": {
    "enrich": {
      "processed_entries": 44,
      "refill_amount": 50,
      "refill_limit": 10,
      "remaining": 50.76
    },
    "verify": {
      "processed_entries": 251,
      "refill_amount": 50,
      "refill_limit": 10,
      "remaining": 51.685
    }
  },
  "created": 1500401705000,
  "credits": {
    "charge_failed": 0,
    "refill_credits": 100,
    "refill_limit": 279000,
    "refill_price": 50,
    "remains": 467999,
    "total": 478750
  },
  "email": "user@voilanorbert.com",
  "firstname": "Norbert",
  "has_cc": true,
  "is_account_verified": true,
  "language": "en",
  "name": "Norbert",
  "optin": false,
  "phone_verified": null,
  "plan": {
    "credits": 15000,
    "display": "Advisor",
    "rollover": false,
    "workers": 50,
    "yearly": false
  }
}

GET`/account/`

Returns information about the current account, plan details if exists, credit and api balance details.

Organization ¶

Resource ¶

GET /organization/

RequestsCurl

Body

curl https://api.voilanorbert.com/2018-01-08/organization/ \
 -u any_string:{secure_token}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "company_name": "Voilanorbert",
  "company_vat": null,
  "address": "",
  "zipcode": "90800",
  "city": "BELFORT",
  "country": "France",
  "is_auto_renew": true,
  "auto_renew_at": 10,
  "auto_renew_quantity": 1000,
  "cc_expires": 1575158400000,
  "plan": {
    "credits": 10000,
    "id": 3,
    "name": "Advisor",
    "price": 249
  },
  "is_yearly": false,
  "next_payment": 1466899200000,
  "credits": {
    "remains": 1234,
    "total": 12345
  }
}

GET`/organization/`

Retrieve information about the organization.

Credits ¶

Resource ¶

GET /organization/credits/

RequestsCurl

Body

curl https://api.voilanorbert.com/2018-01-08/organization/credits \
 -u any_string:{secure_token}

Responses200

Headers

Content-Type: application/json

Body

{
  "charge_failed": 0,
  "refill_credits": 100,
  "refill_limit": 279000,
  "refill_price": 50,
  "remains": 467999,
  "total": 478750
}

GET`/organization/credits/`

Retrieve the current remaining credits and the total available.

Contacts ¶

Resource ¶

GET /contacts/

RequestsCurl

Body

curl https://api.voilanorbert.com/2018-01-08/contacts/?order_by=-name&name=larry \
 -u any_string:{secure_token}

Responses200

Headers

Content-Type: application/json

Body

{
  "has_next": true,
  "has_prev": false,
  "page": 1,
  "pages": 1,
  "result": [
    {
      "company": {
        "description": null,
        "is_done": true,
        "keywords": [
          "Some",
          "Keywords",
          "For",
          "This",
          "Domain"
        ],
        "logo": "https://logo.clearbit.com/example.com",
        "name": "Example Website",
        "raw_url": "example.com",
        "title": "Example.com super website !",
        "url": "http://www.example.com"
      },
      "created": 1465371124000,
      "email": {
        "avatar_url": "https://secure.gravatar.com/avatar/abcde&s=128",
        "email": "second@example.com",
        "is_done": true,
        "score": 100
      },
      "id": 12345,
      "lists": [],
      "name": "Second User",
      "owner": {
        "admin": true,
        "avatar_url": "https://secure.gravatar.com/avatar/54321?d=mm&s=128",
        "email": "user@voilanorbert.com",
        "firstname": "Cyril",
        "language": "en",
        "name": "Cyril"
      },
      "searching": false,
      "status": "LEAD"
    },
    {
      "company": {
        "description": null,
        "is_done": true,
        "keywords": [
          "Some",
          "Keywords",
          "For",
          "This",
          "Domain"
        ],
        "logo": "https://logo.clearbit.com/example.com",
        "name": "Example Website",
        "raw_url": "example.com",
        "title": "Example.com super website !",
        "url": "http://www.example.com"
      },
      "created": 1465371184000,
      "email": null,
      "id": 12346,
      "lists": [],
      "name": "Fake User",
      "owner": {
        "admin": true,
        "avatar_url": "https://secure.gravatar.com/avatar/987654?d=mm&s=128",
        "email": "user@voilanorbert.com",
        "firstname": "Cyril",
        "language": "en",
        "name": "Cyril"
      },
      "searching": false,
      "status": "CONTACTED"
    }
  ],
  "total": 2
}

GET`/contacts/`

Return a list of all your contacts.

You can filter them using the following parameters:

URI Parameters

HideShow

ids: List of Integers (optional) Example: 1,2,3
List of ids to get an exact set of contacts
query: String (optional) Example: "larry"
A search query that will used against the name, email, domain and company name of the contacts
name: String (optional) Example: "larry"
A partial name of the contact
email: String (optional) Example: "@google.com"
A partial email of the contact
company: String (optional) Example: "goog"
A partial name of the company
status: String (optional) Example: "LEAD"
The status of the contact, must be LEAD, CONTACTED, WON, LOST
found: Boolean (optional) Example: 1
Filter the result with only contacts found or all. Accepts true, 1 as “true” values
history: Boolean (optional) Example: 1
Returns only contacts that are available in the search history
lists: Integer/List of integers (optional) Example: 1,2
Filter the contacts that are in the given lists. Accepts one id or an array of ids.
created: string (required) Example: "2016
04-01 10:00" (String, optional) - Filter by creation date. Allow accept more advanced search when appending >, <, >=, <= to the date to find for before/after equal a specific date.
order_by: string (required) Example: "
-created" (String, optional) - Order by any specific field present in the contact. You can append - to reverse the order (DESC)

Resource ¶

GET /contacts/ContactId

RequestsCurl

Body

curl https://api.voilanorbert.com/2018-01-08/contacts/12345 \
 -u any_string:{secure_token}

Responses200

Headers

Content-Type: application/json

Body

{
  "company": {
    "description": null,
    "is_done": true,
    "keywords": [
      "Some",
      "Keywords",
      "For",
      "This",
      "Domain"
    ],
    "logo": "https://logo.clearbit.com/example.com",
    "name": "Example Website",
    "raw_url": "example.com",
    "title": "Example.com super website !",
    "url": "http://www.example.com"
  },
  "created": 1465371124000,
  "email": {
    "avatar_url": "https://secure.gravatar.com/avatar/abcde&s=128",
    "email": "second@example.com",
    "is_done": true,
    "score": 100
  },
  "id": 12345,
  "lists": [],
  "name": "Second User",
  "owner": {
    "admin": true,
    "avatar_url": "https://secure.gravatar.com/avatar/54321?d=mm&s=128",
    "email": "user@voilanorbert.com",
    "firstname": "Cyril",
    "language": "en",
    "name": "Cyril"
  },
  "searching": false,
  "status": "LEAD"
}

GET`/contacts/{id}`

Return a specific contact.

The object email is either null when the email is not found, or contains an object with at least email (the email string) and the score.

URI Parameters

HideShow

id: number (required) Example: ContactId
The contact’s id

Lists ¶

GET /lists/

RequestsCurl

Body

curl https://api.voilanorbert.com/2018-01-08/lists/ \
 -u any_string:{secure_token} \

Responses200

Headers

Content-Type: application/json

Body

{
  "result": [
    {
      "contacts": 45,
      "created": 1466070977000,
      "id": 2,
      "name": "My great list"
    },
    {
      "contacts": 22,
      "created": 1464860382000,
      "id": 1,
      "name": "Awesome leads"
    }
  ]
}

Get lists
GET`/lists/`

Returns a list of … your lists.

POST /lists/

RequestsDefinitionCurl

Headers

Content-Type: application/x-www-form-urlencoded

Body

name = Awesome leads

Responses200400

Headers

Content-Type: application/json

Body

{
  "contacts": 0,
  "created": 1464860382000,
  "id": 2,
  "name": "Awesome leads"
}

Headers

Content-Type: application/json

Body

{
  "name": [
    "This field is required."
  ]
}

Body

curl -X POST https://api.voilanorbert.com/2018-01-08/lists/ \
 -u any_string:{secure_token} \
 -d "name=Awesome leads"

Responses200400

Headers

Content-Type: application/json

Body

{
  "contacts": 0,
  "created": 1464860382000,
  "id": 2,
  "name": "Awesome leads"
}

Headers

Content-Type: application/json

Body

{
  "name": [
    "This field is required."
  ]
}

Create lists
POST`/lists/`

Create a new list.

List Items ¶

GET /lists/ListId

RequestsCurl

Body

curl https://api.voilanorbert.com/2018-01-08/lists/1 \
 -u any_string:{secure_token}

Responses200404

Headers

Content-Type: application/json

Body

{
  "contacts": 0,
  "created": 1464860382000,
  "id": 1,
  "name": "Awesome leads"
}

Headers

Content-Type: application/json

Body

{
  "code": 404,
  "error": "Page not found."
}

Get list item
GET`/lists/{id}`

Returns the details of one of your lists.

URI Parameters

HideShow

id: number (required) Example: ListId
The list’s id

PUT /lists/ListId

RequestsDefinitionCurlCurl

Headers

Content-Type: application/x-www-form-urlencoded

Body

name = "My New Name" &
removed = false

Responses200

Headers

Content-Type: application/json

Body

{
  "contacts": 0,
  "created": 1464860382000,
  "id": 1,
  "name": "My New Name"
}

Body

curl -X PUT https://api.voilanorbert.com/2018-01-08/lists/1 \
 -u any_string:{secure_token} \
 -d "name=My New Name"

Responses200

Headers

Content-Type: application/json

Body

{
  "contacts": 0,
  "created": 1464860382000,
  "id": 1,
  "name": "My New Name"
}

Body

curl -X PUT https://api.voilanorbert.com/2018-01-08/lists/1 \
 -u any_string:{secure_token} \
 -d "removed=1"

Responses202

This response has no content.

Update list item
PUT`/lists/{id}`

Update or set to deletion a given list.

URI Parameters

HideShow

id: number (required) Example: ListId
The list’s id

POST /lists/ListId

RequestsCurl

Body

curl -X POST https://api.voilanorbert.com/2018-01-08/lists/1 \
 -u any_string:{secure_token} \
 -d "company=Google"

Responses200

Headers

Content-Type: application/json

Body

{
  "contacts": 150,
  "created": 1464860382000,
  "id": 1,
  "name": "My New Name"
}

Create list item
POST`/lists/{id}`

Effect a given list of contacts to that list.

The list of contacts is generated from the same query returned from the GET request to /contacts/, with the same parameters. This let you apply a big number of contacts to this list

@see GET /contacts/

URI Parameters

HideShow

id: number (required) Example: ListId
The list’s id

Verify Endpoint ¶

Resource ¶

GET /verifier/"Verify token"

RequestsCurl

Body

curl https://api.voilanorbert.com/2018-01-08/verifier/<token> \
 -u any_string:{secure_token}

Responses200

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "bounces": 2,
  "created": 1623215587000,
  "deliverables": 4,
  "email": null,
  "ended": 1623215631000,
  "enrich": false,
  "enrich_token": null,
  "entries": 6,
  "filename": "upload.txt",
  "id": 873,
  "is_loaded": true,
  "name": null,
  "paid": 1623215588000,
  "path": "verify/2021/06/<token>/upload.txt",
  "price": null,
  "refunded": null,
  "risky": 1,
  "started": 1623215588000,
  "status": "ENDED",
  "stripe_id": null,
  "token": "<token>",
  "treated": 6,
  "type": "API"
}

GET`/verifier/{token}`

Returns the latest status of the verification request with given token. If verify is not found or API key is not valid you will receive a 404 error.

URI Parameters

HideShow

token: string (required) Example: "Verify token"
The verify’s token

Resource ¶

POST /verifier/upload

RequestsDefinitionPythonCurl

Headers

Content-Type: application/x-www-form-urlencoded

Body

data = "nedstark@voilanorbert.com,aryastark@voilanorbert.com" &
webhook = "http://requestb.in/aaaaaa" &
rerun_frequency = 0

Responses200402400

Headers

Content-Type: application/json

Body

{
"success": True,
"status": "Processing ...",
"token": "unique_token",
"channel": "channel_token"
}

Headers

Content-Type: application/json

Body

{
  "code": "402",
  "error": "Please provide a webhook to which we will post the verify results"
}

Headers

Content-Type: application/json

Body

{
  "code": "400",
  "error": "Please provide a file size lower than 100Mb. If you need more, please contact us."
}

Body

import requests, time

# Here is a quick sample Python code snippet that implements the algorithm:

API_TOKEN = 'abcde'

req = requests.post(
  'https://api.voilanorbert.com/2018-01-08/verifier/upload',
  auth=('any_string', API_TOKEN),
  data = {
      'data': 'testme@voilanorbert.com',
      'webhook': 'http://mywebhook.com'
  },
  headers={'Content-Type': 'application/x-www-form-urlencoded'}
)

if not req.success:
  return None

Responses200402400

Headers

Content-Type: application/json

Body

{
"success": True,
"status": "Processing ...",
"token": "unique_token",
"channel": "channel_token"
}

Headers

Content-Type: application/json

Body

{
  "code": "402",
  "error": "Please provide a webhook to which we will post the verify results"
}

Headers

Content-Type: application/json

Body

{
  "code": "400",
  "error": "Please provide a file size lower than 100Mb. If you need more, please contact us."
}

Body

curl -X POST https://api.voilanorbert.com/2018-01-08/verifier/upload \
 -u any_string:{secure_token} \
 -d data="testme@voilanorbert.com" \
 -d webhook="http://mywebhook.com"

Responses200402400

Headers

Content-Type: application/json

Body

{
"success": True,
"status": "Processing ...",
"token": "unique_token",
"channel": "channel_token"
}

Headers

Content-Type: application/json

Body

{
  "code": "402",
  "error": "Please provide a webhook to which we will post the verify results"
}

Headers

Content-Type: application/json

Body

{
  "code": "400",
  "error": "Please provide a file size lower than 100Mb. If you need more, please contact us."
}

POST`/verifier/upload`

Verifies the given list of emails.

In case your account does not have a sufficient Verify API balance the service will try to auto refill the balance by charging using the billing details of the account. If it fails to charge, an HTTP status code of 402 will be returned.

The endpoint accepts two types of inputs. One is a csv file and other is emails on one line a piece as a POST parameter. At least one of these parameters should be provided.

You should provide a callback url using the webhook parameter. We will send a POST request to this URL and expect a status code of 2xx. If we get something else, we will try again 2 more times with incrementing interval of 30 seconds between each request. After the third request, the server will stop trying.

Webhook will be called with a results parameter. ‘results’ will include list of objects for each email entry that is sent for verification. The object will include email, is_deliverable, is_risky, is_bounce, error_msg fields.

Resource ¶

PUT /verifier/"Verify token"/resume

RequestsPythonCurl

Body

import requests, time

# Here's a quick sample Python code that implements the algorithm :

API_TOKEN = 'abcde'

req = requests.put(
  'https://api.voilanorbert.com/2018-01-08/verifier/<token>/resume',
  auth=('any_string', API_TOKEN)
)

Responses200

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "bounces": 2,
  "created": 1623215587000,
  "deliverables": 4,
  "email": null,
  "ended": 1623215631000,
  "enrich": false,
  "enrich_token": null,
  "entries": 6,
  "filename": "upload.txt",
  "id": 873,
  "is_loaded": true,
  "name": null,
  "paid": 1623215588000,
  "path": "verify/2021/06/<token>/upload.txt",
  "price": null,
  "refunded": null,
  "risky": 1,
  "started": 1623215588000,
  "status": "PROCESSING",
  "stripe_id": null,
  "token": "<token>",
  "treated": 6,
  "type": "API"
}

Body

curl -X PUT https://api.voilanorbert.com/2018-01-08/verifier/<token>/resume \
 -u any_string:{secure_token}

Responses200

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "bounces": 2,
  "created": 1623215587000,
  "deliverables": 4,
  "email": null,
  "ended": 1623215631000,
  "enrich": false,
  "enrich_token": null,
  "entries": 6,
  "filename": "upload.txt",
  "id": 873,
  "is_loaded": true,
  "name": null,
  "paid": 1623215588000,
  "path": "verify/2021/06/<token>/upload.txt",
  "price": null,
  "refunded": null,
  "risky": 1,
  "started": 1623215588000,
  "status": "PROCESSING",
  "stripe_id": null,
  "token": "<token>",
  "treated": 6,
  "type": "API"
}

PUT`/verifier/{token}/resume`

Resumes the paused verify request with given token.

URI Parameters

HideShow

token: string (required) Example: "Verify token"
The verify’s token

Resource ¶

PUT /verifier/VerifyToken/pause

RequestsPythonCurl

Body

import requests, time

# Here's a quick sample Python code that implements the algorithm :

API_TOKEN = 'abcde'

req = requests.put(
  'https://api.voilanorbert.com/2018-01-08/verifier/<token>/pause',
  auth=('any_string', API_TOKEN)
)

Responses200

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "bounces": 2,
  "created": 1623215587000,
  "deliverables": 4,
  "email": null,
  "ended": 1623215631000,
  "enrich": false,
  "enrich_token": null,
  "entries": 6,
  "filename": "upload.txt",
  "id": 873,
  "is_loaded": true,
  "name": null,
  "paid": 1623215588000,
  "path": "verify/2021/06/<token>/upload.txt",
  "price": null,
  "refunded": null,
  "risky": 1,
  "started": 1623215588000,
  "status": "PAUSED",
  "stripe_id": null,
  "token": "<token>",
  "treated": 6,
  "type": "API"
}

Body

curl -X PUT https://api.voilanorbert.com/2018-01-08/verifier/<token>/pause \
 -u any_string:{secure_token}

Responses200

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "bounces": 2,
  "created": 1623215587000,
  "deliverables": 4,
  "email": null,
  "ended": 1623215631000,
  "enrich": false,
  "enrich_token": null,
  "entries": 6,
  "filename": "upload.txt",
  "id": 873,
  "is_loaded": true,
  "name": null,
  "paid": 1623215588000,
  "path": "verify/2021/06/<token>/upload.txt",
  "price": null,
  "refunded": null,
  "risky": 1,
  "started": 1623215588000,
  "status": "PAUSED",
  "stripe_id": null,
  "token": "<token>",
  "treated": 6,
  "type": "API"
}

PUT`/verifier/{token}/pause`

Pauses an active verify request with given token.

URI Parameters

HideShow

token: string (required) Example: VerifyToken
The verify’s token

Resource ¶

GET /verifier/VerifyToken/download

RequestsPythonCurl

Body

import requests, time

# Here's a quick sample Python code that implements the algorithm :

API_TOKEN = 'abcde'

req = requests.get(
  'https://api.voilanorbert.com/2018-01-08/verifier/<token>/download',
  auth=('any_string', API_TOKEN)
)

Responses200

Headers

Content-Type: application/csv

Body

curl https://api.voilanorbert.com/2018-01-08/verifier/<token>/download \
 -u any_string:{secure_token}

Responses200

Headers

Content-Type: application/csv

GET`/verifier/{token}/download`

Downloads the result file of a verify request with given token.

URI Parameters

HideShow

token: string (required) Example: VerifyToken
The verify’s id

Enrichment Endpoint ¶

Resource ¶

GET /enrich/EnrichToken

RequestsCurl

Body

curl https://api.voilanorbert.com/2018-01-08/enrich/<token> \
 -u any_string:{secure_token}

Responses200

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "created": 1623215621000,
  "email": null,
  "ended": 1623216065000,
  "entries": 6,
  "filename": "upload.txt",
  "id": 187,
  "is_loaded": true,
  "paid": 1623215652000,
  "path": "enrich/2021/06/<token>/upload.txt",
  "price": null,
  "refunded": null,
  "started": 1623215652000,
  "status": "ENDED",
  "stripe_id": null,
  "success": 3,
  "token": "<token>",
  "treated": 6,
  "type": "API"
}

GET`/enrich/{token}`

Returns the latest status of the enrichment request with given token. If enrichment is not found or API key is not valid you will receive a 404 error.

URI Parameters

HideShow

token: string (required) Example: EnrichToken
The enrich’s token

Resource ¶

POST /enrich/upload

RequestsDefinitionPythonCurl

Headers

Content-Type: application/x-www-form-urlencoded

Body

data = "testme@voilanorbert.com" &
webhook = "http://mywebhook.com" &

Responses200402400

Headers

Content-Type: application/json

Body

{
"success": True,
"status": "Processing ...",
"token": "unique_token",
"channel": "channel_token"
}

Headers

Content-Type: application/json

Body

{
  "code": "402",
  "error": "Please provide a webhook to which we will post the enrich results"
}

Headers

Content-Type: application/json

Body

{
  "code": "400",
  "error": "Please provide a file size lower than 100Mb. If you need more, please contact us."
}

Body

import requests, time

# Here is a quick sample Python code snippet that implements the algorithm:

API_TOKEN = 'abcde'

req = requests.post(
  'https://api.voilanorbert.com/2018-01-08/enrich/upload',
  auth=('any_string', API_TOKEN),
  data = {
      'data': 'testme@voilanorbert.com',
      'webhook': 'http://mywebhook.com'
  },
  headers={'Content-Type': 'application/x-www-form-urlencoded'}
)

if not req.success:
  return None

Responses200402400

Headers

Content-Type: application/json

Body

{
"success": True,
"status": "Processing ...",
"token": "unique_token",
"channel": "channel_token"
}

Headers

Content-Type: application/json

Body

{
  "code": "402",
  "error": "Please provide a webhook to which we will post the enrich results"
}

Headers

Content-Type: application/json

Body

{
  "code": "400",
  "error": "Please provide a file size lower than 100Mb. If you need more, please contact us."
}

Body

curl -X POST https://api.voilanorbert.com/2018-01-08/enrich/upload \
 -u any_string:{secure_token} \
 -d data="testme@voilanorbert.com" \
 -d webhook="http://mywebhook.com"

Responses200402400

Headers

Content-Type: application/json

Body

{
"success": True,
"status": "Processing ...",
"token": "unique_token",
"channel": "channel_token"
}

Headers

Content-Type: application/json

Body

{
  "code": "402",
  "error": "Please provide a webhook to which we will post the enrich results"
}

Headers

Content-Type: application/json

Body

{
  "code": "400",
  "error": "Please provide a file size lower than 100Mb. If you need more, please contact us."
}

POST`/enrich/upload`

Enriches the given list of emails.

In case your account does not have a sufficient Enrich API balance the service will try to auto refill the balance by charging using the billing details of the account. If it fails to charge, an HTTP status code of 402 will be returned.

The endpoint accepts two types of inputs. One is a csv file and other is emails on one line a piece as a POST parameter. At least one of these parameters should be provided.

Webhook will be called with a results parameter. ‘results’ will include list of objects for each email entry that is sent for enrichment. The object will include email, is_deliverable, is_risky, is_bounce, error_msg fields.

URI Parameters

HideShow

data: string (optional) Example: "testme@voilanorbert.com\ntestit@voilanorbert.com"
Line separated emails
file: string (optional) Example: File content
CSV File content which includes the list of emails in it
webhook: string (required) Example: "http://requestb.in/aaaaaa"
URL where the result will be POSTed

Resource ¶

PUT /enrich/EnrichToken/resume

RequestsPythonCurl

Body

import requests, time

# Here's a quick sample Python code that implements the algorithm :

API_TOKEN = 'abcde'

req = requests.put(
  'https://api.voilanorbert.com/2018-01-08/enrich/<token>/resume',
  auth=('any_string', API_TOKEN)
)

Responses200

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "created": 1623215621000,
  "email": null,
  "ended": 1623216065000,
  "entries": 6,
  "filename": "upload.txt",
  "id": 187,
  "is_loaded": true,
  "paid": 1623215652000,
  "path": "enrich/2021/06/<token>/upload.txt",
  "price": null,
  "refunded": null,
  "started": 1623215652000,
  "status": "PROCESSING",
  "stripe_id": null,
  "success": 3,
  "token": "<token>",
  "treated": 6,
  "type": "API"
}

Body

curl -X PUT https://api.voilanorbert.com/2018-01-08/enrich/<token>/resume \
 -u any_string:{secure_token}

Responses200

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "created": 1623215621000,
  "email": null,
  "ended": 1623216065000,
  "entries": 6,
  "filename": "upload.txt",
  "id": 187,
  "is_loaded": true,
  "paid": 1623215652000,
  "path": "enrich/2021/06/<token>/upload.txt",
  "price": null,
  "refunded": null,
  "started": 1623215652000,
  "status": "PROCESSING",
  "stripe_id": null,
  "success": 3,
  "token": "<token>",
  "treated": 6,
  "type": "API"
}

PUT`/enrich/{token}/resume`

Resumes the paused enrich request with given token.

URI Parameters

HideShow

token: string (required) Example: EnrichToken
The enrich’s token

Resource ¶

PUT /enrich/EnrichToken/pause

RequestsPythonCurl

Body

import requests, time

# Here's a quick sample Python code that implements the algorithm :

API_TOKEN = 'abcde'

req = requests.put(
  'https://api.voilanorbert.com/2018-01-08/enrich/<token>/pause',
  auth=('any_string', API_TOKEN)
)

Responses200

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "created": 1623215621000,
  "email": null,
  "ended": 1623216065000,
  "entries": 6,
  "filename": "upload.txt",
  "id": 187,
  "is_loaded": true,
  "paid": 1623215652000,
  "path": "enrich/2021/06/<token>/upload.txt",
  "price": null,
  "refunded": null,
  "started": 1623215652000,
  "status": "PAUSED",
  "stripe_id": null,
  "success": 3,
  "token": "<token>",
  "treated": 6,
  "type": "API"
}

Body

curl -X PUT https://api.voilanorbert.com/2018-01-08/enrich/<token>/pause \
 -u any_string:{secure_token}

Responses200

Headers

Content-Type: application/json

Body

{
  "account": {
    "email": "account email",
    "firstname": "account firstname",
    "name": "account name",
    "plan": null
  },
  "created": 1623215621000,
  "email": null,
  "ended": 1623216065000,
  "entries": 6,
  "filename": "upload.txt",
  "id": 187,
  "is_loaded": true,
  "paid": 1623215652000,
  "path": "enrich/2021/06/<token>/upload.txt",
  "price": null,
  "refunded": null,
  "started": 1623215652000,
  "status": "PAUSED",
  "stripe_id": null,
  "success": 3,
  "token": "<token>",
  "treated": 6,
  "type": "API"
}

PUT`/enrich/{token}/pause`

Pauses an active enrich request with given token.

URI Parameters

HideShow

token: string (required) Example: EnrichToken
The enrich’s token

Resource ¶

GET /enrich/EnrichToken/download

RequestsPythonCurl

Body

import requests, time

# Here's a quick sample Python code that implements the algorithm :

API_TOKEN = 'abcde'

req = requests.get(
  'https://api.voilanorbert.com/2018-01-08/enrich/<token>/download',
  auth=('any_string', API_TOKEN)
)

Responses200

Headers

Content-Type: application/csv

Body

curl https://api.voilanorbert.com/2018-01-08/enrich/<token>/download \
 -u any_string:{secure_token}

Responses200

Headers

Content-Type: application/csv

GET`/enrich/{token}/download`

Downloads the result file of an enrich request with given token.

URI Parameters

HideShow

token: string (required) Example: EnrichToken
The enrich’s token

Generated by aglio on 27 Oct 2024

API Endpoint

API Endpoint ¶

Authentication ¶

How do we determine your credits ¶

Prospecting Service ¶

Enrich & Verify Services ¶

API Rate Limit ¶

HTTP Status Code ¶

Errors ¶

Search Endpoint ¶

Resource ¶

Headers

Body

Headers

Body

Headers

Body

Body

Headers

Body

Headers

Body

Body

Headers

Body

Headers

Body

POST/search/name

Resource ¶

Headers

Body

Headers

Body

Headers

Body

Body

Headers

Body

Headers

Body

Body

Headers

Body

Headers

Body

POST/search/domain

Bulk Search Endpoint ¶

Bulk operations ¶

Headers

Body

Headers

Body

Headers

Body

Body

Headers

Body

Headers

Body

Body

Headers

Body

Headers

Body

Submit a bulk filePOST/massives/

Body

Headers

Body

Body

Headers

Body

List bulk filesGET/massives/{?offset,limit}

Bulk item operations ¶

Body

Headers

Body

RetrieveGET/massives/{id}

Headers

Body

Headers

API Endpoint

Authentication

How do we determine your credits

Prospecting Service

Enrich & Verify Services

API Rate Limit

HTTP Status Code

Errors

POST`/search/name`

POST`/search/domain`

Submit a bulk file
POST`/massives/`

List bulk files
GET`/massives/{?offset,limit}`

Retrieve
GET`/massives/{id}`

Remove
DELETE`/massives/{id}`

Resume
POST`/massives/{id}/resume`

Pause
POST`/massives/{id}/pause`

Set rerun
PUT`/massives/{id}/rerun`

Reset rerun
DELETE`/massives/{id}/rerun`

GET`/account/`

GET`/organization/`

GET`/organization/credits/`

GET`/contacts/`