Atlas API

Download OpenAPI specification:Download

Atlas REST API (Application Programming Interfaces) provides endpoints for sending a questionnaire based on several industry and custom templates available in Atlas and getting back questionnaires with answers.

Quick start

This guide is designed to help users to start with our API and use it for basic workflow:

  1. Authenticating to the API with your SecurityScorecard ratings platform credentials.

  2. Select a questionnaire template which was previously defined in Atlas. You can select any of the industry standard templates (e.g. SIG, NIST, PCI, HIPAA, ISO…) or use your own custom template which was previously created in the Atlas UI.

    GET /companies/current/standards

  3. Send a questionnaire request based on the selected template and target user or company domain.

    POST /requests

  4. Find out details of the request, e.g. who was the recipient, or in which status the questionnaire request is (Open, In progress, Under review, Accepted/Closed).

    GET /requests/{request_id}

  5. Get the questionnaire responses and attachments.

    GET /forms/{form_id}

Vocabulary

Atlas API needs to define more specialized terms than those used in the Atlas UI. Therefore, the terms can differ a bit. These are the most important terms you should know in order to use the Atlas API properly. The introduction part of this documentation is using terms similar to the ones in UI and mentioning proper APIs to be used. Documentation of endpoints is using the API terms.

  • Standard - questionnaire standard is the questionnaire template. Examples of standards with type SYSTEM are industry standard templates such as NIST, GDPR, ISO. Standards with type CUSTOM are templates which your company created using the template creator UI or by uploading Excel template. Object Standard contains template name, year and version. Object FormDefinition contains a set of questions for given standard.

  • FormFilling - any questionnaire sent. In Atlas there are several types of questionnaires. The most important types are REQUEST (visible in Sent / Received questionnaire page), MASTER and UPLOAD (visible in Answer & Evidence page, keeping default answers or answers based on uploaded questionnaire) and PREVIEW (preview of questionnaire templates).

  • Form versus Request - use /requests endpoints to get information for form filling of type REQUEST - i.e. only Sent / Received questionnaires. For more options you can use the endpoint /forms to get information about forms of other form filling types, e.g. for your MASTER and UPLOAD questionnaires on Answer & Evidence page.

Authentication with API key

Atlas users are authenticated via the SecurityScorecard ratings platform account. Please follow the guide in order to login to API with platform API key.

  1. Sign in to SecurityScorecard Ratings Platform.

  2. Go to API settings page.

  3. Click Generate New Token.

  4. Copy the token.

  5. Test the token by calling GET /users/current/info:

    curl -X GET "https://api.securityscorecard.io/atlas/users/current/info" \
    -H "Accept: application/json" \
    -H "Authorization: Token <your token>"

This endpoint returns information about your Atlas account. It returns (among other things) your user name and number of received and sent requests and how many credits you have available for sending a questionnaire - see attribute credits.remaining.

User info popover in the GUI

Select a template

Atlas continas Templates page housing all the standard templates and custom questionnaires. Atlas offers 20 out of the box templates (as listed below) but you can additionally upload an excel template, use the provided template, or create a custom questionnaire template. Templates are called standards in the API.

Example of available templates in the GUI
curl -X GET "https://api.securityscorecard.io/atlas/companies/current/standards" \
  -H "Accept: application/json" \
  -H "Authorization: Token <your token>"

Select your preferred template based on the field name. Later you can refer to it based on the field id. You can select templates based on their status - system standards are industry standard templates (e.g. SIG, ISO, NIST), custom standards are templates created by your company by uploading Excel template or by creating new template in the UI template builder. Drafts are templates which are not published yet and therefore it is not possible to send a questionnaire request based on this template.

For example, if you want to send a CIS 2016 v.6 questionnaire request, you are looking for the following information:

{
   "id": "8053deba-bcd6-449b-81e4-a3bf4fe7fe83",
   "name": "CIS Critical Security Controls",
   "version": "v.6",
   "year": 2016,
   ...
}

Send a questionnaire request

Select a questionnaire template or multiple questionnaire templates at once. Atlas enables you to send more questionnaires based on multiple templates to one or more recipients. Each sent questionnaire will cost 1 credit.

