papi (2)

Download OpenAPI specification:Download

Panorays public api

Overview

The following document will introduce and document the API endpoints exposed to external clients. All endpoints will work using REST API and JSON format. The documentation will include 2 types of requests and available endpoints - by demand API and event hooks.

API Access

Panorays API endpoint is under the domain of https://api.panoraysapp.com All requests should be sent there with the appropriate route and parameters. The API rate limit is 150 requests per minute. Exceeding this limit will result in a 429 HTTP error and a 1-hour block.

Requirements

All requests to the different endpoints should include an Authorization Token. The Authorization Token is generated by Panorays and sent during onboarding. It should be kept a secret and not shared. The Authorization Token should be sent as part of the Authorization header in the format of Bearer <token>.

Routes Pagination

Panorays API paginated routes are using cursor pagination, this means the response containing a token that will get you the next page. This way you can send several requests in a loop phrase to get all relevant data.

let res = await axios.get('https://api.panoraysapp.com/v2/suppliers?limit=100');
// Process first page data 
// If there is a next page you will get has_next = true, next = <next_token>
while (res.has_next) {
   res = await axios.get(`https://api.panoraysapp.com/v2/suppliers?limit=100&next_token=${res.next}`);
  // Process next page data
} 

Offset pagination is not supported in Panorays API so sending skip as parameter won't work.

We encourage you to use a low limit param such as limit=100 to reduce the change of getting an error.

Supplier

Use these routes to access and update your suppliers.

Post supplier

Add a new supplier to the portfolio. If a questionnaire is also sent via this request, and you have more than 1 questionnaire template, the latest template will be sent. For information regarding which template is the latest one, please contact Panorays Support. It is recommended to use “Send questionnaire” POST request to send a questionnaire instead.

Securitybearer
Request
Request Body schema: application/json
required
Array of objects (PocDto)
business_impact
number [ 1 .. 5 ]
Array of objects (BusinessInformationInput)
evaluation_type
string
Enum: "Continuous 360 Evaluation" "Continuous Posture Evaluation" "Bi-Annual 360 Evaluation" "Bi-Annual Posture Evaluation" "Smart Questionnaires" "Inventory"
portfolios
Array of strings
questionnaire_contacts
Array of strings
questionnaire_type
string
Enum: "external" "internal" "both"
name
required
string
asset
required
string
questionnaire_template_name
string
relationships
Array of strings
tags
Array of strings
Responses
200

Supplier created successfully.

400

Invalid input

401

Invalid Request. Portfolios are not available for this user

403

Forbidden.

429

Too Many Requests

post/v2/suppliers
Request samples
application/json
{
  • "pocs": [
    ],
  • "business_impact": 1,
  • "business_information": [
    ],
  • "evaluation_type": "Continuous 360 Evaluation",
  • "portfolios": [
    ],
  • "questionnaire_contacts": [
    ],
  • "questionnaire_type": "external",
  • "name": "string",
  • "asset": "string",
  • "questionnaire_template_name": "string",
  • "relationships": [
    ],
  • "tags": [
    ]
}
Response samples
application/json
{
  • "id": "string"
}

Get suppliers

Get all of your suppliers

Securitybearer
Request
query Parameters
fields
string

Suppliers will only contain specified fields (all if none)

Enum: "name" "assets" "relationships" "business_impact" "business_information" "tags" "contacts" "insert_ts" "created_by" "approval" "risk" "combined_score" "posture_score" "questionnaire_overall_score" "questionnaires" "evaluation_type" "portfolios" "id" "latest_assessment_date" "segment_id"
names
Array of strings

Search by supplier names

ids
Array of strings

Search by supplier ids

assets
Array of strings

Search by supplier assets

tags
Array of strings

Search by supplier tags

sortBy
Array of strings

Name of the field to sort by

Items Enum: "name" "business_impact" "insert_ts"
sortDirection
string

The direction of the field sort specified by sort_by

Enum: "ASC" "asc" "1" "DESC" "desc" "-1"
limit
number [ 1 .. 100 ]
Default: 100

Number of records to return in the response

next_token
string

Token received from a previous request to obtain the next chunk of data

segment_ids
Array of strings

Search by supplier segment ids

Responses
200

All found suppliers are returned.

204

No suppliers found.

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

get/v2/suppliers
Response samples
application/json
[
  • {
    }
]

Get supplier

Get a single supplier by id

Securitybearer
Request
path Parameters
id
required
string
query Parameters
fields
Array of strings

Suppliers will only contain specified fields (all if none)

Items Enum: "name" "assets" "relationships" "business_impact" "business_information" "tags" "contacts" "insert_ts" "created_by" "approval" "risk" "combined_score" "posture_score" "questionnaire_overall_score" "questionnaires" "evaluation_type" "portfolios" "id" "latest_assessment_date" "segment_id"
Responses
200

Supplier found.

401

Unauthorized.

403

Forbidden.

