Introduction

Learn how to access and use SecurityScorecard's Bulk Data API. Using API for interaction and SFTP for delivery, Bulk Data API is the best way to access data from your account that is beyond the regular capabilities of our customer-facing REST API.

Onboarding

While the Customer-facing REST API can be accessed out of the box, the Bulk Data API requires some setup between your organization and SecurityScorecard. Don't worry though; we will be with you at every stage in the process. Please read below to see the steps involved.

Setting up the data transfer

Bulk Data files are shared using SFTP. To enable Bulk Data requests for your organization, SecurityScorecard will create an SFTP account for you in our own SFTP server. After this, you will be able to see your files by logging in. For example:

% sftp <my-org-domain>@ssc-sftp.securityscorecard.tech
Connected to ssc-sftp.securityscorecard.tech

Creating projects for your organization

Bulk data requests are managed within an organization using projects. A project defines a purpose for the data request, and is defined either by the domains in the project or the data types available to the project. One organization can have one or many projects depending on their use case.

Your organization may have multiple projects, and data cannot be requested without one. To create a new project, contact SecurityScorecard support with the unique name of the project(s) you want.

Each bulk data request endpoint requires a project name as part of the request payload. For example:

"project_name": "critical-vendors"

Sharing your domains

There are two ways to let the Bulk Data API know what domains (companies) you want information for. A portfolio can be provided to the endpoint, or a previously uploaded list in a file format.

Using a SecurityScorecard portfolio (<3000 domains)

If you have an existing SecurityScorecard portfolio that contains the domains you want data for, it is only necessary to specify the portfolio ID in your bulk data request payload. For example:

  "domain_source": {
    "portfolio": {
      "portfolio_id": "00000000-0000-0000-0000-000000000000"
    }
  }

Note: this refers to a portfolio that exists in your SecurityScorecard instance. The portfolio can be managed using the SecurityScorecard platform or through the customer-facing REST API.

Using a domain list (>3000 domains)

If your use case is not supported by a portfolio-based approach due to domain limit or any other reason, the SecurityScorecard Bulk Data API is able to read from a previously submitted CSV file containing the list of domains you want data for. To provide a domain list, please submit the following to SecurityScorecard support:

A CSV file that contains one row per domain
A known domain for this CSV file (this name is how this list will be referenced in request calls)
The name of your organization project that was created earlier during the onboarding process

SecurityScorecard support will intake this list of domains for you. After this onboarding step, you can request data by specifying the file name in your request payload. For example:

  "domain_source": {
    "url_list": {
      "file_name": "vendors.csv"
    }
  }

Notes on Usage

You may utilize both portfolios and CSV request files. It is recommended to use CSV request files for large lists of domains (more than around 3000 domains) whose domains do not change often, and portfolios for smaller lists of domains that change more often.

Accessing API Reference Documentation

Currently, SecurityScorecard can manually provide you with OpenAPI documentation on the available endpoints, upon request. The available endpoints do the following:

Request bulk data - submit a data request by specifying your project name, the source of the domains to get data for, and the data fields you want
Get project configurations - these endpoints make it easier to create a bulk data request by providing information about what you have previously configured. For example, you can get all the project names you have registered for your organization, and all the domain lists you have uploaded.
Get run status - these endpoints allow you to track the status of in-flight requests

Usage

Building a Request

A request to the Bulk Data API contains at least the following components:

organization domain (path param)
output format (header)
authorization (header)
project name (payload)
domain source (payload)
requested fields (payload)

Depending on the request, other facets may be included, as well as other commonly provided headers.

For full examples of requests that can be made to the Bulk Data API, see the "Examples" section below.

Organization Domain

Type: Path Parameter

You must specify the domain of your own organization in the URL path of your request, so that SecurityScorecard is aware of what SFTP account to export data to. This is your own organization's domain, not a domain that you are requesting data for. Instead, these other domains are provided using the request's domain_source field.

For example, /bulk-data-export/v1/run/scorecard-issues/my-organization/example.com means that data will be generated to example.com's SFTP account.

