UpGuard CyberRisk provides a public API to enable you to add and view vendor information by primary domain. When you are first setting up your account it may be useful to bulk import a pre-existing list of vendors so you can get up and running quickly. This guide shows you how to leverage the API to import vendors from a CSV file.

Here we are going to:

  • Prepare our vendors into the correct format for bulk import,
  • Prepare a sample script to import the vendors via the API

Preparing your list of vendors

UpGuard CyberRisk uses the primary domain name of a vendor as a unique way to identify a vendor. This prevents any ambiguity that may arise between Apple the multinational technology company and Apple, the record producer. So, when preparing your list of vendors you will need to assign each their primary domain name. Here’s an example of a prepared spreadsheet of some vendors of UpGuard.

vendor,    domain
Google, google.com
auth0, auth0.com
Taco bell, tacobell.com

If you have your list of vendors and their domains in a spreadsheet, you can export to CSV for the next section. When importing vendors via the API, we only technically need the primary domain, but most customers also list the name of the vendor, so we’re going to use a vendor name and domain setup for the example shown on this page.

Locating your API Key

To access your API key, navigate to the Account Settings page via the bottom of the left panel. You will need to be an admin user for your account to see this menu item.

From the Account Settings page, navigate to the API tab. If you have not generated an API key before, you can generate one by clicking generate one here.

Building and Running the Import Script

Here we have provided a few sample scripts that can ingest the above two column CSV file format and import vendors into your account. You will need to substitute your own API Key into these scripts in place of the sample key. If you don’t see your preferred scripting language below, please contact UpGuard Support and we can add more examples to this page.

For more information on the endpoint we are using here, please visit Get vendor details.

Ruby

require 'httparty'
require 'csv'

$api_key = "1234-567-89..."
$base_url = "https://cyber-risk.upguard.com/api/public"

CSV.foreach("vendors.csv") do |row|
vendor = row[0]
domain = row[1]
next if vendor == "vendor" # trying to ignore the header first line of the CSV file

response = HTTParty.get("#{$base_url}/vendor?hostname=#{domain}&start_monitoring=true",
:headers => { "Authorization" => $api_key })
puts "#{vendor} (#{domain})"
puts response.code
puts response.body
end

Note: the line next if vendor == "vendor" is an attempt to not include the header row of the CSV file as an API lookup. You could additionally export your vendor list to CSV without the header vendor_name,domain row.

Python

import csv
import requests

api_key = "1234-567-89..."
headers = { "Authorization": api_key }
base_url = "https://cyber-risk.upguard.com/api/public"

with open("vendors.csv") as csvfile:
lines = csv.reader(csvfile, delimiter=',')
for row in lines:
vendor = row[0]
domain = row[1]
if vendor == "vendor":
continue # trying to ignore the header row
url = base_url + "/vendor?hostname=" + domain + "&start_monitoring=true"
response = requests.get(url, headers=headers)
print(response.status_code)
print(response.text)

Note: the lines if vendor == "vendor": continue are an attempt to not include the header line of the CSV file in the API lookup.

Bash/Curl

#!/bin/bash

API_KEY="1234-567-89..."

for d in `cat vendors.csv | awk -F "," '{print $NF}' | grep -vE "^domain$"
do
curl -H "Authorization: $API_KEY" "https://cyber-risk.upguard.com/api/public/vendor?hostname=$d&start_monitoring=true" done

Note: The grep -vE "^domain$" part of the script is an attempt to ignore the header row of your CSV file. You could additionally not export spreadsheet headers to your CSV file or manually delete the header row before importing.

Note: If you would like an example in a language not listed here, please contact UpGuard Support.

What Next?

For more information on viewing the security score and risks of particular vendors, please refer to our article What is UpGuard Vendor Risk?.

If you would like to start sending Security Questionnaires to your vendors, please see our article on Sending Security Questionnaires to Vendors.

Did this answer your question?