404

Supplier was not found

429

Too Many Requests

get/v2/suppliers/{id}
Response samples
application/json
{
  • "business_information": [
    ],
  • "contacts": [
    ],
  • "questionnaires": [
    ],
  • "evaluation_type": "Continuous 360 Evaluation",
  • "latest_assessment_date": "string",
  • "id": "string",
  • "name": "string",
  • "relationships": [
    ],
  • "business_impact": 0,
  • "insert_ts": "string",
  • "created_by": "string",
  • "approval": {
    },
  • "risk": 0,
  • "combined_score": 0,
  • "posture_score": 0,
  • "tags": [
    ],
  • "questionnaire_overall_score": 0,
  • "portfolios": [
    ],
  • "segmentId": "string"
}

Update supplier

Update a single supplier by id.

Securitybearer
Request
path Parameters
supplierId
required
string

Id of the supplier

Request Body schema: application/json
required
name
string

The supplier's name

assets
Array of strings unique

Supplier assets as entered by the user

Array of objects (PocDto)
object
relationships
Array of strings unique
tags
Array of strings unique
business_impact
number [ 1 .. 5 ]
Array of objects (BusinessInformationInput)
evaluation_type
string
Enum: "Continuous 360 Evaluation" "Continuous Posture Evaluation" "Bi-Annual 360 Evaluation" "Bi-Annual Posture Evaluation" "Smart Questionnaires"
portfolios
Array of strings unique
Responses
200
204

Supplier updated.

400

Invalid input

401

Invalid Request. Portfolios are not available for this user

403

Forbidden.

429

Too Many Requests

put/v2/suppliers/{supplierId}
Request samples
application/json
{
  • "name": "Panorays",
  • "assets": [
    ],
  • "pocs": [
    ],
  • "approval": {
    },
  • "relationships": [
    ],
  • "tags": [
    ],
  • "business_impact": 1,
  • "business_information": [
    ],
  • "evaluation_type": "Continuous 360 Evaluation",
  • "portfolios": [
    ]
}
Response samples
application/json
{ }

Delete supplier

Delete a single supplier by id.

Securitybearer
Request
path Parameters
supplierId
required
string

Id of the supplier

Request Body schema: application/json
required
reason
required
string

Reason of supplier's removal

Enum: "Supplier No Longer Required" "Non-Compliance with Policy" "Duplicate Supplier Entry" "License Costs"
Responses
204

Supplier deleted Or Supplier not found.

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

delete/v2/suppliers/{supplierId}
Request samples
application/json
{
  • "reason": "Supplier No Longer Required"
}

Get suppliers tests

This endpoint will return data and information about the requested supplier’s tests performed as part of the evaluation.

Request
path Parameters
supplierId
required
string

Id of the supplier

query Parameters
limit
number [ 1 .. 200 ]
Default: 200

Number of records to return in the response

sortBy
Array of strings

Name of the field to sort by

Items Enum: "name" "severity" "category" "category_text" "sub_category" "sub_category_text" "criterion_text" "open_findings_count" "closed_findings_count"
sortDirection
string

The direction of the field sort specified by sort_by

Enum: "ASC" "asc" "1" "DESC" "desc" "-1"
next_token
string

Token received from a previous request to obtain the next chunk of data

name
Array of strings

Tests will only contain specified name (all if none)

severity
Array of strings

Tests will only contain specified severity (all if none)

Items Enum: "info" "low" "medium" "high" "critical"
fields
string
Enum: "name" "severity" "category" "category_text" "sub_category" "sub_category_text" "criterion_text" "open_findings_count" "closed_findings_count"
Responses
200

Tests.

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

get/v2/suppliers/{supplierId}/tests
Response samples
application/json
{
  • "severity": "INFO",
  • "category": "string",
  • "category_text": "string",
  • "sub_category": "string",
  • "sub_category_text": "string",
  • "open_findings_count": 0,
  • "closed_findings_count": 0,
  • "id": "string",
  • "name": "string",
  • "criterion_text": "string"
}

Post supplier assets

This endpoint will create assets of a supplier.

Request
path Parameters
supplierId
required
string

Id of the supplier

Request Body schema: application/json
required
assets
required
Array of strings

assets by name, e.g., "127.0.0.1", "panorays.com"

Responses
200

Assets.

204

Supplier not found.

401

Unauthorized.

403

Forbidden.

404

Connection was not found

429

Too Many Requests

post/v2/suppliers/{supplierId}/assets
Request samples
application/json
{
  • "assets": [
    ]
}
Response samples
application/json
{
  • "type": "DOMAIN",
  • "is_up": true,
  • "location": "string",
  • "domains": [
    ],
  • "ips": [
    ],
  • "asset_lifecycle": "string",
  • "dispute_status": "string",
  • "discovery_origin": "string",
  • "name": "string",
  • "insert_ts": "string"
}

Get supplier's assets

Get assets of a specific supplier.