Your organization's account (and therefore domain) must have been onboarded as described in the previous section, and have SecurityScorecard Bulk Data API enabled as a feature. If you are not a member of the provided organization, or if the organization does not have the SecurityScorecard Bulk API feature enabled, the request will receive a permission failure response code.

Data output format

Type: Header
Header Name: X-Output-Format

You can request that your bulk data files be exported as either CSV or PARQUET. To specify the output file format, enter the format in the request header X-Output-Format. For example:

'X-Output-Format: CSV'

Authorization

Type: Header
Header Name: Authorization

The Bulk Data API uses the same API Token as the customer-facing REST API. This can be acquired from the My Settings section in the SecurityScorecard platform.

Provide the API Token as follows:

'Authorization: Bearer AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA'

Project Name

Type: Payload JSON Field
Field Name: project_name

The project name should have been previously provided to SecurityScorecard support during onboarding. Many organizations will have just one project, but there are cases where multiple projects are needed. Which project name you should use for what purpose will have been established during onboarding.

Domain Source

Type: Payload JSON Field
Field Name: domain_source

The domain source depends on decisions made during the onboarding process. A SecurityScorecard Platform Portfolio ID is an option, and so is a previously uploaded list of domains in a file format.

Portfolio as a source:

  "domain_source": {
    "portfolio": {
      "portfolio_id": "00000000-0000-0000-0000-000000000000"
    }
  }

File as a source:

  "domain_source": {
    "url_list": {
      "file_name": "vendors.csv"
    }
  }

Note: Only one source can be provided per request.

Response Dataset Fields

Type: Payload JSON Field
Field Name: fields

The fields field specifies what fields (presented as columns in CSV format) the user wants to be present in the generated file. Fields differ between different endpoints and data types.

Here is an example. Please read below to find the fields applicable to the calls you want to make.

"fields": {
    "total_score_fields": [
      "total_score",
      "total_grade",
      "breach_penalty"
    ],
    "factor_score_fields": [
      "factor_score",
      "factor_grade"
    ],
    "company_info_fields": [
      "company_name",
      "industry",
      "num_employees",
       "scorecard_birth_date"
    ]
  }

API Response format

Because of the volume of data in a Bulk Data dataset, the response from a request is not the data itself. Instead, a path is returned specifying where the data will become available when the processing is completed. The path will refer to a location inside your account's space located in Security Scorecard's SFTP server.

Additionally, the response will contain a Run ID that can be used to track the status of your processing bulk data request.

Here is an example response:

{
  "run_id": 1234,
  "pending_output_path": "my-project/scorecard-issues"
}

When the data is ready, you will be able to access it by logging into your SFTP account with SecurityScorecard, as described in the Onboarding seciton of this guide. The file that is generated will be tagged with the dataset name and the date of the request.

For example:

% sftp <my-org-domain>@ssc-sftp.securityscorecard.tech
Connected to ssc-sftp.securityscorecard.tech
% ls my-project/scorecard-issues
my-project/scorecard-issues/scorecard-issues_20220101.csv.gz

You can later view the status of a run by calling a status endpoint using the Run ID.

Common Troubleshooting

Any missed configuration or onboarding steps can lead to failure while using the Bulk Data API. Here are some examples:

You do not have any project set up yet for your organization, or you specified a non-existant project in your request
The Portfolio ID in your request payload does not exist or does not belong to your organization
The domain list filename provided in your request payload does not exist for your account

In addition, each endpoint has an enumeration of all the available fields you may request. You will receive an error if you enter a value in the request payload that is not one of the available fields. All the available fields are listed in the API reference for SecurityScorecard Bulk Data API.

Domain List Management

When requesting data generation, either a portfolio is supplied or a file that is available in the FTP server. Portfolios can be freely managed through the SecurityScorecard Platform. Domain Lists can be managed through the Bulk Data API.

When a Domain List is uploaded, an ID will be returned. This ID can be used in place of a file name in any data generation call.

All of the following requests can be made to the Bulk Data API endpoints, here:

https://api.securityscorecard.io/bulk-data-api/v1/

Uploading a Domain List

First, a request must be made to retrieve a secure upload link.

Method: POST

Endpoint:

/project-info/:organization/projects/:project-name/domain-lists?file-name=file-name.csv

Sample Response

{
	"domainList": {
		"domainListId": "293ee511-9f6c-459e-9249-bfecea06adfp",
		"projectId": "e3cdb079-75bc-4625-a77e-064e074b76ap",
		"fileName": "file-name.csv",
		"storedPath": <final destination of uploaded file>
	},
	"uploadUrl": {
		"method": "PUT",
		"url": <secure upload URL>,
		"headers": {
			"host": "ssc-data-exchange.s3-fips.us-east-1.amazonaws.com",
			"content-type": "application/binary"
		},
		"expiresAt": 1695154521981
	}
}

The secure upload URL can be used to upload a file, along with the provided method and headers. The PUT call to this secure URL should contain the desired file as its contents.

Please note that this upload link will be valid only for the next 60 minutes. If it expires, a user can simply re-generate a new link. Performing a file upload does not count towards quotas, so uploads can be done as many times as needed.

The domainListId provided in the response will act as a reference to the uploaded file from this point forward. This is what is used in the place of file-name when generating Bulk Data.

Replacing an existing Domain List

The instructions are the same as before. The only condition to replace an existing file is to use the same file name in the initial POST call.

Validating an Uploaded Domain List

Method: POST

Endpoint:

/project-info/:organization/projects/:project-name/domain-lists/:domain-list-id/validations

This call will trigger a job that takes in the a Domain List and produces a validated version of that Domain List. Validation may involve detecting malformed entries or mapping domains that actually redirect to other domains for their Scorecards.

Statuses can be:

Pending
Failed
Completed

Sample Response Body

{
    "domainListValidationId": "48169784-7f8f-43e2-88a4-997a2f6e00b7",
    "domainListId": "8f03e7be-8818-47cd-8bab-d07b46217ec1",
    "status": "pending",
    "createdAt": "2023-09-27T18:33:14.376822",
    "updatedAt": "2023-09-27T18:33:14.376822"
}

Checking Validation Job Status

Method: GET

Endpoint:

/project-info/:organization/projects/:project-name/domain-lists/:domain-list-id/validations/:domain-list-validation-id

Sample Response Body

{
    "domainListValidationId": "48169784-7f8f-43e2-88a4-997a2f6e00b7",
    "domainListId": "8f03e7be-8818-47cd-8bab-d07b46217ec1",
    "status": "pending",
    "createdAt": "2023-09-27T18:33:14.376822",
    "updatedAt": "2023-09-27T18:33:14.376822"
}

Viewing and Downloading Domain Lists

Method: GET

Endpoint:

project-info/:organization/projects/:project-name/domain-lists

The above call provides information about all of your Domain Lists under the specified project.

Method: GET

Endpoint:

project-info/:organization/projects/:project-name/domain-lists/:domain-list-id/download

The above call will allow you to download a previously uploaded Domain List.

Method: GET

Endpoint:

project-info/:organization/projects/:project-name/domain-lists/:domain-list-id/validations/:validation-id/download

The above call will allow you to download a Validated Domain List. This is necessary to view the data outputted by the validation system.

Validation Output

The validation functionality receives a set of domains, and for each domain, it returns a domain representing a particular Scorecard. In the case that the original domain has its own Scorecard, it will be returned. In some cases a domain does not have its own Scorecard. This could be because it simply redirects to another domain, or it has been merged into another Scorecard to more accurately represent an organization. In these cases, a different domain will be returned by the validation endpoints.

The Validated Domain List contains the following columns:

domain - The domain that was provided in the original Domain List
etld - The 2nd level domain that is processable by SecurityScorecard
resolved - The domain of the Scorecard that the provided domain maps to
status - A validation status that indicates the connection between the original domain and the Scorecard domain

These are the potential statuses that can be returned:

MAPPED
This status indicates that a Scorecard exists that is represented by this exact domain name. For example, walmart.com would represent Walmart Inc.’s Scorecard.

MAPPED_HOST
Scorecards are always represented with a second-level domain, which is a TLD with an additional level, such as yahoo.com. When a lower level domain is provided, the validation endpoint will return this status while providing a valid second-level domain that directly represents a Scorecard. For example, news.yahoo.com pertains to the Scorecard represented by yahoo.com.