You can send a questionnaire either to the recipient's email, or straight to the company domain. Note that some subdomains are merged under one domain in SecurityScorecard platform. Anybody associated with the company in SecurityScorecard can use the link to respond and collaborate to the questionnaire.

Recepient selection GUI example

See example how to send a questionnaire based on template CIS (which ID we know from previous query) to recipient user@company.com, with due date 2020-06-08, reminder two weeks before due date, using personalized message:

curl -X POST "https://api.securityscorecard.io/atlas/requests" \
  -H "Accept: application/json" \
  -H "Authorization: Token <your token>" \
  -H 'Content-Type: application/json' \
  -d '{"due_date":"2020-06-08T22:00:00.000Z","email_body":"Hi! Message to recipient","notify":true,"reminder":14,"standard_ids":["8053deba-bcd6-449b-81e4-a3bf4fe7fe83"],"targets":["user@company.com"]}'

See example how to set parameters if the questionnaire should be sent to a company domain company.com.

'{"due_date":"2020-06-08T22:00:00.000Z","email_body":"","notify":false,"reminder":-1,"standard_ids":["8053deba-bcd6-449b-81e4-a3bf4fe7fe83"],"targets":["company.com"]}'

You will receive a confirmation message, which contains ID of the questionnaire request and ID of the form. These will be used later for getting the status and answers on the questionnaire.

"form_id": "2bb7ad61-e9db-498a-84d6-707c898506f7",
"form_name": "Request for CIS Critical Security,
"id": "fa1b9fcc-2a7c-4cb6-8294-822a4583a9a3"

Get status of the questionnaire request

Find out details of the request. You will be notified via email when the recipient submits a questionnaire, but if you would like to automate the process by using the API, you can use the following endpoint for getting status of the questionnaire:

curl -X GET "https://api.securityscorecard.io/atlas/requests/fa1b9fcc-2a7c-4cb6-8294-822a4583a9a3" \
  -H "Accept: application/json" \
  -H "Authorization: Token <your token>"

In the response you can find field status (Open, In progress, Under review, Accepted/Closed) and other important information, for example who was the recipient of the questionnaire (see target properties), how many questions are filled in etc.

Received form item in the GUI

Get the questionnaire responses and attachments

Once the recipient submitted the questionnaire for review or allowed you to see the responses, you can get the responses and attachments from the questionnaire.

Question example in the GUI

If you want to continue with processing of the data, you can use the endpoint GET /forms/{form_id} to get all details about the sent form:

curl -X GET "https://api.securityscorecard.io/atlas/forms/2bb7ad61-e9db-498a-84d6-707c898506f7" \
  -H "Accept: application/json" \
  -H "Authorization: Token <your token>"

To obtain questions and responses of the form, use the dedicated endpoint GET /forms/{form_id}/questions:

curl -X GET "https://api.securityscorecard.io/atlas/forms/2bb7ad61-e9db-498a-84d6-707c898506f7/questions?limit=30" \
  -H "Accept: application/json" \
  -H "Authorization: Token <your token>"

You can optionally limit the results to contain only questions from a specific category or apply various other filters.

If you want to download questionnaire with answers in CSV format, for example for archiving purposes, please use GET /forms/{form_id}/downloads/csv_export

You can also download a ZIP file which contains the CSV with answers and also attachments by using GET /forms/{form_id}/downloads/attachments

curl -X GET "https://api.securityscorecard.io/atlas/forms/2bb7ad61-e9db-498a-84d6-707c898506f7/downloads/attachments" \
  --output file.zip \
  -H 'Accept: application/json' \
  -H "Authorization: Token <your token>" \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'

companies

Companies can be referred to using their ID or using /current/ as placeholder for the company ID of the signed-in user

Return list of standards belonging to the given company

Authorizations:
query Parameters
hp
boolean
Default: true

Return only standards for homepage (applies to system standards only)

limit
integer >= 1

Limits the number of entries in the response.

sort
string
Default: "name"
Enum: "name" "most_recent" "most_used"

Method of sorting the results