Securitybearer
Request
path Parameters
supplierId
required
string

Id of the supplier

query Parameters
limit
number [ 1 .. 200 ]
Default: 200

Number of records to return in the response

sortBy
string

Name of the field to sort by

Enum: "name" "type" "insert_ts"
sortDirection
string

The direction of the field sort specified by sort_by

Enum: "ASC" "asc" "1" "DESC" "desc" "-1"
next_token
string

Token received from a previous request to obtain the next chunk of data

fields
Array of strings

Asset will only contain specified fields (all if none)

Items Enum: "name" "insert_ts" "type" "is_up" "location" "domains" "ips" "asset_lifecycle" "dispute_status" "id" "discovery_origin" "segments"
name
Array of strings

Name of the asset

type
Array of strings

Asset type

Items Enum: "DOMAIN" "SUBDOMAIN" "IP" "IP_RANGE" "domain" "subdomain" "ip" "ip_range"
is_up
boolean

Is the asset active or not

segments
Array of strings

Ids of the segments

Responses
200

All found assets.

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

get/v2/suppliers/{supplierId}/assets
Response samples
application/json
[
  • {
    }
]

Posture

Get supplier's posture

This endpoint will return data and information about the requested supplier’s posture in the portfolio.

Securitybearer
Request
path Parameters
supplierId
required
string

Id of the supplier

query Parameters
fields
Array of strings

Posture will only contain specified fields (all if none)

Items Enum: "grade" "categories" "id" "name"
segmentId
string

segmentId of the posture

Responses
200

Posture.

401

Unauthorized.

403

Forbidden.

404

No posture found.

429

Too Many Requests

get/v2/suppliers/{supplierId}/posture
Response samples
application/json
{
  • "categories": [
    ],
  • "id": "string",
  • "grade": 0,
  • "name": "string"
}

Get company posture

This endpoint will return data and information about the posture in the portfolio.

Securitybearer
Request
query Parameters
fields
Array of strings

Posture will only contain specified fields (all if none)

Items Enum: "grade" "categories" "id" "name"
segmentId
string

segmentId of the posture

Responses
200

Posture.

204

Posture not found

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

get/v2/posture
Response samples
application/json
{
  • "categories": [
    ],
  • "id": "string",
  • "grade": 0,
  • "name": "string"
}

Portfolio

Get company portfolios

This endpoint will return the portfolios and the supplier’s id’s under it.

Securitybearer
Request
query Parameters
limit
number [ 1 .. 200 ]
Default: 200

Number of records to return in the response

sortBy
Array of strings

Name of the field to sort by

sortDirection
string

The direction of the field sort specified by sort_by

Enum: "ASC" "asc" "1" "DESC" "desc" "-1"
next_token
string

Token received from a previous request to obtain the next chunk of data

fields
Array of strings
Responses
200

Found portfolios are being returned.

204

No portfolios found.

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

get/v2/portfolios
Response samples
application/json
[
  • {
    }
]

Asset

Get company assets

The endpoint is used to get all company assets.

Securitybearer
Request
query Parameters
limit
number [ 1 .. 200 ]
Default: 200

Number of records to return in the response

sortBy
string

Name of the field to sort by

Enum: "name" "type" "insert_ts"
sortDirection
string

The direction of the field sort specified by sort_by

Enum: "ASC" "asc" "1" "DESC" "desc" "-1"
next_token
string

Token received from a previous request to obtain the next chunk of data

fields
Array of strings

Asset will only contain specified fields (all if none)

Items Enum: "name" "insert_ts" "type" "is_up" "location" "domains" "ips" "asset_lifecycle" "dispute_status" "id" "discovery_origin" "segments"
name
Array of strings

Name of the asset

type
Array of strings

Asset type

Items Enum: "DOMAIN" "SUBDOMAIN" "IP" "IP_RANGE" "domain" "subdomain" "ip" "ip_range"
is_up
boolean

Is the asset active or not

segments
Array of strings

Ids of the segments

Responses
200

All found assets

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

get/v2/assets
Response samples
application/json
[
  • {
    }
]

Create company assets

The endpoint is used to create company assets.

Request
Request Body schema: application/json
required
assets
required
Array of strings

assets by name, e.g., "127.0.0.1", "panorays.com"

Responses
200

All created assets

201
401

Unauthorized.

403

Forbidden.

429

Too Many Requests

post/v2/assets
Request samples
application/json
{
  • "assets": [
    ]
}
Response samples
application/json
[
  • {
    }
]

Finding

Get company finding

This endpoint will return data and information about a specific finding.

Securitybearer
Request
path Parameters
id
required
string

The finding id

query Parameters
fields
string

Fields to include in response

Enum: "id" "status" "severity" "asset_name" "category" "sub_category" "test_text" "test_name" "finding_text" "description" "insert_ts" "update_ts" "metadata" "cves"
Responses
200

Finding found

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