MALFORMED
In some cases, a dataset may provide URLs that are not exact domain. In this case, this status will be returned and a new domain will not be suggested. The user can then retrieve the validated domain list and edit the URLs which are not exact domains. An example of an exact domain is nyt.com, whereas https://nyt.com or nyt.com/ would be considered malformed.

NO_SCORECARD
Not all domains have a Scorecard, even if the domain is considered valid. This can be for several cases, which will be described below. As the validation process runs, this status will be given to these cases. As validation continues, the below statuses will be updated along with the most applicable scorecard. If none of the cases below are located, then this status will remain, indicating that there is no appropriate Scorecard because the domain does not exist.

MAPPED_REDIRECT
In some cases, a domain exists to redirect to another domain. If a domain of this description is provided to the system, the second domain will be returned, along with this status.

MAPPED_CHILD
In some cases, a domain is a member of another Scorecard as a part of their digital footprint. If a domain of this description is provided, this status will be returned along with the domain that does map to the Scorecard. In this way, a completely accurate result is returned even if the domain does not pertain to a Scorecard directly.

Rate Limiting

Number of completed requests

By default, any project is able to receive 5 completed bulk data requests per 24 hours. To stay within your request limits, we recommend that you add all your domains of interest to your portfolio or domain list file, and then submit a data request for all your domains in a single request. If you have exceeded your completed request limit, the response will be a 429 error (Too Many Requests). If you feel it is applicable, you may contact SecurityScorecard support to discuss an increase in your request limit.

Note: A failed request does not count towards your 5 requests per day.

Number of concurrent requests

Your organization project is permitted a default of at most 5 concurrent in-flight requests. If your request exceeds the maximum concurrent request number, you will still receive a response with a run ID on submitting your bulk data request; however, that request will be skipped instead of being processed. It will also not be retried. This will be reflected if you query the the run status endpoint, which will show a status of SKIPPED due to too many concurrent requests.

Note: Skipped requests do not count towards your 5 requests per day.

Report Types

SecurityScorecard Bulk API currently supports four main groups of datasets:

scorecard summary, which retrieves summary, score and factor score information for a set of domains
scorecard issues, which retrieves summary data and issue summary information (such as a count of issue findings per type) for a set of domains
scorecard issue details, which retrieves details for issue findings, such as an asset's IP address, por or domain, if applicable
scorecard digital footprint, which retrieves IP-related digital footprint data about a set of domains

Each of these datasets has its own endpoint.

/v1/run/scorecard-summary/my-organization/{organization}
/v1/run/scorecard-issues/my-organization/{organization}
/v1/run/scorecard-issue-details/my-organization/{organization}
/v1/run/scorecard-digital-footprint/my-organization/{organization}

Each endpoint generates a dataset that has primary keys that are always present in the generated dataset. Since the primary keys are always automatically included, they should not be explicitly specified in the request payload.

The scorecard-summary endpoint has a primary key of parent_domain
The scorecard-issues endpoint has a primary key of parent_domain and issue_type
The scorecard-issue-details endpoint has a primary key of parent_domain and issue_type
The scorecard-digital-footprint endpoint has a primary key of parent_domain

For example, to request a scorecard-summary dataset with columns parent_domain, total_score only specify total_score in your data request.

Scorecard-summary

Endpoint

/v1/run/scorecard-summary/my-organization/{organization}

Available Fields

total_score_fields

total_score: numeric company rating (0-100).
total_grade: A-F company grade.
breach_penalty: the numeric penalty to the total score due to a breach event.

factor_score_fields (if requested, the factor name will also be automatically included as a column)

factor_score: numeric score for the factor (0-100).
factor_grade: A-F grade for the factor.

company_info_fields

company_name: Name of the company that owns the domain.
industry: Industry of the company that owns the domain. For example, "technology".
num_employees: A range describing the number of employees the company has.
scorecard_birth_date: The first day from which SecurityScorecard has data for this domain.