status
Array of strings
Default: ["system","custom","draft"]
Items Enum: "system" "custom" "draft"

Fetch only standards with specified statuses

  • SYSTEM standards are accessible to all companies. They should be owned by company with internal_status = SYSTEM.
  • CUSTOM standards are created by individual companies. Only owner of the standard can send request for this standard.
  • DRAFT standard is a standard whose form definition is currently being created in the form creator. Request from this standard cannot be (yet) sent.

Responses

200

Success

Response Schema: application/json
entries
required
Array of objects (Standard)
msg
required
string

Message related to response

401

User is not authorized.

403

Standard doesn't exist or user doesn't have access to it.

get/companies/current/standards
/v2/companies/current/standards

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "msg": "string",
  • "entries":
    [
    ]
}

Return list of standards belonging to the given company

Authorizations:
path Parameters
company_id
required
string
query Parameters
hp
boolean
Default: true

Return only standards for homepage (applies to system standards only)

limit
integer >= 1

Limits the number of entries in the response.

sort
string
Default: "name"
Enum: "name" "most_recent" "most_used"

Method of sorting the results

status
Array of strings
Default: ["system","custom","draft"]
Items Enum: "system" "custom" "draft"

Fetch only standards with specified statuses

  • SYSTEM standards are accessible to all companies. They should be owned by company with internal_status = SYSTEM.
  • CUSTOM standards are created by individual companies. Only owner of the standard can send request for this standard.
  • DRAFT standard is a standard whose form definition is currently being created in the form creator. Request from this standard cannot be (yet) sent.

Responses

200

Success

Response Schema: application/json
entries
required
Array of objects (Standard)
msg
required
string

Message related to response

401

User is not authorized.

403

Standard doesn't exist or user doesn't have access to it.

get/companies/{company_id}/standards
/v2/companies/{company_id}/standards

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "msg": "string",
  • "entries":
    [
    ]
}

forms

Return details, metadata and statistics of the given form

Note: Remember to check the form.initialization_status in the response to be sure that the form is properly initialized (has status FINISHED_SUCCESS) and contains complete data.

URL parameters:

  • form_id - UUID of the form
Authorizations:
path Parameters
form_id
required
string
query Parameters
assignee_id
string

Filter questions by specified assignee

filters
Array of strings
Default: []
Items Enum: "yes" "no" "na" "attachments" "attachments_new" "comments" "comments_new" "required" "filled" "completely_filled" "partially_filled" "not_filled" "ssc_data" "ssc_data_new" "vrm_review_pending" "vrm_review_flagged" "vrm_review_done" "unassigned" "responses" "responses_new" "autocomplete_done" "autocomplete_suggestions_available"

Comma separated list of filters applied to form questions, possible values:

  • yes - questions with YES answer
  • no - questions with NO answer
  • na - questions with N/A answer
  • attachments - questions with attachemnts
  • attachments_new - questions with new attachments added since last view
  • comments - questions with comments
  • comments_new - questions with new comments added since last view
  • required - questions that contain at least one required response (filled or not)
  • filled - questions with all required responses filled plus filled optional questions
  • completely_filled
  • partially_filled
  • not_filled - completely empty questions and questions with missing required responses
  • ssc_data - questions with SecurityScorecard data available
  • ssc_data_new - questions with SecurityScorecard data newly available since last view
  • vrm_review_pending - questions with pending VRM review
  • vrm_review_flagged - questions flagged by VRM
  • vrm_review_done - questions marked as reviewed by VRM
  • unassigned - questions that are not assigned to a specific user
  • responses
  • responses_new - questions with new responses added since last view
  • autocomplete_done - questions that are autocompleted
  • autocomplete_suggestions_available - questions with autocompletion suggestions available

Example: required,not_filled

question_ids
Array of strings
Default: []

List of questions to be used for stats

Responses

200

Success

Response Schema: application/json
entry
required
object (FormMetadata)
msg
required
string

Message related to response

401

User is not authorized.

403

Form doesn't exist or user doesn't have access to it.

410

Form is already deleted.

get/forms/{form_id}
/v2/forms/{form_id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "msg": "string",
  • "entry":
    {