get/v2/findings/{id}
Response samples
application/json
{
  • "status": "OPEN",
  • "severity": "LOW",
  • "id": "string",
  • "metadata": { },
  • "cves": [
    ],
  • "asset_name": "string",
  • "category": "string",
  • "sub_category": "string",
  • "test_text": "string",
  • "finding_text": "string",
  • "description": "string",
  • "insert_ts": "string",
  • "update_ts": "string",
  • "test_name": "string",
  • "segments": [
    ]
}

Get company findings

This endpoint will return data and information about findings in the portfolio.

Securitybearer
Request
query Parameters
limit
number [ 1 .. 200 ]
Default: 200

Number of records to return in the response

sortBy
string

Name of the field to sort by

Enum: "status" "asset_name" "test_name" "insert_ts" "update_ts"
sortDirection
string

The direction of the field sort specified by sort_by

Enum: "ASC" "asc" "1" "DESC" "desc" "-1"
next_token
string

Token received from a previous request to obtain the next chunk of data

fields
string

Fields to include in response

Enum: "id" "status" "severity" "asset_name" "category" "sub_category" "test_text" "test_name" "finding_text" "description" "insert_ts" "update_ts" "metadata" "cves"
status
Array of strings

Status of the finding(s)

severity
Array of strings

Severity of the finding(s)

asset_name
Array of strings

Asset of finding(s)

id
Array of strings

Id of the finding(s)

sub_category
Array of strings

Sub category of finding(s)

segments
Array of strings

Ids of segments of finding(s)

test_name
Array of strings
Responses
200

All found findings are returned.

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

get/v2/findings
Response samples
application/json
[
  • {
    }
]

Get supplier's report

This endpoint will return csv with information about findings in the portfolio.

Securitybearer
Request
path Parameters
supplierId
required
string

Id of the supplier

query Parameters
lang
string

Report language (en|ja)

Enum: "en" "ja"
Responses
200

Report has been found

401

Unauthorized.

403

Forbidden.

404

Report was not found.

429

Too Many Requests

get/v2/suppliers/{supplierId}/report/findings

Get supplier finding by id

This endpoint will return data and information about a supplier’s specific finding.

Securitybearer
Request
path Parameters
supplierId
required
string

Id of the supplier

findingId
required
string

Finding id to fetch

query Parameters
fields
string

Fields to include in response

Enum: "id" "status" "severity" "asset_name" "category" "sub_category" "test_text" "test_name" "finding_text" "description" "insert_ts" "update_ts" "metadata" "cves"
Responses
200

Found supplier finding by id.

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

get/v2/suppliers/{supplierId}/findings/{findingId}

Get supplier's findings

This endpoint will return data and information about findings in the portfolio.

Securitybearer
Request
path Parameters
supplierId
required
string

Id of the supplier

query Parameters
limit
number [ 1 .. 200 ]
Default: 200

Number of records to return in the response

sortBy
string

Name of the field to sort by

Enum: "status" "asset_name" "test_name" "insert_ts" "update_ts"
sortDirection
string

The direction of the field sort specified by sort_by

Enum: "ASC" "asc" "1" "DESC" "desc" "-1"
next_token
string

Token received from a previous request to obtain the next chunk of data

fields
string

Fields to include in response

Enum: "id" "status" "severity" "asset_name" "category" "sub_category" "test_text" "test_name" "finding_text" "description" "insert_ts" "update_ts" "metadata" "cves"
status
Array of strings

Status of the finding(s)

severity
Array of strings

Severity of the finding(s)

asset_name
Array of strings

Asset of finding(s)

id
Array of strings

Id of the finding(s)

sub_category
Array of strings

Sub category of finding(s)

segments
Array of strings

Ids of segments of finding(s)

test_name
Array of strings
Responses
200

All found findings are returned.

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

get/v2/suppliers/{supplierId}/findings
Response samples
application/json
[
  • {
    }
]

Get supplier's assessment report

This endpoint will return pdf with assessment report.

Securitybearer
Request
path Parameters
supplierId
required
string

Id of the supplier

query Parameters
lang
string

Report language (en|ja)

Enum: "en" "ja"
postureOnly
boolean

Report only displaying cyber posture data (true | false, default = false)

Responses
200

Report has been found

401

Unauthorized.

403

Forbidden.

404

Report was not found.

429

Too Many Requests

get/v2/suppliers/{supplierId}/report/summary

RemediationTasks

Get remediation task by id

THis endpoint is used to get a specific remediation task of a supplier by id.

Securitybearer
Request
path Parameters
supplierId
required
string
taskId
required
string
query Parameters
fields
string
Enum: "company_id" "supplier_id" "type" "issue_id" "created_by" "start_date" "end_date" "due_date" "status" "description" "priority" "pocs" "title" "created_at" "updated_at" "inquiry_id" "question_id" "criterion_id" "finding_id" "status_reason"
enrich
string
Enum: "created_by" "pocs" "criterion_id" "finding_id" "company_id" "question_id" "inquiry_id"
Responses
200