Example Request Body

  "fields": {
    "total_score_fields": [
      "total_score",
      "total_grade",
      "breach_penalty"
    ],
    "factor_score_fields": [
      "factor_score",
      "factor_grade"
    ],
    "company_info_fields": [
      "company_name",
      "industry",
      "num_employees",
       "scorecard_birth_date"
    ]
  }

Folder Structure

The folder structure will be as follows:
organization-name/project-name/scorecard-summary/requestdate=_YYYYMMDD/scorecard-summary_file-name.csv.gz

Response Columns

url
parent_domain
company_name
industry
num_employees
total_score
total_grade
breach_penalty
application_security_grade
application_security_score
application_security_count
cubit_score_grade
cubit_score_score
cubit_score_count
dns_health_grade
dns_health_score
dns_health_count
endpoint_security_grade
endpoint_security_score
endpoint_security_count
hacker_chatter_grade
hacker_chatter_score
hacker_chatter_count
ip_reputation_grade
ip_reputation_score
ip_reputation_count
leaked_information_grade
leaked_information_score
leaked_information_count
network_security_grade
network_security_score
network_security_count
patching_cadence_grade
patching_cadence_score
patching_cadence_count
social_engineering_grade
social_engineering_score
social_engineering_count

Scorecard-issues

Endpoint

/v1/run/scorecard-issues/my-organization/{organization}

Available Fields

scorecard_issue_fields

factor_name: The factor that the issue type belongs to. For example, the issue type domain_missing_https belongs to the application_security factor.
issue_count: The number of issues found for an issue_type under a given domain.
total_score_impact and factor_score_impact: the numeric penalty to the total or factor score due to findings of a particular issue type on a domain.

Example Request Body

"fields": {
  "scorecard_issue_fields": [
    "factor_name", 
    "issue_count",
    "total_score_impact",
    "factor_score_impact"
  ]
}

Folder Structure

The folder structure will be as follows:
organization-name/project-name/scorecard-issues/requestdate=_YYYYMMDD/scorecard-summary_file-name.csv.gz

Response Columns

parent_domain
issue_type
issue_count
total_score
total_score_impact
severity
factor_score
factor_name
factor_score_impact

Scorecard-issue-details

The Issue Details endpoint is different than the others. The customer is able to select the fields they want to see, but they are also able to select the issues themselves by specifying them.

Endpoint

/v1/run/scorecard-issue-details/my-organization/{organization}

Available Issues

outdated_browser
outdated_os
admin_subdomain_v2
csp_no_policy_v2
csp_too_broad_v2
csp_unsafe_policy_v2
domain_missing_https_v2
hosted_on_object_storage_v2
hsts_incorrect_v2
insecure_https_redirect_pattern_v2
redirect_chain_contains_http_v2
references_object_storage_v2
site_uses_hsts_preloading_v2
unsafe_sri_v2
uses_go_daddy_managed_wordpress
uses_log4j
waf_detected_v2
x_content_type_options_incorrect_v2
x_frame_options_incorrect_v2
x_xss_protection_incorrect_v2
communication_server_with_expired_cert
cookie_missing_http_only
cookie_missing_secure_attribute
exploited_product
adware_installation_trail
adware_installation
anonymous_proxy
attack_detected
malware_controller
malware_infection_trail
malware_infection
phishing
pva_installation_trail
pva_installation
ransomware_infection_trail
ransomware_infection
suspicious_traffic
service_end_of_life
service_end_of_service
ransomware_association
ransomware_victim
bitcoin_server
cdn_hosting
cobalt_strike_c2_service
exploited_product
exposed_embedded_iot_web_server
exposed_iscsi_device
exposed_mac_airport_device
exposed_mobile_printing_service
exposed_network_attached_storage_device
exposed_printer
industrial_control_device
iot_camera
java_debugger
mail_server_unusual_port
microsoft_exchange_0_day_vulnerability
microsoft_exchange_http_api_vulnerability
minecraft_server
mysql_server_empty_password
product_uses_vulnerable_log4j
remote_access
service_cassandra
service_cloud_provider
service_couchdb
service_dns
service_elasticsearch
service_exposed_port
service_ftp
service_generic
service_http_proxy
service_imap
service_ldap
service_ldap_anonymous
service_microsoft_sql
service_mongodb
service_mysql
service_neo4j
service_netbus_remote_access
service_networking
service_open_vpn
service_oracle_db
service_oracle_registry
service_pop3
service_postgresql
service_pptp
service_pulse_vpn
service_rdp
service_redis
service_rsync
service_smb
service_soap
service_socks_proxy
service_telnet
service_vnc
telephony
tor_server
upnp_accessible
spa_browser
uce
spf_record_malformed
spf_record_missing
spf_record_softfail
spf_record_wildcard
ssh_weak_cipher
ssh_weak_mac
ssh_weak_protocol
tls_ocsp_stapling
tls_weak_cipher
tls_weak_protocol
patching_cadence_high
patching_cadence_info
patching_cadence_low
patching_cadence_medium
service_vuln_host_high
service_vuln_host_info
service_vuln_host_low
service_vuln_host_medium
web_vuln_host_high
web_vuln_host_low
web_vuln_host_medium
tlscert_excessive_expiration
tlscert_expired
tlscert_extended_validation
tlscert_no_revocation
tlscert_revoked
tlscert_self_signed
tlscert_weak_signature
uses_go_daddy_infrastructure
alleged_breach_incident
patching_analysis_high
patching_analysis_low
patching_analysis_medium
threat_actor_hosting_infrastructure
webapp_vulnerable_to_spring4shell

