NAV Navbar
Logo
shell ruby python

Introduction

Welcome to the Toofr Sales Hacking API! You can use our API to guess business emails, test emails, and extract prospects from webpages and our database.

We have language examples in Shell, Ruby, and Python. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

Every Toofr user has access to our API. API calls use credits in the same way that our web application use credits. For more information on how credits are used, view our FAQ.

To get an API key, first register for a free Toofr account. Check your email for a confirmation message, click through the link, and log in. Your API key is available on your Account page.

If you run out of credits, you’ll need to sign up for a monthly plan to get more. Currenty they start at just $19/mo.

Your API key is a long alphanumeric string that looks similar to this:

e3eabc123ccabcd3efg233hij06b7031

Emails

Guess Emails

require 'net/http'
require 'json'

uri = URI('https://www.toofr.com/api/v1/guess_email.json')
res = Net::HTTP.post_form(uri, 'key' => 'abc123yourkeyhere', 'first_name' => 'ryan', 'last_name' => 'buckley', 'company_name' => 'toofr.com')
JSON.parse(res.body)
import requests

uri = 'https://www.toofr.com/api/v1/guess_email.json'
payload = {'key': 'abc123yourkeyhere', 'first_name': 'ryan', 'last_name': 'buckley', 'company_name': 'toofr.com'}
r = requests.post(uri, data = payload)
r.json()
curl --data "key=abc123yourkeyhere&first_name=ryan&last_name=buckley&company_name=toofr.com" https://www.toofr.com/api/v1/guess_email.json

The above command returns JSON structured like this:

{
  "ryan@toofr.com": {
    "confidence":119,"email":"ryan@toofr.com","default":20
  },
  "rbuckley@toofr.com": {
    "confidence":20,"email":"rbuckley@toofr.com","default":15
  },
  "ryan.buckley@toofr.com": {
    "confidence":18,"email":"ryan.buckley@toofr.com","default":16
  },
  "ryanbuckley@toofr.com": {
    "confidence":17,"email":"ryanbuckley@toofr.com","default":17
  },
  "ryan_buckley@toofr.com": {
    "confidence":16,"email":"ryan_buckley@toofr.com","default":18
  },
  "ryan-buckley@toofr.com": {
    "confidence":15,"email":"ryan-buckley@toofr.com","default":19
  },
  "ryanb@toofr.com": {
    "confidence":14,"email":"ryanb@toofr.com","default":14
  },
  "buckley@toofr.com": {
    "confidence":13,"email":"buckley@toofr.com","default":13
  }
}

This endpoint discovers emails based on the first name, last name, and company name.

HTTP Request

POST https://www.toofr.com/api/v1/guess_email.json

Query Parameters

Parameter Description
key Your key is required for any request and is found on your Toofr account page
first_name This is the text of the first name of your prospect, cleansed of spaces and non-ASCII characters (por favor!)
last_name This is the text of the last name of your prospect, cleansed of spaces and non-ASCII characters (por favor!)
company_name This is the text of either the company name or website

Test Emails

require 'net/http'
require 'json'

uri = URI('https://www.toofr.com/api/v1/test_email.json')
res = Net::HTTP.post_form(uri, 'key' => 'abc123yourkeyhere', 'email' => 'ryan@toofr.com')
JSON.parse(res.body)
import requests

uri = 'https://www.toofr.com/api/v1/guess_email.json'
payload = {'key': 'abc123yourkeyhere', 'email': 'ryan@toofr.com'}
r = requests.post(uri, data = payload)
r.json()
curl --data "key=abc123yourkeyhere&email=ryan@scripted.com" https://www.toofr.com/api/v1/test_email.json

The above command returns JSON structured like this:

{ "email": "ryan@toofr.com", "confidence": 119 }

This endpoint delivers our confidence score for a given email address.

HTTP Request

POST https://www.toofr.com/api/v1/test_email.json

Query Parameters

Parameter Description
key Your key is required for any request and is found on your Toofr account page
email The properly formatted email address you want to test

Companies

Get Prospects and Patterns

require 'net/http'
require 'json'

uri = URI('https://www.toofr.com/api/v1/prospect')
res = Net::HTTP.get(uri, 'key' => 'abc123yourkeyhere', 'company_name' => 'toofr.com')
JSON.parse(res.body)
import requests

uri = 'https://www.toofr.com/api/v1/prospect'
payload = {'key': 'abc123yourkeyhere', 'company_name': 'toofr.com'}
r = requests.get(uri, data = payload)
r.json()
curl https://www.toofr.com/api/v1/prospect?key=abc123yourkeyhere&company_name_=toofr.com

The above command returns JSON structured like this:

{ "prospects":    
  [
    { 
      "email":"ryan@toofr.com", 
      "first_name":"Ryan",
      "last_name":"Buckley",
      "confidence":119,
      "profile": {
        "fn"=>"Ryan Buckley", "photo"=>"https://media.licdn.com/mpr/mpr/shrinknp_200_200/AAEAAQAAAAAAAAniAAAAJGU1MjAxMWI1LTU1ZDItNDQ3OS1iYWVlLWNhNTNhNmIzZWU1Yw.jpg", 
        "title"=>"Founder of Toofr.com, eNPS.co, and Thinboxapp.com", 
        "linkedin_profile"=>"https://www.linkedin.com/in/rbuckley"
      }
    },
    { 
      "email":"kurdt@toofr.com", 
      "first_name":"Kurt",
      "last_name":"Cobain",
      "confidence":89,
      "profile": {
        "fn"=>"Kurdt Cobain", "photo"=>"https://media.licdn.com/mpr/mpr/shrinknp_200_200/AAEAAQAAAAAAAAniAAAAJGU1MjAxMWI1LTU1ZDItNDQ3OS1iYWVlLWNhNTNhNmIzZWU1Yw.jpg", 
        "title"=>"Singer / songwriter", 
        "linkedin_profile"=>"https://www.linkedin.com/in/rbuckley"
      }
    },
    { 
      "email":"dave@toofr.com", 
      "first_name":"Dave",
      "last_name":"Grohl",
      "confidence":104,
      "profile": {
        "fn"=>"David Grohl", "photo"=>"https://media.licdn.com/mpr/mpr/shrinknp_200_200/AAEAAQAAAAAAAAniAAAAJGU1MjAxMWI1LTU1ZDItNDQ3OS1iYWVlLWNhNTNhNmIzZWU1Yw.jpg", 
        "title"=>"Drummer extraordinaire and future stadium rocker", 
        "linkedin_profile"=>"https://www.linkedin.com/in/rbuckley"
      }
    },
    { 
      "email":"krist@toofr.com", 
      "first_name":"Krist",
      "last_name":"Novoselic",
      "confidence":93,
      "profile": {
        "fn"=>"Krist Novoselic", "photo"=>"https://media.licdn.com/mpr/mpr/shrinknp_200_200/AAEAAQAAAAAAAAniAAAAJGU1MjAxMWI1LTU1ZDItNDQ3OS1iYWVlLWNhNTNhNmIzZWU1Yw.jpg", 
        "title"=>"The quiet bassist", 
        "linkedin_profile"=>"https://www.linkedin.com/in/rbuckley"
      }
    }
  ],
  "top_pattern":
    [ "first name", "miles@toofr.com" ]
}

This endpoint delivers the prospects in our database based on company name or website.

HTTP Request

GET https://www.toofr.com/api/v1/prospect

Query Parameters

Parameter Description
key Your key is required for any request and is found on your Toofr account page
company_name This is the text of either the company name or website.

Get Profiles

require 'net/http'
require 'json'

uri = URI('https://www.toofr.com/api/v1/profile')
res = Net::HTTP.get(uri, 'key' => 'abc123yourkeyhere', 'first_name' => 'ryan', 'last_name' => 'buckley', 'email' => 'ryan@toofr.com')
JSON.parse(res.body)
import requests

uri = 'https://www.toofr.com/api/v1/profile'
payload = {'key': 'abc123yourkeyhere', 'first_name': 'ryan', 'last_name': 'buckley', 'email': 'ryan@toofr.com'}
r = requests.get(uri, data = payload)
r.json()
curl https://www.toofr.com/api/v1/profile?key=abc123yourkeyhere&first_name=ryan&last_name=buckley&email=ryan@toofr.com

The above command returns JSON structured like this:

{
  "profile": {
    "fn":"Ryan Buckley",
    "photo":"https://media.licdn.com/mpr/mpr/shrinknp_200_200/p/3/000/063/38c/276e158.jpg",
    "title":"CEO of Toofr",
    "linkedin_profile":"https://www.linkedin.com/in/rbuckley"
  }
}

This endpoint returns the profile data we have on a given prospect and attempts to fetch it in real-time if it’s not in our database.

HTTP Request

GET https://www.toofr.com/api/v1/profile

Query Parameters

Parameter Description
key Your key is required for any request and is found on your Toofr account page
first_name The first name of the prospect
last_name The last name of the prospect
email The known email address of the prospect

Get Company Industry and Agency Data

require 'net/http'
require 'json'

uri = URI('https://www.toofr.com/api/v1/classify')
res = Net::HTTP.get(uri, 'key' => 'abc123yourkeyhere', 'company_name' => 'toofr.com')
JSON.parse(res.body)
import requests