Supplier remediation task

400

Invalid input

401

Unauthorized.

403

Forbidden.

404

Task was not found

429

Too Many Requests

get/v2/suppliers/{supplierId}/remediation/{taskId}
Response samples
application/json
{
  • "status_reason": {
    },
  • "account": {
    },
  • "company": {
    },
  • "question": {
    },
  • "findings": [
    ],
  • "id": "string",
  • "company_id": "string",
  • "supplier_id": "string",
  • "type": "string",
  • "issue_id": "string",
  • "created_by": "string",
  • "start_date": "string",
  • "end_date": "string",
  • "due_date": "string",
  • "status": "string",
  • "description": "string",
  • "priority": "string",
  • "pocs": [
    ],
  • "title": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "inquiry_id": "string",
  • "question_id": "string"
}

Get supplier's remediation tasks

The endpoint will retrieve all the remediation tasks of a specific supplier

Request
path Parameters
supplierId
required
string

Id of the supplier

query Parameters
limit
number [ 1 .. 50 ]
Default: 50

Number of records to return in the response

sortBy
Array of strings

Name of the field to sort by

sortDirection
string

The direction of the field sort specified by sort_by

Enum: "ASC" "asc" "1" "DESC" "desc" "-1"
next_token
string

Token received from a previous request to obtain the next chunk of data

segmentId
string

SegmentId to filter tasks

fields
Array of strings

Suppliers will only contain specified fields (all if none)

Items Enum: "company_id" "supplier_id" "type" "issue_id" "created_by" "start_date" "end_date" "due_date" "status" "description" "priority" "pocs" "title" "created_at" "updated_at" "inquiry_id" "question_id" "criterion_id" "finding_id" "status_reason"
type
string
Enum: "CRITERION_REMEDIATION" "QUESTION_REMEDIATION"
gte
string
lte
string
gt
string
lt
string
Responses
200

All found remediation tasks.

204

No remediation tasks found.

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

get/v2/suppliers/{supplierId}/remediation
Response samples
application/json
[
  • {
    }
]

Get suppliers remediation tasks

The endpoint retrieves all the remediation task of all suppliers

Request
query Parameters
limit
number [ 1 .. 50 ]
Default: 50

Number of records to return in the response

sortBy
Array of strings

Name of the field to sort by

sortDirection
string

The direction of the field sort specified by sort_by

Enum: "ASC" "asc" "1" "DESC" "desc" "-1"
next_token
string

Token received from a previous request to obtain the next chunk of data

fields
Array of strings

Suppliers will only contain specified fields (all if none)

Items Enum: "company_id" "supplier_id" "type" "issue_id" "created_by" "start_date" "end_date" "due_date" "status" "description" "priority" "pocs" "title" "created_at" "updated_at" "inquiry_id" "question_id" "criterion_id" "finding_id" "status_reason"
type
string
Enum: "CRITERION_REMEDIATION" "QUESTION_REMEDIATION"
Responses
200

All found remediation tasks.

204

No remediation tasks found.

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

get/v2/suppliers/remediation
Response samples
application/json
[
  • {
    }
]

BusinessInformation

Get company business information template

The endpoint is used to get business information questions and structure

Securitybearer
Responses
200

Business information template.

204

Business information template was not found

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

get/v2/business_information
Response samples
application/json
{
  • "questions": [
    ]
}

File

Get file

The endpoint is used to get related files to the company or its suppliers

Securitybearer
Request
path Parameters
fileId
required
string
Responses
200

Found file is returned.

401

Unauthorized.

403

Forbidden.

404

File was not found

429

Too Many Requests

get/v2/files/{fileId}
Response samples
application/json
"string"

Get supplier's files

The endpoint will retrieve all the files of a specific supplier

Request
path Parameters
supplierId
required
string

Id of the supplier

query Parameters
limit
number [ 1 .. 200 ]
Default: 200

Number of records to return in the response

sortBy
string

Name of the field to sort by

sortDirection
string

The direction of the field sort specified by sort_by

Enum: "ASC" "asc" "1" "DESC" "desc" "-1"
next_token
string

Token received from a previous request to obtain the next chunk of data

origin
string

A list of possible file origins

Enum: "businessInformation" "connection" "inquiry"
fields
Array of strings

Suppliers will only contain specified fields (all if none)

Items Enum: "added_by" "filename" "insert_ts" "origin" "type"
Responses
200

All found files.

204

No files found.

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

get/v2/suppliers/{supplierId}/files
Response samples
application/json
[
  • {
    }
]

Questionnaire

Get supplier questionnaires info

This endpoint will return info about the latest questionnaires for each template sent to a specific supplier.

Securitybearer
Request
path Parameters
supplierId
required
string

Id of the supplier

query Parameters
limit
number [ 1 .. 20 ]
Default: 20