Example Request Body

In this example request body, the Issue of patching_cadence_medium is selected, and a set of fields that belong to it are specified, such as parent_domain, measurement_type, etc.

"issues_detail_fields": {
	"patching_cadence_medium":[
			"url",
			"parent_domain",
			"effective_date",
			"issue_type",
			"measurement_id",
			"measurement_count",
			"first_seen_time",
			"last_seen_time",
			"vulnerability_id",
			"vulnerability_url",
			"vulnerability_description",
			"vulnerability_publish_date",
			"connection_attributes"
	]
}

Folder Structure

The folder structure will be as follows:
organization-name/project-name/scorecard-issue-details/requestdate=_YYYYMMDD/issuetype_partition=_issue-type/scorecard-summary_file-name.csv.gz

Scorecard-digital-footprint

Endpoint

/v1/run/scorecard-digital-footprint/my-organization/{organization}

Here is an example below:

"digital_footprint_fields": {
    "digital_footprint_fields":[
        "parent_domain",
        "ip", 
        "detection", 
        "score_impact", 
        "issues", 
        "findings", 
        "country", 
        "code", 
        "city", 
        "domains", 
        "domains_count"
    ]
}

Response Columns

ip: Real ip address in the digital footprint
detection: The detection method inside SecurityScorecard
score_impact: The numeric penalty to the total score due to findings by the corresponding ip
issues and findings: The count for the issue type and the count for the issues
country and code and city: Geo information under current ip
domains: Listed all child domains used by current ip
domains_count: Count of the above listed child domains

Selecting Score Version

Beginning in early 2024 and ending April 9th 2024, Scoring 3.0 data will be available simultaneously with the previous scoring version. On April 9th, the data will permanently switch to Scoring 3.0 and the previous scoring data will no longer be available. Scoring 3.0 is an improvement to SecurityScorecard's scoring methodology.

During the transitionary period, specific scoring data can be requested using an input parameter. This parameter is a query parameter, score-type. It can be used on the scorecard-summary report. There is one caveat: This query parameter is available only on a new path (to ensure there is no interference with existing implementations). Instead of /v1/run/scorecard-summary/my-organization/{organization}the path must be /v1/run/scorecard-summary-score-type/my-organization/{organization}

The possible values for score-type are:

scoring_v3
scoring_v2

If not included, the default will be scoring_v2 until April 9th, after which scoring_v3 will become the default. At this time, the original path "scorecard-summary" will also default to Scoring 3.0 data.

Examples

Put your organization domain in the URL path so that SecurityScorecard can export data to your SFTP account. Here, because securityscorecard.io is in the URL path, the data will be exported to securityscorecard.io's SFTP account (as long as you are a user who belongs to the organization - otherwise the request will be unpermissioned)