uri = 'https://www.toofr.com/api/v1/classify'
payload = {'key': 'abc123yourkeyhere', 'company_name': 'toofr.com'}
r = requests.get(uri, data = payload)
r.json()
curl https://www.toofr.com/api/v1/classify?key=abc123yourkeyhere&company_name=toofr.com

The above command returns JSON structured like this:

{
  "industry":"marketing_and_advertising",
  "agency_category":"advertising",
  "is_agency":"no"
}

This endpoint uses our natural language processing engine to determine the industry and agency category and status of any website.

HTTP Request

GET https://www.toofr.com/api/v1/classify

Query Parameters

Parameter Description
key Your key is required for any request and is found on your Toofr account page
company_name This is the text of either the company name or website.

Query Responses

Parameter Description
industry The general industry our artificial intelligence believes the website to be in.
is_agency A boolean (true / false) response on whether we believe the company is an agency.
agency_category If we believe the company is an agency, this is the more specific agency category it falls under.

Lists

Get All Lists

require 'net/http'
require 'json'

uri = URI('https://www.toofr.com/api/v1/lists')
res = Net::HTTP.get(uri, 'key' => 'abc123yourkeyhere')
JSON.parse(res.body)
import requests

uri = 'https://www.toofr.com/api/v1/lists'
payload = {'key': 'abc123yourkeyhere'}
r = requests.get(uri, data = payload)
r.json()
curl https://www.toofr.com/api/v1/lists?key=abc123yourkeyhere

The above command returns a JSON array structured like this:

[
  { 
    "id":137,
    "name":"My first file upload",
    "description":"Prospects generated from web scrape.", 
    "created_at":"2017-05-20T20:55:44.635Z", 
    "state":"finished",
    "records_count_in":5,
    "records_count_processed":5
  },
  {
    "id":134,
    "name":"Web results",
    "description":"Good emails found by my VA.", 
    "created_at":"2017-05-16T19:56:10.155Z",
    "state":"finished",
    "records_count_in":null,
    "records_count_processed":null
  }
]

This endpoint delivers the array of lists seen in your account at https://www.toofr.com/lists/owned.

HTTP Request

GET https://www.toofr.com/api/v1/lists

Query Parameters

Parameter Description
key Your key is required for any request and is found on your Toofr account page

Get A Specific List

require 'net/http'
require 'json'

uri = URI('https://www.toofr.com/api/v1/lists/:id')
res = Net::HTTP.get(uri, 'key' => 'abc123yourkeyhere')
JSON.parse(res.body)
import requests

uri = 'https://www.toofr.com/api/v1/lists/:id'
payload = {'key': 'abc123yourkeyhere'}
r = requests.get(uri, data = payload)
r.json()
curl https://www.toofr.com/api/v1/lists/:id?key=abc123yourkeyhere

The above command returns JSON structured like this:

{
  "id":137,
  "name":"My first file upload",
  "description":"Prospects generated from web scrape.", 
  "created_at":"2017-05-20T20:55:44.635Z", 
  "state":"finished",
  "records_count_in":5,
  "records_count_processed":5
}

This endpoint delivers the JSON hash of a specific list.

HTTP Request

GET https://www.toofr.com/api/v1/lists/:id

Query Parameters

Parameter Description
key Your key is required for any request and is found on your Toofr account page

Create A List

require 'net/http'
require 'json'

uri = URI('https://www.toofr.com/api/v1/lists')
res = Net::HTTP.post_form(uri, 'key' => 'abc123yourkeyhere', 'name' => 'API list', 'description' => 'Created via API')
JSON.parse(res.body)
import requests

uri = 'https://www.toofr.com/api/v1/lists'
payload = {'key': 'abc123yourkeyhere', 'name': 'API list', 'description': 'Created via API'}
r = requests.post(uri, data = payload)
r.json()
curl --data "key=abc123yourkeyhere&name='API list'&description='Created via API'" https://www.toofr.com/api/v1/lists

The above command returns JSON structured like this:

{
  "id":137,
  "name":"My first file upload",
  "description":"Prospects generated from web scrape.", 
  "created_at":"2017-05-20T20:55:44.635Z", 
  "state":"finished",
  "records_count_in":5,
  "records_count_processed":5
}

This endpoint delivers the array of lists seen in your account at https://www.toofr.com/lists/owned.

HTTP Request

POST https://www.toofr.com/api/v1/lists

Query Parameters

Parameter Description
key Your key is required for any request and is found on your Toofr account page
name A short string to name your list
description A longer string to describe your list
file_type For bulk processing, select the type of file it would be if you were to import it rather than use the API. See acceptable values below or leave blank if no processing is required.
File Type Description
guess You provide the names and companies of prospects and Toofr appends the best email and confidence score
guess_all Like guess, but Toofr gives all emails and confidence scores, not just the best one
test You provide emails and Toofr appends a confidence score
get You provide companies (names or websites) and Toofr returns all the related emails with confidence scores in our database
pattern You provide companies (names or websites) and Toofr returns the best related email pattern

