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