To specify the domains to retrieve data about, use the domain_source field of your request payload. Here, data will be retrieved for the domains in the vendors.csv file that you previously registered.

Replace the XXX in the authorization: Token header with your authorization token. If you don't have an authorization token, you can request one at My Settings -> API

Scorecard-issues

Domains from an uploaded list

curl -X 'POST' 
'https://api.securityscorecard.io/bulk-data-export/v1/run/scorecard-issues/my-organization/securityscorecard.io' 
-H 'accept: application/json' 
-H 'X-Output-Format: CSV' 
-H 'Content-Type: application/json' 
-H 'authorization: Token XXXXXXXXXXXXXXX' 
-d '{
"project_name": "critical-vendors",
"domain_source":  {
  "url_list": {
    "file_name": "vendors.csv"
  }
 },
"fields": {
  "scorecard_issue_fields": [
    "issue_count",
    "total_score_impact"
    ]
  }
}'

This endpoint will retrieve data for domains in the vendors.csv file that you must have previously submitted. The output of this endpoint will be a file SFTPd to your account that has columns parent_domain, issue_type, issue_count, total_score_impact

Domains from a portfolio

curl -X 'POST' 
'https://api.securityscorecard.io/bulk-data-export/v1/run/scorecard-issues/my-organization/securityscorecard.io' 
-H 'accept: application/json' 
-H 'X-Output-Format: CSV' 
-H 'Content-Type: application/json' 
-H 'authorization: Token XXXXXXXXXXXXXXX' 
-d '{
"project_name": "critical-vendors",
"domain_source": {
  "portfolio": {
    "portfolio_id": "00000000-0000-0000-0000-000000000000"
  }
},
"fields": {
  "scorecard_issue_fields": [
    "issue_count",
    "total_score_impact"
    ]
  }
}'

This endpoint will retrieve data for domains in your existing SecurityScorecard portfolio with ID 00000000-0000-0000-0000-000000000000. The output of this endpoint will be a file SFTPd to your account that has columns parent_domain, issue_type, issue_count, total_score_impact

Scorecard-issue-details

Domains from an uploaded list

curl -X 'POST' 
'https://api.securityscorecard.io/bulk-data-export/v1/run/scorecard-issue-details/my-organization/securityscorecard.io' 
-H 'accept: application/json' 
-H 'X-Output-Format: CSV' 
-H 'Content-Type: application/json' 
-H 'authorization: Token XXXXXXXXXXXXXXX' 
-d '{
"project_name": "critical-vendors",
"domain_source":  {
  "url_list": {
    "file_name": "vendors.csv"
  }
 },
"cumulative":false,
"issues_detail_fields": {
	"patching_cadence_medium":[
			"url",
			"parent_domain",
			"effective_date",
			"issue_type",
			"measurement_id",
			"measurement_count",
			"first_seen_time",
			"last_seen_time",
			"vulnerability_id",
			"vulnerability_url",
			"vulnerability_description",
			"vulnerability_publish_date",
			"connection_attributes"
	]
  }
}'

Similar to Scorecard-issues, this endpoint will retrieve issue details data for domains in the vendors.csv file that you must have previously submitted. Parameter cumulative being set to true means querying all active issues up to now and set false means querying only daily active issues that observed by current effective date.

Scorecard-summary

Domains from an uploaded list, no factor score fields

curl -X 'POST' 
'https://api.securityscorecard.io/bulk-data-export/v1/run/scorecard-issues/my-organization/securityscorecard.io' 
-H 'accept: application/json' 
-H 'X-Output-Format: CSV' 
-H 'Content-Type: application/json' 
-H 'authorization: Token XXXXXXXXXXXXXXX' 
-d '{
"project_name": "critical-vendors",
"domain_source":  {
  "url_list": {
    "file_name": "vendors.csv"
  }
 },
"fields": {
  "total_score_fields": [
    "total_score"
  ],
  "company_info_fields": [
    "company_name"
  ]
}

Domains from an uploaded list, with factor score fields