Number of records to return in the response

sortBy
string

Name of the field to sort by

Enum: "questionnaire_id" "template_name" "completion_rate" "status_update_date" "created_by" "status" "score" "ttl" "weight" "questionnaire_submit_date" "questionnaire_sent_date"
sortDirection
string

The direction of the field sort specified by sort_by

Enum: "ASC" "asc" "1" "DESC" "desc" "-1"
next_token
string

Token received from a previous request to obtain the next chunk of data

questionnaire_type
string
Enum: "external" "internal" "both"
fields
required
string
Default: ["questionnaire_id","template_name","completion_rate","status_update_date","created_by","status","score","ttl","weight","questionnaire_submit_date","questionnaire_sent_date"]
Enum: "questionnaire_id" "template_name" "completion_rate" "status_update_date" "created_by" "status" "score" "ttl" "weight" "questionnaire_submit_date" "questionnaire_sent_date"
template_names
Array of strings
Responses
200

Supplier questionnaires info

400

Invalid input

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

get/v2/suppliers/{supplierId}/questionnaires
Response samples
application/json
[
  • {
    }
]

Get questionnaire

This endpoint will return info about the latest questionnaires for each template sent to a specific supplier including the answers.

Securitybearer
Request
path Parameters
supplierId
required
string
questionnaireId
required
string
query Parameters
questionnaire_type
string
Enum: "external" "internal" "both"
fields
string
Enum: "score" "template_name" "template_id" "status" "ttl" "questions" "id" "display_name" "internal_notes" "comments"
language
string
Enum: "en" "ja" "zh" "he"
out_of_policy_only
boolean
Responses
200

Supplier questionnaire answers info

400

Invalid input

401

Unauthorized.

403

Forbidden.

404

Questionnaires was not found

429

Too Many Requests

get/v2/suppliers/{supplierId}/questionnaires/{questionnaireId}
Response samples
application/json
{
  • "status": "SENT",
  • "score": 0,
  • "ttl": "string",
  • "questions": [
    ],
  • "questionnaire_type": "external",
  • "id": "string",
  • "template_name": "string"
}

Put Questionnaire

This endpoint will extend due date of a questionnaire.

Securitybearer
Request
path Parameters
supplierId
required
string

Id of the supplier

questionnaireId
required
string

Id of the questionnaire

Request Body schema: application/json
required
note
string

note from the evaluator to the supplier, that will be sent with the questionnaire

ttl
object
Default: "2025-01-04T09:26:47.336Z"

ttl is the due date specified by the the evaluator. defaults to 30 days from now

questionnaire_type
string
Default: "external"

Type of the questionnaire

Enum: "internal" "external"
Responses
200

Questionnaire.

401

Unauthorized.

403

Forbidden.

404

Connection was not found

429

Too Many Requests

put/v2/suppliers/{supplierId}/questionnaires/{questionnaireId}
Request samples
application/json
{
  • "note": "string",
  • "ttl": "2025-01-04T09:26:47.336Z",
  • "questionnaire_type": "internal"
}
Response samples
application/json
{
  • "questionnaire_id": { },
  • "status": "string",
  • "ttl": "2019-08-24T14:15:22Z",
  • "template_name": "string",
  • "weight": 0,
  • "created_by": "string",
  • "status_update_date": "2019-08-24T14:15:22Z",
  • "completion_rate": 0,
  • "questionnaire_type": "string"
}

Get supplier's questionnaire report

This endpoint will return pdf with questionnaire report.

Securitybearer
Request
path Parameters
supplierId
required
string
templateName
required
string
query Parameters
lang
string

Report language

Enum: "en" "ja"
isConfidential
boolean

Optional - set to true if you want to get confidential pdf (including questions, answers, scores, comments & notes, and tags & relationships) (false | true) -> false is the default (including only questions, answers and conversation with suppliers)

questionnaireId
string
Responses
200

Report has been found

401

Unauthorized.

403

Forbidden.

404

Report was not found.

429

Too Many Requests

get/v2/suppliers/{supplierId}/report/questionnaire/{templateName}

Post questionnaire

This endpoint will send questionnaire to supplier.

Securitybearer
Request
path Parameters
supplierId
required
string

Id of the supplier

templateId
string

name of the template to use for the questionnaire. Needs to be provided for sending a questionnaire. I's called "templateId" to not confuse the users with "display_name"

Request Body schema: application/json
required
pocs
required
Array of strings <email>
template_id
string

name of the template to use for the questionnaire. If not provided the latest template will be sent. For information regarding which template is the latest one, please contact Panorays Support.

note
string

note from the evaluator to the supplier, that will be sent with the questionnaire

ttl
string <date-time>

ttl is the due date specified by the the evaluator

questionnaire_type
string
Default: "external"

Questionnaire type - internal/external

Enum: "external" "internal" "both"
Responses
200

Questionnaire.

201
401

Unauthorized.

