Find contacts by job title at relevant companies

Introduction

Mattermark is a powerful tool for finding contacts at companies. In this guide, we will use the Companies List endpoint and Python to find companies of a certain class (e.g. hired more than 10 employees in the past 6 months). We will then connect that to the Personnel endpoint to find employees with a certain title (e.g. CTO).

Walk through step by step or see the full commented source at the bottom.

Setup

You’ll need a Mattermark API Key and Python 2 before you get started.

api_key = "YOUR_MATTERMARK_API_KEY"

Search for relevant companies

The companies_payload variable contains the parameters we’re sending to the Companies List endpoint. See the companies list documentation to fit this search to your needs.

# data we'll be sending to the companies endpoint
companies_payload = {
    "key":      api_key,

    # change page here to restart from a later point
    "page":     1,
    "per_page": 50,

    # limit to companies in the analytics and finance industries that hired 40-50 employees in the past month
    "industries":                 "Analytics|Finance",
    "employees_added_in_month":   "40~50"
}

Choose a job title to search for

In this guide we’re looking for CTOs.

# string to look for in each employee's job title
target_job_title = 'CTO'

# List for CTOs we find
ctos = []

Look for CTOs at these companies

Loop through each company and request their employees. If any employee matches our target_job_title also request contact details for that employee and save them to our list.

# get the first page of companies from mattermark
# see Full Source section for this method
companies = get_companies(companies_payload)

# get employees of each company
for company in companies['companies']:
    # see Full Source section for this method
    people = get_people(company)

    # check each employee for 'CTO' in their title
    for person in people:
        if re.match(target_job_title, person['title']):
            # keep the company data with this person
            person['comany'] = company

            # request the contact details from mattermark
            # see Full Source section for this method
            person['contact'] = request_contact_details(company, person)

            # add them to our list of CTOs
            ctos.append(person)

Full Source

This includes the above code as well as additional functions, error handling, and saving the output to a CSV.

import requests
import re
import os.path
import unicodecsv as csv

# config
api_key = "YOUR_MATTERMARK_API_KEY"

# data we'll be sending to the companies endpoint
companies_payload = {
    "key":      api_key,

    # change page here to restart from a later point
    "page":     1,
    "per_page": 50,

    # limit to companies in the analytics and finance industries that hired 40-50 employees in the past month
    # more details on customizing search results at 
    # https://docs.mattermark.com/rest_api/companies_list/index.html
    "industries":                 "Analytics|Finance",
    "employees_added_in_month":   "40~50"
}

# get a list of companies from mattermark
# returns 50 companies each time it's called
def get_companies(payload):
    # company search endpoint
    companies_url = "https://api.mattermark.com/companies"

    # mattermark call
    print "Getting companies page %i" % payload['page']
    response = requests.get(companies_url, params=payload)
    response.raise_for_status()

    # automatically increment page whenever this function is called
    payload['page'] += 1

    return response.json()
    # returns:
    # { 
    #   companies: [{id, company_name, domain, url}], 
    #   meta: {current_page, per_page, total_pages, total_record_count}
    # }


# get a list of people that work at a particular company
def get_people(company):
    global api_key

    # company people endpoint
    people_url = "https://api.mattermark.com/companies/%s/people" % company['id']

    # mattermark call
    response = requests.get(people_url, params={ "key": api_key })
    response.raise_for_status()

    return response.json()
    # returns: [{name, path, title}]


# request an email address for a person.
# email will be null in the response if mattermark can't find an email address for them
def request_contact_details(company, person):
    global api_key

    # contact endpoint
    contact_url = "https://api.mattermark.com/companies/%s/contact" % company['id']

    # data we'll be sending to the contact endpoint
    payload = {
        "key":          api_key,
        "full_name":    person['name']
    }

    # mattermark call
    response = requests.get(contact_url, params=payload)
    response.raise_for_status()

    return response.json()
    # returns {email, name, company_id}



# string to look for in each employee's job title
target_job_title = 'CTO'

# List for CTOs we find
ctos = []

# get the first page of companies from mattermark
companies = get_companies(companies_payload)

try:
    # keep doing this until we don't get any new companies
    while companies['companies']:
        # get employees of each company
        for company in companies['companies']:
            people = get_people(company)

            # check each employee for 'CTO' in their title
            for person in people:
                if re.match(target_job_title, person['title']):
                    # keep the company data with this person
                    person['comany'] = company
                    person['contact'] = request_contact_details(company, person)

                    # add them to our list of CTOs
                    ctos.append(person)

        # get a new list of companies for the next loop
        companies = get_companies(companies_payload)

except requests.exceptions.HTTPError as err:
    if err.response.status_code == 429:
        # Quota and Rate Limiting details available at
        # https://docs.mattermark.com/rest_api/getting_started/index.html#quota-usage
        print "429: Too many requests. Try again later."
        print "Next page: %i" % payload['page']
    else:
        raise


# next save results to a csv
file_name = './ctos.csv'

# check if our output csv file exists before writing
output_file_exists = os.path.isfile(file_name):

# create or append to ctos.csv 
with open(file_name, 'ab') as f:
    w = csv.writer(f)

    # if the file already existed we'll skip creating the header
    if not output_file_exists:
        w.writerow(['name', 'email', 'title', 'path', 'company_name', 'company_id'])

    # write the rows we've downloaded to file
    for cto in ctos:
        w.writerow([
            cto['name'], 
            cto['contact']['email'], 
            cto['title'], 
            cto['path'],
            cto['company']['company_name'],
            cto['company']['id'],
        ])