curl -X 'POST' 
'https://api.securityscorecard.io/bulk-data-export/v1/run/scorecard-issues/my-organization/securityscorecard.io' 
-H 'accept: application/json' 
-H 'X-Output-Format: CSV' 
-H 'Content-Type: application/json' 
-H 'authorization: Token XXXXXXXXXXXXXXX' 
-d '{
"project_name": "critical-vendors",
"domain_source":  {
  "url_list": {
    "file_name": "vendors.csv"
  }
 },
"fields": {
  "total_score_fields": [
    "total_score"
  ],
  "factor_score_fields": [
    "factor_score"
  ]
}

This endpoint will retrieve data for domains in the vendors.csv file that you must have previously submitted. Because factor data was requested, the factor names will also appear as columns. The output of this endpoint will be a file SFTPd to your account that has columns parent_domain, total_score, application_security_score, dns_health_score, ... (and <factor_name_here>_score for the rest of the factors)

Job Run Status

curl -X 'GET'
'https://api.securityscorecard.io/bulk-data-export/v1/run/status/my-organization/securityscorecard.io?run-id=*****' 
-H 'Content-Type: text/palin' 
-H 'authorization: Token XXXXXXXXXXXXXXX'

This endpoint is used for checking the run status after sending a report request like scorecard-summary, scorecard-issues and domain validation. possible results can be PENDING, RUNNING or SUCCESS.

Scorecard-digital-footprint

Domains from an uploaded list

curl -X 'POST' 
'https://api.securityscorecard.io/bulk-data-export/v1/run/scorecard-digital-footprint/my-organization/securityscorecard.io' 
-H 'accept: application/json' 
-H 'X-Output-Format: CSV' 
-H 'Content-Type: application/json' 
-H 'authorization: Token XXXXXXXXXXXXXXX' 
-d '{
"project_name": "critical-vendors",
"domain_source":  {
  "url_list": {
    "file_name": "vendors.csv"
  }
 },
"digital_footprint_fields": {
    "digital_footprint_fields":[
        "parent_domain",
        "ip", 
        "detection", 
        "score_impact", 
        "issues", 
        "findings", 
        "country", 
        "code", 
        "city", 
        "domains", 
        "domains_count"
    ]
}

This endpoint will retrieve data for domains in the vendors.csv file that you must have previously submitted. The output of this endpoint will be split files SFTPd to your account that has above columns

Predictive-breach-score (PoC)

Note: This endpoint is in PoC (proof of concept) stage and only available to a handful of clients that will interact with it to provide feedback.

This endpoint will retrieve breach scores predicted for domains in the vendors.csv file that you must have previously submitted. (This .csv file must have a single column named url that contains all the domains)

curl -X 'POST' 
'https://api.securityscorecard.io/bulk-data-export/v1/run/breach-score-predictions/my-organization/{CUSTOMER_DOMAIN}' 
-H 'accept: application/json' 
-H 'X-Output-Format: CSV' 
-H 'Content-Type: application/json' 
-H 'authorization: Token XXXXXXXXXXXXXXX' 
-d '{
"project_name": "breach_score_predictions",
"domain_source": {
  "url_list": {
      "file_name": "vendors.csv"
  }
},
"model_versions": ["v1", "v2"],
"score_dates": ["20230115", "20220601"]
}

Put your organization domain in the URL path so that SecurityScorecard can export data to your SFTP account.
To specify the domains to retrieve data about, use the domain_source field of your request payload. Here, data will be retrieved for the domains in the vendors.csv file that you previously registered.
Replace the XXX in the authorization: Token header with your authorization token. If you don't have an authorization token, you can request one at My Settings -> API

Request body fields

project_name: always should be "breach_score_predictions"
domain_source.url_list.file_name: should be the name of the file with the domains
model_versions: list of model versions used for predictions
- v1: predicts using data from measurements, digital assets, total and factor scores
- v2: predicts using the same data that v1 but also adding firmographics data.
score_dates: list of dates to perform the predictions on. Format should must be YYYYMMDD.

Output

The output of this endpoint will be a CSV file named breach_scores.csv SFTPd to your account that has columns domain, total_score, breach_predictive_score, model_version, score_date