403

Forbidden.

404

Connection was not found

429

Too Many Requests

post/v2/suppliers/{supplierId}/questionnaires/{templateId}
Request samples
application/json
{
  • "pocs": [
    ],
  • "template_id": "string",
  • "note": "string",
  • "ttl": "2019-08-24T14:15:22Z",
  • "questionnaire_type": "external"
}
Response samples
application/json
{
  • "ttl": "string",
  • "id": { },
  • "insert_ts": "2019-08-24T14:15:22Z",
  • "pocs": [
    ],
  • "status": "string",
  • "template_id": "string",
  • "template_name": "string"
}

Tests

Get company tests

This endpoint returns the tests of the company.

Request
query Parameters
limit
number [ 1 .. 200 ]
Default: 200

Number of records to return in the response

sortBy
Array of strings

Name of the field to sort by

Items Enum: "name" "severity" "category" "category_text" "sub_category" "sub_category_text" "criterion_text" "open_findings_count" "closed_findings_count"
sortDirection
string

The direction of the field sort specified by sort_by

Enum: "ASC" "asc" "1" "DESC" "desc" "-1"
next_token
string

Token received from a previous request to obtain the next chunk of data

name
Array of strings

Tests will only contain specified name (all if none)

severity
Array of strings

Tests will only contain specified severity (all if none)

Items Enum: "info" "low" "medium" "high" "critical"
fields
string
Enum: "name" "severity" "category" "category_text" "sub_category" "sub_category_text" "criterion_text" "open_findings_count" "closed_findings_count"
Responses
200

Tests.

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

get/v2/tests
Response samples
application/json
{
  • "severity": "INFO",
  • "category": "string",
  • "category_text": "string",
  • "sub_category": "string",
  • "sub_category_text": "string",
  • "open_findings_count": 0,
  • "closed_findings_count": 0,
  • "id": "string",
  • "name": "string",
  • "criterion_text": "string"
}

RiskInsights

Get company risk insights

This endpoint will return data and information about risk insights of the company.

Securitybearer
Request
query Parameters
limit
number [ 1 .. 200 ]
Default: 200

Number of records to return in the response

sortBy
Array of strings

Name of the field to sort by

sortDirection
string

The direction of the field sort specified by sort_by

Enum: "ASC" "asc" "1" "DESC" "desc" "-1"
next_token
string

Token received from a previous request to obtain the next chunk of data

fields
string

Fields to include in response

Enum: "impact_on_my_company" "impact_on_direct_suppliers" "date_added" "last_update" "insight_status" "event_id" "event_type" "event_date" "event_title" "event_links"
Responses
200

All found risk insights are returned.

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

get/v2/risk_insights/company
Response samples
application/json
[
  • {
    }
]

BusinessSnapshot

Get company business snapshot

Securitybearer
Responses
200

Business snapshot.

204

Business snapshot was not found

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

get/v2/business_snapshot
Response samples
application/json
{
  • "location": {
    },
  • "security_statements": [
    ],
  • "company_name": "string",
  • "industry": "string",
  • "company_size": "string",
  • "company_type": "string",
  • "founded_year": 0,
  • "capital": "string",
  • "linkedin_url": "string",
  • "facebook_url": "string",
  • "twitter_url": "string"
}

Get supplier business snapshot

This endpoint will return business snapshot information.

Securitybearer
Request
path Parameters
supplierId
required
string

Id of the supplier

Responses
200

Business snapshot.

204

No business snapshot found.

401

Unauthorized.

403

Forbidden.

404

Connection was not found

429

Too Many Requests

get/v2/suppliers/{supplierId}/business_snapshot
Response samples
application/json
{
  • "location": {
    },
  • "security_statements": [
    ],
  • "company_name": "string",
  • "industry": "string",
  • "company_size": "string",
  • "company_type": "string",
  • "founded_year": 0,
  • "capital": "string",
  • "linkedin_url": "string",
  • "facebook_url": "string",
  • "twitter_url": "string"
}

Relationship

Get relationships

This endpoint will return all defined relationships.

Securitybearer
Request
query Parameters
limit
number [ 1 .. 200 ]
Default: 200

Number of records to return in the response

sortBy
Array of strings

Name of the field to sort by

sortDirection
string

The direction of the field sort specified by sort_by

Enum: "ASC" "asc" "1" "DESC" "desc" "-1"
next_token
string

Token received from a previous request to obtain the next chunk of data

Responses
200
401

Unauthorized.

403

Forbidden.

429

Too Many Requests

get/v2/relationships

Licenses

Get quantity of purchased licenses and the current usage

This endpoint will return data and information about licenses of the company.

Securitybearer
Responses
200

Array of product names with the corresponding quantity and usage.

401

Unauthorized.

403

Forbidden.

404

Not Found.

429

Too Many Requests

get/v2/licenses
Response samples
application/json
{
  • "licenses": [
    ]
}