List Records

Get All List Records On A List

require 'net/http'
require 'json'

uri = URI('https://www.toofr.com/api/v1/lists/:list_id/list_records')
res = Net::HTTP.get(uri, 'key' => 'abc123yourkeyhere', 'page' => 1)
JSON.parse(res.body)
import requests

uri = 'https://www.toofr.com/api/v1/lists/:list_id/list_records'
payload = {'key': 'abc123yourkeyhere', 'page': 1}
r = requests.get(uri, data = payload)
r.json()
curl https://www.toofr.com/api/v1/lists/:list_id/list_records?key=abc123yourkeyhere&page=1

The above command returns a JSON array structured like this:

[
  {
    "id":16347, 
    "first_name":"ryan", 
    "last_name":"buckerooski",
    "company":"toofr.com",
    "email_address":"ryan@toofr.com",
    "meta":{
      "top":"true"
    },
    "created_at":"2017-05-24T03:33:37.234Z",
    "processed_at":"2017-05-24T03:33:53.325Z"
  },
  {
    "id":16346,
    "first_name":"james",
    "last_name":"bond",
    "company":"toofr.com",
    "email_address":"bondjamesbond@toofr.com",
    "meta":{
      "top":"true"
    },
    "created_at":"2017-05-24T03:32:29.271Z",
    "processed_at":"2017-05-24T03:32:34.876Z"
  },
]

This endpoint delivers the array of list records you would see if you exported your list from https://www.toofr.com/lists/:id.

HTTP Request

GET https://www.toofr.com/api/v1/lists/:list_id/list_records

Query Parameters

Parameter Description
key Your key is required for any request and is found on your Toofr account page
page Results are paginated 100 at a time so you can iterate through the pages numerically to extract list records

Get A Specific List Record

require 'net/http'
require 'json'

uri = URI('https://www.toofr.com/api/v1/lists/:list_id/list_records/:id')
res = Net::HTTP.get(uri, 'key' => 'abc123yourkeyhere')
JSON.parse(res.body)
import requests

uri = 'https://www.toofr.com/api/v1/lists/:list_id/list_records/:id'
payload = {'key': 'abc123yourkeyhere'}
r = requests.get(uri, data = payload)
r.json()
curl https://www.toofr.com/api/v1/lists/:list_id/list_records/:id?key=abc123yourkeyhere

The above command returns JSON structured like this:

{
  "id":16347, 
  "first_name":"ryan", 
  "last_name":"buckerooski",
  "company":"toofr.com",
  "email_address":"ryan@toofr.com",
  "meta":{
    "top":"true"
  },
  "created_at":"2017-05-24T03:33:37.234Z",
  "processed_at":"2017-05-24T03:33:53.325Z"
}

This endpoint delivers the JSON hash of a specific list_record.

HTTP Request

GET https://www.toofr.com/api/v1/lists/:id

Query Parameters

Parameter Description
key Your key is required for any request and is found on your Toofr account page

Create A List Record

require 'net/http'
require 'json'

uri = URI('https://www.toofr.com/api/v1/lists/:list_id/list_records')
res = Net::HTTP.post_form(uri, 'key' => 'abc123yourkeyhere', 'first_name' => 'Ryan', 'last_name' => 'Buckley', 'company' => 'toofr.com')
JSON.parse(res.body)
import requests

uri = 'https://www.toofr.com/api/v1/lists/:list_id/list_records'
payload = {'key': 'abc123yourkeyhere', 'first_name': 'Ryan', 'last_name': 'Buckley', 'company': 'toofr.com'}
r = requests.post(uri, data = payload)
r.json()
curl --data "key=abc123yourkeyhere&first_name=Ryan&last_name=Buckley&company=toofr.com" https://www.toofr.com/api/v1/lists/:list_id/list_records

The above command returns JSON structured like this:

{
  "id":16348,
  "first_name":"ryan",
  "last_name":"buckerooski",
  "company":"toofr.com",
  "email_address":null,
  "meta":{}
}

This endpoint creates and initiates a background process on the created list record. The type of process run will be based on the file_type of its associated list (the :list_id it’s created on).

HTTP Request

POST https://www.toofr.com/api/v1/lists/:list_id/list_records

Query Parameters

Parameter Description
key Your key is required for any request and is found on your Toofr account page

Errors

The Toofr API uses the following error codes:

Error Code Meaning
401 Unauthorized – There was a problem with your API key.
404 Not Found – The resource you requested could not be found.
406 Not Acceptable – You requested a format that isn’t compatible with our API.
500 Internal Server Error – We had an unexpected problem with your request.