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)

ignore_preview_uninitialized
boolean
Default: true
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)

ignore_preview_uninitialized
boolean
Default: true
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":
    {
    }
}

Download zip file with form and attachments

URL parameters:

  • form_id - uuid, id or code
Authorizations:
path Parameters
form_id
required
string

Responses

200

Zip file

401

User is not authorized.

403

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

get/forms/{form_id}/downloads/attachments
/v2/forms/{form_id}/downloads/attachments

Response samples

Content type
No sample

Download form in csv format

Authorizations:
path Parameters
form_id
required
string

Responses

200

CSV file

401

User is not authorized.

403

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

get/forms/{form_id}/downloads/csv_export
/v2/forms/{form_id}/downloads/csv_export

Response samples

Content type
No sample

Return questions in given form

Path parameters:

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

Filter by assignee

blocks
Array of strings
Default: ["attachments"]
Items Enum: "attachments" "comments" "ssc_data" "history"

List of blocks to return, possible values:

  • attachments - Block with attachments
  • comments - Block with comments
  • ssc_data - Block with SSC data
  • history - Block with history
category
string

Filter by category

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, 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
ids
Array of strings
Default: []

List of specific questions to return

limit
integer >= 1
Default: 50

Max number of questions to return

offset
integer >= 0
Default: 0

Number of questions to skip

Responses

200

Success

Response Schema: application/json
entries
required
Array of objects (QuestionMetadata)
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.

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

Response samples

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

requests

Sending and handling form requests, sent between two companies

Return requests using given criteria

Authorizations:
query Parameters
company_id
Array of strings
Default: []

Return only requests sent OR received by the given company (or by any of given companies)

form_roles
Array of strings
Default: []
Items Enum: "VENDOR" "VENDOR_PROXY" "VRM" "VRM_PROXY"

Return only requests such that the logged user has one of the specified form roles toward them

limit
integer

Limit the number of returned results

only_external
boolean
Default: false
only_internal
boolean
Default: false
sent_time_from
string <date-time>

Return only requests sent after given time/date (inclusive)

sent_time_to
string <date-time>

Return only requests sent before given time/date (inclusive)

source_id
Array of strings
Default: []

Return only requests sent by the given company (or by any of given companies)

source_team_ids
Array of strings
Default: []

Return requests that are sent by the given teams

source_user_email
Array of strings
Default: []

Return only requests sent by the user with given email (or by any of given users)

standard_id
Array of strings
Default: []

Return only requests with any of given standards

status
Array of strings
Default: []
Items Enum: "CREATED" "VENDOR_IN_PROGRESS" "VRM_IN_PROGRESS" "ACCEPTED" "CANCELED" "ARCHIVED" "UNARCHIVED"

Return only requests with any of given statuses

target_id
Array of strings
Default: []

Return only requests received by the given company (or by any of given companies)

target_team_ids
Array of strings
Default: []

Return requests that are sent to the given teams

target_user_email
Array of strings
Default: []

Return only requests received by the user with given email (or by any of given users)

user_email
Array of strings
Default: []

Return only requests sent OR received by the user with given email (or by any of given users)

with_revisions
integer
Default: ""

Return requests by number of reviews

Responses

200

Success

Response Schema: application/json
entries
required
Array of objects (RequestDetail)
meta
required
object (RequestFiltersStatsMeta)
msg
required
string

Message related to response

401

User is not authorized.

403

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

get/requests
/v2/requests

Response samples

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

Send new request(s)

Authorizations:
Request Body schema: application/json
due_date
string <date-time>

Due date for filling the form. Omit to send questionnaire without a due date

email_body
string
Default: ""

Text of the email sent to the vendor

notify
boolean
Default: true

Set to true if recepients specified in targets should be notified via email. This is usually useful for sending requests to individual users, in case of sending to a company by domain, company.requests_email is used.

reminder
integer

How many days before due date should the user be notified

source_team
string

Source team UUID of the actual sender. This field is optional when a user who is not a part of any team, sends a questionnaire to another user/company.

standard_ids
required
Array of strings

List of IDs of standards that should be sent to the vendor for filling

targets
required
Array of strings

List of recepients of the standards. Recepient can be either a company specified as a domain (e.g. "example.com") or a specific user from the company (e.g. "john.doe@example.com").

Limitation: In order to keep the sevice accessible for everyone, the total recipients should not exceed 30 per request.

Responses

200

Success

Response Schema: application/json
entries
required
Array of objects (RequestDetail)
meta
required
object (CreditsChangeSummaryMeta)
msg
required
string

Message related to response

401

User is not authorized.

403

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

post/requests
/v2/requests

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "due_date": "2020-06-08T22:00:00.000Z",
  • "email_body": "Hi! Message to recipient",
  • "notify": true,
  • "reminder": 0,
  • "source_team": "string",
  • "standard_ids":
    [
    ],
  • "targets":
    [
    ]
}

Response samples

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

Send new internal request(s)

Authorizations:
Request Body schema: application/json
due_date
string <date-time>

Due date for filling the form. Omit to send questionnaire without a due date

email_body
string
Default: ""

Text of the email sent to the vendor

notify
boolean
Default: true

Set to true if recepients specified in targets should be notified via email. This is usually useful for sending requests to individual users, in case of sending to a company by domain, company.requests_email is used.

reminder
integer

How many days before due date should the user be notified

source_team
required
string

Source team UUID of the actual sender. The request sender must belong to this team, to be able to send an internal request.

standard_ids
required
Array of strings

List of IDs of standards that should be sent to the vendor for filling

target_teams
required
Array of strings

List of recepient teams UUID of the standards. All recepient teams must belong to the same company of the sender.

Limitation: In order to keep the sevice accessible for everyone, the total recipients in all target teams should not exceed 30.
Note: If you need to send an email for more than 30 recipients, please use the POSTrequest/ API with 30 emails per request.
Note: Currently, for the feature to perform as intended, all the users must visit ATLAS at least once before using this API endpoint.

Responses

200

Success

Response Schema: application/json
entries
required
Array of objects (RequestDetail)
meta
required
object (CreditsChangeSummaryMeta)
msg
required
string

Message related to response

401

User is not authorized.

403

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

post/requests/internal
/v2/requests/internal

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "due_date": "2020-06-08T22:00:00.000Z",
  • "email_body": "Hi! Message to recipient",
  • "notify": true,
  • "reminder": 0,
  • "source_team": "string",
  • "standard_ids":
    [
    ],
  • "target_teams":
    [
    ]
}

Response samples

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

Return single request detail

Authorizations:
path Parameters
request_id
required
string

Responses

200

Success

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

Message related to response

401

User is not authorized.

403

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

410

Request is already deleted.

get/requests/{request_id}
/v2/requests/{request_id}

Response samples

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

users

Information about currently signed-in user.

Return information about the currently logged in user

When the response to GET /users/current/info states that the user is not fully initialized (as indicated by field user.internal_status having value of MERGING), the subsequent results from other endpoints may be incomplete (namely GET /forms/{form_id}, ...) until user initialization is finished.

It is advised to periodically re-check user status, until user.internal_status is NORMAL, before querying any other data. The expected time before user initialization finishes depends on number of form filling requests received by the user - from seconds to minutes (in extreme cases).

Authorizations:
query Parameters
include_credit_history
boolean
Default: false

Responses

200

Success

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

Message related to response

401

User is not authorized.

403

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

get/users/current/info
/v2/users/current/info

Response samples

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

Return information about the currently logged in user's credits

Authorizations:

Responses

200

Success

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

Message related to response

401

User is not authorized.

403

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

get/users/current/info/credits
/v2/users/current/info/credits

Response samples

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