Templates

Get templates

Get all company templates

Securitybearer
Request
query Parameters
limit
number [ 1 .. 20 ]
Default: 20

Number of records to return in the response

sortBy
string

Name of the field to sort by

Enum: "status" "weight" "created_at" "updated_at"
sortDirection
string

The direction of the field sort specified by sort_by

Enum: "ASC" "asc" "1" "DESC" "desc" "-1"
next_token
string

Token received from a previous request to obtain the next chunk of data

fields
string

Fields to include in response

Enum: "template_display_name" "template_name" "description" "status" "weight" "created_at" "updated_at" "created_by" "updated_by"
Responses
200

All templates are returned.

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

get/v2/templates
Response samples
application/json
[
  • {
    }
]

Intro

The hook api provides a simple way of registering to events that happen with your suppliers

Getting Started

The following steps will walk you trough the process of registering and reacting to webhooks

  1. Registering a service account

    If you dont already have a service account you will need to contact a Panorays customer support at support@panorays.com.
  2. Register your app

    Before you can start receiving events, you will need to register your application with Panorays using the Handshake api call
  3. Subscribe to relevant events

    You will only receive event calls for event you subscribe to using the Subscribe api call
  • Note that you can always unsubscribe from receiving events using the Unsubscribe api call
  1. Start reciving events

    You're done! from now on you will receive notifications for every event you subscribed to. To know how to better secure your app and ensure that you handle events ONLY from Panorays, read about Verifying requests

Verify Requests

Panorays signs every request with a secret that's unique to your service account, using this secret you can verify that the incoming request arrived from Panorays servers.

How do I use the secret

On every request Panorays sends we provide X-Panorays-Signature header, this header contains a signature created from combining the event body, the request time and your secret using an HMAC SHA256 keyed hash. By recreating this code on your side and comparing the values you can verify that the event came from Panorays.

Step by step guide for verifying requests

  • Take your URL secret (The one you received when calling the handshake route)
    secret = 'kqouK3lV+xOWzZ3SOvBv5lhbVhjolJJQs51hM8jG0xA60WqAz0wz/fMDqf/dd8rP' 
    
  • Extract the request time from the X-Pano-Request-Time header
    timestamp = request.headers['X-Pano-Request-Time'] 
    
  • Concatenate the request time with the request body using a colon : as a delimiter
  • From the resulting string create an hmac using your secret and a sha256 algorithm and convert the result to a base64 string
    signature = createHmac('sha256', secret) 
    .update(`${timestamp}:${JSON.stringify(request.body)}`) 
    .digest('base64'); 
    
  • Compare your hmac string to the signature inside X-Panorays-Signature header.
    if (signature !== request.headers['X-Panorays-Signature']) { 
    // stop everything and hide. 
    } 
    
    • If the values are equal, you now verified that the request came from Panorays.

Handshake

Handshake

Before being able to register and receive events, a server should be registered and verified. A “Verification Handshake” will happen which will verify SSL certificate and send a POST with a body of { challenge: <hash> } to the server given. The response to the POST message should contain the given challenge hash and status 200. The verification handshake process should only happen once and will be done during the onboarding of the API by Panorays.

Securitybearer
Request
Request Body schema: application/json
required
url
required
string
Responses
200

url registered, secret generated

201
401

Unauthorized.

403

Forbidden.

429

Too Many Requests

post/v2/hooks/handshake
Request samples
application/json
{
  • "url": "string"
}
Response samples
application/json
{
  • "secret": "string"
}

Subscription

Subscribe

To enable notifications for a certain event you will need to subscribe to it using this route.

Securitybearer
Request
Request Body schema: application/json
required
hooks
required
Array of strings
Items Enum: "url_verification" "inquiry_submitted" "approval_changed" "risk_changed" "inquiry_sent" "supplier_added"
Responses
200

Subscription complete

201
400

One or more of the given hooks are already subscribed to.

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

Callbacks
postApproval changed
postInquiry submitted
postInquiry Sent
postRisk updated
postSupplier Added
post/v2/hooks/subscriptions
Request samples
application/json
{
  • "hooks": [
    ]
}
Response samples
application/json
{
  • "secret": "string"
}
Callback payload samples
application/json
{
  • "type": "approval_changed",
  • "event": {
    }
}

Unsubscribe

To disable notifications for a certain event you will need to unsubscribe from it using this route.

Securitybearer
Request
Request Body schema: application/json
required
hooks
required
Array of strings
Items Enum: "url_verification" "inquiry_submitted" "approval_changed" "risk_changed" "inquiry_sent" "supplier_added"
Responses
200

Unsubscribed successfully

400

One or more of the given hooks are not subscribed to.

401

Unauthorized.

403

Forbidden.

429

Too Many Requests

delete/v2/hooks/subscriptions
Request samples
application/json
{
  • "hooks": [
    ]
}
Response samples
application/json
{
  • "secret": "string"
}