BlueVoyant API Reference for GraphQL ('query') Endpoint

Version: 7f5fed21d

The BlueVoyant Supply Chain Defense API is a primarily GraphQL API that provides access to our risk scores and findings along with additional services and capabilities. This guide is designed to help users get started with our API, familiarize themselves with our offerings and understand how they can leverage our API to build out integrated solutions that bring value to clients.

How to Authenticate and Use

1. Get API Key

BlueVoyant Supply Chain Defense API endpoints require an authentication key to be passed in an X-BlueVoyant-Auth header in order to return data. Users with API access in the SCD portal can generate API keys from the "API Access" section under Settings, or keys can be obtained by contacting the BlueVoyant team directly. Sample API key: "ERMSOjCzwgq51As6MVo-qT-6q_IQjp48nKtZAm1qKbd"

API keys will expire after 30 days but will renew each time you use them. We recommend using a key at least monthly to ensure you do not run into authorization issues.

2. Determine Client UUID

To determine your allowed client UUID(s), use the non-GraphQL endpoint

https://api.bluevoyant.com/3pr/v1/clientUuids

which returns a JSON array in the following output format:

[
  {
    defaultFlag  boolean       "Client is the default client for this user"
    name         string        "Client name"
    uuid         string() "Client UUID"
  }
]

[
  {
    "defaultFlag": true,
    "name": "My Client",
    "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
]

or the equivalent GraphQL myClients query, with an all-zero clientUuid:

https://api.bluevoyant.com/3pr/v1/clients/00000000-0000-0000-0000-000000000000/query

which returns the same information after substituting your default clientUuid. The API will also provide

location

and

Your-Default-Customer

http response headers with the default clientUuid.

3. Call the GraphQL Query

Use the value in the "uuid" or "clientUuid" field returned from one of the above requests to replace {clientUuid} in the GraphQL query, so

https://api.bluevoyant.com/3pr/v1/clients/{clientUuid}/query

becomes

https://api.bluevoyant.com/3pr/v1/clients/3fa85f64-5717-4562-b3fc-2c963f66afa6/query

Sample Queries

POST example with curl, getting emerging vulnerability summary info (emergingVulnerabilitySummaryInfo query)

curl -H "X-BlueVoyant-Auth: <API_KEY>" https://api.bluevoyant.com/3pr/v1/clients/3fa85f64-5717-4562-b3fc-2c963f66afa6/query -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{ "query": "{ emergingVulnerabilitySummaryInfo ( limit: 10 offset: 0 filter: { sortBy: [{field: title direction:desc}] minNumOfThirdPartiesIdentified: 3 } ) { offset limit totalCount pageLength emergingVulnerabilitySummaries { id title numOfThirdPartiesAcknowledged numOfThirdPartiesIdentified numOfThirdPartiesMitigated versionIdentified notificationDate notificationDetails } } }" }'

The equivalent GET example with curl:

curl -H "X-BlueVoyant-Auth: <API_KEY>" 'https://api.bluevoyant.com/3pr/v1/clients/3fa85f64-5717-4562-b3fc-2c963f66afa6/query?query=%7B+emergingVulnerabilitySummaryInfo+(+limit%3A+10+offset%3A+0+filter%3A+%7B+sortBy%3A+%5B%7Bfield%3A+title+direction%3Adesc%7D%5D+minNumOfThirdPartiesIdentified%3A+3+%7D+)+%7B+offset+limit+totalCount+pageLength+emergingVulnerabilitySummaries+%7B+id+title+numOfThirdPartiesAcknowledged+numOfThirdPartiesIdentified+numOfThirdPartiesMitigated+versionIdentified+notificationDate+notificationDetails+%7D+%7D+%7D'

Role-Based Access to Operations

Access to GraphQL operations is limited to users with particular roles. When operations require additional access beyond the lowest-level role ("viewer"), it is indicated in the documentation.

To determine your user's roles and current level of access, use the myUser query. To become the "admin" role if you have permission to do so, use the adminOn mutation.

Rate Limits

All API endpoints are rate-limited and you can make up to 250 requests per minute per IP. If you exceed the limit, you will be temporarily blocked and receive an error response for one minute after which you will be able to resume using the API again.

Users who have API access in the SCD portal can use it to generate an API key. While you only need one API key, if you forgot to copy the API key you can generate up to nine more (10 keys can be requested per 10-minute window) before being blocked for one hour.

GraphQL Resources

API Endpoints

# GraphQL endpoint (GET or POST):
https://api.bluevoyant.com/3pr/v1/clients/{clientUuid}/query

Headers

# Your API token
X-BlueVoyant-Auth: <API_KEY>

Queries

`attributeInfo`

Description

Get client-provided attributes across companies. Attributes can be used to filter and group companies.

Response

Returns an AttributeInfo

Arguments

Name	Description
`portfolioTypes` - `[PortfolioType!]`	The attributes will be limited to those associated with companies in the specified portfolio types. Default: 'external_regular'

Example

Query

query attributeInfo($portfolioTypes: [PortfolioType!]) {
  attributeInfo(portfolioTypes: $portfolioTypes) {
    attributes
  }
}

Variables

{"portfolioTypes": ["external_regular"]}

Response

{
  "data": {
    "attributeInfo": {
      "attributes": ["xyz789"]
    }
  }
}

Queries

`availableQuartersInfo`

Description

Get quarters within the given start and end dates for which the client had any monitored companies and available scores

Response

Returns [AvailableQuarters!]!

Arguments

Name	Description
`startDate` - `String!`	The start of the date range. Date is in 'YYYY-MM-DD' format
`endDate` - `String!`	The end of the date range. Date is in 'YYYY-MM-DD' format
`portfolioType` - `PortfolioType`	The portfolio type is either 'external_regular' or 'high_volume_monitoring' and defaults to 'external_regular'

Example

Query

query availableQuartersInfo(
  $startDate: String!,
  $endDate: String!,
  $portfolioType: PortfolioType
) {
  availableQuartersInfo(
    startDate: $startDate,
    endDate: $endDate,
    portfolioType: $portfolioType
  ) {
    year
    quarter
    startDate
    endDate
    count
  }
}

Variables

{
  "startDate": "2023-01-31",
  "endDate": "2023-03-31",
  "portfolioType": "external_regular"
}

Response

{
  "data": {
    "availableQuartersInfo": [
      {
        "year": 2023,
        "quarter": 2,
        "startDate": "2023-04-01T00:00:00Z",
        "endDate": "2023-06-30T00:00:00Z",
        "count": 123
      }
    ]
  }
}

Queries

`bvgsRiskEventInfo`

Description

Risk events found by 202 Group for various suppliers. This is only available to government clients via api.bluevoyantgov.com for users with the 202_group_risk_events role.

** EXPERIMENTAL **

Response

Returns an BVGSRiskEventInfo

Arguments

Name	Description
`filter` - `BVGSRiskEventFilter`	Default = `null`
`locationFilter` - `BVGSLocationFilter`	Filter risk events by supplier location. Default = `null`
`sortBy` - `[BVGSRiskEventSortBy!]`	Default = `null`
`offset` - `Int!`	Pagination - skip offset number of risk event items before returning up to limit number of items. Default = `0`
`limit` - `Int`	Pagination - skip offset number of risk event items before returning up to limit number of items. Default = `1000`

Example

Query

query bvgsRiskEventInfo(
  $filter: BVGSRiskEventFilter,
  $locationFilter: BVGSLocationFilter,
  $sortBy: [BVGSRiskEventSortBy!],
  $offset: Int!,
  $limit: Int
) {
  bvgsRiskEventInfo(
    filter: $filter,
    locationFilter: $locationFilter,
    sortBy: $sortBy,
    offset: $offset,
    limit: $limit
  ) {
    offset
    limit
    totalCount
    pageLength
    riskEvents {
      ...BVGSRiskEventDataFragment
    }
  }
}

Variables

{
  "filter": null,
  "locationFilter": null,
  "sortBy": null,
  "offset": 0,
  "limit": 1000
}

Response

{
  "data": {
    "bvgsRiskEventInfo": {
      "offset": 987,
      "limit": 987,
      "totalCount": 123,
      "pageLength": 987,
      "riskEvents": [BVGSRiskEventData]
    }
  }
}

Queries

`bvgsSupplierInfo`

Description

Suppliers found by 202 Group. This is only available to government clients via api.bluevoyantgov.com for users with the 202_group_beta_testing role.

** EXPERIMENTAL **

Response

Returns an BVGSSupplierInfo

Arguments

Name	Description
`filter` - `BVGSSupplierFilter`	Default = `null`
`locationFilter` - `BVGSLocationFilter`	Filter suppliers by location. Default = `null`
`sortBy` - `[BVGSSupplierSortBy!]`	Default = `null`
`offset` - `Int!`	Pagination - skip offset number of suppliers before returning up to limit number of suppliers. Default = `0`
`limit` - `Int`	Pagination - skip offset number of suppliers before returning up to limit number of suppliers. Default = `1000`

Example

Query

query bvgsSupplierInfo(
  $filter: BVGSSupplierFilter,
  $locationFilter: BVGSLocationFilter,
  $sortBy: [BVGSSupplierSortBy!],
  $offset: Int!,
  $limit: Int
) {
  bvgsSupplierInfo(
    filter: $filter,
    locationFilter: $locationFilter,
    sortBy: $sortBy,
    offset: $offset,
    limit: $limit
  ) {
    offset
    limit
    totalCount
    pageLength
    suppliers {
      ...BVGSSupplierDataFragment
    }
  }
}

Variables

{
  "filter": null,
  "locationFilter": null,
  "sortBy": null,
  "offset": 0,
  "limit": 1000
}

Response

{
  "data": {
    "bvgsSupplierInfo": {
      "offset": 123,
      "limit": 987,
      "totalCount": 123,
      "pageLength": 987,
      "suppliers": [BVGSSupplierData]
    }
  }
}

Queries

`caseHistoryInfo`

Description

Escalated findings in time period

Response

Returns a CaseHistoryInfo

Arguments

Name	Description
`filter` - `CaseHistoryFilter`	A list of fields to be able to filter on. Default = `null`
`offset` - `Int!`	The offset to start returning data on. Starts at 0. Default = `0`
`limit` - `Int`	The maximum number of cases to return. Default = `1000`

Example

Query

query caseHistoryInfo(
  $filter: CaseHistoryFilter,
  $offset: Int!,
  $limit: Int
) {
  caseHistoryInfo(
    filter: $filter,
    offset: $offset,
    limit: $limit
  ) {
    totalCount
    pageLength
    meanTimeToResolve
    meanDurationActiveEscalated
    cases {
      ...CaseWithCompanyFragment
    }
  }
}

Variables

{"filter": null, "offset": 0, "limit": 1000}

Response

{
  "data": {
    "caseHistoryInfo": {
      "totalCount": 123,
      "pageLength": 123,
      "meanTimeToResolve": 987.65,
      "meanDurationActiveEscalated": 123.45,
      "cases": [CaseWithCompany]
    }
  }
}

Queries

`caseStatistics`

Description

Statistics regarding handling of escalated cases. If portfolioUuids and attributes are not specified, statistics are included regardless of whether the associated companies are still in the client's portfolios.

resolved{Start,End}Date allow filtering on the resolution time ts_first_resolved (or ts_first_escalated depending on the specific resolver). If neither date is specified, you will get both resolved and unresolved cases.

Response

Returns a CaseStatistics!

Arguments

Name	Description
`resolvedStartDate` - `String`	Date is in 'YYYY-MM-DD' format. Default = `null`
`resolvedEndDate` - `String`	Date is in 'YYYY-MM-DD' format. Default = `null`
`activeEscalated` - `Boolean`	Default = `null`
`escalatedOnly` - `Boolean`	Default = `null`
`zeroTolerance` - `Boolean`	Default = `null`
`critical` - `Boolean`	Default = `null`
`portfolioUuids` - `[UUID!]`	If provided, the statistics will be limited to those BV IDs that are currently in the client's portfolios associated with the specified portfolio UUIDs
`attributes` - `[String!]`	If provided, the statistics will be limited to those BV IDs that are currently in the client's portfolios and associated with the specified attributes (which match case-sensitively, and exactly)
`bvids` - `[UUID!]`	If specified, will be filtered by any portolios and attributes specified. Default = `null`

Example

Query

query caseStatistics(
  $resolvedStartDate: String,
  $resolvedEndDate: String,
  $activeEscalated: Boolean,
  $escalatedOnly: Boolean,
  $zeroTolerance: Boolean,
  $critical: Boolean,
  $portfolioUuids: [UUID!],
  $attributes: [String!],
  $bvids: [UUID!]
) {
  caseStatistics(
    resolvedStartDate: $resolvedStartDate,
    resolvedEndDate: $resolvedEndDate,
    activeEscalated: $activeEscalated,
    escalatedOnly: $escalatedOnly,
    zeroTolerance: $zeroTolerance,
    critical: $critical,
    portfolioUuids: $portfolioUuids,
    attributes: $attributes,
    bvids: $bvids
  ) {
    cases
    findings
    companies
    meanDaysToResolve
    escalatedFindingTypes {
      ...EscalatedFindingCountFragment
    }
    companyCasesCounts {
      ...CompanyStatisticFragment
    }
  }
}

Variables

{
  "resolvedStartDate": "2023-01-31",
  "resolvedEndDate": "2023-03-31",
  "activeEscalated": null,
  "escalatedOnly": null,
  "zeroTolerance": null,
  "critical": null,
  "portfolioUuids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "attributes": ["xyz789"],
  "bvids": null
}

Response

{
  "data": {
    "caseStatistics": {
      "cases": 123,
      "findings": 123,
      "companies": 123,
      "meanDaysToResolve": 987.65,
      "escalatedFindingTypes": [EscalatedFindingCount],
      "companyCasesCounts": [CompanyStatistic]
    }
  }
}

Queries

`casesInPeriodStatistics`

Description

Statistics regarding companies affected by handling of cases. If portfolioUuids and attributes are not specified, statistics are included regardless of whether the associated companies are still in the client's portfolios.

Response

Returns a CasesInPeriodStatistics!

Arguments

Name	Description
`startDate` - `String!`	Date is in 'YYYY-MM-DD' format
`endDate` - `String!`	Date is in 'YYYY-MM-DD' format
`portfolioUuids` - `[UUID!]`	If provided, the statistics will be limited to those BV IDs that are currently in the client's portfolios associated with the specified portfolio UUIDs
`attributes` - `[String!]`	If provided, the statistics will be limited to those BV IDs that are currently in the client's portfolios and associated with the specified attributes (which match case-sensitively, and exactly)
`bvids` - `[UUID!]`	If specified, will be filtered by any portolios and attributes specified. Default = `null`

Example

Query

query casesInPeriodStatistics(
  $startDate: String!,
  $endDate: String!,
  $portfolioUuids: [UUID!],
  $attributes: [String!],
  $bvids: [UUID!]
) {
  casesInPeriodStatistics(
    startDate: $startDate,
    endDate: $endDate,
    portfolioUuids: $portfolioUuids,
    attributes: $attributes,
    bvids: $bvids
  ) {
    companiesResolvedInPeriod
    companiesWithCreatedEscalationInPeriod
    companiesWithEscalationAtStartOfPeriod
    casesResolvedInPeriod
    casesWithCreatedEscalationInPeriod
    casesWithEscalationAtStartOfPeriod
    emergingVulnerabilityCases
    emergingVulnerabilityCompanies
    caseResolutionPercentages {
      ...ResolutionPercentageFragment
    }
    controlResolutionPercentages {
      ...ResolutionPercentageFragment
    }
    companiesFullyResolvedInPeriod
    companiesGoneBadInPeriod
  }
}

Variables

{
  "startDate": "2023-01-31",
  "endDate": "2023-03-31",
  "portfolioUuids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "attributes": ["abc123"],
  "bvids": null
}

Response

{
  "data": {
    "casesInPeriodStatistics": {
      "companiesResolvedInPeriod": 987,
      "companiesWithCreatedEscalationInPeriod": 987,
      "companiesWithEscalationAtStartOfPeriod": 123,
      "casesResolvedInPeriod": 123,
      "casesWithCreatedEscalationInPeriod": 987,
      "casesWithEscalationAtStartOfPeriod": 987,
      "emergingVulnerabilityCases": 987,
      "emergingVulnerabilityCompanies": 987,
      "caseResolutionPercentages": [ResolutionPercentage],
      "controlResolutionPercentages": [
        ResolutionPercentage
      ],
      "companiesFullyResolvedInPeriod": 987,
      "companiesGoneBadInPeriod": 987
    }
  }
}

Queries

`clientContactInfo`

Description

Get client contacts (contacts at the client) responsible for escalations for one or more vendor/monitored companies

Response

Returns a ClientContactInfo

Arguments

Name	Description
`filter` - `ContactFilter`	Filters which contacts to return. Default = `null`
`offset` - `Int!`	Pagination - skip offset contacts before returning up to limit of companies. Default = `0`
`limit` - `Int`	Pagination - skip offset contacts before returning up to limit of companies. Default = `1000`

Example

Query

query clientContactInfo(
  $filter: ContactFilter,
  $offset: Int!,
  $limit: Int
) {
  clientContactInfo(
    filter: $filter,
    offset: $offset,
    limit: $limit
  ) {
    offset
    limit
    totalCount
    pageLength
    clientContacts {
      ...ClientContactFragment
    }
  }
}

Variables

{"filter": null, "offset": 0, "limit": 1000}

Response

{
  "data": {
    "clientContactInfo": {
      "offset": 987,
      "limit": 987,
      "totalCount": 123,
      "pageLength": 123,
      "clientContacts": [ClientContact]
    }
  }
}

Queries

`companyInPeriodStatistics`

Description

Statistics regarding companies during a specified period

Response

Returns a CompanyStatistics!

Arguments

Name	Description
`startDate` - `String!`	Date is in 'YYYY-MM-DD' format
`endDate` - `String!`	Date is in 'YYYY-MM-DD' format
`portfolioUuids` - `[UUID!]`	If provided, the statistics will be limited to those BV IDs that are currently in the client's portfolios associated with the specified portfolio UUIDs
`attributes` - `[String!]`	If provided, the statistics will be limited to those BV IDs that are currently in the client's portfolios and associated with the specified attributes (which match case-sensitively, and exactly)
`portfolioType` - `PortfolioType`	Filter results by portfolio type. Specifying a portfolio type that is different from the type of the portfolios specified with portfolioUuids will result in no results.

Example

Query

query companyInPeriodStatistics(
  $startDate: String!,
  $endDate: String!,
  $portfolioUuids: [UUID!],
  $attributes: [String!],
  $portfolioType: PortfolioType
) {
  companyInPeriodStatistics(
    startDate: $startDate,
    endDate: $endDate,
    portfolioUuids: $portfolioUuids,
    attributes: $attributes,
    portfolioType: $portfolioType
  ) {
    meanCompanyScores {
      ...CompanyStatisticFragment
    }
    meanTimeToResolve {
      ...CompanyStatisticFragment
    }
  }
}

Variables

{
  "startDate": "2023-01-31",
  "endDate": "2023-03-31",
  "portfolioUuids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "attributes": ["abc123"],
  "portfolioType": "external_regular"
}

Response

{
  "data": {
    "companyInPeriodStatistics": {
      "meanCompanyScores": [CompanyStatistic],
      "meanTimeToResolve": [CompanyStatistic]
    }
  }
}

Queries

`companyInfo`

Description

This is the query to get information about companies within a client's portfolios.

Response

Returns a CompanyInfo

Arguments

Name	Description
`filter` - `CompanyFilter`	Filters which companies to return. Null indicates no restriction, EXCEPT by portfolioType, which is 'external_regular' by default. Default = `null`
`findingFilter` - `FindingFilter`	Filter the findings found for each company. Default = `null`
`cpeCveFilter` - `CPECVEFilter`	Filter cpe and cve entries to match only these specified. Default = `null`
`evFilter` - `EmergingVulnerabilityFilter`	Default = `null`
`limitByFindings` - `Boolean!`	If true, return only companies for which findings are retrieved. companyInfo is a multi-part query and the limit/offset refer to the main query, which first gets back all companies, filtered by any direct company filters (CompanyFilter). That set of company results is further limited by the finding filters. It might be preferable to use findingInfo to search for companies with particular findings, or increase the limit to larger than the total number of companies in your portfolios. Default = `false`
`limitByCPECVE` - `Boolean!`	If true, return only companies for which CPE/CVEs are retrieved. companyInfo is a multi-part query and the limit/offset refer to the main query, which first gets back all companies, filtered by any direct company filters (CompanyFilter). That set of company results is further limited by the CPE/CVE filters. It might be necessary to increase the limit to larger than the total number of companies in your portfolios. Default = `false`
`limitByEmergingVulnerability` - `Boolean!`	If true, and at least one EmergingVulnerability field is requested, return only companies for which emerging vulnerabilities are retrieved. companyInfo is a multi-part query and the limit/offset refer to the main query, which first gets back all companies, filtered by any direct company filters (CompanyFilter). That set of company results (the number of which appears in totalCount) is further limited by the emerging vulnerability filters (and the count appears in pageLength). It is preferable to use emergingVulnerabilitySummaryInfo or emergingVulnerabilityInfo to search for companies with particular emerging vulnerabilities, or increase the limit to larger than the total number of companies in your portfolios. Default = `false`
`offset` - `Int!`	Pagination - skip offset companies before returning up to limit of companies. Default = `0`
`limit` - `Int`	Pagination - skip offset companies before returning up to limit of companies. Default = `1000`

Example

Query

query companyInfo(
  $filter: CompanyFilter,
  $findingFilter: FindingFilter,
  $cpeCveFilter: CPECVEFilter,
  $evFilter: EmergingVulnerabilityFilter,
  $limitByFindings: Boolean!,
  $limitByCPECVE: Boolean!,
  $limitByEmergingVulnerability: Boolean!,
  $offset: Int!,
  $limit: Int
) {
  companyInfo(
    filter: $filter,
    findingFilter: $findingFilter,
    cpeCveFilter: $cpeCveFilter,
    evFilter: $evFilter,
    limitByFindings: $limitByFindings,
    limitByCPECVE: $limitByCPECVE,
    limitByEmergingVulnerability: $limitByEmergingVulnerability,
    offset: $offset,
    limit: $limit
  ) {
    offset
    limit
    totalCount
    pageLength
    companies {
      ...CompanyFragment
    }
    commonAttributes
  }
}

Variables

{
  "filter": null,
  "findingFilter": null,
  "cpeCveFilter": null,
  "evFilter": null,
  "limitByFindings": false,
  "limitByCPECVE": false,
  "limitByEmergingVulnerability": false,
  "offset": 0,
  "limit": 1000
}

Response

{
  "data": {
    "companyInfo": {
      "offset": 123,
      "limit": 987,
      "totalCount": 987,
      "pageLength": 987,
      "companies": [Company],
      "commonAttributes": ["abc123"]
    }
  }
}

Queries

`companyRequestInfo`

Description

Get all requests to add a company, or all that match specified filters. This endpoint is restricted to users with manager (and higher-level) roles.

Response

Returns a CompanyRequestInfo

Arguments

Name	Description
`filter` - `CompanyRequestFilter`	Default = `null`
`offset` - `Int!`	Pagination - skip offset company requests before returning up to limit of company requests. Default = `0`
`limit` - `Int`	Pagination - skip offset company requests before returning up to limit of company requests. Default = `1000`

Example

Query

query companyRequestInfo(
  $filter: CompanyRequestFilter,
  $offset: Int!,
  $limit: Int
) {
  companyRequestInfo(
    filter: $filter,
    offset: $offset,
    limit: $limit
  ) {
    offset
    limit
    totalCount
    pageLength
    companyRequests {
      ...CompanyRequestFragment
    }
  }
}

Variables

{"filter": null, "offset": 0, "limit": 1000}

Response

{
  "data": {
    "companyRequestInfo": {
      "offset": 987,
      "limit": 123,
      "totalCount": 987,
      "pageLength": 987,
      "companyRequests": [CompanyRequest]
    }
  }
}

Queries

`companySearch`

Description

Search for companies known to BlueVoyant (as opposed to companies in a client's portfolios) that match a given name and/or domain. Returns companies with the best matching scores. Performs both exact and fuzzy matching against all domains and names associated with a company, and exact matching on domains in companies' footprints. This endpoint is restricted to users with manager (and higher-level) roles.

Error responses:

400 | Bad request (neither name nor domain is provided, or either one is too short)

Response

Returns a CompanySearchInfo

Arguments

Name	Description
`name` - `String`	Text used to search the company names
`domain` - `String`	Text used to search the company domains

Example

Query

query companySearch(
  $name: String,
  $domain: String
) {
  companySearch(
    name: $name,
    domain: $domain
  ) {
    totalCount
    pageLength
    companySearchResults {
      ...CompanyWithSearchResultFragment
    }
  }
}

Variables

{
  "name": "abc123",
  "domain": "abc123"
}

Response

{
  "data": {
    "companySearch": {
      "totalCount": 123,
      "pageLength": 987,
      "companySearchResults": [CompanyWithSearchResult]
    }
  }
}

Queries

`configurationInfo`

Description

Returns the client configuration along with the client's licensing information and service setups.

Response

Returns a ClientConfiguration

Arguments

Name	Description
`active` - `Boolean`	Filters only active licenses if set to true. Default = `true`

Example

Query

query configurationInfo($active: Boolean) {
  configurationInfo(active: $active) {
    clientName
    clientUuid
    bvid
    enableMrs
    useClientEntityIds
    clientEntityIdLabel
    useEntityAttributes
    entityAttributeLabel
    enforceEntityQuota
    entityQuota
    entityCount
    enforceEntityChurn
    entityChurnPercent
    entityChurnDays
    entityChurnCount
    enforceMaxEntityAdditions
    maxEntityAdditions
    entityAdditionsDays
    entityAdditionsCount
    enforceHvmEntityQuota
    hvmEntityQuota
    hvmEntityCount
    enforceHvmEntityChurn
    hvmEntityChurnPercent
    hvmEntityChurnDays
    hvmEntityChurnCount
    enforceMaxHvmEntityAdditions
    maxHvmEntityAdditions
    hvmEntityAdditionsDays
    hvmEntityAdditionsCount
    licenseQuantity {
      ...LicenseQuantityFragment
    }
    serviceSetups {
      ...ServiceSetupFragment
    }
  }
}

Variables

{"active": true}

Response

{
  "data": {
    "configurationInfo": {
      "clientName": "abc123",
      "clientUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "enableMrs": false,
      "useClientEntityIds": false,
      "clientEntityIdLabel": "abc123",
      "useEntityAttributes": false,
      "entityAttributeLabel": "xyz789",
      "enforceEntityQuota": true,
      "entityQuota": 987,
      "entityCount": 123,
      "enforceEntityChurn": false,
      "entityChurnPercent": 987.65,
      "entityChurnDays": 123,
      "entityChurnCount": 123,
      "enforceMaxEntityAdditions": true,
      "maxEntityAdditions": 123,
      "entityAdditionsDays": 987,
      "entityAdditionsCount": 123,
      "enforceHvmEntityQuota": true,
      "hvmEntityQuota": 987,
      "hvmEntityCount": 987,
      "enforceHvmEntityChurn": true,
      "hvmEntityChurnPercent": 123.45,
      "hvmEntityChurnDays": 123,
      "hvmEntityChurnCount": 123,
      "enforceMaxHvmEntityAdditions": true,
      "maxHvmEntityAdditions": 123,
      "hvmEntityAdditionsDays": 987,
      "hvmEntityAdditionsCount": 987,
      "licenseQuantity": [LicenseQuantity],
      "serviceSetups": [ServiceSetup]
    }
  }
}

Queries

`cveCompanyInfo`

Description

This is the query to get information about the cves affecting specific companies within a client's portfolios. Limited to companies for which the client has access to detailed datasets.

More limited (presently) than companyInfo but it does allow sorting by cve-related fields.

Response

Returns a CVECompanyInfo

Arguments

Name	Description
`filter` - `CVECompanyFilter`	Default = `null`
`offset` - `Int`
`limit` - `Int`

Example

Query

query cveCompanyInfo(
  $filter: CVECompanyFilter,
  $offset: Int,
  $limit: Int
) {
  cveCompanyInfo(
    filter: $filter,
    offset: $offset,
    limit: $limit
  ) {
    offset
    limit
    totalCount
    pageLength
    companies {
      ...CVECompanyFragment
    }
  }
}

Variables

{"filter": null, "offset": 123, "limit": 987}

Response

{
  "data": {
    "cveCompanyInfo": {
      "offset": 987,
      "limit": 987,
      "totalCount": 123,
      "pageLength": 123,
      "companies": [CVECompany]
    }
  }
}

Queries

`dictionary`

Description

Retrieve key/value mappings used in the SCD portal and API as parameters or lookup values

Response

Returns a DataDictionary!

Example

Query

query dictionary {
  dictionary {
    industryCodes {
      ...DictionaryValueFragment
    }
    riskLevels {
      ...DictionaryValueFragment
    }
    severityLabels {
      ...DictionaryValueFragment
    }
    findingCodes {
      ...DictionaryValueFragment
    }
    findingDescriptions {
      ...DictionaryValueFragment
    }
    insightCodes {
      ...DictionaryValueFragment
    }
    attackSurfaceCodes {
      ...DictionaryValueFragment
    }
    questionnaireGroups {
      ...DictionaryValueFragment
    }
  }
}

Response

{
  "data": {
    "dictionary": {
      "industryCodes": [DictionaryValue],
      "riskLevels": [DictionaryValue],
      "severityLabels": [DictionaryValue],
      "findingCodes": [DictionaryValue],
      "findingDescriptions": [DictionaryValue],
      "insightCodes": [DictionaryValue],
      "attackSurfaceCodes": [DictionaryValue],
      "questionnaireGroups": [DictionaryValue]
    }
  }
}

Queries

`emergingVulnerabilityInfo`

Description

Information about emerging vulnerabilities and companies for which they have been detected. Generally these are recently revealed vulnerabilities that our analysts have manually located in our data and are not yet available as findings.

Null dates are assumed to indicate no restriction on date. Date in 'YYYY-MM-DD' format. Nulls for other parameters indicate no restriction in that dimension.

Response

Returns an EmergingVulnerabilityInfo

Arguments

Name	Description
`filter` - `EmergingVulnerabilityFilter`	Default = `null`
`offset` - `Int!`	Pagination - skip offset emerging vulnerabilities before returning up to limit of emerging vulnerabilities. Default = `0`
`limit` - `Int`	Pagination - skip offset emerging vulnerabilities before returning up to limit of emerging vulnerabilities. Default = `10000`

Example

Query

query emergingVulnerabilityInfo(
  $filter: EmergingVulnerabilityFilter,
  $offset: Int!,
  $limit: Int
) {
  emergingVulnerabilityInfo(
    filter: $filter,
    offset: $offset,
    limit: $limit
  ) {
    offset
    limit
    totalCount
    pageLength
    emergingVulnerabilities {
      ...EmergingVulnerabilityFragment
    }
  }
}

Variables

{"filter": null, "offset": 0, "limit": 10000}

Response

{
  "data": {
    "emergingVulnerabilityInfo": {
      "offset": 987,
      "limit": 123,
      "totalCount": 123,
      "pageLength": 987,
      "emergingVulnerabilities": [EmergingVulnerability]
    }
  }
}

Queries

`emergingVulnerabilitySummaryInfo`

Description

Summary information about emerging vulnerabilities. Generally these are recently revealed vulnerabilities that our analysts have manually located in our data and are not yet available as findings.

Response

Returns an EmergingVulnerabilitySummaryInfo

Arguments

Name	Description
`filter` - `EmergingVulnerabilitySummaryFilter`	Default = `null`
`evDetailFilter` - `EmergingVulnerabilityDetailFilter`	Filter on EV details (companies) associated with an EV. Default = `null`
`offset` - `Int!`	Pagination - skip offset emerging vulnerability summaries before returning up to limit of emerging vulnerability summaries. Default = `0`
`limit` - `Int`	Pagination - skip offset emerging vulnerability summaries before returning up to limit of emerging vulnerability summaries. Default = `1000`

Example

Query

query emergingVulnerabilitySummaryInfo(
  $filter: EmergingVulnerabilitySummaryFilter,
  $evDetailFilter: EmergingVulnerabilityDetailFilter,
  $offset: Int!,
  $limit: Int
) {
  emergingVulnerabilitySummaryInfo(
    filter: $filter,
    evDetailFilter: $evDetailFilter,
    offset: $offset,
    limit: $limit
  ) {
    offset
    limit
    totalCount
    pageLength
    emergingVulnerabilitySummaries {
      ...EmergingVulnerabilitySummaryFragment
    }
  }
}

Variables

{"filter": null, "evDetailFilter": null, "offset": 0, "limit": 1000}

Response

{
  "data": {
    "emergingVulnerabilitySummaryInfo": {
      "offset": 123,
      "limit": 123,
      "totalCount": 987,
      "pageLength": 123,
      "emergingVulnerabilitySummaries": [
        EmergingVulnerabilitySummary
      ]
    }
  }
}

Queries

`findingInfo`

Description

This is the query to get information about findings relating to companies within a client's (external_regular) portfolios.

Response

Returns a FindingInfo

Arguments

Name	Description
`companyFilter` - `CompanyFilter`	Filters which companies to return data for. Null indicates no restriction (except portfolioType='external_regular'). Default = `null`
`findingFilter` - `FindingFilter`	Filter the findings to return. Null indicates no restriction. Default = `null`
`offset` - `Int!`	Pagination - skip offset findings before returning up to limit of findings. Default = `0`
`limit` - `Int`	Pagination - skip offset findings before returning up to limit of findings. Default = `1000`

Example

Query

query findingInfo(
  $companyFilter: CompanyFilter,
  $findingFilter: FindingFilter,
  $offset: Int!,
  $limit: Int
) {
  findingInfo(
    companyFilter: $companyFilter,
    findingFilter: $findingFilter,
    offset: $offset,
    limit: $limit
  ) {
    offset
    limit
    totalCount
    pageLength
    findings {
      ...FindingFragment
    }
  }
}

Variables

{"companyFilter": null, "findingFilter": null, "offset": 0, "limit": 1000}

Response

{
  "data": {
    "findingInfo": {
      "offset": 123,
      "limit": 987,
      "totalCount": 123,
      "pageLength": 123,
      "findings": [Finding]
    }
  }
}

Queries

`groupInfo`

Description

Get information about groups that can be assigned to users of the SCD portal and API. This endpoint is restricted to admin users.

Response

Returns a GroupInfo

Arguments

Name	Description
`filter` - `GroupFilter`	Filter groups returned by various criteria. Default = `null`
`offset` - `Int!`	Pagination - skip offset groups before returning up to limit of groups. Default = `0`
`limit` - `Int`	Pagination - skip offset groups before returning up to limit of groups. Default = `200`

Example

Query

query groupInfo(
  $filter: GroupFilter,
  $offset: Int!,
  $limit: Int
) {
  groupInfo(
    filter: $filter,
    offset: $offset,
    limit: $limit
  ) {
    offset
    limit
    totalCount
    pageLength
    groups {
      ...GroupFragment
    }
  }
}

Variables

{"filter": null, "offset": 0, "limit": 200}

Response

{
  "data": {
    "groupInfo": {
      "offset": 123,
      "limit": 123,
      "totalCount": 987,
      "pageLength": 123,
      "groups": [Group]
    }
  }
}

Queries

`insightsInfo`

Description

Get insights about companies. Each field of InsightsInfo will identify what date field the filter applies to, or whether the startDate/endDate apply at all.

** Experimental **

Response

Returns an InsightsInfo

Arguments

Name	Description
`startDate` - `String!`
`endDate` - `String!`
`filter` - `PortfolioAttributeFilter`	Default = `null`

Example

Query

query insightsInfo(
  $startDate: String!,
  $endDate: String!,
  $filter: PortfolioAttributeFilter
) {
  insightsInfo(
    startDate: $startDate,
    endDate: $endDate,
    filter: $filter
  ) {
    fourthPartyExposure {
      ...ExposureDataWithCompanyInfoFragment
    }
    pdnsVendorDependency {
      ...PdnsVendorDependencyInfoFragment
    }
    vendorDependency {
      ...VendorDependencyInfoFragment
    }
    vendorDependencyLegacy {
      ...VendorDependencyLegacyInfoFragment
    }
    categorySummarizedCount {
      ...CategorySummarizedCountInfoFragment
    }
    vendorSummarizedCount {
      ...VendorSummarizedCountInfoFragment
    }
    productSummarizedCount {
      ...ProductSummarizedCountInfoFragment
    }
    companiesSummarizedCount {
      ...CompanySummarizedCountInfoFragment
    }
    vendorDependencyCountsPerCategory {
      ...VendorDependencyCountsPerCategoryInfoFragment
    }
    vendorDependencyCountsPerVendor {
      ...VendorDependencyCountsPerVendorInfoFragment
    }
    vendorDependencyCountsPerProduct {
      ...VendorDependencyCountsPerProductInfoFragment
    }
    emailSaasInsights {
      ...EmailSaasInsightsInfoFragment
    }
    emailSaasDomainWithoutSecurity {
      ...EmailSaasInsightsInfoFragment
    }
    bannerBusterInsights {
      ...BannerBusterInsightsInfoFragment
    }
    businessRisk {
      ...BusinessRiskInsightInfoFragment
    }
    cveCatalog {
      ...CVECatalogRollupInfoFragment
    }
    cveCatalogGeneric {
      ...CVECatalogGenericInfoFragment
    }
  }
}

Variables

{
  "startDate": "xyz789",
  "endDate": "xyz789",
  "filter": null
}

Response

{
  "data": {
    "insightsInfo": {
      "fourthPartyExposure": ExposureDataWithCompanyInfo,
      "pdnsVendorDependency": PdnsVendorDependencyInfo,
      "vendorDependency": VendorDependencyInfo,
      "vendorDependencyLegacy": VendorDependencyLegacyInfo,
      "categorySummarizedCount": CategorySummarizedCountInfo,
      "vendorSummarizedCount": VendorSummarizedCountInfo,
      "productSummarizedCount": ProductSummarizedCountInfo,
      "companiesSummarizedCount": CompanySummarizedCountInfo,
      "vendorDependencyCountsPerCategory": VendorDependencyCountsPerCategoryInfo,
      "vendorDependencyCountsPerVendor": VendorDependencyCountsPerVendorInfo,
      "vendorDependencyCountsPerProduct": VendorDependencyCountsPerProductInfo,
      "emailSaasInsights": EmailSaasInsightsInfo,
      "emailSaasDomainWithoutSecurity": EmailSaasInsightsInfo,
      "bannerBusterInsights": BannerBusterInsightsInfo,
      "businessRisk": BusinessRiskInsightInfo,
      "cveCatalog": CVECatalogRollupInfo,
      "cveCatalogGeneric": CVECatalogGenericInfo
    }
  }
}

Queries

`myClients`

Description

Get all clients associated with the current SCD user

Response

Returns [ClientMini!]

Example

Query

query myClients {
  myClients {
    clientUuid
    clientName
    defaultFlag
  }
}

Response

{
  "data": {
    "myClients": [
      {
        "clientUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
        "clientName": "abc123",
        "defaultFlag": true
      }
    ]
  }
}

Queries

`myUser`

Description

Get information about the current SCD user associated with the client. Not all fields in the User object are available. Only the following fields can be requested: bvid, businessPhoneNumber, email, firstName, jobTitle, lastLoginTS, lastName, mobilePhoneNumber, primaryName, ssoManagedFlag, status, temporaryAdminExpirationTS, temporaryAdminFlag, username, userCategory, userClass, userType, uuid, functions:*, groups:description, groups:name, groups:uuid, roles:description, roles:name, roles:uuid, roles:policyPermissions:*, roles:resourcePermissions:*

Response

Returns a User!

Example

Query

query myUser {
  myUser {
    uuid
    username
    firstName
    lastName
    email
    status
    userType
    userCategory
    userClass
    bvid
    primaryName
    jobTitle
    businessPhoneNumber
    mobilePhoneNumber
    ssoManagedFlag
    lastLoginTS
    createdTS
    updatedTS
    createdBy
    updatedBy
    roles {
      ...RoleFragment
    }
    groups {
      ...GroupFragment
    }
    functions {
      ...FunctionFragment
    }
    temporaryAdminFlag
    temporaryAdminExpirationTS
  }
}

Response

{
  "data": {
    "myUser": {
      "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "username": "xyz789",
      "firstName": "xyz789",
      "lastName": "xyz789",
      "email": "xyz789",
      "status": "STAGED",
      "userType": "abc123",
      "userCategory": "External",
      "userClass": "Client",
      "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "primaryName": "abc123",
      "jobTitle": "xyz789",
      "businessPhoneNumber": "abc123",
      "mobilePhoneNumber": "xyz789",
      "ssoManagedFlag": false,
      "lastLoginTS": "xyz789",
      "createdTS": "xyz789",
      "updatedTS": "xyz789",
      "createdBy": "abc123",
      "updatedBy": "abc123",
      "roles": [Role],
      "groups": [Group],
      "functions": [Function],
      "temporaryAdminFlag": false,
      "temporaryAdminExpirationTS": "2023-09-29T18:59:37Z"
    }
  }
}

Queries

`portfolioInfo`

Description

Return portfolio with count

Response

Returns a PortfolioInfo

Arguments

Name	Description
`filter` - `PortfolioFilter`	Filters which portfolios to return. Null indicates no restriction, EXCEPT by portfolioType. Default = `null`
`offset` - `Int!`	Default = `0`
`limit` - `Int`	Default = `1000`

Example

Query

query portfolioInfo(
  $filter: PortfolioFilter,
  $offset: Int!,
  $limit: Int
) {
  portfolioInfo(
    filter: $filter,
    offset: $offset,
    limit: $limit
  ) {
    offset
    limit
    totalCount
    pageLength
    portfolios {
      ...PortfolioDataFragment
    }
  }
}

Variables

{"filter": null, "offset": 0, "limit": 1000}

Response

{
  "data": {
    "portfolioInfo": {
      "offset": 987,
      "limit": 987,
      "totalCount": 987,
      "pageLength": 123,
      "portfolios": [PortfolioData]
    }
  }
}

Queries

`portfoliosAuditLog`

Description

Return portfolio audit log data with count. This endpoint is restricted to users with manager (and higher-level) roles.

Response

Returns a PortfoliosAuditLog

Arguments

Name	Description
`offset` - `Int!`	Default = `0`
`limit` - `Int`	Default = `1000`

Example

Query

query portfoliosAuditLog(
  $offset: Int!,
  $limit: Int
) {
  portfoliosAuditLog(
    offset: $offset,
    limit: $limit
  ) {
    offset
    limit
    totalCount
    pageLength
    portfoliosAuditLog {
      ...PortfoliosAuditLogDataFragment
    }
  }
}

Variables

{"offset": 0, "limit": 1000}

Response

{
  "data": {
    "portfoliosAuditLog": {
      "offset": 123,
      "limit": 123,
      "totalCount": 987,
      "pageLength": 123,
      "portfoliosAuditLog": [PortfoliosAuditLogData]
    }
  }
}

Queries

`riskFilterInfo`

Description

Get information about client risk filters. Risk filters are used to generate ServiceNOW cases based on a set of conditions, or match rules. Match rules in the same risk filter are ANDed together. This endpoint is restricted to users with manager (and higher-level) roles.

Response

Returns a RiskFilterInfo

Arguments

Name	Description
`filter` - `RiskFilterFilter`	Fields to filter results by. Default = `null`
`offset` - `Int!`	Pagination - skip offset risk filters before returning up to limit. Default = `0`
`limit` - `Int`	Pagination - skip offset risk filters before returning up to limit. Default = `200`
`sortBy` - `[RiskFilterSortBy!]`	Fields to sort by

Example

Query

query riskFilterInfo(
  $filter: RiskFilterFilter,
  $offset: Int!,
  $limit: Int,
  $sortBy: [RiskFilterSortBy!]
) {
  riskFilterInfo(
    filter: $filter,
    offset: $offset,
    limit: $limit,
    sortBy: $sortBy
  ) {
    offset
    limit
    totalCount
    pageLength
    riskFilters {
      ...RiskFilterFragment
    }
  }
}

Variables

{
  "filter": null,
  "offset": 0,
  "limit": 200,
  "sortBy": [RiskFilterSortBy]
}

Response

{
  "data": {
    "riskFilterInfo": {
      "offset": 123,
      "limit": 123,
      "totalCount": 123,
      "pageLength": 987,
      "riskFilters": [RiskFilter]
    }
  }
}

Queries

`roleInfo`

Description

Get information about roles that can be assigned to users of the SCD portal and API. This endpoint is restricted to admin users.

Response

Returns a RoleInfo

Arguments

Name	Description
`filter` - `RoleFilter`	Filter roles returned by various criteria. Default = `null`
`offset` - `Int!`	Pagination - skip offset roles before returning up to limit of roles. Default = `0`
`limit` - `Int`	Pagination - skip offset roles before returning up to limit of roles. Default = `200`

Example

Query

query roleInfo(
  $filter: RoleFilter,
  $offset: Int!,
  $limit: Int
) {
  roleInfo(
    filter: $filter,
    offset: $offset,
    limit: $limit
  ) {
    offset
    limit
    totalCount
    pageLength
    roles {
      ...RoleFragment
    }
  }
}

Variables

{"filter": null, "offset": 0, "limit": 200}

Response

{
  "data": {
    "roleInfo": {
      "offset": 123,
      "limit": 123,
      "totalCount": 123,
      "pageLength": 987,
      "roles": [Role]
    }
  }
}

Queries

`rolePolicyPermissionInfo`

Description

Get information about policy permissions that form the basis of roles for the SCD portal and API. This endpoint is restricted to admin users.

Response

Returns a RolePolicyPermissionInfo

Arguments

Name	Description
`filter` - `RolePolicyPermissionFilter`	Filter policy permissions returned by various criteria. Default = `null`

Example

Query

query rolePolicyPermissionInfo($filter: RolePolicyPermissionFilter) {
  rolePolicyPermissionInfo(filter: $filter) {
    policyPermissions {
      ...RolePolicyPermissionFragment
    }
  }
}

Variables

{"filter": null}

Response

{
  "data": {
    "rolePolicyPermissionInfo": {
      "policyPermissions": [RolePolicyPermission]
    }
  }
}

Queries

`timeseries`

Description

Get some time series data from between the start and end dates. Each metric may or may not additionally support filtering on portfolio, attribute or BV ID. If the parameter is used to filter the data it will be echoed back in the response for that metric. If it is not used it will be ignored. If portfolioUuids, attributes, and bvids are not specified, statistics are included regardless of whether the associated companies are still in the client's portfolios.

Response

Returns an AvailableTimeSeries!

Arguments

Name	Description
`startDate` - `String!`	Start of the time series. Date is in 'YYYY-MM-DD' format
`endDate` - `String!`	End of the time series. Date is in 'YYYY-MM-DD' format
`portfolioType` - `PortfolioType`	The time series will be limited to the specified portfolio type, which is either 'external_regular' or 'high_volume_monitoring' and defaults to 'external_regular'
`bvids` - `[UUID!]`	If provided, the time series will be limited to the specified BV IDs
`portfolioUuids` - `[UUID!]`	If provided, the time series will be limited to those BV IDs that are currently in the client's portfolios associated with the specified portfolio UUIDs
`attributes` - `[String!]`	If provided, the time series will be limited to those BV IDs that are currently in the client's portfolios and associated with the specified attributes (which match case-sensitively, and exactly)

Example

Query

query timeseries(
  $startDate: String!,
  $endDate: String!,
  $portfolioType: PortfolioType,
  $bvids: [UUID!],
  $portfolioUuids: [UUID!],
  $attributes: [String!]
) {
  timeseries(
    startDate: $startDate,
    endDate: $endDate,
    portfolioType: $portfolioType,
    bvids: $bvids,
    portfolioUuids: $portfolioUuids,
    attributes: $attributes
  ) {
    countEscalatedCases {
      ...TimeSeriesFragment
    }
    countResolvedCases {
      ...TimeSeriesFragment
    }
    countCompaniesEscalatedCases {
      ...TimeSeriesFragment
    }
    countCompaniesExceedingRisk {
      ...TimeSeriesFragment
    }
    meanScore {
      ...TimeSeriesFragment
    }
    totalPortfolioSize {
      ...TimeSeriesFragment
    }
    criticalCompanies {
      ...TimeSeriesFragment
    }
    highCompanies {
      ...TimeSeriesFragment
    }
    mediumCompanies {
      ...TimeSeriesFragment
    }
    lowCompanies {
      ...TimeSeriesFragment
    }
  }
}

Variables

{
  "startDate": "2023-01-31",
  "endDate": "2023-03-31",
  "portfolioType": "external_regular",
  "bvids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "portfolioUuids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "attributes": ["xyz789"]
}

Response

{
  "data": {
    "timeseries": {
      "countEscalatedCases": TimeSeries,
      "countResolvedCases": TimeSeries,
      "countCompaniesEscalatedCases": TimeSeries,
      "countCompaniesExceedingRisk": TimeSeries,
      "meanScore": TimeSeries,
      "totalPortfolioSize": TimeSeries,
      "criticalCompanies": TimeSeries,
      "highCompanies": TimeSeries,
      "mediumCompanies": TimeSeries,
      "lowCompanies": TimeSeries
    }
  }
}

Queries

`userClients`

Description

Get client(s) associated with user. This endpoint is restricted to superadmin users.

Response

Returns [ClientMini!]

Arguments

Name	Description
`userUuid` - `UUID!`

Example

Query

query userClients($userUuid: UUID!) {
  userClients(userUuid: $userUuid) {
    clientUuid
    clientName
    defaultFlag
  }
}

Variables

{
  "userUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
}

Response

{
  "data": {
    "userClients": [
      {
        "clientUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
        "clientName": "abc123",
        "defaultFlag": false
      }
    ]
  }
}

Queries

`userInfo`

Description

Get information about users of the SCD portal and API. This endpoint is restricted to admin users.

Response

Returns a UserInfo

Arguments

Name	Description
`filter` - `UserFilter`	Filter users returned by various criteria. Default = `null`
`offset` - `Int!`	Pagination - skip offset users before returning up to limit of users. Default = `0`
`limit` - `Int`	Pagination - skip offset users before returning up to limit of users. Default = `200`

Example

Query

query userInfo(
  $filter: UserFilter,
  $offset: Int!,
  $limit: Int
) {
  userInfo(
    filter: $filter,
    offset: $offset,
    limit: $limit
  ) {
    offset
    limit
    totalCount
    pageLength
    users {
      ...UserFragment
    }
  }
}

Variables

{"filter": null, "offset": 0, "limit": 200}

Response

{
  "data": {
    "userInfo": {
      "offset": 987,
      "limit": 987,
      "totalCount": 987,
      "pageLength": 987,
      "users": [User]
    }
  }
}

Queries

`vendorContactInfo`

Description

Get vendor contacts (contacts at vendor/monitored companies) responsible for escalations for the company

Response

Returns a VendorContactInfo

Arguments

Name	Description
`filter` - `ContactFilter`	Filters which contacts to return. Default = `null`
`offset` - `Int!`	Pagination - skip offset contacts before returning up to limit of companies. Default = `0`
`limit` - `Int`	Pagination - skip offset contacts before returning up to limit of companies. Default = `1000`

Example

Query

query vendorContactInfo(
  $filter: ContactFilter,
  $offset: Int!,
  $limit: Int
) {
  vendorContactInfo(
    filter: $filter,
    offset: $offset,
    limit: $limit
  ) {
    offset
    limit
    totalCount
    pageLength
    vendorContacts {
      ...VendorContactFragment
    }
  }
}

Variables

{"filter": null, "offset": 0, "limit": 1000}

Response

{
  "data": {
    "vendorContactInfo": {
      "offset": 987,
      "limit": 987,
      "totalCount": 987,
      "pageLength": 987,
      "vendorContacts": [VendorContact]
    }
  }
}

Mutations

`adminOff`

Description

Revoke temporary admin privileges. This endpoint is restricted to users with the 'can_admin' role policy permission.

Response

Returns a Response!

Example

Query

mutation adminOff {
  adminOff {
    code
    message
  }
}

Response

{
  "data": {
    "adminOff": {
      "code": 987,
      "message": "xyz789"
    }
  }
}

Mutations

`adminOn`

Description

Temporarily assume admin privileges. This endpoint is restricted to users with the 'can_admin' role policy permission. Default time permitted: 30 minutes. Maximum time permitted: 180 minutes

Response

Returns a Response!

Arguments

Name	Description
`durationMinutes` - `Float`

Example

Query

mutation adminOn($durationMinutes: Float) {
  adminOn(durationMinutes: $durationMinutes) {
    code
    message
  }
}

Variables

{"durationMinutes": 987.65}

Response

{
  "data": {
    "adminOn": {
      "code": 123,
      "message": "xyz789"
    }
  }
}

Mutations

`clientContactBulkCompanyUpdate`

Description

Add, update, or delete company relationships for a specified client contact and filtered companies. This endpoint is restricted to users with analyst (and higher-level) roles.

Response

Returns a ClientContactBulkUpdate

Arguments

Name	Description
`companyFilter` - `CompanyFilter!`	Filters which companies for which to add, update, or delete relationships with a client contact. Null indicates no restriction, EXCEPT by portfolioType, which is 'external_regular' by default. At least one other filter is required.
`clientContactLookup` - `ClientContactLookup!`	Client contact for which to add, update, or delete company relationships
`addCompanyRelationships` - `Boolean`	Add or update company relationships to the contact. (Either addCompanyRelationships or deleteCompanyRelationships is required.). Default = `false`
`deleteCompanyRelationships` - `Boolean`	Delete company relationships from the contact. (Either addCompanyRelationships or deleteCompanyRelationships is required.). Default = `false`
`escalationPreference` - `AddressType`	Recipient field for contact's email address for the filtered companies : 'to' or 'cc' (primary/notification). (Required if addCompanyRelationships is specified)
`ignoreHarmlessErrors` - `Boolean`	If true, ignore errors when trying to add company relationships that already exist, or trying to delete company relationships that don't exist. Existing relationships will have their escalation preferences updated if true. Default = `false`
`createNewClientContact` - `Boolean`	If email doesn't exist and createNewClientContact is false, don't create a new client contact. Otherwise, create it and add any matching companies. Default = `false`

Example

Query

mutation clientContactBulkCompanyUpdate(
  $companyFilter: CompanyFilter!,
  $clientContactLookup: ClientContactLookup!,
  $addCompanyRelationships: Boolean,
  $deleteCompanyRelationships: Boolean,
  $escalationPreference: AddressType,
  $ignoreHarmlessErrors: Boolean,
  $createNewClientContact: Boolean
) {
  clientContactBulkCompanyUpdate(
    companyFilter: $companyFilter,
    clientContactLookup: $clientContactLookup,
    addCompanyRelationships: $addCompanyRelationships,
    deleteCompanyRelationships: $deleteCompanyRelationships,
    escalationPreference: $escalationPreference,
    ignoreHarmlessErrors: $ignoreHarmlessErrors,
    createNewClientContact: $createNewClientContact
  ) {
    clientContact {
      ...ClientContactFragment
    }
    statuses {
      ...CompanyBulkUpdateStatusFragment
    }
  }
}

Variables

{
  "companyFilter": "An example at this level does nothing, stuff them on the fields",
  "clientContactLookup": ClientContactLookup,
  "addCompanyRelationships": false,
  "deleteCompanyRelationships": false,
  "escalationPreference": "to",
  "ignoreHarmlessErrors": false,
  "createNewClientContact": false
}

Response

{
  "data": {
    "clientContactBulkCompanyUpdate": {
      "clientContact": ClientContact,
      "statuses": [CompanyBulkUpdateStatus]
    }
  }
}

Mutations

`clientContactCreate`

Description

Create a client contact - a contact who works at the client and is responsible for escalations. This endpoint is restricted to users with analyst (and higher-level) roles.

Response

Returns a ClientContact!

Arguments

Name	Description
`input` - `ClientContactToAdd!`

Example

Query

mutation clientContactCreate($input: ClientContactToAdd!) {
  clientContactCreate(input: $input) {
    id
    contactName
    email
    businessPhoneNumber
    jobTitle
    createdTS
    updatedTS
    createdBy
    updatedBy
    companyRelationshipInfo {
      ...ClientContactCompanyRelationshipInfoFragment
    }
  }
}

Variables

{"input": ClientContactToAdd}

Response

{
  "data": {
    "clientContactCreate": {
      "id": 987,
      "contactName": "xyz789",
      "email": "abc123",
      "businessPhoneNumber": "abc123",
      "jobTitle": "xyz789",
      "createdTS": "abc123",
      "updatedTS": "xyz789",
      "createdBy": "abc123",
      "updatedBy": "xyz789",
      "companyRelationshipInfo": ClientContactCompanyRelationshipInfo
    }
  }
}

Mutations

`clientContactUpdate`

Description

Update a client contact - a contact who works at the client and is responsible for escalations. This endpoint is restricted to users with analyst (and higher-level) roles.

Response

Returns a ClientContact!

Arguments

Name	Description
`input` - `ClientContactToUpdate!`

Example

Query

mutation clientContactUpdate($input: ClientContactToUpdate!) {
  clientContactUpdate(input: $input) {
    id
    contactName
    email
    businessPhoneNumber
    jobTitle
    createdTS
    updatedTS
    createdBy
    updatedBy
    companyRelationshipInfo {
      ...ClientContactCompanyRelationshipInfoFragment
    }
  }
}

Variables

{"input": ClientContactToUpdate}

Response

{
  "data": {
    "clientContactUpdate": {
      "id": 987,
      "contactName": "xyz789",
      "email": "xyz789",
      "businessPhoneNumber": "abc123",
      "jobTitle": "abc123",
      "createdTS": "abc123",
      "updatedTS": "xyz789",
      "createdBy": "abc123",
      "updatedBy": "abc123",
      "companyRelationshipInfo": ClientContactCompanyRelationshipInfo
    }
  }
}

Mutations

`clientEntityDataUpdate`

Description

Add/update/delete one or more client entity IDs with optional names and domains for a single company. Returns all client entity data associated with the specified company after the change. This endpoint is restricted to users with analyst (and higher-level) roles.

Expected error responses:

400 | Missing fields, mismatch between client entity ID and BV ID, or duplicates in input
404 | Client entity ID data to update or delete not found
409 | Client entity ID would be a duplicate, or no change
410 | Company not found in client's portfolios
500 | Internal server error

Response

Returns [ClientEntityData!]

Arguments

Name	Description
`input` - `ClientEntityDataUpdate!`

Example

Query

mutation clientEntityDataUpdate($input: ClientEntityDataUpdate!) {
  clientEntityDataUpdate(input: $input) {
    id
    clientEntityId
    clientEntityName
    clientEntityDomain
    createdBy
    createdTS
    updatedBy
    updatedTS
  }
}

Variables

{"input": ClientEntityDataUpdate}

Response

{
  "data": {
    "clientEntityDataUpdate": [
      {
        "id": 123,
        "clientEntityId": "xyz789",
        "clientEntityName": "abc123",
        "clientEntityDomain": "xyz789",
        "createdBy": "abc123",
        "createdTS": "0",
        "updatedBy": "xyz789",
        "updatedTS": "0"
      }
    ]
  }
}

Mutations

`companyBulkUpdate`

Description

Filter companies and either move the matched companies to a destination portfolio (with moveCompaniesToPortfolio set to true and destinationPortfolioUuid set), delete the matched companies (with deleteCompaniesFromPortfolios set to true), add an attribute to the matched companies (with attributeToAdd specified) or delete an attribute from the matched companies (with attributeToDelete specified). This endpoint is restricted to users with manager (and higher-level) roles.

Expected status responses (overall):

204 | No companies matched criteria
206 | Total count of companies matching criteria is larger than number of companies affected
400 | Bad request (including size of matched companies too large to update)
404 | Destination portfolio not found
412 | No companies match filter criteria

CompanyBulkUpdateStatus: Possible status for each BVID with moveCompaniesToPortfolio:

200 | OK (company moved successfully)
409 | BVID is already in the destination portfolio
410 | BVID is not in a portfolio (but matched initially)
422 | BVID is not unique across portfolios
428 | Quota would be exceeded
500 | Internal server error

CompanyBulkUpdateStatus: Possible status for each BVID with deleteCompaniesFromPortfolios:

200 | OK (company deleted successfully)
410 | BVID already is not in a portfolio (but matched initially)
422 | BVID is not unique across portfolios
500 | Internal server error

CompanyBulkUpdateStatus: Possible status for each BVID with attributeToAdd:

200 | OK (company deleted successfully)
409 | Duplicate attribute, with an exact or case-insensitive match (Attributes are unique case-insensitively on a company)
500 | Internal server error

CompanyBulkUpdateStatus: Possible status for each BVID with attributeToDelete:

200 | OK (company deleted successfully)
404 | Attribute not found
500 | Internal server error

Response

Returns a CompanyBulkUpdate

Arguments

Name	Description
`filter` - `CompanyFilter!`	Required filter. Filters which company or companies to update or delete. At least one filter criterion other than portfolioType, which is 'external_regular' by default, must be specified.
`offset` - `Int!`	Pagination - skip offset companies before matching up to limit of companies. Default = `0`
`limit` - `Int`	Pagination - skip offset companies before matching up to limit of companies. Only 1000 companies can be updated at a time. Default = `1000`
`moveCompaniesToPortfolio` - `Boolean`	If true, move the filtered companies to the portfolio specified in destinationPortfolioUuid. Default = `false`
`deleteCompaniesFromPortfolios` - `Boolean`	If true, delete the filtered companies from the client's portfolios. Default = `false`
`destinationPortfolioUuid` - `UUID`	With moveCompaniesToPortfolio, move filtered companies to the specified portfolio
`attributeToAdd` - `String`	If specified, add this attribute to all filtered companies
`attributeToDelete` - `String`	If specified, delete this attribute from all filtered companies
`ignoreHarmlessErrors` - `Boolean`	If true, when moving companies to a portfolio, ignore errors if a company is already in the portfolio (409). If true, when deleting companies, ignore errors if a company is already not in the client's portfolios (410). If true, when adding an attribute, ignore errors if the attribute already exists on the company and is an exact match (409). Adding an attribute that matches an existing one but does not match its case (409) is not considered a harmless error. If true, when deleting an attribute, ignore errors if the attribute (exactly matching by case) already does not exist (404). Default = `false`

Example

Query

mutation companyBulkUpdate(
  $filter: CompanyFilter!,
  $offset: Int!,
  $limit: Int,
  $moveCompaniesToPortfolio: Boolean,
  $deleteCompaniesFromPortfolios: Boolean,
  $destinationPortfolioUuid: UUID,
  $attributeToAdd: String,
  $attributeToDelete: String,
  $ignoreHarmlessErrors: Boolean
) {
  companyBulkUpdate(
    filter: $filter,
    offset: $offset,
    limit: $limit,
    moveCompaniesToPortfolio: $moveCompaniesToPortfolio,
    deleteCompaniesFromPortfolios: $deleteCompaniesFromPortfolios,
    destinationPortfolioUuid: $destinationPortfolioUuid,
    attributeToAdd: $attributeToAdd,
    attributeToDelete: $attributeToDelete,
    ignoreHarmlessErrors: $ignoreHarmlessErrors
  ) {
    offset
    limit
    totalCount
    pageLength
    succeededCount
    failedCount
    statuses {
      ...CompanyBulkUpdateStatusFragment
    }
  }
}

Variables

{
  "filter": "An example at this level does nothing, stuff them on the fields",
  "offset": 0,
  "limit": 1000,
  "moveCompaniesToPortfolio": false,
  "deleteCompaniesFromPortfolios": false,
  "destinationPortfolioUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "attributeToAdd": "abc123",
  "attributeToDelete": "xyz789",
  "ignoreHarmlessErrors": false
}

Response

{
  "data": {
    "companyBulkUpdate": {
      "offset": 987,
      "limit": 987,
      "totalCount": 123,
      "pageLength": 987,
      "succeededCount": 987,
      "failedCount": 987,
      "statuses": [CompanyBulkUpdateStatus]
    }
  }
}

Mutations

`companyRequestCancel`

Description

Cancel a request to add a company to the system and portfolio, only if it has 'Received' status. This endpoint is restricted to users with manager (and higher-level) roles.

Response

Returns a CompanyRequest!

Arguments

Name	Description
`input` - `CompanyRequestToCancel!`

Example

Query

mutation companyRequestCancel($input: CompanyRequestToCancel!) {
  companyRequestCancel(input: $input) {
    requestUuid
    attributes
    bvid
    canceledReason
    primaryDomain
    clientEntityId
    clientEntityIds {
      ...ClientEntityDataRequestFragment
    }
    primaryName
    notes
    open
    portfolioUuid
    status
    createdBy
    createdTS
    updatedBy
    updatedTS
  }
}

Variables

{"input": CompanyRequestToCancel}

Response

{
  "data": {
    "companyRequestCancel": {
      "requestUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "attributes": ["abc123"],
      "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "canceledReason": "xyz789",
      "primaryDomain": "xyz789",
      "clientEntityId": "abc123",
      "clientEntityIds": [ClientEntityDataRequest],
      "primaryName": "xyz789",
      "notes": "xyz789",
      "open": false,
      "portfolioUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "status": "Received",
      "createdBy": "xyz789",
      "createdTS": "xyz789",
      "updatedBy": "abc123",
      "updatedTS": "xyz789"
    }
  }
}

Mutations

`companyRequestCreate`

Description

Create a request to add a company to the system and portfolio if it cannot be found in the company search endpoint. This endpoint is restricted to users with manager (and higher-level) roles.

Response

Returns a CompanyRequest!

Arguments

Name	Description
`input` - `CompanyRequestToAdd!`

Example

Query

mutation companyRequestCreate($input: CompanyRequestToAdd!) {
  companyRequestCreate(input: $input) {
    requestUuid
    attributes
    bvid
    canceledReason
    primaryDomain
    clientEntityId
    clientEntityIds {
      ...ClientEntityDataRequestFragment
    }
    primaryName
    notes
    open
    portfolioUuid
    status
    createdBy
    createdTS
    updatedBy
    updatedTS
  }
}

Variables

{"input": CompanyRequestToAdd}

Response

{
  "data": {
    "companyRequestCreate": {
      "requestUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "attributes": ["abc123"],
      "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "canceledReason": "abc123",
      "primaryDomain": "xyz789",
      "clientEntityId": "xyz789",
      "clientEntityIds": [ClientEntityDataRequest],
      "primaryName": "abc123",
      "notes": "xyz789",
      "open": false,
      "portfolioUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "status": "Received",
      "createdBy": "xyz789",
      "createdTS": "abc123",
      "updatedBy": "xyz789",
      "updatedTS": "xyz789"
    }
  }
}

Mutations

`findingEscalationUpdateThirdParty`

Description

Updates the third-party disposition for an escalated finding. This endpoint is restricted to Monitored_Company (third-party) users with a third_party* role.

Response

Returns a Response!

Arguments

Name	Description
`input` - `FindingEscalationUpdateThirdParty!`

Example

Query

mutation findingEscalationUpdateThirdParty($input: FindingEscalationUpdateThirdParty!) {
  findingEscalationUpdateThirdParty(input: $input) {
    code
    message
  }
}

Variables

{"input": FindingEscalationUpdateThirdParty}

Response

{
  "data": {
    "findingEscalationUpdateThirdParty": {
      "code": 123,
      "message": "xyz789"
    }
  }
}

Mutations

`findingMessageAdd`

Description

Appends a new message to existing message(s) for a finding. This endpoint is restricted to users with analyst (and higher-level) roles.

Response

Returns a Response!

Arguments

Name	Description
`input` - `FindingMessage!`

Example

Query

mutation findingMessageAdd($input: FindingMessage!) {
  findingMessageAdd(input: $input) {
    code
    message
  }
}

Variables

{"input": FindingMessage}

Response

{
  "data": {
    "findingMessageAdd": {
      "code": 123,
      "message": "xyz789"
    }
  }
}

Mutations

`findingMessageAddThirdParty`

Description

Appends a new message to existing message(s) for an escalated finding. This endpoint is restricted to Monitored_Company (third-party) users with a third_party* role.

Response

Returns a Response!

Arguments

Name	Description
`input` - `FindingMessage!`

Example

Query

mutation findingMessageAddThirdParty($input: FindingMessage!) {
  findingMessageAddThirdParty(input: $input) {
    code
    message
  }
}

Variables

{"input": FindingMessage}

Response

{
  "data": {
    "findingMessageAddThirdParty": {
      "code": 123,
      "message": "xyz789"
    }
  }
}

Mutations

`portfolioCompanyAdd`

Description

Add a company to a portfolio. This endpoint is restricted to users with manager (and higher-level) roles. Expected status responses:

200 | OK (company that was added)
400 | Bad request
401 | Client not found
404 | No portfolio found for client
409 | Company is already in portfolio/client-provided entity ID is on another company
410 | Company not found
422 | No official variant found for company because it has not yet been footprinted
423 | Company is restricted
428 | Quota would be exceeded

Response

Returns a CompanyByService!

Arguments

Name	Description
`bvid` - `UUID!`	The unique BlueVoyant identifier (BV ID) of the company.
`portfolioUuid` - `UUID!`	Portfolio ID
`clientEntityIds` - `[ClientEntityDataInput!]`	Additional client-provided IDs (along with optional names or domains) for the company. clientEntityIds must be unique across all companies in the client's portfolios.
`attributes` - `[String!]`	Client-provided attributes or tags that can be associated with one or more companies, used for filtering or grouping companies. Default = `null`

Example

Query

mutation portfolioCompanyAdd(
  $bvid: UUID!,
  $portfolioUuid: UUID!,
  $clientEntityIds: [ClientEntityDataInput!],
  $attributes: [String!]
) {
  portfolioCompanyAdd(
    bvid: $bvid,
    portfolioUuid: $portfolioUuid,
    clientEntityIds: $clientEntityIds,
    attributes: $attributes
  ) {
    ... on Company {
      ...CompanyFragment
    }
    ... on CompanyHVM {
      ...CompanyHVMFragment
    }
    ... on CompanyBROnly {
      ...CompanyBROnlyFragment
    }
  }
}

Variables

{
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "portfolioUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "clientEntityIds": [ClientEntityDataInput],
  "attributes": null
}

Response

{"data": {"portfolioCompanyAdd": Company}}

Mutations

`portfolioCreate`

Description

Create/Insert a portfolio. This endpoint is restricted to users with manager (and higher-level) roles. Expected status responses:

200 | OK (The newly added portfolio)
400 | Bad request/missing portfolio name
401 | Client not found
409 | New portfolio name already exists

Response

Returns a PortfolioData!

Arguments

Name	Description
`input` - `PortfolioToAdd!`

Example

Query

mutation portfolioCreate($input: PortfolioToAdd!) {
  portfolioCreate(input: $input) {
    portfolioName
    portfolioType
    portfolioUuid
    companyCount
    description
    createdBy
    createdTS
    updatedBy
    updatedTS
  }
}

Variables

{"input": PortfolioToAdd}

Response

{
  "data": {
    "portfolioCreate": {
      "portfolioName": "abc123",
      "portfolioType": "external_regular",
      "portfolioUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "companyCount": 987,
      "description": "xyz789",
      "createdBy": "abc123",
      "createdTS": "abc123",
      "updatedBy": "abc123",
      "updatedTS": "xyz789"
    }
  }
}

Mutations

`portfolioDelete`

Description

Delete a portfolio. This endpoint is restricted to users with manager (and higher-level) roles. Expected status responses:

200 | OK (Status/message for each company BVID that matches filters)
400 | Bad request
401 | Client not found
412 | Portfolio contains companies and 'force' is not true

Response

Returns a Response!

Arguments

Name	Description
`portfolioUuid` - `UUID!`	Portfolio ID
`force` - `Boolean`	Must be true to delete portfolios containing companies

Example

Query

mutation portfolioDelete(
  $portfolioUuid: UUID!,
  $force: Boolean
) {
  portfolioDelete(
    portfolioUuid: $portfolioUuid,
    force: $force
  ) {
    code
    message
  }
}

Variables

{
  "portfolioUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "force": true
}

Response

{
  "data": {
    "portfolioDelete": {
      "code": 987,
      "message": "xyz789"
    }
  }
}

Mutations

`portfolioUpdate`

Description

Update a portfolio. This endpoint is restricted to users with manager (and higher-level) roles. Expected status responses:

200 | OK (The edited portfolio)
400 | Bad request
401 | Client not found
404 | Portfolio not found
428 | Quota would be exceeded on type change

Response

Returns a PortfolioData!

Arguments

Name	Description
`input` - `PortfolioToUpdate!`

Example

Query

mutation portfolioUpdate($input: PortfolioToUpdate!) {
  portfolioUpdate(input: $input) {
    portfolioName
    portfolioType
    portfolioUuid
    companyCount
    description
    createdBy
    createdTS
    updatedBy
    updatedTS
  }
}

Variables

{"input": PortfolioToUpdate}

Response

{
  "data": {
    "portfolioUpdate": {
      "portfolioName": "abc123",
      "portfolioType": "external_regular",
      "portfolioUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "companyCount": 123,
      "description": "abc123",
      "createdBy": "xyz789",
      "createdTS": "xyz789",
      "updatedBy": "abc123",
      "updatedTS": "abc123"
    }
  }
}

Mutations

`riskFilterCreate`

Description

Create a new risk filter for client, with the given description. This endpoint is restricted to admin users.

NOT YET AVAILABLE - Please contact your CSM.

Expected error responses:

400 | Bad request (poorly formed or invalid input)

Response

Returns a RiskFilter!

Arguments

Name	Description
`input` - `RiskFilterToAdd!`

Example

Query

mutation riskFilterCreate($input: RiskFilterToAdd!) {
  riskFilterCreate(input: $input) {
    riskFilterId
    description
    matchRules {
      ...RiskFilterMatchRuleFragment
    }
    enabled
    updatedTS
  }
}

Variables

{"input": RiskFilterToAdd}

Response

{
  "data": {
    "riskFilterCreate": {
      "riskFilterId": 123,
      "description": "xyz789",
      "matchRules": [RiskFilterMatchRule],
      "enabled": true,
      "updatedTS": "2024-02-06T20:24:21"
    }
  }
}

Mutations

`riskFilterDelete`

Description

Delete a risk filter. This endpoint is restricted to admin users.

NOT YET AVAILABLE - Please contact your CSM.

Expected error responses:

404 | Risk filter not found
412 | Risk filter contains match rules and 'force' is not true

Response

Returns a Response!

Arguments

Name	Description
`input` - `RiskFilterToDelete!`

Example

Query

mutation riskFilterDelete($input: RiskFilterToDelete!) {
  riskFilterDelete(input: $input) {
    code
    message
  }
}

Variables

{"input": RiskFilterToDelete}

Response

{
  "data": {
    "riskFilterDelete": {
      "code": 987,
      "message": "xyz789"
    }
  }
}

Mutations

`riskFilterUpdate`

Description

Update the description and/or enabled fields of a risk filter for client. This endpoint is restricted to admin users.

NOT YET AVAILABLE - Please contact your CSM.

Expected error responses:

400 | Bad request (poorly formed or invalid input), or nothing to update
404 | Risk filter not found, or match rule to be updated or deleted is not found

Response

Returns a RiskFilter!

Arguments

Name	Description
`input` - `RiskFilterToUpdate!`

Example

Query

mutation riskFilterUpdate($input: RiskFilterToUpdate!) {
  riskFilterUpdate(input: $input) {
    riskFilterId
    description
    matchRules {
      ...RiskFilterMatchRuleFragment
    }
    enabled
    updatedTS
  }
}

Variables

{"input": RiskFilterToUpdate}

Response

{
  "data": {
    "riskFilterUpdate": {
      "riskFilterId": 123,
      "description": "abc123",
      "matchRules": [RiskFilterMatchRule],
      "enabled": true,
      "updatedTS": "2024-02-06T20:24:21"
    }
  }
}

Mutations

`roleCreate`

Description

Create a role to manage users' access to the SCD portal and API. This endpoint is restricted to admin users.

NOT YET AVAILABLE

Response

Returns a Role!

Arguments

Name	Description
`input` - `RoleToAdd!`

Example

Query

mutation roleCreate($input: RoleToAdd!) {
  roleCreate(input: $input) {
    uuid
    name
    description
    configurableFlag
    assignableFlag
    extensionFlag
    defaultFlag
    clientUuid
    createdTS
    updatedTS
    createdBy
    updatedBy
    policyPermissions {
      ...RolePolicyPermissionFragment
    }
    resourcePermissions {
      ...RoleResourcePermissionFragment
    }
    users {
      ...UserFragment
    }
  }
}

Variables

{"input": RoleToAdd}

Response

{
  "data": {
    "roleCreate": {
      "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "name": "abc123",
      "description": "abc123",
      "configurableFlag": true,
      "assignableFlag": true,
      "extensionFlag": true,
      "defaultFlag": true,
      "clientUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "createdTS": "abc123",
      "updatedTS": "abc123",
      "createdBy": "abc123",
      "updatedBy": "xyz789",
      "policyPermissions": [RolePolicyPermission],
      "resourcePermissions": [RoleResourcePermission],
      "users": [User]
    }
  }
}

Mutations

`roleDelete`

Description

Delete a role. (The role must not be associated with any users and must have configurableFlag set to true.) This endpoint is restricted to admin users.

NOT YET AVAILABLE

Response

Returns a Response!

Arguments

Name	Description
`uuid` - `UUID!`

Example

Query

mutation roleDelete($uuid: UUID!) {
  roleDelete(uuid: $uuid) {
    code
    message
  }
}

Variables

{
  "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
}

Response

{
  "data": {
    "roleDelete": {
      "code": 987,
      "message": "abc123"
    }
  }
}

Mutations

`roleUpdate`

Description

Update an existing role to manage users' access to the SCD portal and API. This endpoint is restricted to admin users.

NOT YET AVAILABLE

Response

Returns a Role!

Arguments

Name	Description
`input` - `RoleToUpdate!`

Example

Query

mutation roleUpdate($input: RoleToUpdate!) {
  roleUpdate(input: $input) {
    uuid
    name
    description
    configurableFlag
    assignableFlag
    extensionFlag
    defaultFlag
    clientUuid
    createdTS
    updatedTS
    createdBy
    updatedBy
    policyPermissions {
      ...RolePolicyPermissionFragment
    }
    resourcePermissions {
      ...RoleResourcePermissionFragment
    }
    users {
      ...UserFragment
    }
  }
}

Variables

{"input": RoleToUpdate}

Response

{
  "data": {
    "roleUpdate": {
      "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "name": "xyz789",
      "description": "abc123",
      "configurableFlag": false,
      "assignableFlag": false,
      "extensionFlag": true,
      "defaultFlag": false,
      "clientUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "createdTS": "xyz789",
      "updatedTS": "xyz789",
      "createdBy": "xyz789",
      "updatedBy": "abc123",
      "policyPermissions": [RolePolicyPermission],
      "resourcePermissions": [RoleResourcePermission],
      "users": [User]
    }
  }
}

Mutations

`userActivate`

Description

Activate a STAGED or DEPROVISIONED user and send it an email with activation instructions. The user will remain in PROVISIONED status until completing the activation sequence. This endpoint is restricted to admin users.

Response

Returns a Response!

Arguments

Name	Description
`uuid` - `UUID!`

Example

Query

mutation userActivate($uuid: UUID!) {
  userActivate(uuid: $uuid) {
    code
    message
  }
}

Variables

{
  "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
}

Response

{
  "data": {
    "userActivate": {
      "code": 987,
      "message": "abc123"
    }
  }
}

Mutations

`userClientAdd`

Description

Add a client to an existing user. This endpoint is restricted to superadmin users.

Response

Returns [ClientMini!]

Arguments

Name	Description
`input` - `UserClientAdd!`

Example

Query

mutation userClientAdd($input: UserClientAdd!) {
  userClientAdd(input: $input) {
    clientUuid
    clientName
    defaultFlag
  }
}

Variables

{"input": UserClientAdd}

Response

{
  "data": {
    "userClientAdd": [
      {
        "clientUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
        "clientName": "xyz789",
        "defaultFlag": false
      }
    ]
  }
}

Mutations

`userClientDelete`

Description

Remove a client from an existing user (if it's the only client). This endpoint is restricted to admin users.

Response

Returns a Response!

Arguments

Name	Description
`input` - `UserClientDelete!`

Example

Query

mutation userClientDelete($input: UserClientDelete!) {
  userClientDelete(input: $input) {
    code
    message
  }
}

Variables

{"input": UserClientDelete}

Response

{
  "data": {
    "userClientDelete": {
      "code": 123,
      "message": "xyz789"
    }
  }
}

Mutations

`userClientSetDefault`

Description

Set the default client for a user to one of its current clients. Non-admin users can only set their own default, so cannot specify the input argument.

Response

Returns [ClientMini!]

Arguments

Name	Description
`input` - `UserClientSetDefault`

Example

Query

mutation userClientSetDefault($input: UserClientSetDefault) {
  userClientSetDefault(input: $input) {
    clientUuid
    clientName
    defaultFlag
  }
}

Variables

{"input": UserClientSetDefault}

Response

{
  "data": {
    "userClientSetDefault": [
      {
        "clientUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
        "clientName": "xyz789",
        "defaultFlag": false
      }
    ]
  }
}

Mutations

`userCreate`

Description

Create a user that can access the SCD portal and API. The user will receive an email with login instructions. This endpoint is restricted to admin users.

Response

Returns a User!

Arguments

Name	Description
`input` - `UserToAdd!`

Example

Query

mutation userCreate($input: UserToAdd!) {
  userCreate(input: $input) {
    uuid
    username
    firstName
    lastName
    email
    status
    userType
    userCategory
    userClass
    bvid
    primaryName
    jobTitle
    businessPhoneNumber
    mobilePhoneNumber
    ssoManagedFlag
    lastLoginTS
    createdTS
    updatedTS
    createdBy
    updatedBy
    roles {
      ...RoleFragment
    }
    groups {
      ...GroupFragment
    }
    functions {
      ...FunctionFragment
    }
    temporaryAdminFlag
    temporaryAdminExpirationTS
  }
}

Variables

{"input": UserToAdd}

Response

{
  "data": {
    "userCreate": {
      "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "username": "xyz789",
      "firstName": "abc123",
      "lastName": "xyz789",
      "email": "xyz789",
      "status": "STAGED",
      "userType": "abc123",
      "userCategory": "External",
      "userClass": "Client",
      "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "primaryName": "abc123",
      "jobTitle": "xyz789",
      "businessPhoneNumber": "abc123",
      "mobilePhoneNumber": "xyz789",
      "ssoManagedFlag": false,
      "lastLoginTS": "abc123",
      "createdTS": "abc123",
      "updatedTS": "xyz789",
      "createdBy": "xyz789",
      "updatedBy": "xyz789",
      "roles": [Role],
      "groups": [Group],
      "functions": [Function],
      "temporaryAdminFlag": false,
      "temporaryAdminExpirationTS": "2023-09-29T18:59:37Z"
    }
  }
}

Mutations

`userDeactivate`

Description

Deactivate a user, which will remove the user's groups, and block access to the SCD portal and API. The user cannot already have DEPROVISIONED status. This endpoint is restricted to admin users.

Response

Returns a Response!

Arguments

Name	Description
`uuid` - `UUID!`

Example

Query

mutation userDeactivate($uuid: UUID!) {
  userDeactivate(uuid: $uuid) {
    code
    message
  }
}

Variables

{
  "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
}

Response

{
  "data": {
    "userDeactivate": {
      "code": 123,
      "message": "xyz789"
    }
  }
}

Mutations

`userFactorsReset`

Description

Reset a user's factors (MFA). This endpoint is restricted to admin users.

Response

Returns a Response!

Arguments

Name	Description
`uuid` - `UUID!`

Example

Query

mutation userFactorsReset($uuid: UUID!) {
  userFactorsReset(uuid: $uuid) {
    code
    message
  }
}

Variables

{
  "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
}

Response

{
  "data": {
    "userFactorsReset": {
      "code": 987,
      "message": "abc123"
    }
  }
}

Mutations

`userGroupsUpdate`

Description

Update a user's groups by providing groups to add and/or delete. Only the '3pr-api-accounts' group, which provides access in the SCD portal to API key generation for the public API, and the 'Show-3pr-OnCentrl-Link' group, which gives access to the questionnaire portal from the SCD portal, may be added to or removed from a user at this time. This endpoint is restricted to admin users.

Response

Returns a User!

Arguments

Name	Description
`input` - `UserGroupsToUpdate!`

Example

Query

mutation userGroupsUpdate($input: UserGroupsToUpdate!) {
  userGroupsUpdate(input: $input) {
    uuid
    username
    firstName
    lastName
    email
    status
    userType
    userCategory
    userClass
    bvid
    primaryName
    jobTitle
    businessPhoneNumber
    mobilePhoneNumber
    ssoManagedFlag
    lastLoginTS
    createdTS
    updatedTS
    createdBy
    updatedBy
    roles {
      ...RoleFragment
    }
    groups {
      ...GroupFragment
    }
    functions {
      ...FunctionFragment
    }
    temporaryAdminFlag
    temporaryAdminExpirationTS
  }
}

Variables

{"input": UserGroupsToUpdate}

Response

{
  "data": {
    "userGroupsUpdate": {
      "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "username": "xyz789",
      "firstName": "abc123",
      "lastName": "xyz789",
      "email": "xyz789",
      "status": "STAGED",
      "userType": "abc123",
      "userCategory": "External",
      "userClass": "Client",
      "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "primaryName": "abc123",
      "jobTitle": "xyz789",
      "businessPhoneNumber": "abc123",
      "mobilePhoneNumber": "abc123",
      "ssoManagedFlag": false,
      "lastLoginTS": "xyz789",
      "createdTS": "abc123",
      "updatedTS": "abc123",
      "createdBy": "xyz789",
      "updatedBy": "abc123",
      "roles": [Role],
      "groups": [Group],
      "functions": [Function],
      "temporaryAdminFlag": true,
      "temporaryAdminExpirationTS": "2023-09-29T18:59:37Z"
    }
  }
}

Mutations

`userPasswordExpire`

Description

Expire a user's password and puts it in PASSWORD_EXPIRED status. The user will be required to change their password at the next login. This endpoint is restricted to admin users.

Response

Returns a Response!

Arguments

Name	Description
`uuid` - `UUID!`

Example

Query

mutation userPasswordExpire($uuid: UUID!) {
  userPasswordExpire(uuid: $uuid) {
    code
    message
  }
}

Variables

{
  "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
}

Response

{
  "data": {
    "userPasswordExpire": {
      "code": 123,
      "message": "xyz789"
    }
  }
}

Mutations

`userPasswordReset`

Description

Reset a user's password, which puts the user in RECOVERY status, and sends an email to it. This endpoint is restricted to admin users.

Response

Returns a Response!

Arguments

Name	Description
`uuid` - `UUID!`

Example

Query

mutation userPasswordReset($uuid: UUID!) {
  userPasswordReset(uuid: $uuid) {
    code
    message
  }
}

Variables

{
  "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
}

Response

{
  "data": {
    "userPasswordReset": {
      "code": 123,
      "message": "xyz789"
    }
  }
}

Mutations

`userReactivate`

Description

Reactivate a PROVISIONED user and (re)send it an email with activation instructions. This endpoint is restricted to admin users.

Response

Returns a Response!

Arguments

Name	Description
`uuid` - `UUID!`

Example

Query

mutation userReactivate($uuid: UUID!) {
  userReactivate(uuid: $uuid) {
    code
    message
  }
}

Variables

{
  "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
}

Response

{
  "data": {
    "userReactivate": {
      "code": 987,
      "message": "abc123"
    }
  }
}

Mutations

`userRolesUpdate`

Description

Update a user's roles by providing roles to add and/or delete, or replace all. This endpoint is restricted to admin users.

Response

Returns a User!

Arguments

Name	Description
`input` - `UserRolesToUpdate!`

Example

Query

mutation userRolesUpdate($input: UserRolesToUpdate!) {
  userRolesUpdate(input: $input) {
    uuid
    username
    firstName
    lastName
    email
    status
    userType
    userCategory
    userClass
    bvid
    primaryName
    jobTitle
    businessPhoneNumber
    mobilePhoneNumber
    ssoManagedFlag
    lastLoginTS
    createdTS
    updatedTS
    createdBy
    updatedBy
    roles {
      ...RoleFragment
    }
    groups {
      ...GroupFragment
    }
    functions {
      ...FunctionFragment
    }
    temporaryAdminFlag
    temporaryAdminExpirationTS
  }
}

Variables

{"input": UserRolesToUpdate}

Response

{
  "data": {
    "userRolesUpdate": {
      "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "username": "xyz789",
      "firstName": "xyz789",
      "lastName": "abc123",
      "email": "abc123",
      "status": "STAGED",
      "userType": "abc123",
      "userCategory": "External",
      "userClass": "Client",
      "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "primaryName": "xyz789",
      "jobTitle": "xyz789",
      "businessPhoneNumber": "abc123",
      "mobilePhoneNumber": "abc123",
      "ssoManagedFlag": true,
      "lastLoginTS": "abc123",
      "createdTS": "abc123",
      "updatedTS": "abc123",
      "createdBy": "xyz789",
      "updatedBy": "xyz789",
      "roles": [Role],
      "groups": [Group],
      "functions": [Function],
      "temporaryAdminFlag": false,
      "temporaryAdminExpirationTS": "2023-09-29T18:59:37Z"
    }
  }
}

Mutations

`userSuspend`

Description

Suspend an ACTIVE user, preventing it from logging in. This endpoint is restricted to admin users.

Response

Returns a Response!

Arguments

Name	Description
`uuid` - `UUID!`

Example

Query

mutation userSuspend($uuid: UUID!) {
  userSuspend(uuid: $uuid) {
    code
    message
  }
}

Variables

{
  "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
}

Response

{
  "data": {
    "userSuspend": {
      "code": 123,
      "message": "abc123"
    }
  }
}

Mutations

`userUnlock`

Description

Unlock a LOCKED_OUT user, returning it to ACTIVE status. This endpoint is restricted to admin users.

Response

Returns a Response!

Arguments

Name	Description
`uuid` - `UUID!`

Example

Query

mutation userUnlock($uuid: UUID!) {
  userUnlock(uuid: $uuid) {
    code
    message
  }
}

Variables

{
  "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
}

Response

{
  "data": {
    "userUnlock": {
      "code": 123,
      "message": "abc123"
    }
  }
}

Mutations

`userUnsuspend`

Description

Unsuspend a SUSPENDED user, returning it to ACTIVE status. This endpoint is restricted to admin users.

Response

Returns a Response!

Arguments

Name	Description
`uuid` - `UUID!`

Example

Query

mutation userUnsuspend($uuid: UUID!) {
  userUnsuspend(uuid: $uuid) {
    code
    message
  }
}

Variables

{
  "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
}

Response

{
  "data": {
    "userUnsuspend": {
      "code": 123,
      "message": "xyz789"
    }
  }
}

Mutations

`userUpdate`

Description

Update some attributes for a user. If the username is changed, the user will receive an email at the old email address. This endpoint is restricted to admin users.

Response

Returns a User!

Arguments

Name	Description
`input` - `UserToUpdate!`

Example

Query

mutation userUpdate($input: UserToUpdate!) {
  userUpdate(input: $input) {
    uuid
    username
    firstName
    lastName
    email
    status
    userType
    userCategory
    userClass
    bvid
    primaryName
    jobTitle
    businessPhoneNumber
    mobilePhoneNumber
    ssoManagedFlag
    lastLoginTS
    createdTS
    updatedTS
    createdBy
    updatedBy
    roles {
      ...RoleFragment
    }
    groups {
      ...GroupFragment
    }
    functions {
      ...FunctionFragment
    }
    temporaryAdminFlag
    temporaryAdminExpirationTS
  }
}

Variables

{"input": UserToUpdate}

Response

{
  "data": {
    "userUpdate": {
      "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "username": "abc123",
      "firstName": "xyz789",
      "lastName": "abc123",
      "email": "abc123",
      "status": "STAGED",
      "userType": "xyz789",
      "userCategory": "External",
      "userClass": "Client",
      "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "primaryName": "abc123",
      "jobTitle": "abc123",
      "businessPhoneNumber": "xyz789",
      "mobilePhoneNumber": "xyz789",
      "ssoManagedFlag": true,
      "lastLoginTS": "abc123",
      "createdTS": "xyz789",
      "updatedTS": "abc123",
      "createdBy": "abc123",
      "updatedBy": "abc123",
      "roles": [Role],
      "groups": [Group],
      "functions": [Function],
      "temporaryAdminFlag": false,
      "temporaryAdminExpirationTS": "2023-09-29T18:59:37Z"
    }
  }
}

Mutations

`vendorContactCreate`

Description

Create a vendor contact - a contact at a monitored company who is responsible for escalations. This endpoint is restricted to users with analyst (and higher-level) roles.

Response

Returns a VendorContact!

Arguments

Name	Description
`input` - `VendorContactToAdd!`

Example

Query

mutation vendorContactCreate($input: VendorContactToAdd!) {
  vendorContactCreate(input: $input) {
    id
    contactName
    firstName
    lastName
    email
    jobTitle
    businessPhoneNumber
    bvid
    primaryName
    escalationPreference
    addressType
    mobilePhoneNumber
    customerProvided
    requirePortalProvision
    source
    createdTS
    updatedTS
    createdBy
    updatedBy
  }
}

Variables

{"input": VendorContactToAdd}

Response

{
  "data": {
    "vendorContactCreate": {
      "id": 123,
      "contactName": "xyz789",
      "firstName": "abc123",
      "lastName": "xyz789",
      "email": "abc123",
      "jobTitle": "xyz789",
      "businessPhoneNumber": "abc123",
      "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "primaryName": "abc123",
      "escalationPreference": "to",
      "addressType": "to",
      "mobilePhoneNumber": "abc123",
      "customerProvided": true,
      "requirePortalProvision": true,
      "source": "xyz789",
      "createdTS": "xyz789",
      "updatedTS": "xyz789",
      "createdBy": "xyz789",
      "updatedBy": "abc123"
    }
  }
}

Mutations

`vendorContactDelete`

Description

Delete a vendor contact - a contact at a monitored company who is responsible for escalations. This endpoint is restricted to users with analyst (and higher-level) roles.

Response

Returns a Response!

Arguments

Name	Description
`input` - `ContactToDelete!`

Example

Query

mutation vendorContactDelete($input: ContactToDelete!) {
  vendorContactDelete(input: $input) {
    code
    message
  }
}

Variables

{"input": ContactToDelete}

Response

{
  "data": {
    "vendorContactDelete": {
      "code": 123,
      "message": "xyz789"
    }
  }
}

Mutations

`vendorContactUpdate`

Description

Update a vendor contact - a contact at a monitored company who is responsible for escalations. This endpoint is restricted to users with analyst (and higher-level) roles.

Response

Returns a VendorContact!

Arguments

Name	Description
`input` - `VendorContactToUpdate!`

Example

Query

mutation vendorContactUpdate($input: VendorContactToUpdate!) {
  vendorContactUpdate(input: $input) {
    id
    contactName
    firstName
    lastName
    email
    jobTitle
    businessPhoneNumber
    bvid
    primaryName
    escalationPreference
    addressType
    mobilePhoneNumber
    customerProvided
    requirePortalProvision
    source
    createdTS
    updatedTS
    createdBy
    updatedBy
  }
}

Variables

{"input": VendorContactToUpdate}

Response

{
  "data": {
    "vendorContactUpdate": {
      "id": 987,
      "contactName": "abc123",
      "firstName": "abc123",
      "lastName": "xyz789",
      "email": "abc123",
      "jobTitle": "abc123",
      "businessPhoneNumber": "xyz789",
      "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
      "primaryName": "abc123",
      "escalationPreference": "to",
      "addressType": "to",
      "mobilePhoneNumber": "xyz789",
      "customerProvided": false,
      "requirePortalProvision": true,
      "source": "xyz789",
      "createdTS": "xyz789",
      "updatedTS": "abc123",
      "createdBy": "xyz789",
      "updatedBy": "xyz789"
    }
  }
}

Types

AddressType

Description

Email address recipient field for contact

Values

Enum Value	Description
`to`
`cc`

Example

"to"

Types

Asset

Description

An IP or domain on which findings might appear

Fields

Field Name	Description
`asset` - `String!`
`findings` - `[String!]`	This isn't a list of findings, but a list of findings summaries.
`numberOfFindings` - `Int`
`numberOfObservations` - `Int`
`lastUpdated` - `String!`

Example

{
  "asset": "abc123",
  "findings": ["abc123"],
  "numberOfFindings": 987,
  "numberOfObservations": 123,
  "lastUpdated": "xyz789"
}

Types

AttributeInfo

Description

This is the holder for attributes, from the attributeInfo query.

Fields

Field Name	Description
`attributes` - `[String!]`	A unique set of all attributes in case-insensitive alphabetical order that are associated with the filtered companies

Example

{"attributes": ["abc123"]}

Types

AvailableQuarters

Description

Quarters within the given start and end dates for which the client had any monitored companies and available scores, returned by the availableQuartersInfo query

Fields

Field Name	Description
`year` - `Int!`	The year in 'YYYY' format
`quarter` - `Int!`	The quarter of the year (1-4)
`startDate` - `String!`	The timestamp of the beginning of the quarter
`endDate` - `String!`	The timestamp of the end of the quarter
`count` - `Int!`	The number of distinct companies in the client's portfolios at any time during the quarter

Example

{
  "year": 2023,
  "quarter": 2,
  "startDate": "2023-04-01T00:00:00Z",
  "endDate": "2023-06-30T00:00:00Z",
  "count": 987
}

Types

AvailableTimeSeries

Description

All time series that can be returned by a timeseries query

Fields

Field Name	Description
`countEscalatedCases` - `TimeSeries!`	For each date the number of cases that went to an escalated state on that date If not limited by portfolios or companies in the filter, this will reflect the cases for companies in the client's portfolios as they were from time to time. If limited by portfolios or companies this will reflect cases for the companies in the client's current portfolios.
`countResolvedCases` - `TimeSeries!`	For each date the number of cases that went to a resolved state on that date If not limited by portfolios or companies in the filter, this will reflect the cases for companies in the client's portfolios as they were at midnight on the measurement date. If limited by portfolios or companies this will reflect cases for the companies in the client's current portfolios.
`countCompaniesEscalatedCases` - `TimeSeries!`	Number of companies with an escalated case for a given day If not limited by portfolios or companies in the filter, this will reflect the cases for companies in the client's portfolios as they were at midnight on the measurement date. If limited by portfolios or companies this will reflect cases for the companies in the client's current portfolios.
`countCompaniesExceedingRisk` - `TimeSeries`	Number of companies exceeding risk for a given day. Specifically, this is the count on each day of which companies from the client's current set of portfolio companies had at least one finding exceeding risk tolerance against the current client's set of rules as they were at the time. Five quarters (457 days) of data are available.
`meanScore` - `TimeSeries!`	Mean score of companies across client portfolios for a given day The companies included are the companies currently in the client's portfolios, regardless of whether or not the companies were in the client's portfolios at the measurement date. The companies also must have had a score on the date in question - all companies in a client portfolio will have a score, and BlueVoyant also scores millions of companies not in any client portfolio, but exceptionally some companies may have a score history shorter than the time window requested.
`totalPortfolioSize` - `TimeSeries!`	Total number of companies that are in a client's portfolios (or only those matching the filters) at midnight on a given day, and that have scores available for that day. If not limited by portfolio or company, counted based on the set of companies in the client's portfolios as they were at midnight on the measurement date.
`criticalCompanies` - `TimeSeries!`	Number of companies with a critical score severity for a given day If not limited by portfolio or company, counted based on the set of companies in the client's portfolios from time to time. If limited by portfolio or company it is limited to the intersection of what is in the selected portfolio (or passed in set of companies) and the companies that were in the client portfolios as they were at midnight on the measurement date.
`highCompanies` - `TimeSeries!`	Number of companies with a high score severity for a given day If not limited by portfolio or company, counted based on the set of companies in the client's portfolios from time to time. If limited by portfolio or company it is limited to the intersection of what is in the selected portfolio (or passed in set of companies) and the companies that were in the client portfolios as they were at midnight on the measurement date.
`mediumCompanies` - `TimeSeries!`	Number of companies with a medium score severity for a given day If not limited by portfolio or company, counted based on the set of companies in the client's portfolios from time to time. If limited by portfolio or company it is limited to the intersection of what is in the selected portfolio (or passed in set of companies) and the companies that were in the client portfolios as they were at midnight on the measurement date.
`lowCompanies` - `TimeSeries!`	Number of companies with a low score severity for a given day If not limited by portfolio or company, counted based on the set of companies in the client's portfolios from time to time. If limited by portfolio or company it is limited to the intersection of what is in the selected portfolio (or passed in set of companies) and the companies that were in the client portfolios as they were at midnight on the measurement date.

Example

{
  "countEscalatedCases": TimeSeries,
  "countResolvedCases": TimeSeries,
  "countCompaniesEscalatedCases": TimeSeries,
  "countCompaniesExceedingRisk": TimeSeries,
  "meanScore": TimeSeries,
  "totalPortfolioSize": TimeSeries,
  "criticalCompanies": TimeSeries,
  "highCompanies": TimeSeries,
  "mediumCompanies": TimeSeries,
  "lowCompanies": TimeSeries
}

Types

BVGSLocation

Description

A location. In so far as it corresponds to a street address, the format is loosely based on the USPS standard

Fields

Field Name	Description
`address1` - `String`	Address line 1, typically corresponding to a building or door
`address2` - `String`	Address line 2, typically corresponding to a unit within whatever address1 is
`city` - `String`	City
`congressionalDistrict` - `String`	US Congressional district where applicable
`stateName` - `String`	Generally corresponds to the next subdivision used below country in postal addresses
`countyFipsCode` - `String`	5-digit county FIPS code, where available. See https://www.census.gov/library/reference/code-lists/ansi.html
`countryName` - `String`	Country name. May exceptionally be null.
`zipCode` - `String`	The part of an address that's a code
`longitude` - `String`	Longitude in degrees relative to WGS84. String so that json serialization/parsing doesn't truncate the fractional part
`latitude` - `String`	Latitude in degrees relative to WGS84. String so that json serialization/parsing doesn't truncate the fractional part

Example

{
  "address1": "xyz789",
  "address2": "xyz789",
  "city": "xyz789",
  "congressionalDistrict": "xyz789",
  "stateName": "abc123",
  "countyFipsCode": "xyz789",
  "countryName": "xyz789",
  "zipCode": "xyz789",
  "longitude": "xyz789",
  "latitude": "abc123"
}

Types

BVGSLocationFilter

Description

Fields available by which to filter BVGS items with associated locations

Fields

Input Field	Description
`countries` - `[String!]`	Limit output to suppliers located in the listed countries. Currently matched against the freeform text country field and country code. Default = `null`
`excludeCountries` - `[String!]`	Limit output to suppliers NOT located in the listed countries. Currently matched against the freeform text country field and country code. Default = `null`
`states` - `[String!]`	States to limit the output. Currently matched against the freeform text state field and state code. Default = `null`
`congressionalDistricts` - `[String!]`	Congressional districts to limit the output. Matched exactly but case-insensitively against the congressionalDistrict field. Default = `null`
`zipCodes` - `[String!]`	Zip codes to limit the output. Matched exactly but case-insensitively against the zipCode field. Default = `null`
`box` - `Box`	Limit output to sites inside the box. Only includes sites having non-null latitude and longitude fields. Default = `null`

Example

{
  "countries": ["abc123"],
  "excludeCountries": ["xyz789"],
  "states": ["abc123"],
  "congressionalDistricts": ["xyz789"],
  "zipCodes": ["abc123"],
  "box": Box
}

Types

BVGSProject

Description

BVGS projects collect together suppliers in a similar way to SCD portfolios collecting entities.

Fields

Field Name	Description
`projectId` - `UUID!`	Unique ID for the project
`legacyProjectId` - `Int64!`	Unique legacy ID for the project Use 'projectId'
`projectName` - `String!`	Project's name

Example

{
  "projectId": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "legacyProjectId": 123,
  "projectName": "xyz789"
}

Types

BVGSRiskEventData

Fields

Field Name	Description
`legacyEventId` - `Int64!`	Unified identifier for this risk event Will use UUID soon
`supplier` - `BVGSSupplier`	Information about the company affected
`publicationDate` - `Time`	The date the referenced news item was published
`fullTextLink` - `String`	Link to the source news item
`title` - `String`	A title for this risk event
`analystNote` - `String`	Our analysts' analysis as to the impact and relevance of this event
`eventExtract` - `String`	An extract from the underlying news report
`newsSourceName` - `String`	A name for the news source
`riskEventCategory` - `RiskEventCategory`	A categorisation of the risk. One of: Financial Foreign Ownership Control or Influence Political and Regulatory Infrastructure Technology and Cybersecurity Transportation and Distribution Product Quality and Design Economic Manufacturing and Supply Environment Compliance Human Capital Note that these are completely independent of the risk categories used to categorise SCD findings
`riskLevel` - `RiskLevel`	A qualitative bucketing of risk

Example

{
  "legacyEventId": 123,
  "supplier": BVGSSupplier,
  "publicationDate": "2024-02-06T00:00:00Z",
  "fullTextLink": "abc123",
  "title": "abc123",
  "analystNote": "abc123",
  "eventExtract": "xyz789",
  "newsSourceName": "abc123",
  "riskEventCategory": "Financial",
  "riskLevel": "low"
}

Types

BVGSRiskEventFilter

Description

Fields available by which to filter BVGS risk events

Fields

Input Field	Description
`projectIds` - `[UUID!]`	Limit output to suppliers for the listed BVGS projects. Default = `null`
`bvids` - `[UUID!]`	Limit output to the listed BV IDs. Note that some risk event items relate to suppliers without corresponding BV IDs. Default = `null`
`supplierIds` - `[UUID!]`	Limit output to the listed supplier IDs. Default = `null`
`riskEventCategories` - `[RiskEventCategory!]`	Limit output to the listed categories. Default = `null`
`riskLevels` - `[RiskLevel!]`	Limit output to the listed risk levels. Default = `null`
`minPublicationDate` - `Time`	Limit output to events dated no earlier than this. Default = `null`
`maxPublicationDate` - `Time`	Limit output to events dated no later than this. Default = `null`
`supplierNamesWildcard` - `[String!]`	Return only suppliers that case-insensitively match these strings, with wildcard matching. Default = `null`
`text` - `String`	Return only events with title or eventExtract or analystNote that case insensitively match this string. Default = `null`
`dunsNumbers` - `[String!]`	Limit output to the listed DUNS numbers. Default = `null`
`cageIds` - `[String!]`	Limit output to the listed cage IDs, matched exactly but case-insensitively. Default = `null`
`legacyEventIds` - `[Int64!]`	Limit output to the listed legacy event IDs (will be deprecated in favor or a UUID soon). Default = `null`

Example

{
  "projectIds": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "bvids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "supplierIds": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "riskEventCategories": ["Financial"],
  "riskLevels": ["low"],
  "minPublicationDate": ["2025-04-01"],
  "maxPublicationDate": ["2025-04-10"],
  "supplierNamesWildcard": ["abc123"],
  "text": "abc123",
  "dunsNumbers": ["136108342"],
  "cageIds": ["8X691"],
  "legacyEventIds": [123]
}

Types

BVGSRiskEventInfo

Description

This is the holder for risk events, with pagination and counts

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`
`totalCount` - `Int64!`	Count of risk events matching filter regardless of whether they fit within limit
`pageLength` - `Int!`
`riskEvents` - `[BVGSRiskEventData!]`	List of risk events for client

Example

{
  "offset": 123,
  "limit": 123,
  "totalCount": 123,
  "pageLength": 123,
  "riskEvents": [BVGSRiskEventData]
}

Types

BVGSRiskEventSortBy

Description

Holder for the risk events sort fields for the bvgsRiskEventInfo query

Fields

Input Field	Description
`field` - `BVGSRiskEventSorts!`
`direction` - `SortDirection`

Example

{"field": "legacyEventId", "direction": "asc"}

Types

BVGSRiskEventSorts

Description

Fields available to sort risk events by in the bvgsRiskEventInfo query; default: legacyEventId

Values

Enum Value	Description
`legacyEventId`	Unified ID assigned to each risk event
`supplierName`	Name of the supplier
`publicationDate`	Date of news items

Example

"legacyEventId"

Types

BVGSSupplier

Description

Suppliers are in essence a company plus location

Fields

Field Name	Description
`supplierId` - `UUID`	Identifier for the supplier within the BVGS data model
`legacySupplierId` - `Int`	Don't use this. It's going away. Old identifier for the supplier within the BVGS data model. Use 'supplierId'
`supplierName` - `String`	The supplier name
`cageId` - `String`	An identifier for the company part of a supplier, as allocated by the US govt
`dunsNumber` - `String`	Dun & Bradstreet (DUNS) identifier for the company part of a supplier, as allocated by the US govt
`projects` - `[BVGSProject!]`	Projects associated with the supplier
`bvidAvailable` - `Boolean`	Whether this supplier have a corresponding SCD company
`website` - `String`	Website as recorded in the BVGS supplier data. If no company available, use this to supply the website
`company` - `CompanyFromSearchResult`	The SCD company part of the supplier. Note: If the company is NOT in the customer's SCD portfolios (is not cyber-monitored), the CompanyOnly type will be used. The other concrete company types can be accessed with `... on CompanyBase` but CompanyOnly must be separately accessed with `... on CompanyOnly`
`location` - `BVGSLocation`

Example

{
  "supplierId": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "legacySupplierId": 987,
  "supplierName": "xyz789",
  "cageId": "abc123",
  "dunsNumber": "xyz789",
  "projects": [BVGSProject],
  "bvidAvailable": true,
  "website": "abc123",
  "company": Company,
  "location": BVGSLocation
}

Types

BVGSSupplierData

Fields

Field Name	Description
`supplier` - `BVGSSupplier!`	Information about the supplier
`transactionInfo` - `BVGSSupplierTransactionInfo`	Transactions (contracts, subawards, etc.) associated with supplier. If projects are limited in the parent query, only transactions for those projects are displayed.
Arguments `limit` - `Int` Limit and offset are per-supplier `offset` - `Int!` Limit and offset are per-supplier `sortBy` - `[BVGSSupplierTransactionSortBy!]`

Example

{
  "supplier": BVGSSupplier,
  "transactionInfo": BVGSSupplierTransactionInfo
}

Types

BVGSSupplierFilter

Description

Fields available by which to filter BVGS suppliers

Fields

Input Field	Description
`projectIds` - `[UUID!]`	Limit output to suppliers for the listed BVGS projects. BVGS projects collect together suppliers in a similar way to SCD portfolios collecting entities. BVGS Projects are entirely unrelated to the concept of project in SCD. Default = `null`
`bvids` - `[UUID!]`	Limit output to suppliers with the listed BV IDs. Default = `null`
`bvidAvailable` - `Boolean`	Limit output to suppliers with an associated BV ID. Default = `null`
`cyberMonitored` - `Boolean`	Limit output to suppliers under cyber-monitoring by this client. Default = `null`
`supplierIds` - `[UUID!]`	Limit output to suppliers with the listed supplier IDs. Not all suppliers have BV IDs. Default = `null`
`legacySupplierIds` - `[Int!]`	Identifier for the supplier within the BVGS data model. This will be deprecated. Default = `null`
`supplierNamesWildcard` - `[String!]`	Return only suppliers that case-insensitively match these strings, with wildcard matching. Default = `null`
`dunsNumbers` - `[String!]`	Limit output to the listed DUNS numbers. Default = `null`
`cageIds` - `[String!]`	Limit output to the listed cage IDs, matched exactly but case-insensitively. Default = `null`
`text` - `String`	Return only suppliers with name or cageId that case insensitively match this string. Default = `null`

Example

{
  "projectIds": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "bvids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "bvidAvailable": false,
  "cyberMonitored": false,
  "supplierIds": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "legacySupplierIds": [987],
  "supplierNamesWildcard": ["abc123"],
  "dunsNumbers": ["136108342"],
  "cageIds": ["8X691"],
  "text": "xyz789"
}

Types

BVGSSupplierInfo

Description

This is the holder for suppliers, with pagination and counts

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`
`totalCount` - `Int64!`	Count of suppliers matching filter regardless of whether they fit within limit
`pageLength` - `Int!`
`suppliers` - `[BVGSSupplierData!]`	List of suppliers for client

Example

{
  "offset": 123,
  "limit": 987,
  "totalCount": 123,
  "pageLength": 987,
  "suppliers": [BVGSSupplierData]
}

Types

BVGSSupplierSortBy

Description

Holder for the supplier sort fields for the supplierInfo query

Fields

Input Field	Description
`field` - `BVGSSupplierSorts!`
`direction` - `SortDirection`

Example

{"field": "supplierName", "direction": "asc"}

Types

BVGSSupplierSorts

Description

Fields available to sort suppliers by in the supplierInfo query; default: supplierName

Values

Enum Value	Description
`supplierName`	Name of the supplier
`legacySupplierId`	Legacy ID of the supplier. Will be deprecated

Example

"supplierName"

Types

BVGSSupplierTransaction

Description

Transactions associated with a supplier, like contracts, subawards, logistics, research, etc.

Fields

Field Name	Description
`project` - `BVGSProject!`	Project associated with the transaction
`category` - `String`	Optional category for the transaction
`description` - `String!`	Transaction description

Example

{
  "project": BVGSProject,
  "category": "xyz789",
  "description": "abc123"
}

Types

BVGSSupplierTransactionInfo

Description

This is the holder for supplier transactions, with pagination and counts

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`
`totalCount` - `Int64!`	Count of transactions matching filter regardless of whether they fit within limit
`pageLength` - `Int!`
`transactions` - `[BVGSSupplierTransaction!]`	List of transactions for supplier

Example

{
  "offset": 123,
  "limit": 123,
  "totalCount": 123,
  "pageLength": 123,
  "transactions": [BVGSSupplierTransaction]
}

Types

BVGSSupplierTransactionSortBy

Description

Holder for the transaction sort fields for the transactionInfo subquery of the supplierInfo query

Fields

Input Field	Description
`field` - `BVGSSupplierTransactionSorts!`
`direction` - `SortDirection`

Example

{"field": "category", "direction": "asc"}

Types

BVGSSupplierTransactionSorts

Description

Fields available to sort transactions by in the transactionInfo subquery of the supplierInfo query

Values

Enum Value	Description
`category`	Category of the transaction
`description`	Description of the transaction

Example

"category"

Types

BannerBusterInsight

Description

Insight indicating that a product was detected on an IP address/port in a monitored company's footprint

Fields

Field Name	Description
`bvid` - `UUID!`	The unique BlueVoyant identifier (BV ID) of the company associated with this insight
`ip` - `String!`	The IP address on which a product was detected
`port` - `Int!`	The port on which a product was detected
`subdomain` - `String`	The hostname associated with the IP address
`swVersion` - `String`	Software version
`swPackage` - `String`	Other software version-related information
`deviceVersion` - `String`	The version of the (hardware) device
`deviceName` - `String`	The name of the device
`httpTitle` - `String`	Web page title
`authType` - `String`	The type of authentication detected
`httpHeaderServer` - `String`	HTTP server information.
`lastObservedTS` - `Time!`	The last time this specific insight was observed.
`findingCode` - `Int64!`	Finding code is an integer that represents the specific type of a finding. See the dictionary query and the DataDictionary type.
`category` - `String`	The category associated with the product
`vendor` - `String`	Name of the vendor providing the product
`product` - `String`	The product detected
`updatedTS` - `Time!`	The time the insight was last updated
`company` - `CompanyByService`	Company associated with the insight
`mfaType` - `String`	Use 'authType' instead

Example

{
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "ip": "xyz789",
  "port": 123,
  "subdomain": "xyz789",
  "swVersion": "abc123",
  "swPackage": "xyz789",
  "deviceVersion": "xyz789",
  "deviceName": "abc123",
  "httpTitle": "abc123",
  "authType": "abc123",
  "httpHeaderServer": "xyz789",
  "lastObservedTS": "2024-02-06T20:24:21Z",
  "findingCode": 123,
  "category": "xyz789",
  "vendor": "abc123",
  "product": "abc123",
  "updatedTS": "2024-02-06T20:24:21Z",
  "company": Company,
  "mfaType": "abc123"
}

Types

BannerBusterInsightsInfo

Fields

Field Name	Description
`bannerBusterInsights` - `[BannerBusterInsight!]`	A list of all the returned banner buster insights.
`totalCount` - `Int64!`	The total number of objects that fit the filter given regardless of limit.
`pageLength` - `Int!`	The total amount of objects returned to user. Between zero and the limit provided.

Example

{
  "bannerBusterInsights": [BannerBusterInsight],
  "totalCount": 123,
  "pageLength": 123
}

Types

BannerBusterSort

Values

Enum Value	Description
`category`	The category associated with the product
`vendor`	The category associated with the product
`product`	The product detected
`updatedTS`	The time the insight was last updated (process date)
`findingCode`	Finding code is an integer that represents the specific type of a finding. See the dictionary query and the DataDictionary type.
`bvid`	The unique BlueVoyant identifier (BV ID) of the company associated with this insight
`companyName`	Primary name of the company
`portfolioName`	Name of the portfolio containing the company
`lastObservedTS`	The last time this specific insight was observed or validated

Example

"category"

Types

BannerBusterSortBy

Fields

Input Field	Description
`field` - `BannerBusterSort!`	Field by which to sort vendors. Default = `updatedTS`
`direction` - `SortDirection`	Direction in which to sort vendors (asc/desc). Default = `asc`

Example

{"field": "category", "direction": "asc"}

Types

Boolean

Description

The Boolean scalar type represents true or false.

Types

Box

Fields

Input Field	Description
`boxLat1` - `Float!`	boxLat1 and boxLng1 define one corner of the box, and boxLat2 and boxLng2 define the other corner of the box. Only includes sites having non-null latitude and longitude fields)
`boxLng1` - `Float!`
`boxLat2` - `Float!`
`boxLng2` - `Float!`

Example

{"boxLat1": 987.65, "boxLng1": 123.45, "boxLat2": 123.45, "boxLng2": 987.65}

Types

BusinessRiskFilter

Description

** Experimental **

Fields

Input Field	Description
`bvids` - `[UUID!]`	The BV ID is the unique identifier for a company. If specified, results will be limited to companies with bvids listed here. If not specified, all companies selected for business risk for this client, with events with dates in the time range specified in the insightsInfo filter, matching any provided portfolioUuids and attributes, will be used. TO BE DEPRECATED This field will eventually go away when the BusinessRisk query starts to respect the bvids field in PortfolioAttributeFilter. The portfolioUuids and attributes fields from that filter are used here.
`eventIds` - `[Int64!]`	The ID associated with this specific business risk event.
`riskRatings` - `[BusinessRiskRating!]`	risk rating - Low/Medium/High
`categories` - `[String!]`	categories of risk - not yet firmed up to be an enum

Example

{
  "bvids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "eventIds": [123],
  "riskRatings": ["High"],
  "categories": ["abc123"]
}

Types

BusinessRiskInsight

Fields

Field Name	Description
`bvid` - `UUID!`	The BV ID is the unique identifier for the company.
`eventId` - `Int64!`	The ID associated with this specific business risk event.
`city` - `String`	City in which the HQ of the affected entity is located.
`state` - `String`	State in which the HQ of the affected entity is located.
`country` - `String`	Country in which the HQ of the affected entity is located.
`address` - `String`	The address at which the HQ of the affected entity is located.
`eventSummary` - `String`	Summary encompassing what happened in this business risk event.
`eventTitle` - `String`	A title for this event
`newsSource` - `String`	Information about the source of information
`category` - `String`	The category of risk this event correlated to. (Financial, Foreign Influence, Governance, etc)
`riskRating` - `BusinessRiskRating`	The severity rating of this specific event. (High/Medium/Low)
`url` - `String`	Full link to where this data was gathered from.
`analystNote` - `String`	An analyst's note indicating why this record is relevant.
`date` - `String!`	The date on which the business risk event was recorded. Will look like: "2023-07-18"
`company` - `CompanyByService`	The company affected by this event

Example

{
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "eventId": 123,
  "city": "abc123",
  "state": "abc123",
  "country": "xyz789",
  "address": "xyz789",
  "eventSummary": "xyz789",
  "eventTitle": "abc123",
  "newsSource": "abc123",
  "category": "xyz789",
  "riskRating": "High",
  "url": "xyz789",
  "analystNote": "abc123",
  "date": "2024-02-06",
  "company": Company
}

Types

BusinessRiskInsightInfo

Description

Some business risk insights and information about the set of results

Fields

Field Name	Description
`businessRiskInsights` - `[BusinessRiskInsight!]`	The set of results depending on the offset/limit/filter and anything else selected
`totalCount` - `Int64!`	The total count of what you could get based on current filters if you weren't limiting or setting the offset

Example

{
  "businessRiskInsights": [BusinessRiskInsight],
  "totalCount": 123
}

Types

BusinessRiskRating

Values

Enum Value	Description
`High`
`Medium`
`Low`

Example

"High"

Types

BusinessRiskSort

Values

Enum Value	Description
`date`
`riskRating`
`category`
`companyName`
`portfolioName`

Example

"date"

Types

BusinessRiskSortBy

Fields

Input Field	Description
`field` - `BusinessRiskSort!`	Field by which to sort business risks. Default = `date`
`direction` - `SortDirection`	Direction in which to sort policy permissions (asc/desc). Default = `asc`

Example

{"field": "date", "direction": "asc"}

Types

CISAKEVCVE

Description

CVEs that include a KEV list flag and the confidence rating

Fields

Field Name	Description
`findingCode` - `Int!`	Finding code is an integer that represents the specific type of a finding. See the dictionary query and the DataDictionary type.
`findingHash` - `String!`	An ID of int64 type that is unique for a BV ID, variant, and finding code
`ip` - `String!`	The IP address of the entity.
`port` - `Int!`	The port used by the entity.
`latestObservation` - `String!`	The last time this specific entity was observed.
`cpeId` - `String!`	ID of CPE associated with entity
`cveId` - `String!`	ID of CVE associated with entity
`dateAdded` - `String!`	Date entity was added to kev
`confidence` - `String!`	Confidence rating
`updatedTS` - `String!`	Timestamp when last updated

Example

{
  "findingCode": 123,
  "findingHash": 9039052908188215000,
  "ip": "abc123",
  "port": 123,
  "latestObservation": "abc123",
  "cpeId": "xyz789",
  "cveId": "abc123",
  "dateAdded": "xyz789",
  "confidence": "xyz789",
  "updatedTS": "abc123"
}

Types

CPECVE

Description

CPE and CVEs known to be associated with the specified finding

Fields

Field Name	Description
`findingHash` - `String!`	An ID of int64 type that is unique for a BV ID, variant, and finding code
`cpeId` - `String!`
`cves` - `[String!]`

Example

{
  "findingHash": 9039052908188215000,
  "cpeId": "abc123",
  "cves": ["xyz789"]
}

Types

CPECVEFilter

Fields

Input Field	Description
`cpeIds` - `[String!]`
`cves` - `[String!]`

Example

{
  "cpeIds": ["abc123"],
  "cves": ["abc123"]
}

Types

CPEFamily

Description

CPE families

Values

Enum Value	Description
`windows`
`ie`
`ios`
`mobile_safari`
`chrome_frame`
`edge`
`firefox`
`chrome`
`ubuntu`
`chrome_mobile`
`ie_mobile`
`firefox_ios`
`android`
`edge_mobile`
`safari`

Example

"windows"

Types

CPEType

Description

CPE types

Values

Enum Value	Description
`os_desktop`
`os_mobile`
`browser`

Example

"os_desktop"

Types

CVE

Description

CVE type is used to hold the metadata associated to a CVE ID

Fields

Field Name	Description
`cveId` - `String!`	The actual CVE ID; For example: CVE-2014-12345
`description` - `String`	Description of the CVE, as pulled down via ETL from Directus
`score` - `Float`	Score value, as pulled down via ETL from Directus
`nistUrl` - `String!`	The NIST URL for a given CVE ID; For example: https://nvd.nist.gov/vuln/detail/CVE-2024-21762

Example

{
  "cveId": "abc123",
  "description": "xyz789",
  "score": 123.45,
  "nistUrl": "abc123"
}

Types

CVEAsset

Fields

Field Name	Description
`ip` - `String`
`port` - `Int`
`cpe` - `String`

Example

{
  "ip": "abc123",
  "port": 123,
  "cpe": "xyz789"
}

Types

CVEAssetSort

Values

Enum Value	Description
`cpe`
`ip`
`port`

Example

"cpe"

Types

CVEAssetSortBy

Fields

Input Field	Description
`field` - `CVEAssetSort!`	Field by which to sort items. Default = `port`
`direction` - `SortDirection`	Direction in which to sort items (asc/desc). Note that when sorting desc nulls come first. Default = `asc`

Example

{"field": "cpe", "direction": "asc"}

Types

CVEAssetsExposedInfo

Description

Wraps a list of CVEAssets.

Note that CVECompany.cveAssetsExposedCount provides the totalCount you might expect here.

Fields

Field Name	Description
`cveAssets` - `[CVEAsset!]`
`pageLength` - `Int`	length of cveAssets

Example

{"cveAssets": [CVEAsset], "pageLength": 123}

Types

CVECatalogDetailGeneric

Description

Generic, non-client-specific information about CVEs known to BV

Fields

Field Name	Description
`cveId` - `String`	The CVE ID (see https://nvd.nist.gov/vuln)
`onKevList` - `Boolean`
`addedToKevTS` - `Time`	when sorting desc nulls come first. This field is null for everything not on the kev (Known Exploited Vulnerability) list
`cvePublishedTS` - `Time`
`cvssv3Score` - `Float`
`cvssv3Severity` - `RiskLevel`	A categorical description of how severe the cve is

Example

{
  "cveId": "abc123",
  "onKevList": false,
  "addedToKevTS": "0",
  "cvePublishedTS": "0",
  "cvssv3Score": 987.65,
  "cvssv3Severity": "low"
}

Types

CVECatalogDetailRollup

Description

Aggregate counts of how cves affect the client's portfolio

Fields

Field Name	Description
`clientUUID` - `UUID`
`cveId` - `String`	The CVE ID (see https://nvd.nist.gov/vuln)
`findingCodes` - `[Int64!]`	The finding codes rolled up in a result
`cpeCount` - `Int64`	Number of cpes detected for this cve in the client portfolio
`companyCount` - `Int64`	Number of companies detected for this cve in the client portfolio
`confidence` - `ConfidenceLevel`	Low, medium, high
`onKevList` - `Boolean`
`addedToKevTS` - `Time`	when sorting desc nulls come first. This field is null for everything not on the kev (Known Exploited Vulnerability) list
`cvePublishedTS` - `Time`
`cvssv3Score` - `Float`
`cvssv3Severity` - `RiskLevel`	A categorical description of how severe the cve is
`lastObservedTS` - `Time`	Latest observation for any company in this filtered set
`ipCount` - `Int64`	Number of ips affected by this cve for companies in the client portfolio
`portCount` - `Int64`	Number of ports affected by this cve for companies in the client portfolio
`observationCount` - `Int64`	Number of observations of this cve for comapanies in the client portfolio
`updatedTS` - `Time`

Example

{
  "clientUUID": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "cveId": "abc123",
  "findingCodes": [123],
  "cpeCount": 123,
  "companyCount": 123,
  "confidence": "low",
  "onKevList": false,
  "addedToKevTS": "0",
  "cvePublishedTS": "0",
  "cvssv3Score": 987.65,
  "cvssv3Severity": "low",
  "lastObservedTS": "0",
  "ipCount": 123,
  "portCount": 123,
  "observationCount": 123,
  "updatedTS": "0"
}

Types

CVECatalogGenericInfo

Fields

Field Name	Description
`cveCatalogDetails` - `[CVECatalogDetailGeneric!]`
`totalCount` - `Int64!`	Total number available with the current set of filters ignoring limits and offsets
`pageLength` - `Int!`	length of cveCatalogDetails

Example

{
  "cveCatalogDetails": [CVECatalogDetailGeneric],
  "totalCount": 123,
  "pageLength": 123
}

Types

CVECatalogGenericSortBy

Fields

Input Field	Description
`field` - `CVECatalogSort!`	Field by which to sort items. Default = `cveId`
`direction` - `SortDirection`	Direction in which to sort items (asc/desc). Note that when sorting desc nulls come first. Default = `asc`

Example

{"field": "cveId", "direction": "asc"}

Types

CVECatalogRollupFilter

Fields

Input Field	Description
`cves` - `[String!]`	The cves to return
`severities` - `[RiskLevel!]`	The severities of interest.
`confidence` - `[ConfidenceLevel!]`	Confidence levels
`onKevList` - `Boolean`	Select items on or not on kev list. Null to have no restriction

Example

{
  "cves": ["abc123"],
  "severities": ["low"],
  "confidence": ["low"],
  "onKevList": true
}

Types

CVECatalogRollupInfo

Description

Wrapper for a list of CVECatalogDetailRollups

Fields

Field Name	Description
`cveCatalogDetails` - `[CVECatalogDetailRollup!]`
`totalCount` - `Int64`	Total number available with the current set of filters ignoring limits and offsets
`pageLength` - `Int`	length of cveCatalogDetails

Example

{
  "cveCatalogDetails": [CVECatalogDetailRollup],
  "totalCount": 123,
  "pageLength": 987
}

Types

CVECatalogSort

Values

Enum Value	Description
`cveId`
`cpeCount`
`cvssv3Score`
`cvssv3Severity`
`cvePublishedTS`
`addedToKevTS`
`onKevList`
`confidence`
`lastObservedTS`
`ipCount`
`portCount`
`observationCount`
`companyCount`

Example

"cveId"

Types

CVECatalogSortBy

Fields

Input Field	Description
`field` - `CVECatalogSort!`	Field by which to sort items. Default = `cveId`
`direction` - `SortDirection`	Direction in which to sort items (asc/desc). Note that when sorting desc nulls come first. Default = `asc`

Example

{"field": "cveId", "direction": "asc"}

Types

CVECompany

Description

Company Information from the cveCompanyInfo query.

More limited (at least presently) than the companyInfo query data

Fields

Field Name	Description
`bvid` - `UUID!`	The BV ID, the unique identifier for the company
`primaryName` - `String`	Primary name of the company
`primaryDomain` - `String`	Primary domain associated with the company
`clientEntityData` - `[ClientEntityData!]`	clientEntityIds WITHOUT their associated info. A clientEntityId is an identifier allocated by the client for a company (entity). A clientEntityId can only be assigned to one company in all of the client's portfolios.
`attributes` - `[String!]`	Client-provided attributes or tags that can be associated with one or more companies, used for filtering or grouping companies
`clientEntityIds` - `[String!]`	clientEntityIds are case-insensitive identifiers allocated by the client for a company (entity). Typically you would use them to store your internal company identifiers (or a surrogate therefore) in our system. A clientEntityId can only be assigned to one company in all of the client's portfolios.
`industryDescription` - `String`	This will always be empty Use 'firmographicFields -> industryDescription'
`firmographicFields` - `FirmographicData`	These will always be blank
`portfolios` - `[Portfolio!]`
`cveId` - `String`
`cveAssetsExposedCount` - `Int`
`cveLastObservedTS` - `Time`
`cveFindingHash` - `Int64`
`cveFindingSummary` - `String`
`cveAssetsExposed` - `CVEAssetsExposedInfo`
Arguments `sortBy` - `[CVEAssetSortBy!]` `limit` - `Int` `offset` - `Int`

Example

{
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "primaryName": "abc123",
  "primaryDomain": "abc123",
  "clientEntityData": [ClientEntityData],
  "attributes": ["xyz789"],
  "clientEntityIds": ["xyz789"],
  "industryDescription": "abc123",
  "firmographicFields": FirmographicData,
  "portfolios": [Portfolio],
  "cveId": "abc123",
  "cveAssetsExposedCount": 987,
  "cveLastObservedTS": "0",
  "cveFindingHash": 123,
  "cveFindingSummary": "abc123",
  "cveAssetsExposed": CVEAssetsExposedInfo
}

Types

CVECompanyFilter

Fields

Input Field	Description
`cves` - `[String!]`	Cves for which to get data. Default = `null`
`bvids` - `[UUID!]`	The BV ID is the unique identifier for the company. Default = `null`
`portfolioUuids` - `[UUID!]`
`attributes` - `[String]`	Search on attributes is case-sensitive and exact. Supply an empty string as a value to match companies with no attributes. Default = `null`
`clientEntityIds` - `[String]`	A clientEntityId is an identifier allocated by the client for a company (entity). A clientEntityId is unique case-insensitively across all companies in the client's portfolios. This field is for exact, case-sensitive matches only. Default = `null`
`primaryNames` - `[String!]`	Filter by primary name of company with substring matching. Default = `null`
`sortBy` - `[CVECompanySortBy]`

Example

{
  "cves": ["xyz789"],
  "bvids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "portfolioUuids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "attributes": ["abc123"],
  "clientEntityIds": ["xyz789"],
  "primaryNames": ["abc123"],
  "sortBy": [CVECompanySortBy]
}

Types

CVECompanyInfo

Description

Wrapper for list of CVECompany objects

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`	Limit and offset echo back the parameters
`totalCount` - `Int64!`	Count of companies matching filter regardless of whether they fit within limit
`pageLength` - `Int!`	Count of companies returned
`companies` - `[CVECompany!]`	Companies in the client's portfolios

Example

{
  "offset": 987,
  "limit": 123,
  "totalCount": 123,
  "pageLength": 123,
  "companies": [CVECompany]
}

Types

CVECompanySortBy

Fields

Input Field	Description
`field` - `CVECompanySorts!`
`direction` - `SortDirection`

Example

{"field": "primaryName", "direction": "asc"}

Types

CVECompanySorts

Description

Fields available by which to sort companies; default: primaryName/asc

Values

Enum Value	Description
`primaryName`	Primary name of the company
`portfolioNames`
`attributes`
`cveAssetsExposedCount`
`cveLastObservedTS`
`cveFindingHash`
`cveFindingSummary`
`bvid`

Example

"primaryName"

Types

Case

Description

ServiceNOW case information associated with the specified finding

Fields

Field Name	Description
`caseNumber` - `String!`	Identifier for the case
`active` - `Boolean`	Whether the case is currently active
`firstEscalatedTS` - `String`	First escalated timestamp on the finding's case
`lastEscalatedTS` - `String`	Last escalated timestamp on the finding's case
`automatedFollowUpCount` - `Int`	Number of automated follow-ups on the finding's case
`daysSinceFirstEscalated` - `Int`	Number of days since the finding's case was first escalated
`firstResolvedTS` - `String`	First resolved timestamp on the finding's case
`durationTimeToResolve` - `ISODuration`	Time from escalated to resolved as ISO 8601 duration format
`emailsSent` - `Int`	Number of emails sent
`escalationStatus` - `FindingEscalationStatus`	Escalation status of this case
`thirdPartyAcknowledgedTS` - `String`	Third-party acknowledged timestamp on the finding's case, if thirdPartyAcknowledged is true
`thirdPartyAcknowledged` - `Boolean`	Whether third party has acknowledged communications

Example

{
  "caseNumber": "3PR0123456",
  "active": false,
  "firstEscalatedTS": "2022-11-30T21:15:13Z",
  "lastEscalatedTS": "2022-12-01T19:10:10Z",
  "automatedFollowUpCount": 123,
  "daysSinceFirstEscalated": 987,
  "firstResolvedTS": "2022-12-15T20:25:23Z",
  "durationTimeToResolve": "PT25H10M02S",
  "emailsSent": 123,
  "escalationStatus": "Pending",
  "thirdPartyAcknowledgedTS": "2022-11-30T21:15:13Z",
  "thirdPartyAcknowledged": false
}

Types

CaseHistoryFilter

Description

Filter used by the caseHistoryInfo query.

Fields

Input Field	Description
`portfolioUuids` - `[UUID!]`	Unique identifiers for portfolios. Default = `null`
`attributes` - `[String!]`	Attributes associated with this company. Default = `null`
`bvids` - `[String!]`	The unique identifier for an entity. Default = `null`
`findingCodes` - `[Int64!]`	A small description of the specific finding. Default = `null`
`caseNumbers` - `[String!]`	The identifying number of the case. Default = `null`
`escalationStatuses` - `[FindingEscalationStatus!]`	The current state of the case.
`escalatedOrResolvedStartDate` - `Time`	The earliest you want a case with an escalated or resolved time. If just the date is provided for both the start and end date (e.g. '2025-03-31' or '2025-03-31T00:00:00Z' (i.e. hours, minutes, seconds and time zone offset are all zero or have not been provided), then the start date will start at the beginning of the day in UTC. If time zones other than UTC are used, values will be converted to UTC and the time format, rather the full date format, will be used.
`escalatedOrResolvedEndDate` - `Time`	The latest you want a case with an escalated or resolved time. If just the date is provided for both the start and end date (e.g. '2025-03-31' or '2025-03-31T00:00:00Z' (i.e. hours, minutes, seconds and time zone offset are all zero or have not been provided), then the end date will end at the beginning of the day in UTC (e.g. '2025-03-31T23:59:59Z'). If time zones other than UTC are used, values will be converted to UTC and the time format, rather the full date format, will be used.
`isEscalated` - `Boolean`	If set to true then all returned objects have to have a escalation timestamp; if false, they do not.
`caseHistoryPeriod` - `[CaseHistoryPeriod!]`	Allows you to filter on a time period on a specific timestamp column.
`active` - `Boolean`	If true will only return active cases, else if false then will return only inactive cases.
`sortBy` - `[CaseHistorySortBy!]`	The field(s) you would like to sort on.

Example

{
  "portfolioUuids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "attributes": ["xyz789"],
  "bvids": ["abc123"],
  "findingCodes": [123],
  "caseNumbers": ["xyz789"],
  "escalationStatuses": ["Pending"],
  "escalatedOrResolvedStartDate": "2024-02-06T20:24:21Z",
  "escalatedOrResolvedEndDate": "2024-02-06T21:37:02Z",
  "isEscalated": false,
  "caseHistoryPeriod": [CaseHistoryPeriod],
  "active": false,
  "sortBy": [CaseHistorySortBy]
}

Types

CaseHistoryInfo

Description

Object returned by the caseHistoryInfo query.

Fields

Field Name	Description
`totalCount` - `Int64!`	Total amount of cases regardless of provided filters
`pageLength` - `Int!`	Total amount of cases returned in this query
`meanTimeToResolve` - `Float`	Mean resolution time for all cases returned in query with a resolution time in seconds.
`meanDurationActiveEscalated` - `Float`	The average amount of time active cases have been escalated in seconds.
`cases` - `[CaseWithCompany!]`	An array of the cases.

Example

{
  "totalCount": 123,
  "pageLength": 987,
  "meanTimeToResolve": 123.45,
  "meanDurationActiveEscalated": 987.65,
  "cases": [CaseWithCompany]
}

Types

CaseHistoryPeriod

Description

Used by caseHistoryPeriod in the CaseHistoryFilter filter

Fields

Input Field	Description
`field` - `CaseHistoryPeriods`	The timestamp column to filter on. Required.
`startDate` - `Time`	The start of the time period filter. If just the date is provided for both the start and end date (e.g. '2025-03-31' or '2025-03-31T00:00:00Z' (i.e. hours, minutes, seconds and time zone offset are all zero or have not been provided), then the end date will end at the beginning of the day in UTC (e.g. '2025-03-31T23:59:59Z'). If time zones other than UTC are used, values will be converted to UTC and the time format, rather the full date format, will be used.
`endDate` - `Time`	The end of the time period filter. If just the date is provided for both the start and end date (e.g. '2025-03-31' or '2025-03-31T00:00:00Z' (i.e. hours, minutes, seconds and time zone offset are all zero or have not been provided), then the end date will end at the beginning of the day in UTC (e.g. '2025-03-31T23:59:59Z'). If time zones other than UTC are used, values will be converted to UTC and the time format, rather the full date format, will be used.

Example

{
  "field": "firstEscalatedTS",
  "startDate": "2024-02-06T20:24:21Z",
  "endDate": "2024-02-06T21:37:02Z"
}

Types

CaseHistoryPeriods

Description

Allowed values for field in the CaseHistoryPeriod filter

Values

Enum Value	Description
`firstEscalatedTS`
`firstResolvedTS`

Example

"firstEscalatedTS"

Types

CaseHistorySortBy

Fields

Input Field	Description
`field` - `CaseHistorySorts!`
`direction` - `SortDirection`

Example

{"field": "caseNumber", "direction": "asc"}

Types

CaseHistorySorts

Values

Enum Value	Description
`caseNumber`
`findingSummary`
`primaryName`
`portfolioName`
`attribute`
`firstEscalatedTS`
`firstResolvedTS`
`durationTimeToResolve`
`durationActiveEscalated`
`escalationStatus`
`active`

Example

"caseNumber"

Types

CaseStatistics

Description

All case statistics that can be returned by a caseStatistics query

Fields

Field Name	Description
`cases` - `Int`	Specify resolved{Start,End}Date in the caseStatistics query to get the number of cases resolved in the period.
`findings` - `Int`	Specify resolved{Start,End}Date in the caseStatistics query to get the number of distinct findings resolved in the period.
`companies` - `Int`	Specify resolved{Start,End}Date in the caseStatistics query to get the number of distinct companies with a resolved case in the period.
`meanDaysToResolve` - `Float`	Specify resolved{Start,End}Date in the caseStatistics query to get the mean days to resolve for all cases that resolved in the period. Specify no dates to get the mean days to resolve for all resolved cases
`escalatedFindingTypes` - `[EscalatedFindingCount!]`	Specify resolved{Start,End}Date in the caseStatistics query to get the finding types escalated in the period. Specify no dates in the caseStatistics query to get current results It would be cool if we didn't group by keys not requested, but we don't. Users may need to group the output here further if less granularity is needed.
`companyCasesCounts` - `[CompanyStatistic!]`	The cases count, broken down by company
Arguments `limit` - `Int` `direction` - `SortDirection`

Example

{
  "cases": 123,
  "findings": 987,
  "companies": 987,
  "meanDaysToResolve": 987.65,
  "escalatedFindingTypes": [EscalatedFindingCount],
  "companyCasesCounts": [CompanyStatistic]
}

Types

CaseWithCompany

Fields

Field Name	Description
`caseNumber` - `String!`	The identifying case number of this case.
`findingCode` - `Int64`	Finding code is an integer that represents the specific type of a finding. Finding code 0 indicates the overall company score. See the dictionary query and the DataDictionary type.
`findingHash` - `String`	An ID of int64 type that is unique for a BV ID, variant, and finding code
`findingSummary` - `String`	A small description of the finding related to the case.
`primaryName` - `String`	The company name.
`bvid` - `UUID`	The unique BlueVoyant identifier (BV ID) of the company. A standard field.
`portfolioNames` - `[String!]`	A list of names of portfolios this case is in.
`attributes` - `[String!]`	A list of attributes associated with the company.
`firstEscalatedTS` - `Time`	When this case was first escalated if it was escalated.
`firstResolvedTS` - `Time`	When this case was resolved if it was resolved.
`durationTimeToResolveSeconds` - `Int`	The duration of time in seconds it took to resolve this case.
`durationActiveEscalated` - `Int`	The amount of time in seconds since the case has been escalated only if the case is both active and escalated.
`escalationStatus` - `FindingEscalationStatus`	The current escalated status for this case. All possible values: Pending, Overdue, In Dispute, Escalation, Resolved, Unset, Resolved Not Escalated, Risk Accepted, Waiting for Third Party Response, In Review, Escalated to Client
`active` - `Boolean!`	The overall status of the case regardless of escalation status. Can be either open or closed.

Example

{
  "caseNumber": "abc123",
  "findingCode": 10001,
  "findingHash": "abc123",
  "findingSummary": "xyz789",
  "primaryName": "xyz789",
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "portfolioNames": ["xyz789"],
  "attributes": ["xyz789"],
  "firstEscalatedTS": "0",
  "firstResolvedTS": "0",
  "durationTimeToResolveSeconds": 123,
  "durationActiveEscalated": 123,
  "escalationStatus": "Pending",
  "active": true
}

Types

CasesInPeriodStatistics

Description

Results of the casesInPeriodStatistics query

Fields

Field Name	Description
`companiesResolvedInPeriod` - `Int`	Number of companies that closed out at least one escalation in the period
`companiesWithCreatedEscalationInPeriod` - `Int`	Number of companies that escalated at least one case in the period
`companiesWithEscalationAtStartOfPeriod` - `Int`	Number of companies with at least one escalation before the start of the period that is either not resolved or that resolved after the start
`casesResolvedInPeriod` - `Int`	Number of escalated cases that closed out in the period
`casesWithCreatedEscalationInPeriod` - `Int`	Number of cases that were first escalated in the period
`casesWithEscalationAtStartOfPeriod` - `Int`	Number of cases escalated before the start of the period that are either not resolved or that resolved after the start
`emergingVulnerabilityCases` - `Int`	Number of emerging vulnerability cases created in the period, in which a notification was sent regarding the associated company, either through its own case or via a bulk notification to the client. This does not currently include the number of companies for which only identification and bulk notification of EVs was done, but no cases were created. See emergingVulnerabilitySummaryInfo.
`emergingVulnerabilityCompanies` - `Int`	Number of companies with at least one vulnerability case created in the period, in which a notification was sent regarding the company, either through its own case or via a bulk notification to the client. This does not currently include the number of companies for which only identification of EVs and bulk notification was done, but no cases were created. See emergingVulnerabilitySummaryInfo.
`caseResolutionPercentages` - `[ResolutionPercentage!]`	Percentages of cases resolved by thresholdDays. The buckets are cumulative. Data are for all time and thus the query ignores the dates supplied.
`controlResolutionPercentages` - `[ResolutionPercentage!]`	Percentages of findings resolved by thresholdDays. The buckets are cumulative. Data are for a control group of companies NOT under management. Data are for all time and thus the query ignores the dates (and other filters) supplied. Accordingly, these data will be the same for all clients.
`companiesFullyResolvedInPeriod` - `Int`	Number of companies in period that closed out all of their escalations that existed at the start of the period
`companiesGoneBadInPeriod` - `Int`	Number of companies that started the period with ZERO escalations that subsequently had more than 0 escalations in the period, regardless of whether they had any escalations at the end of the period

Example

{
  "companiesResolvedInPeriod": 987,
  "companiesWithCreatedEscalationInPeriod": 123,
  "companiesWithEscalationAtStartOfPeriod": 123,
  "casesResolvedInPeriod": 123,
  "casesWithCreatedEscalationInPeriod": 987,
  "casesWithEscalationAtStartOfPeriod": 987,
  "emergingVulnerabilityCases": 987,
  "emergingVulnerabilityCompanies": 123,
  "caseResolutionPercentages": [ResolutionPercentage],
  "controlResolutionPercentages": [ResolutionPercentage],
  "companiesFullyResolvedInPeriod": 123,
  "companiesGoneBadInPeriod": 123
}

Types

CategoryScore

Description

Score details for category scores (those that have finding codes that are multiples of 10000), used in CategoryScores

Fields

Field Name	Description
`scoreDate` - `String!`	Score is calculated based on data collected through the end of this date. Accordingly this will usually be yesterday's date, in YYYY-MM-DD format
`findingCode` - `Int!`	Finding code is an integer that represents the specific type of a finding. See the dictionary query and the DataDictionary type.
`findingCount` - `Int`	This is the count of all findings for the category. No findings indicate the category cannot be scored.
`score` - `Float`	Score can be from 0 to 100, or null if not scored
`riskLevel` - `RiskLevel`	A bucketing of the risk level
`scoreImpact` - `Float`	The impact of a finding on the overall company risk score
`scorePercentile` - `Float`	This has never actually been a peer percentile, but a percentile of all scores
`findingStatus` - `FindingStatus`	Will be closed if no findings and category cannot be scored; see findingCount
`numberOfDetails` - `Int`
`numberDomainsAffected` - `Int`
`numberIpsAffected` - `Int`

Example

{
  "scoreDate": "2024-01-01",
  "findingCode": 123,
  "findingCount": 123,
  "score": 987.65,
  "riskLevel": "low",
  "scoreImpact": 123.45,
  "scorePercentile": 987.65,
  "findingStatus": "open",
  "numberOfDetails": 123,
  "numberDomainsAffected": 987,
  "numberIpsAffected": 987
}

Types

CategoryScores

Description

The score for each risk category used in Company categoryScores

Fields

Field Name	Description
`adversarialThreats` - `CategoryScore`	Finding code: 40000
`emailSecurity` - `CategoryScore`	Finding code: 10000
`itHygiene` - `CategoryScore`	Finding code: 20000
`maliciousActivity` - `CategoryScore`	Finding code: 50000
`vulnerability` - `CategoryScore`	Finding code: 30000

Example

{
  "adversarialThreats": CategoryScore,
  "emailSecurity": CategoryScore,
  "itHygiene": CategoryScore,
  "maliciousActivity": CategoryScore,
  "vulnerability": CategoryScore
}

Types

CategorySummarizedCountFilter

Fields

Input Field	Description
`portfolios` - `[String!]`	The portfolios to filter on.

Example

{"portfolios": ["abc123"]}

Types

CategorySummarizedCountInfo

Fields

Field Name	Description
`totalCount` - `Int!`	Total amount of items that match the user's request regardless of how many were returned.
`pageLength` - `Int!`	The number of items returned to the user.
`items` - `[CategorySummarizedCounts]`	The list of objects returned from the user's request.

Example

{
  "totalCount": 987,
  "pageLength": 123,
  "items": [CategorySummarizedCounts]
}

Types

CategorySummarizedCountSort

Values

Enum Value	Description
`portfolioName`

Example

"portfolioName"

Types

CategorySummarizedCountSortBy

Fields

Input Field	Description
`field` - `CategorySummarizedCountSort!`	Field by which to sort vendors. Default = `portfolioName`
`direction` - `SummarizedSortDirection`	Direction in which to sort users (asc/desc). Default = `asc`

Example

{"field": "portfolioName", "direction": "asc"}

Types

CategorySummarizedCounts

Fields

Field Name	Description
`totalCount` - `Int!`	The total amount of categories associated with this portfolio/client combination.
`portfolio` - `String!`	The portfolio of this vendor dependency.
`categories` - `[String!]`	The list of categories associated with this portfolio/client combination.

Example

{
  "totalCount": 123,
  "portfolio": "xyz789",
  "categories": ["abc123"]
}

Types

ClientConfiguration

Description

Client configuration including the license information, and service setup with quotas and usage.

Fields

Field Name	Description
`clientName` - `String!`	The client's name
`clientUuid` - `UUID!`	The client's UUID
`bvid` - `UUID`	The company ID (BV ID) that corresponds to this client company ("My Company" in the portal)
`enableMrs` - `Boolean!`	True if MRS integration has been enabled
`useClientEntityIds` - `Boolean!`	True if client-provided entity IDs are available in the portal
`clientEntityIdLabel` - `String!`	The client's label for entity IDs in the portal, e.g. "SPAR ID"
`useEntityAttributes` - `Boolean!`	True if client-provided entity attributes are available in the portal
`entityAttributeLabel` - `String!`	The client's label for entity attributes in the portal, e.g. "Tag"
`enforceEntityQuota` - `Boolean!`	Indicates whether the maximum number of allowed entities across all external_regular portfolios (entityQuota) is being enforced See enforceCompanyQuota in serviceSetups. external_regular portfolios are now represented by one or more services/licenses.
`entityQuota` - `Int!`	The maximum number of allowed entities across all external_regular portfolios (not including the "My Company" entity, if present) See companyQuota in serviceSetups. external_regular portfolios are now represented by one or more services/licenses.
`entityCount` - `Int!`	The current number of entities in all external_regular portfolios subject to the quota (entityQuota), not including the "My Company" entity, if present See companyCount in serviceSetups. external_regular portfolios are now represented by one or more services/licenses.
`enforceEntityChurn` - `Boolean!`	Indicates whether the maximum churn rate for entities ((1 + entityChurnPercent/100) * entityQuota) across all external_regular portfolios is being enforced See enforceCompanyChurn in serviceSetups. external_regular portfolios are now represented by one or more services/licenses.
`entityChurnPercent` - `Float!`	The churn rate for entities across all external_regular portfolios as a percentage, e.g. if entityChurnPercent is 5, entityChurnCount cannot exceed (1 + entityChurnPercent/100) * entityQuota during the last entityChurnDays if enforceEntityChurn is true, so if entityQuota is 100 and entityChurnDays is 90, up to 105 different entities (companies) can be swapped in and out of external_regular portfolios during any 90-day period. See companyChurnPercent in serviceSetups. external_regular portfolios are now represented by one or more services/licenses.
`entityChurnDays` - `Int!`	The period in days over which the churn rate for entities across all external_regular portfolios (entityChurnPercent) applies See companyChurnDays in serviceSetups. external_regular portfolios are now represented by one or more services/licenses.
`entityChurnCount` - `Int!`	The current number of distinct entities that were in all external_regular portfolios at any time during the latest churn period (not including the "My Company" entity or any entities that remained in portfolios for less than 24 hours) See companyChurnCount in serviceSetups. external_regular portfolios are now represented by one or more services/licenses.
`enforceMaxEntityAdditions` - `Boolean!`	Indicates whether the maximum number of additions of entities (maxEntityAdditions) during the additions period (entityAdditionsDays) across all external_regular portfolios is being enforced See enforceMaxCompanyAdditions in serviceSetups. external_regular portfolios are now represented by one or more services/licenses.
`maxEntityAdditions` - `Int!`	The maximum number of distinct entities that can be added to all external_regular portfolios during the additions period (entityAdditionsDays) See maxCompanyAdditions in serviceSetups. external_regular portfolios are now represented by one or more services/licenses.
`entityAdditionsDays` - `Int!`	The period in days over which the maximum number of distinct entities added for all external_regular portfolios (maxEntityAdditions) applies See companyAdditionsDays in serviceSetups. external_regular portfolios are now represented by one or more services/licenses.
`entityAdditionsCount` - `Int!`	The current number of distinct entities added to all external_regular portfolios at any time during the latest additions period (not including the "My Company" entity or any entities that remained in portfolios for less than 24 hours) See companyAdditionsCount in serviceSetups. external_regular portfolios are now represented by one or more services/licenses.
`enforceHvmEntityQuota` - `Boolean!`	Indicates whether the maximum number of allowed entities across all HVM portfolios (hvmEntityQuota) is being enforced Use enforceCompanyQuota in serviceSetups for the 'High_Volume_Monitoring' service.
`hvmEntityQuota` - `Int!`	The maximum number of allowed entities across all HVM portfolios (not including the "My Company" entity, if present) Use companyQuota in serviceSetups for the 'High_Volume_Monitoring' service.
`hvmEntityCount` - `Int!`	The current number of entities in all HVM portfolios subject to the quota (hvmEntityQuota), not including the "My Company" entity, if present Use companyCount in serviceSetups for the 'High_Volume_Monitoring' service.
`enforceHvmEntityChurn` - `Boolean!`	Indicates whether the maximum churn rate for entities ((1 + hvmEntityChurnPercent/100) * hvmEntityQuota) across all HVM portfolios is being enforced Use enforceCompanyChurn in serviceSetups for the 'High_Volume_Monitoring' service.
`hvmEntityChurnPercent` - `Float!`	The churn rate for entities across all HVM portfolios as a percentage, e.g. if hvmEntityChurnPercent is 5, hvmEntityChurnCount cannot exceed (1 + hvmEntityChurnPercent/100) * hvmEntityQuota during the last hvmEntityChurnDays if enforceHvmEntityChurn is true, so if hvmEntityQuota is 100 and hvmEntityChurnDays is 90, up to 105 different entities (companies) can be swapped in and out of HVM portfolios during any 90-day period. Use companyChurnPercent in serviceSetups for the 'High_Volume_Monitoring' service.
`hvmEntityChurnDays` - `Int!`	The period in days over which the churn rate for entities across all HVM portfolios (hvmEntityChurnPercent) applies Use companyChurnDays in serviceSetups for the 'High_Volume_Monitoring' service.
`hvmEntityChurnCount` - `Int!`	The current number of distinct entities that were in all HVM portfolios at any time during the latest churn period (not including the "My Company" entity or any entities that remained in portfolios for less than 24 hours) Use companyChurnCount in serviceSetups for the 'High_Volume_Monitoring' service.
`enforceMaxHvmEntityAdditions` - `Boolean!`	Indicates whether the maximum number of additions of entities (maxHvmEntityAdditions) during the additions period (hvmEntityAdditionsDays) across all HVM portfolios is being enforced Use enforceMaxCompanyAdditions in serviceSetups for the 'High_Volume_Monitoring' service.
`maxHvmEntityAdditions` - `Int!`	The maximum number of distinct entities that can be added to all HVM portfolios during the additions period (hvmEntityAdditionsDays) Use maxCompanyAdditions in serviceSetups for the 'High_Volume_Monitoring' service.
`hvmEntityAdditionsDays` - `Int!`	The period in days over which the maximum number of distinct entities added for all HVM portfolios (maxHvmEntityAdditions) applies Use companyAdditionsDays in serviceSetups for the 'High_Volume_Monitoring' service.
`hvmEntityAdditionsCount` - `Int!`	The current number of distinct entities added to all HVM portfolios at any time during the latest additions period (not including the "My Company" entity or any entities that remained in portfolios for less than 24 hours) Use companyAdditionsCount in serviceSetups for the 'High_Volume_Monitoring' service.
`licenseQuantity` - `[LicenseQuantity]!`	Information on the number of licenses of each type a client has. It is filtered by whether the licenses are active/inactive.
`serviceSetups` - `[ServiceSetup]!`	Information on the services, associated quotas, and current usage a client has. Companies that remained in a service for less than 24 hours are not counted against quotas, churn rate or maximum additions limits.

Example

{
  "clientName": "abc123",
  "clientUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "enableMrs": true,
  "useClientEntityIds": false,
  "clientEntityIdLabel": "abc123",
  "useEntityAttributes": true,
  "entityAttributeLabel": "abc123",
  "enforceEntityQuota": false,
  "entityQuota": 987,
  "entityCount": 987,
  "enforceEntityChurn": true,
  "entityChurnPercent": 123.45,
  "entityChurnDays": 123,
  "entityChurnCount": 987,
  "enforceMaxEntityAdditions": false,
  "maxEntityAdditions": 987,
  "entityAdditionsDays": 123,
  "entityAdditionsCount": 123,
  "enforceHvmEntityQuota": true,
  "hvmEntityQuota": 987,
  "hvmEntityCount": 123,
  "enforceHvmEntityChurn": true,
  "hvmEntityChurnPercent": 987.65,
  "hvmEntityChurnDays": 987,
  "hvmEntityChurnCount": 123,
  "enforceMaxHvmEntityAdditions": false,
  "maxHvmEntityAdditions": 123,
  "hvmEntityAdditionsDays": 987,
  "hvmEntityAdditionsCount": 987,
  "licenseQuantity": [LicenseQuantity],
  "serviceSetups": [ServiceSetup]
}

Types

ClientContact

Description

Client contacts are contacts AT the client. They may get escalations for multiple companies/vendors.

Fields

Field Name	Description
`id` - `Int!`
`contactName` - `String!`	Full name of contact
`email` - `String!`	Contact's email address
`businessPhoneNumber` - `String!`	Contact's phone number
`jobTitle` - `String!`	Contact's job title
`createdTS` - `String!`	Timestamp when created
`updatedTS` - `String!`	Timestamp when last updated
`createdBy` - `String!`	Username that created this item
`updatedBy` - `String!`	Username that last updated this item
`companyRelationshipInfo` - `ClientContactCompanyRelationshipInfo`	Companies for which the contact is responsible for receiving escalations
Arguments `offset` - `Int!` `limit` - `Int`

Example

{
  "id": 987,
  "contactName": "xyz789",
  "email": "abc123",
  "businessPhoneNumber": "xyz789",
  "jobTitle": "xyz789",
  "createdTS": "xyz789",
  "updatedTS": "abc123",
  "createdBy": "xyz789",
  "updatedBy": "xyz789",
  "companyRelationshipInfo": ClientContactCompanyRelationshipInfo
}

Types

ClientContactBulkUpdate

Description

Result of the clientContactBulkCompanyUpdate mutation.

Fields

Field Name	Description
`clientContact` - `ClientContact!`	Client contact for which company relationships have been added or deleted
`statuses` - `[CompanyBulkUpdateStatus]`	Holds status/message response for client contact bulk company relationship updates

Example

{
  "clientContact": ClientContact,
  "statuses": [CompanyBulkUpdateStatus]
}

Types

ClientContactCompanyRelationship

Description

Company for which the client contact is responsible for receiving escalations

Fields

Field Name	Description
`id` - `Int!`	ID of the relationship between client and company
`bvid` - `UUID!`	BV ID of the company for which contact receives escalations
`primaryName` - `String!`	Primary name of the company for which contact received escalations
`escalationPreference` - `AddressType!`	Recipient field for contact's email address: 'to' or 'cc' (primary/notification)
`createdTS` - `String!`	Timestamp when relationship between contact and company was created
`updatedTS` - `String!`	Timestamp when relationship between contact and company was last updated
`createdBy` - `String!`	Username that created the relationship between contact and company
`updatedBy` - `String!`	Username that last updated the relationship between contact and company

Example

{
  "id": 987,
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "primaryName": "xyz789",
  "escalationPreference": "to",
  "createdTS": "abc123",
  "updatedTS": "xyz789",
  "createdBy": "abc123",
  "updatedBy": "xyz789"
}

Types

ClientContactCompanyRelationshipInfo

Description

This is the holder for client contact company relationships, with pagination and counts

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`	Limit and offset echo back the parameters
`totalCount` - `Int!`	Count of company relationships matching filter regardless of whether they fit within limit
`pageLength` - `Int!`	Count of company relationships returned
`companyRelationships` - `[ClientContactCompanyRelationship!]`	Companies for which the contact is responsible for receiving escalations

Example

{
  "offset": 123,
  "limit": 987,
  "totalCount": 987,
  "pageLength": 987,
  "companyRelationships": [
    ClientContactCompanyRelationship
  ]
}

Types

ClientContactCompanyRelationshipToAdd

Description

Input for a company for which the client contact is responsible for receiving escalations

Fields

Input Field	Description
`bvid` - `UUID!`	BV ID of the company for which contact receives escalations
`escalationPreference` - `AddressType!`	Recipient field for contact's email address: 'to' or 'cc' (primary/notification)

Example

{
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "escalationPreference": "to"
}

Types

ClientContactCompanyRelationshipToDelete

Description

Input for a company for which the client contact is no longer responsible for receiving escalations. Supply either the id or the bvid field but not both.

Fields

Input Field	Description
`id` - `Int`	ID of the relationship between client and company
`bvid` - `UUID`	BV ID of the company for which contact receives escalations

Example

{
  "id": 123,
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
}

Types

ClientContactCompanyRelationshipToUpdate

Description

Input for a company for which the client contact is responsible for receiving escalations. Supply either the id or the bvid but not both.

Fields

Input Field	Description
`id` - `Int`	ID of the relationship between client and company
`bvid` - `UUID`	BV ID of the company for which contact receives escalations
`escalationPreference` - `AddressType!`	Recipient field for contact's email address: 'to' or 'cc' (primary/notification)

Example

{
  "id": 123,
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "escalationPreference": "to"
}

Types

ClientContactInfo

Description

This is the holder for client contacts, with pagination and counts

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`	Limit and offset echo back the parameters
`totalCount` - `Int!`	Count of client contacts matching filter regardless of whether they fit within limit
`pageLength` - `Int!`	Count of client contacts returned
`clientContacts` - `[ClientContact!]`	Client contacts - contacts AT a client

Example

{
  "offset": 987,
  "limit": 987,
  "totalCount": 123,
  "pageLength": 987,
  "clientContacts": [ClientContact]
}

Types

ClientContactLookup

Description

Used to look up client contact either by ID or by email, or to create it on the fly (if createNewClientContact in clientContactBulkCompanyUpdate is true)

Fields

Input Field	Description
`id` - `Int`	ID of contact to be looked up. Either id or email is required but both are an error
`email` - `String`	Email address of contact to be looked up. Either id or email is required but both are an error
`name` - `String`	Full name of contact (required if adding a contact)
`jobTitle` - `String`	Contact's job title (if adding a contact)
`businessPhoneNumber` - `String`	Contact's phone number (if adding a contact)

Example

{
  "id": 123,
  "email": "xyz789",
  "name": "abc123",
  "jobTitle": "xyz789",
  "businessPhoneNumber": "abc123"
}

Types

ClientContactToAdd

Description

Input to create a new client contact - a contact AT the client

Fields

Input Field	Description
`contactName` - `String!`	Full name of contact
`email` - `String!`	Contact email - unique at the client
`businessPhoneNumber` - `String`	Contact's phone number
`jobTitle` - `String`	Contact's job title
`companyRelationships` - `[ClientContactCompanyRelationshipToAdd!]!`	Companies for which contact is responsible for receiving escalations

Example

{
  "contactName": "abc123",
  "email": "abc123",
  "businessPhoneNumber": "abc123",
  "jobTitle": "xyz789",
  "companyRelationships": [
    ClientContactCompanyRelationshipToAdd
  ]
}

Types

ClientContactToCompany

Description

Client contacts are contacts AT the client. They may get escalations for multiple companies/vendors. This is the flattened view of client contact-to-company from the companyInfo query.

Fields

Field Name	Description
`id` - `Int!`	ID of the contact
`contactName` - `String!`	Full name of contact
`email` - `String!`	Contact email - unique at the client
`businessPhoneNumber` - `String!`	Contact's phone number
`jobTitle` - `String!`	Contact's job title
`createdTS` - `String!`	Timestamp when contact was created
`updatedTS` - `String!`	Timestamp when contact was last updated
`createdBy` - `String!`	Username that created this contact
`updatedBy` - `String!`	Username that last updated this contact
`companyRelationship` - `ClientContactCompanyRelationship!`	Company for which the contact is responsible for receiving escalations

Example

{
  "id": 987,
  "contactName": "xyz789",
  "email": "xyz789",
  "businessPhoneNumber": "abc123",
  "jobTitle": "xyz789",
  "createdTS": "abc123",
  "updatedTS": "abc123",
  "createdBy": "xyz789",
  "updatedBy": "xyz789",
  "companyRelationship": ClientContactCompanyRelationship
}

Types

ClientContactToUpdate

Description

Input to update a client contact - a contact AT the client

Fields

Input Field	Description
`id` - `Int!`	ID of the contact
`companyRelationshipsToAdd` - `[ClientContactCompanyRelationshipToAdd!]`	Use to add companies for which contact is responsible for receiving escalations
`companyRelationshipsToUpdate` - `[ClientContactCompanyRelationshipToUpdate!]`	Use to update the escalation preference for companies for which contact is responsible for receiving escalations
`companyRelationshipsToDelete` - `[ClientContactCompanyRelationshipToDelete!]`	Use to delete companies for which contact is no longer responsible for receiving escalations
`deleteAllCompanyRelationshipsFlag` - `Boolean`	If true, delete all the contact's company relationships. Cannot be used with the companyRelationships* fields.
`ignoreHarmlessErrors` - `Boolean`	If true, ignore errors when trying to add company relationships that already exist, or trying to delete company relationships that don't exist. Existing relationships will have their escalation preferences updated.

Example

{
  "id": 123,
  "companyRelationshipsToAdd": [
    ClientContactCompanyRelationshipToAdd
  ],
  "companyRelationshipsToUpdate": [
    ClientContactCompanyRelationshipToUpdate
  ],
  "companyRelationshipsToDelete": [
    ClientContactCompanyRelationshipToDelete
  ],
  "deleteAllCompanyRelationshipsFlag": false,
  "ignoreHarmlessErrors": false
}

Types

ClientEntityData

Description

Full data related to client-provided ID, and optional name and domain, associated with a company.

Part of the CompanyBROnly, CompanyHVM, and Company types and returned by the clientEntityDataUpdate mutation.

Fields

Field Name	Description
`id` - `Int64!`	System ID associated with clientEntityId
`clientEntityId` - `String!`	Case-insensitive client-provided identifier for a company that is unique across all the client's companies
`clientEntityName` - `String!`	Optional client-provided company name associated with clientEntityId
`clientEntityDomain` - `String!`	Optional client-provided company domain associated with clientEntityId
`createdBy` - `String!`	Username that created this item
`createdTS` - `Time!`	Timestamp when created
`updatedBy` - `String!`	Username that last updated this item
`updatedTS` - `Time!`	Timestamp when last updated

Example

{
  "id": 123,
  "clientEntityId": "xyz789",
  "clientEntityName": "abc123",
  "clientEntityDomain": "xyz789",
  "createdBy": "abc123",
  "createdTS": "0",
  "updatedBy": "abc123",
  "updatedTS": "0"
}

Types

ClientEntityDataInput

Description

Client-provided ID, and optional name and domain, associated with a company.

Part of the CompanyRequestToAdd type used by the companyRequestCreate mutation, and used by the portfolioCompanyAdd mutation.

Fields

Input Field	Description
`clientEntityId` - `String!`	Case-insensitive client-provided identifier for a company that is unique across all the client's companies
`clientEntityName` - `String`	Optional client-provided company name associated with clientEntityId
`clientEntityDomain` - `String`	Optional client-provided company domain associated with clientEntityId

Example

{
  "clientEntityId": "abc123",
  "clientEntityName": "xyz789",
  "clientEntityDomain": "abc123"
}

Types

ClientEntityDataRequest

Description

Requested client-provided ID, and optional name and domain, associated with a company

Part of the CompanyRequest type, which is returned by the companyRequestCreate and companyRequestCancel mutations and is part of the CompanyRequestInfo type returned from the companyRequestInfo query.

Fields

Field Name	Description
`clientEntityId` - `String!`	Case-insensitive client-provided identifier for a company that is unique across all the client's companies
`clientEntityName` - `String!`	Optional client-provided company name associated with clientEntityId
`clientEntityDomain` - `String!`	Optional client-provided company domain associated with clientEntityId

Example

{
  "clientEntityId": "abc123",
  "clientEntityName": "xyz789",
  "clientEntityDomain": "xyz789"
}

Types

ClientEntityDataToAdd

Description

Client-provided ID, and optional name and domain, associated with a company.

Part of the ClientEntityDataUpdate type, which is the input to the clientEntityDataUpdate mutation.

Fields

Input Field	Description
`clientEntityId` - `String!`	Case-insensitive client-provided identifier for a company that is unique across all the client's companies
`clientEntityName` - `String`	Optional client-provided company name associated with clientEntityId
`clientEntityDomain` - `String`	Optional client-provided company domain associated with clientEntityId

Example

{
  "clientEntityId": "xyz789",
  "clientEntityName": "xyz789",
  "clientEntityDomain": "abc123"
}

Types

ClientEntityDataToDelete

Description

Client-provided ID, and optional name and domain, associated with a company, used as input. Either id or clientEntityIdToLookup must be provided to identify the item to delete.

Part of the ClientEntityDataUpdate type, which is the input to the clientEntityDataUpdate mutation.

Fields

Input Field	Description
`id` - `Int64`	System ID associated with clientEntityId that is to be deleted. Provide either id or clientEntityIdToLookup, but not both.
`clientEntityIdToLookup` - `String`	The client-provided identifier for a company that is to be deleted. Provide either id or clientEntityIdToLookup, but not both.

Example

{
  "id": 123,
  "clientEntityIdToLookup": "abc123"
}

Types

ClientEntityDataToUpdate

Description

Client-provided ID, and optional name and domain, associated with a company, used as input. Either id or clientEntityIdToLookup must be provided to identify the item to update.

Part of the ClientEntityDataUpdate type, which is the input to the clientEntityDataUpdate mutation.

Fields

Input Field	Description
`id` - `Int64`	System ID associated with clientEntityId that is to be changed. Provide either id or clientEntityIdToLookup, but not both.
`clientEntityIdToLookup` - `String`	The client-provided identifier for a company that is to be changed. Provide either id or clientEntityIdToLookup, but not both.
`clientEntityId` - `String`	New case-insensitive client-provided identifier for a company that is unique across all the client's companies
`clientEntityName` - `String`	Optional new client-provided company name associated with clientEntityId
`clientEntityDomain` - `String`	Optional new client-provided company domain associated with clientEntityId

Example

{
  "id": 123,
  "clientEntityIdToLookup": "xyz789",
  "clientEntityId": "abc123",
  "clientEntityName": "abc123",
  "clientEntityDomain": "abc123"
}

Types

ClientEntityDataUpdate

Description

Update some or all client entity IDs for a single company. The order of operations is delete, update, add. At least one of clientEntityDataToAdd, clientEntityDataToUpdate, and clientEntityDataToDelete is required.

This is the input to the clientEntityDataUpdate mutation.

Fields

Input Field	Description
`bvid` - `UUID!`	The unique BlueVoyant identifier (BV ID) of the company.
`clientEntityDataToAdd` - `[ClientEntityDataToAdd!]`	Client entity data items to add
`clientEntityDataToUpdate` - `[ClientEntityDataToUpdate!]`	Client entity data items to update
`clientEntityDataToDelete` - `[ClientEntityDataToDelete!]`	Client entity data items to delete

Example

{
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "clientEntityDataToAdd": [ClientEntityDataToAdd],
  "clientEntityDataToUpdate": [ClientEntityDataToUpdate],
  "clientEntityDataToDelete": [ClientEntityDataToDelete]
}

Types

ClientMini

Description

Partial client info for client associated with SCD portal/API user

Fields

Field Name	Description
`clientUuid` - `UUID!`	Client UUID
`clientName` - `String!`	Client name
`defaultFlag` - `Boolean!`	True if the client is the default client for the user

Example

{
  "clientUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "clientName": "abc123",
  "defaultFlag": true
}

Types

CloudProviderInfo

Description

Information about cloud provider for an IP

Fields

Field Name	Description
`country` - `String`
`notes` - `String`
`city` - `String`
`zone` - `String`
`cloudProvider` - `String`
`bvSource` - `String`
`cidr` - `String`
`cloudServiceName` - `String`
`state` - `String`
`region` - `String`

Example

{
  "country": "xyz789",
  "notes": "xyz789",
  "city": "xyz789",
  "zone": "abc123",
  "cloudProvider": "abc123",
  "bvSource": "xyz789",
  "cidr": "xyz789",
  "cloudServiceName": "abc123",
  "state": "xyz789",
  "region": "abc123"
}

Types

CloudStorageInsight

Fields

Field Name	Description
`provider` - `String!`
`domain` - `String!`
`qname` - `String!`
`cname` - `String!`
`bucketName` - `String!`
`isIndexable` - `Boolean!`
`fileCount` - `String`
`lastUpdated` - `String!`
`lastObservedTS` - `Time`
`Provider` - `String!`	Use 'provider'
`Domain` - `String!`	Use 'domain'
`Qname` - `String!`	Use 'qname'
`Cname` - `String!`	Use 'cname'
`BucketName` - `String!`	Use 'bucketName'
`IsIndexable` - `Boolean!`	Use 'isIndexable'
`FileCount` - `String`	Use 'fileCount'

Example

{
  "provider": "xyz789",
  "domain": "xyz789",
  "qname": "abc123",
  "cname": "xyz789",
  "bucketName": "xyz789",
  "isIndexable": false,
  "fileCount": "abc123",
  "lastUpdated": "xyz789",
  "lastObservedTS": "0",
  "Provider": "abc123",
  "Domain": "xyz789",
  "Qname": "xyz789",
  "Cname": "abc123",
  "BucketName": "xyz789",
  "IsIndexable": false,
  "FileCount": "abc123"
}

Types

CloudStorageInsightByCompanyInfo

Fields

Field Name	Description
`totalCount` - `Int64!`	Total number of cloud storage insights.
`pageLength` - `Int!`	Amount of cloud storage insights return in this query.
`cloudStorageInsights` - `[CloudStorageInsight]`	List of cloud insights by company.

Example

{
  "totalCount": 123,
  "pageLength": 123,
  "cloudStorageInsights": [CloudStorageInsight]
}

Types

CloudStorageInsightInfo

Description

A collection of cloud storage insight info organized by finding code. Includes finding code's description, summary, and assessment date.

Fields

Field Name	Description
`summary` - `String`	A brief summary of the finding code
`description` - `String`	A description of what the finding code is.
`assessmentDateEnd` - `String`	The most recent assessment date
`findingCode` - `Int64`	The finding code of these vendor discoveries.
`cloudStorageInsights` - `[CloudStorageInsight]`	List of cloud insights of a specific finding code

Example

{
  "summary": "abc123",
  "description": "abc123",
  "assessmentDateEnd": "abc123",
  "findingCode": 123,
  "cloudStorageInsights": [CloudStorageInsight]
}

Types

Company

Description

Information about a company in the client's portfolios

Fields

Field Name	Description
`bvid` - `UUID!`	The BV ID, the unique identifier for the company
`primaryName` - `String`	Primary name of the company
`primaryDomain` - `String`	Primary domain associated with the company
`companyStatus` - `String`	Values are Remediation in Progress, Escalation in Progress, Under Review, Active
`portfolioNames` - `[String!]`	Use 'portfolios -> portfolioName'
`portfolioUuids` - `[UUID!]`	Use 'portfolios -> portfolioUuid'
`portfolios` - `[Portfolio!]`
`companyScore` - `Score`	Use 'riskScore'
`riskScore` - `Score`	The overall risk score for the company and associated information
`historicScores` - `[HistoricScore!]`	Array of historic scores per company. endDate defaults to most recent assessment end date; startDate defaults to 30 days before endDate. Dates are in 'YYYY-MM-DD' format.
Arguments `startDate` - `String` `endDate` - `String`
`categoryScores` - `CategoryScores`	Scores for this company in each risk category
`peerScores` - `[PeerScore!]`	Sets of scores associated with risk categories and the overall score for a company's industry peers. A peer is defined as an organization in the same industry, and one that has a similar digital footprint size range.
`attributes` - `[String!]`	Client-provided attributes or tags that can be associated with one or more companies, used for filtering or grouping companies
`clientEntityIds` - `[String!]`	clientEntityIds are case-insensitive identifiers allocated by the client for a company (entity). Typically you would use them to store your internal company identifiers (or a surrogate therefore) in our system. A clientEntityId can only be assigned to one company in all of the client's portfolios.
`clientEntityData` - `[ClientEntityData!]`	clientEntityIds and their associated info, which could include an optional name or domain. A clientEntityId is an identifier allocated by the client for a company (entity). A clientEntityId can only be assigned to one company in all of the client's portfolios.
`findingInfo` - `FindingInfo`	Pagination is not per company (that's annoying) but over the whole set of findings. i.e. without limitation of the companies to those with findings or pagination of the companies, you will likely have lots of companies without findings. See the companyInfo query for filtering
Arguments `offset` - `Int!` `limit` - `Int`
`numFindings` - `Int`
`findingsWaitingForResponse` - `Int`
`numberOfEscalatedFindings` - `Int`
`numberofActionableOpenEscalatedFindings` - `Int`
`numberOfActionableOpenFindings` - `Int`
`findingsInDispute` - `Int`
`findingsOverdue` - `Int`
`industryDescription` - `String`
`scorePercentile` - `Float`	This has never actually been a peer percentile, but a percentile of all scores
`exceedsRiskTolerance` - `Boolean`
`exceedsRiskToleranceFirstDate` - `String`
`escalationPath` - `EscalationPath`
`firstAddedTS` - `String`	Time when first added to an external portfolio of this client
`history` - `[History!]`	Now deprecated - use companyHistoryInfo. One subtlety to note is that if you use both companyHistoryInfo and this history property you will get the same data from both even if the parameters are different. Use 'companyHistoryInfo'
Arguments `daysOld` - `Int!`
`companyHistoryInfo` - `CompanyHistoryInfo`	Event history (changes to escalation status and whether risk tolerance is exceeded) for this company. Default look-back period is 30 days. The limits and offset are applied per company.
Arguments `offset` - `Int!` Skip offset event history items before returning up to limit. Applied per company `limit` - `Int` Skip offset event history items before returning up to limit. Applied per company `daysOld` - `Int!` Number of days of event history to be returned
`detectedSecurityDevices` - `[SecurityDevice!]`	Security devices detected for company
`detectedSecurityDevicesByFindingCode` - `[SecurityDeviceInfo!]`	Security devices by finding code
`fourthPartyExposure` - `[ExposureData!]`	Fourth-party exposure insights
`fourthPartyExposureByFindingCode` - `[FourthPartyExposureInsights!]`	Fourth party exposure organized by finding code
`fourthPartyBreachCount` - `Int`	Fourth party breach event count in the last year
`cloudStorage` - `CloudStorageInsightByCompanyInfo`	Cloud storage (e.g. S3, GCS) that is publicly visible. The limit and offset are per company.
Arguments `offset` - `Int!` `limit` - `Int`
`cloudStorageByFindingCode` - `[CloudStorageInsightInfo!]`	Cloud storage organized by finding code.
`cloudStorageBucketCount` - `Int`	Cloud storage distinct bucket name count
`productsByDomainDetection` - `[ProductByDomainDetection!]`	Products detected on domains
`productsByDomainDetectionByFindingCode` - `[ProductByDomainDetectionInfo!]`	Products detected on domains organized by finding codes
`emailSaasDomainsWithoutSecurityCount` - `Int`	Number of distinct domains detected without third-party email security products
`productsByIPDetection` - `[ProductByIPDetection!]`	Products detected on IPs
`productsByIPDetectionByFindingCode` - `[ProductByIPDetectionInsights]`	Products detected on IPs organized by finding code
`exposedLoginPortalCount` - `Int`	Number of distinct IPs detected with exposed login portals
`topTenAssets` - `[Asset]`	Top assets by numbers of findings and observations
`topTenAssetsByFindingCode` - `[TopTenInfo]`	Top assets by numbers of findings and observations
`vendorDiscovery` - `[VendorDiscovery!]`	Vendors known to be used by company (also called "Vendor Dependency")
`vendorDiscoveryByFindingCode` - `[VendorDiscoveryInsights!]`	Vendor discovery organized by finding code with the finding code's summary and description
`cpeCVE` - `[CPECVE!]`	CPEs and CVEs pertaining to this company. findingHash can be used to cross-reference with the findings (also available on findings)
`cisaKev` - `[CISAKEVCVE!]`	CVEs that include a KEV list flag and the confidence rating
`footprintSummary` - `FootprintSummary`	Summary information for this company's most recent footprint. Changes to footprints after the date of the end of the scoring assessment period (assessmentDateEnd) will not be reflected in findings, scores, or details until the next nightly scoring run, so it's expected that assets recently removed from a footprint could still appear in findings.
`domains` - `[DomainInfo!]`	Registration info for domains in this company's most recent footprint. Changes to footprints after the date of the end of the scoring assessment period (assessmentDateEnd) will not be reflected in findings, scores, or details until the next nightly scoring run, so it's expected that assets recently removed from a footprint could still appear in findings. Use domainInfo.
`domainInfo` - `DomainListInfo`	Registration info for domains in this company's most recent footprint. Changes to footprints after the date of the end of the scoring assessment period (assessmentDateEnd) will not be reflected in findings, scores, or details until the next nightly scoring run, so it's expected that assets recently removed from a footprint could still appear in findings.
Arguments `offset` - `Int!` Pagination - skip offset domains before returning up to limit of domains. Default = 0 `limit` - `Int` Pagination - skip offset domains before returning up to limit of domains. `sortBy` - `[DomainSortBy!]` Only one field can be used to sort at the moment
`totalHostnameCountryCount` - `Int`	Total number of countries with hostname resolutions (whose IPs resolve to a particular country) for this footprint (part of network characterization)
`totalHostnameCount` - `Int64`	Total number of hostname resolutions (whose IPs resolve to a particular country) for this footprint (part of network characterization)
`countryDomainCounts` - `[CountryDomainCount!]`	Countries associated with the footprint's domain resolutions from its hostnames to IP addresses in a country, and the number of domains and hostnames per country. This is part of network characterization, and will not be available initially on a new footprint.
`domainCountryInfo` - `DomainCountryInfo`	This list of domains is unique on the combination of domain and country of resolution, (so a particular domain can appear more than once, as opposed to the list in domainInfo). Domain records also include registration info. Not all domains resolve to a country, but they will appear here regardless.
Arguments `offset` - `Int!` Pagination - skip offset domain/country records before returning up to limit. Default = 0 `limit` - `Int` Pagination - skip offset domain/country records before returning up to limit. `filter` - `DomainCountryFilter` Filter domain/country records `sortBy` - `[DomainCountrySortBy!]` Only one field can be used to sort at the moment
`ips` - `[IPInfo!]`	Registration info for IP addresses or ranges in this company's most recent footprint. Changes to footprints after the date of the end of the scoring assessment period (assessmentDateEnd) will not be reflected in findings, scores, or details until the next nightly scoring run, so it's expected that assets recently removed from a footprint could still appear in findings. Use ipInfo.
`ipInfo` - `IPListInfo`	Registration info for IP addresses or ranges in this company's most recent footprint. Changes to footprints after the date of the end of the scoring assessment period (assessmentDateEnd) will not be reflected in findings, scores, or details until the next nightly scoring run, so it's expected that assets recently removed from a footprint could still appear in findings.
Arguments `offset` - `Int!` Pagination - skip offset IP address/range records before returning up to limit. Default = 0 `limit` - `Int` Pagination - skip offset IP address/range records before returning up to limit. `filter` - `IPFilter` Filter IP address/range records `sortBy` - `[IPSortBy!]` Only one field can be used to sort at the moment
`activeIpCount` - `Int64`	From network characterization, the number of unique IP addresses from the company's footprint with any port open
`observedResolutionCount` - `Int64`	From network characterization, the number of observed resolutions associated with the company's footprint. NOT AVAILABLE
`hostingProviderInfo` - `HostingProviderInfo`	From network characterization, the providers that the company relies on to make its domains and subdomains available to the internet.
Arguments `offset` - `Int!` The offset to start returning data on. Starts at 0. `limit` - `Int` The maximum number of providers to return. `sortBy` - `[HostingProviderSortBy!]`
`waitingForStates` - `[WaitingFor!]`	The waiting-for state for a company possible values include: BlueVoyant,Client,Third Party,Unset
`gdd` - `GDD`	GDD Data are no longer available. This will only return an error. GDD Data are no longer available as of 2024-02-01.
Arguments `startDate` - `String` `endDate` - `String` `cpeType` - `CPEType` `isUnsupported` - `Boolean` `offset` - `Int!` `limit` - `Int`
`emergingVulnerabilityInfo` - `EmergingVulnerabilityInfo`	Information about emerging vulnerabilities detected for this company. Generally these are recently revealed vulnerabilities that our analysts have manually located in our data and are not yet available as findings.
Arguments `offset` - `Int!` Offset is per company `limit` - `Int` Limit is per company
`vendorContacts` - `[VendorContact!]`	Vendor contacts (contacts at the vendor company) responsible for escalations for this company
`clientContacts` - `[ClientContactToCompany!]`	Client contacts (contacts at the client) responsible for escalations for this company. The contact may have responsibility for other companies.
`meanTimeToAck` - `Float`	Mean time for a company to ack a case, for this client, across all time, in days
`meanTimeToResolve` - `Float`	Mean time for a company to resolve a case, for this client, across all time, in days
`currentEscalatedCases` - `Int`	Number of currently escalated cases for this company
`firstEscalated` - `String`	First date this company ever had an escalated case
`zeroToleranceOrCriticalFindingCount` - `Int!`	Count of findings for this company that have critical severity or are zero-tolerance
`firmographicFields` - `FirmographicData`	Firmographic information

Example

{
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "primaryName": "abc123",
  "primaryDomain": "xyz789",
  "companyStatus": "abc123",
  "portfolioNames": ["abc123"],
  "portfolioUuids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "portfolios": [Portfolio],
  "companyScore": Score,
  "riskScore": Score,
  "historicScores": [HistoricScore],
  "categoryScores": CategoryScores,
  "peerScores": [PeerScore],
  "attributes": ["abc123"],
  "clientEntityIds": ["xyz789"],
  "clientEntityData": [ClientEntityData],
  "findingInfo": FindingInfo,
  "numFindings": 987,
  "findingsWaitingForResponse": 987,
  "numberOfEscalatedFindings": 987,
  "numberofActionableOpenEscalatedFindings": 987,
  "numberOfActionableOpenFindings": 123,
  "findingsInDispute": 987,
  "findingsOverdue": 123,
  "industryDescription": "abc123",
  "scorePercentile": 123.45,
  "exceedsRiskTolerance": false,
  "exceedsRiskToleranceFirstDate": "abc123",
  "escalationPath": "directTo3rdParty",
  "firstAddedTS": "xyz789",
  "history": [History],
  "companyHistoryInfo": CompanyHistoryInfo,
  "detectedSecurityDevices": [SecurityDevice],
  "detectedSecurityDevicesByFindingCode": [
    SecurityDeviceInfo
  ],
  "fourthPartyExposure": [ExposureData],
  "fourthPartyExposureByFindingCode": [
    FourthPartyExposureInsights
  ],
  "fourthPartyBreachCount": 987,
  "cloudStorage": CloudStorageInsightByCompanyInfo,
  "cloudStorageByFindingCode": [CloudStorageInsightInfo],
  "cloudStorageBucketCount": 987,
  "productsByDomainDetection": [ProductByDomainDetection],
  "productsByDomainDetectionByFindingCode": [
    ProductByDomainDetectionInfo
  ],
  "emailSaasDomainsWithoutSecurityCount": 987,
  "productsByIPDetection": [ProductByIPDetection],
  "productsByIPDetectionByFindingCode": [
    ProductByIPDetectionInsights
  ],
  "exposedLoginPortalCount": 987,
  "topTenAssets": [Asset],
  "topTenAssetsByFindingCode": [TopTenInfo],
  "vendorDiscovery": [VendorDiscovery],
  "vendorDiscoveryByFindingCode": [
    VendorDiscoveryInsights
  ],
  "cpeCVE": [CPECVE],
  "cisaKev": [CISAKEVCVE],
  "footprintSummary": FootprintSummary,
  "domains": [DomainInfo],
  "domainInfo": DomainListInfo,
  "totalHostnameCountryCount": 123,
  "totalHostnameCount": 123,
  "countryDomainCounts": [CountryDomainCount],
  "domainCountryInfo": DomainCountryInfo,
  "ips": [IPInfo],
  "ipInfo": IPListInfo,
  "activeIpCount": 123,
  "observedResolutionCount": 123,
  "hostingProviderInfo": HostingProviderInfo,
  "waitingForStates": ["BlueVoyant"],
  "gdd": GDD,
  "emergingVulnerabilityInfo": EmergingVulnerabilityInfo,
  "vendorContacts": [VendorContact],
  "clientContacts": [ClientContactToCompany],
  "meanTimeToAck": 123.45,
  "meanTimeToResolve": 123.45,
  "currentEscalatedCases": 123,
  "firstEscalated": "xyz789",
  "zeroToleranceOrCriticalFindingCount": 987,
  "firmographicFields": FirmographicData
}

Types

CompanyBROnly

Description

This object contains all the company-related values that can be displayed for a Business Risk-only entity. See CompanyByService or CompanyFromSearchResult.

Fields

Field Name	Description
`bvid` - `UUID!`	The BV ID, the unique identifier for the company
`primaryName` - `String`	Primary name of the company
`primaryDomain` - `String`	Primary domain associated with the company
`attributes` - `[String!]`	Client-provided attributes or tags that can be associated with one or more companies, used for filtering or grouping companies
`clientEntityIds` - `[String!]`	clientEntityIds are case-insensitive identifiers allocated by the client for a company (entity). Typically you would use them to store your internal company identifiers (or a surrogate therefore) in our system. A clientEntityId can only be assigned to one company in all of the client's portfolios.
`clientEntityData` - `[ClientEntityData!]`	clientEntityIds and their associated info, which could include an optional name or domain. A clientEntityId is an identifier allocated by the client for a company (entity). A clientEntityId can only be assigned to one company in all of the client's portfolios.
`industryDescription` - `String`	Use 'firmographicFields -> industryDescription'
`firmographicFields` - `FirmographicData`

Example

{
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "primaryName": "xyz789",
  "primaryDomain": "xyz789",
  "attributes": ["xyz789"],
  "clientEntityIds": ["xyz789"],
  "clientEntityData": [ClientEntityData],
  "industryDescription": "xyz789",
  "firmographicFields": FirmographicData
}

Types

CompanyBase

Description

Common company fields used by CompanyBROnly, CompanyHVM, and Company

Fields

Field Name	Description
`bvid` - `UUID!`	The BV ID, the unique identifier for the company
`primaryName` - `String`	Primary name of the company
`primaryDomain` - `String`	Primary domain associated with the company
`attributes` - `[String!]`	Client-provided attributes or tags that can be associated with one or more companies, used for filtering or grouping companies
`clientEntityIds` - `[String!]`	clientEntityIds are case-insensitive identifiers allocated by the client for a company (entity). Typically you would use them to store your internal company identifiers (or a surrogate therefore) in our system. A clientEntityId can only be assigned to one company in all of the client's portfolios.
`clientEntityData` - `[ClientEntityData!]`	clientEntityIds and their associated info, which could include an optional name or domain. A clientEntityId is an identifier allocated by the client for a company (entity). A clientEntityId can only be assigned to one company in all of the client's portfolios.
`industryDescription` - `String`	Use 'firmographicFields -> industryDescription'
`firmographicFields` - `FirmographicData`

Possible Types

CompanyBase Types
`CompanyBROnly`
`CVECompany`
`CompanyHVM`
`Company`

Example

{
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "primaryName": "xyz789",
  "primaryDomain": "xyz789",
  "attributes": ["xyz789"],
  "clientEntityIds": ["xyz789"],
  "clientEntityData": [ClientEntityData],
  "industryDescription": "xyz789",
  "firmographicFields": FirmographicData
}

Types

CompanyBulkUpdate

Description

Result of the companyBulkUpdate mutation.

Fields

Field Name	Description
`offset` - `Int!`	Offset echoes back the original offset parameter
`limit` - `Int`	Limit returns the limit parameter, which may have been adjusted to the maximum allowed size
`totalCount` - `Int64!`	Count of companies matching filter regardless of whether they fit within limit. Bulk update is attempted only for pageLength companies, not totalCount companies.
`pageLength` - `Int!`	Number of companies matching the filter criteria (and restricted by the limit), for which the bulk update was attempted
`succeededCount` - `Int!`	Number of companies for which updates succeeded
`failedCount` - `Int!`	Number of companies for which updates failed
`statuses` - `[CompanyBulkUpdateStatus]`	Holds status/message response for company bulk updates, with one item per status/message

Example

{
  "offset": 987,
  "limit": 123,
  "totalCount": 123,
  "pageLength": 987,
  "succeededCount": 123,
  "failedCount": 987,
  "statuses": [CompanyBulkUpdateStatus]
}

Types

CompanyBulkUpdateStatus

Description

Result of a bulk update using filtered companies. This will be null if no companies matched the filter. Part of the CompanyBulkUpdate and ClientContactBulkUpdate types.

Fields

Field Name	Description
`bvids` - `[UUID!]`	A set of BV IDs that were matched by the company filter
`status` - `Int!`	HTTP status code after bulk update that applies to the associated set of BV IDs
`message` - `String!`	Error or success message associated with status

Example

{
  "bvids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "status": 123,
  "message": "abc123"
}

Types

CompanyByService

Description

Result of a businessRisk query in BusinessRiskInsight. CompanyByService returns a different company type object depending on the service(s) associated with the company: external_regular, high_volume_monitoring, or business risk (when the last is the only service).

Types

Union Types
`Company`
`CompanyHVM`
`CompanyBROnly`

Example

Company

Types

CompanyFilter

Fields

Input Field	Description
`bvids` - `[UUID!]`	The BV ID is the unique identifier for the company. Default = `null`
`bvidsToExclude` - `[UUID!]`	Exclude companies matching these BV IDs even if matched by the other filters. Default = `null`
`portfolioType` - `PortfolioType`	The portfolio type is either 'external_regular' or 'high_volume_monitoring' and defaults to 'external_regular'. With 'high_volume_monitoring', only certain fields and filters are allowed: HVM filters: limit, offset, filter: (attributes, bvids, bvidsToExclude, clientEntityIds, industryCodes, industryDescriptions, portfolioNames, portfolioType, portfolioUuids, primaryDomains, primaryNames, riskLevels, sortBy) HVM fields: limit, offset, pageLength, totalCount, companies: (attributes, bvid, clientEntityIds, clientEntityData, firmographicFields, industryDescription, portfolios*, primaryDomain, primaryName, riskScore:riskLevel, zeroToleranceOrCriticalFindingCount)
`portfolioUuids` - `[UUID!]`
`portfolioNames` - `[String!]`	Filter on exact portfolio name(s) containing companies. Default = `null`
`attributes` - `[String]`	Search on attributes is case-sensitive and exact. Supply an empty string as a value to match companies with no attributes. Default = `null`
`clientEntityIds` - `[String]`	A clientEntityId is an identifier allocated by the client for a company (entity). A clientEntityId is unique case-insensitively across all companies in the client's portfolios. This field is for exact, case-sensitive matches only. Do not use with the clientEntityIdsWildcard filter field. Default = `null`
`clientEntityIdsWildcard` - `[String!]`	A clientEntityId is an identifier allocated by the client for a company (entity). A clientEntityId is unique case-insensitively across all companies in the client's portfolios. This field is for partial, case-insensitive matches. Do not use with the clientEntityIds filter field. Default = `null`
`primaryNames` - `[String!]`	Filter by primary name of company with wildcard matching. Default = `null`
`primaryDomains` - `[String!]`	Filter by primary domain of company with wildcard matching. Default = `null`
`industryCodes` - `[String]`
`industryDescriptions` - `[String]`
`companyStatuses` - `[CompanyStatus]`
`exceedsRiskTolerance` - `Boolean`
`riskScoreStatuses` - `[FindingStatus!]`
`riskScoreMax` - `Float`	Filter by maximum overall risk score (riskScore.score) for companies, which can be from 0 to 100, or null if not scored. Default = `null`
`riskScoreMin` - `Float`	Filter by minimum overall risk score (riskScore.score) for companies, which can be from 0 to 100, or null if not scored. Default = `null`
`riskLevels` - `[RiskLevel!]`	Filter by a bucketing of the risk level. Default = `null`
`escalationPath` - `[EscalationPath!]`
`legacyEscalationPathString` - `[String!]`	If escalationPath is also specified the result will be the disjunction of all items in both arrays. Default = `null`
`escalationStatuses` - `[FindingEscalationStatus!]`
`waitingFor` - `[WaitingFor]`
`sortBy` - `[CompanySortBy]`

Example

An example at this level does nothing, stuff them on the fields

Types

CompanyFromSearchResult

Description

Result of a companySearch query. CompanyFromSearchResult returns a different company type object depending on the service(s) associated with the company: external_regular, high_volume_monitoring, or business risk (when the last is the only service), or when there are no services at all

Note that three of these can be accessed with ... on CompanyBase but CompanyOnly must be separately accessed with ... on CompanyOnly

Types

Union Types
`Company`
`CompanyHVM`
`CompanyBROnly`
`CompanyOnly`

Example

Company

Types

CompanyHVM

Description

This object contains all the company-related values that can be displayed for an HVM entity. See CompanyByService or CompanyFromSearchResult.

Fields

Field Name	Description
`bvid` - `UUID!`	The BV ID, the unique identifier for the company
`primaryName` - `String`	Primary name of the company
`primaryDomain` - `String`	Primary domain associated with the company
`attributes` - `[String!]`	Client-provided attributes or tags that can be associated with one or more companies, used for filtering or grouping companies
`clientEntityIds` - `[String!]`	clientEntityIds are case-insensitive identifiers allocated by the client for a company (entity). Typically you would use them to store your internal company identifiers (or a surrogate therefore) in our system. A clientEntityId can only be assigned to one company in all of the client's portfolios.
`clientEntityData` - `[ClientEntityData!]`	clientEntityIds and their associated info, which could include an optional name or domain. A clientEntityId is an identifier allocated by the client for a company (entity). A clientEntityId can only be assigned to one company in all of the client's portfolios.
`industryDescription` - `String`	Use 'firmographicFields -> industryDescription'
`firmographicFields` - `FirmographicData`
`portfolios` - `[Portfolio!]`
`zeroToleranceOrCriticalFindingCount` - `Int!`	Count of findings for this company that have critical severity or are zero-tolerance
`riskScore` - `ScoreHVM`	The overall risk score for the company and associated information

Example

{
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "primaryName": "abc123",
  "primaryDomain": "abc123",
  "attributes": ["abc123"],
  "clientEntityIds": ["abc123"],
  "clientEntityData": [ClientEntityData],
  "industryDescription": "xyz789",
  "firmographicFields": FirmographicData,
  "portfolios": [Portfolio],
  "zeroToleranceOrCriticalFindingCount": 123,
  "riskScore": ScoreHVM
}

Types

CompanyHistory

Description

An event indicating a change to a company's escalation status or to whether it exceeds risk tolerance, part of the CompanyHistoryInfo type in the companyHistoryInfo part of the Company type, returned as part of the companyInfo query.

Fields

Field Name	Description
`id` - `UUID`	A unique ID for the event
`message` - `String`	A short description of the change
`timestamp` - `String`	When the event occurred
`description` - `String`	A description of the change
`updateType` - `String`	The type of event or change: "Exceeds Risk Tolerance" or "Status"
`updateValue` - `String`	The new value after the change

Example

{
  "id": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "message": "abc123",
  "timestamp": "2022-07-06T20:23:47.942826Z",
  "description": "xyz789",
  "updateType": "Exceeds Risk Tolerance",
  "updateValue": "true"
}

Types

CompanyHistoryInfo

Description

This is the holder for escalation status and risk tolerance event history for a company, with pagination and counts, returned as part of the companyHistoryInfo part of the Company type that is returned from the companyInfo query.

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters. Applied per company
`limit` - `Int`	Offset and limit echo back the parameters. Applied per company
`totalCount` - `Int64`	Total count of events
`pageLength` - `Int!`	Number of events returned
`statusChangeCount` - `Int64`	Number of events indicating a change to escalation status within the date range, but not subject to the limit
`riskToleranceChangeCount` - `Int64`	Number of events indicating a change to whether the company exceeds risk tolerance within the date range, but not subject to the limit
`companyHistory` - `[CompanyHistory!]`	Events returned

Example

{
  "offset": 987,
  "limit": 987,
  "totalCount": 123,
  "pageLength": 987,
  "statusChangeCount": 123,
  "riskToleranceChangeCount": 123,
  "companyHistory": [CompanyHistory]
}

Types

CompanyInfo

Description

This is the holder for companies, from a companyInfo query, with pagination and counts

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`	Limit and offset echo back the parameters
`totalCount` - `Int!`	Count of companies matching filter regardless of whether they fit within limit
`pageLength` - `Int!`	Count of companies returned
`companies` - `[Company!]`	Companies in the client's portfolios
`commonAttributes` - `[String!]`	Common attributes in all returned (pageLength) companies

Example

{
  "offset": 987,
  "limit": 123,
  "totalCount": 123,
  "pageLength": 987,
  "companies": [Company],
  "commonAttributes": ["xyz789"]
}

Types

CompanyMatchedFieldOrdinal

Description

Part of the CompanySearchResultMatchedField type, indicating the ordinal value of the field that was matched in a companySearch query

Values

Enum Value	Description
`primary`	Indicates the match was on the company's primary name or domain
`secondary`	Indicates the match was on one of the company's alternate, or secondary, names or domains
`none`	Indicates the match was not directly on the company object (e.g. it was on a domain in the company's footprint)

Example

"primary"

Types

CompanyMatchedFieldType

Description

Part of the CompanySearchResultMatchedField type, indicating the type of the field that was matched in a companySearch query

Values

Enum Value	Description
`name`
`domain`

Example

"name"

Types

CompanyOnly

Description

Company information available when when using companySearch to add a company to portfolios, from data associated with the company directly, for a company that is not in a client's portfolios. See CompanyFromSearchResult.

Fields

Field Name	Description
`bvid` - `UUID!`	The BV ID, the unique identifier for the company
`primaryName` - `String`	Primary name of the company
`primaryDomain` - `String`	Primary domain associated with the company
`firmographicFields` - `FirmographicData`	The firmographic data for a company

Example

{
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "primaryName": "xyz789",
  "primaryDomain": "xyz789",
  "firmographicFields": FirmographicData
}

Types

CompanyRequest

Description

A request to add a company to the system and to a client's portfolio.

Returned by the companyRequestCreate and companyRequestCancel mutations and part of the CompanyRequestInfo type returned from the companyRequestInfo query.

Fields

Field Name	Description
`requestUuid` - `UUID!`	Unique identifier for this request, in UUID format
`attributes` - `[String]`	Client-provided attributes for the requested company
`bvid` - `UUID`	The unique BlueVoyant identifier of the company after it has been located or created
`canceledReason` - `String`	Reason for cancelation of request, if canceled
`primaryDomain` - `String!`	The primary domain of the requested company
`clientEntityId` - `String!`	Client's primary, unique, case-insensitive ID for the requested company
`clientEntityIds` - `[ClientEntityDataRequest]`	Additional client-provided IDs/names/domains for the requested company
`primaryName` - `String!`	The primary name of the requested company
`notes` - `String!`	Client-submitted notes
`open` - `Boolean!`	True (open) if request still being worked; false (closed) if it is completed or canceled
`portfolioUuid` - `UUID!`	UUID of portfolio that should hold the requested company
`status` - `CompanyRequestStatus!`	Status of the request
`createdBy` - `String!`	Username that created this item
`createdTS` - `String!`	Timestamp when created
`updatedBy` - `String!`	Username that last updated this item
`updatedTS` - `String!`	Timestamp when last updated

Example

{
  "requestUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "attributes": ["abc123"],
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "canceledReason": "abc123",
  "primaryDomain": "abc123",
  "clientEntityId": "abc123",
  "clientEntityIds": [ClientEntityDataRequest],
  "primaryName": "abc123",
  "notes": "xyz789",
  "open": true,
  "portfolioUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "status": "Received",
  "createdBy": "xyz789",
  "createdTS": "abc123",
  "updatedBy": "abc123",
  "updatedTS": "abc123"
}

Types

CompanyRequestFilter

Description

Where a field is specified, only select requests with a value matching one of those in the set specified. Only return requests for which all per-field constraints are met.

null for no restriction.

Fields

Input Field	Description
`requestUuids` - `[UUID!]`	Filter by unique identifiers for company-creation requests, in UUID format
`open` - `Boolean`	Filter on whether requests are open. Open states: Received, In progress, Actioned, Footprinted. Closed states: Completed, Canceled by customer, Canceled by analyst).
`statuses` - `[CompanyRequestStatus!]`	The request status to filter on (Received: Initial state of the request; In progress: Analyst has begun work; Actioned: Company has been located or created; Footprinted: Company has been footprinted and appears in portfolio; Completed: Company has scores and analytics)
`createdDate` - `String`	Only get requests created since this date, in 'YYYY-MM-DD' or other valid date format
`updatedDate` - `String`	Only get requests updated since this date, in 'YYYY-MM-DD' or other valid date format
`sortBy` - `[CompanyRequestSortBy]`

Example

{
  "requestUuids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "open": false,
  "statuses": ["Received"],
  "createdDate": "xyz789",
  "updatedDate": "abc123",
  "sortBy": [CompanyRequestSortBy]
}

Types

CompanyRequestInfo

Description

This is the holder for company requests from the companyRequestInfo query, with pagination and counts

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`
`totalCount` - `Int!`	Count of company requests matching filter regardless of whether they fit within limit
`pageLength` - `Int!`	Count of company requests returned
`companyRequests` - `[CompanyRequest!]`

Example

{
  "offset": 123,
  "limit": 123,
  "totalCount": 123,
  "pageLength": 123,
  "companyRequests": [CompanyRequest]
}

Types

CompanyRequestSortBy

Fields

Input Field	Description
`field` - `CompanyRequestSorts!`
`direction` - `SortDirection`

Example

{"field": "createdTS", "direction": "asc"}

Types

CompanyRequestSorts

Description

Fields available to sort company requests by; default: createdTS desc

Values

Enum Value	Description
`createdTS`
`updatedTS`
`requestUuid`
`primaryName`	Primary name of the company
`primaryDomain`
`status`
`open`
`clientEntityId`

Example

"createdTS"

Types

CompanyRequestStatus

Description

Status of a company request

Values

Enum Value	Description
`Received`	Initial state of the request (open)
`In_progress`	Analyst has begun work (open)
`Actioned`	Company has been located or created (open)
`Footprinted`	Company has been footprinted and appears in portfolio (open)
`Completed`	Company has scores and analytics (closed)
`Canceled_by_customer`	Canceled (closed)
`Canceled_by_analyst`	Canceled (closed)

Example

"Received"

Types

CompanyRequestToAdd

Description

Data to include to create a request to add a company to the system and to a client's portfolio

Fields

Input Field	Description
`portfolioUuid` - `UUID!`	UUID of portfolio that should hold the requested company
`primaryName` - `String`	The primary name of the requested company
`primaryDomain` - `String`	The primary domain of the requested company. The domain is required unless 'force' is set to true
`clientEntityId` - `String`	Client's primary unique ID for the requested company
`clientEntityIds` - `[ClientEntityDataInput!]`	Additional client-provided IDs/names/domains for the company
`attributes` - `[String!]`	Client-provided attributes or tags that can be associated with one or more companies, used for filtering or grouping companies
`notes` - `String`	Client-submitted notes
`force` - `Boolean`	Force request creation without providing a domain

Example

{
  "portfolioUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "primaryName": "abc123",
  "primaryDomain": "xyz789",
  "clientEntityId": "xyz789",
  "clientEntityIds": [ClientEntityDataInput],
  "attributes": ["xyz789"],
  "notes": "abc123",
  "force": false
}

Types

CompanyRequestToCancel

Description

Data to provide to cancel a request to add a company to the system and to a client's portfolio

Fields

Input Field	Description
`requestUuid` - `UUID!`	Unique identifier of company-creation request to be canceled, in UUID format
`reason` - `String`	Reason for cancelation

Example

{
  "requestUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "reason": "abc123"
}

Types

CompanySearchInfo

Description

This is the holder for CompanyWithSearchResults from a companySearch query against all companies known to BlueVoyant, with counts

Fields

Field Name	Description
`totalCount` - `Int64!`	Count of results regardless of whether they fit within max allowed (500)
`pageLength` - `Int!`	Count of results returned
`companySearchResults` - `[CompanyWithSearchResult!]`	Companies matching supplied name and/or domain

Example

{
  "totalCount": 123,
  "pageLength": 987,
  "companySearchResults": [CompanyWithSearchResult]
}

Types

CompanySearchResultMatchedField

Description

Part of the CompanyWithSearchResult type, giving information about a match in a companySearch query

Fields

Field Name	Description
`ordinal` - `CompanyMatchedFieldOrdinal!`	Indicates whether the matched field is primary or secondary (alternate) on the company object, or not on the company object directly
`type` - `CompanyMatchedFieldType!`	The type of the field that matched
`value` - `String!`	The value of the field that matched

Example

{
  "ordinal": "primary",
  "type": "name",
  "value": "xyz789"
}

Types

CompanySortBy

Fields

Input Field	Description
`field` - `CompanySorts!`
`direction` - `SortDirection`

Example

{"field": "primaryName", "direction": "asc"}

Types

CompanySorts

Description

Fields available by which to sort companies; default: primaryName/asc

Values

Enum Value	Description
`primaryName`	Primary name of the company
`primaryDomain`	Primary domain associated with the company
`industryDescription`
`companyStatus`
`portfolioNames`
`companyScore`	Sort on riskScore.score, the overall company score
`exceedsRiskToleranceFirstDate`
`exceedsRiskTolerance`
`numberOfEscalatedFindings`
`numberofActionableOpenEscalatedFindings`
`numberOfActionableOpenFindings`
`findingsInDispute`
`findingsOverdue`
`findingsWaitingForResponse`
`firstAddedTS`
`escalationPath`
`riskLevel`	A bucketing of the risk level
`zeroToleranceOrCriticalFindingCount`

Example

"primaryName"

Types

CompanyStatistic

Description

a statistic for a given company returned from the companyInPeriodStatistics query as part of the CompanyStatistics type.

As of right now does not embed the full Company type, but it could.

Fields

Field Name	Description
`bvid` - `UUID!`	The unique BlueVoyant identifier (BV ID) of the company.
`value` - `Float`	The value associated with the BV ID

Example

{
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "value": 987.65
}

Types

CompanyStatistics

Description

Statistics broken out by company, returned from the companyInPeriodStatistics query

Fields

Field Name	Description
`meanCompanyScores` - `[CompanyStatistic!]`	meanCompanyScores - mean scores of companies
Arguments `limit` - `Int` `direction` - `SortDirection`
`meanTimeToResolve` - `[CompanyStatistic!]`	Mean time for a company to resolve a case, for this client in days
Arguments `limit` - `Int` `direction` - `SortDirection`

Example

{
  "meanCompanyScores": [CompanyStatistic],
  "meanTimeToResolve": [CompanyStatistic]
}

Types

CompanyStatus

Description

A singular value reflecting the state of finding remediation on the company.

Active is the default where nothing else applies.

Values

Enum Value	Description
`Remediation_in_Progress`
`Escalation_in_Progress`
`Under_Review`
`Active`

Example

"Remediation_in_Progress"

Types

CompanySummarizedCountFilter

Fields

Input Field	Description
`portfolios` - `[String!]`	The portfolios to filter on.
`categories` - `[String!]`	The categories to filter on.
`vendors` - `[String!]`	The vendors to filter on.
`products` - `[String!]`	The products to filter on.

Example

{
  "portfolios": ["abc123"],
  "categories": ["xyz789"],
  "vendors": ["xyz789"],
  "products": ["abc123"]
}

Types

CompanySummarizedCountInfo

Fields

Field Name	Description
`totalCount` - `Int!`	The total count of objects that match the user's request regardless of how many were returned.
`pageLength` - `Int!`	The amount of objects returned to the user.
`items` - `[CompanySummarizedCounts]`	The list of objects that match the user's request.

Example

{
  "totalCount": 987,
  "pageLength": 987,
  "items": [CompanySummarizedCounts]
}

Types

CompanySummarizedCountSort

Values

Enum Value	Description
`portfolioName`
`category`
`vendor`
`product`

Example

"portfolioName"

Types

CompanySummarizedCountSortBy

Fields

Input Field	Description
`field` - `CompanySummarizedCountSort!`	Field by which to sort vendors. Default = `portfolioName`
`direction` - `SummarizedSortDirection`	Direction in which to sort users (asc/desc). Default = `asc`

Example

{"field": "portfolioName", "direction": "asc"}

Types

CompanySummarizedCounts

Fields

Field Name	Description
`portfolio` - `String!`	The portfolio of this portfolio/client/category/vendor/product combination.
`category` - `String!`	The category of this portfolio/client/category/vendor/product combination.
`vendor` - `String!`	The vendor of this portfolio/client/category/vendor/product combination.
`product` - `String!`	The product of this portfolio/client/category/vendor/product combination.
`totalCount` - `Int!`	The total amount of companies in this portfolio/client/category/vendor/product combination.
`companies` - `[String!]`	The companies of this portfolio/client/category/vendor/product combination.

Example

{
  "portfolio": "xyz789",
  "category": "abc123",
  "vendor": "abc123",
  "product": "xyz789",
  "totalCount": 123,
  "companies": ["abc123"]
}

Types

CompanyWithSearchResult

Description

Result of a companySearch query against all companies known to BlueVoyant

Fields

Field Name	Description
`bvid` - `UUID!`	The BV ID, the unique identifier for the company
`company` - `CompanyFromSearchResult`	The company matching the search criteria Only limited fields from the company object can be requested when using this endpoint: bvid, primaryName, primaryDomain, firmographicFields, _typename, attributes, clientEntityIds, clientEntityData, portfolios*
`alternateNames` - `[String!]`	Alternate, or secondary, names for the company
`alternateDomains` - `[String!]`	Alternate, or secondary, domains for the company
`complex` - `Boolean!`	If true, indicates a company with a potentially large customer space such as telecom providers, universities, cloud providers, SAAS providers, etc. Approval is needed to add a complex company to a portfolio.
`matchScore` - `Float!`	The score for the match. 100 indicates an exact match. All matches with scores of at least 20 are provided, up to 500 matches.
`matchType` - `String!`	The type of match, indicating the field(s) matched, and whether the match was exact or fuzzy. Can be one of "Entity Domain/Name", "Entity Domain Only", "Entity Name Only", "Entity Footprint Domain", "Entity Domain/Name (fuzzy)", "Entity Domain (fuzzy)", "Entity Name (fuzzy)". Matches are exact unless 'fuzzy' is indicated. "Entity Footprint Domain" indicates that the exact domain was found in the company's footprint rather than being associated with the company object directly.
`matchedFields` - `[CompanySearchResultMatchedField!]`	Information about the field(s) matched

Example

{
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "company": Company,
  "alternateNames": ["abc123"],
  "alternateDomains": ["xyz789"],
  "complex": true,
  "matchScore": 123.45,
  "matchType": "xyz789",
  "matchedFields": [CompanySearchResultMatchedField]
}

Types

ConfidenceLevel

Values

Enum Value	Description
`low`
`medium`
`high`

Example

"low"

Types

ContactFilter

Description

Filter for contacts

Fields

Input Field	Description
`contactNames` - `[String!]`	Filter contacts by one or more names, with wildcard matching. Default = `null`
`ids` - `[Int!]`	Filter contacts by one or more IDs
`emails` - `[String!]`	Filter contacts by one or more exact emails (case insensitively)
`sortBy` - `[ContactSortBy]`	Sort returned roles by specified fields and directions

Example

{
  "contactNames": ["xyz789"],
  "ids": [987],
  "emails": ["abc123"],
  "sortBy": [ContactSortBy]
}

Types

ContactSortBy

Fields

Input Field	Description
`field` - `ContactSorts!`	Field by which to sort contacts
`direction` - `SortDirection`	Direction in which to sort contacts (asc/desc). Default = `asc`

Example

{"field": "contactName", "direction": "asc"}

Types

ContactSorts

Values

Enum Value	Description
`contactName`
`id`
`email`

Example

"contactName"

Types

ContactToDelete

Description

Input to delete a contact

Fields

Input Field	Description
`id` - `Int!`

Example

{"id": 123}

Types

CountryDomainCount

Description

Country code and its number of domains with hostnames resolving to IP addresses in the footprint

Fields

Field Name	Description
`countryCode` - `String!`	The country as a two-letter code
`netGeoCountry` - `String!`	The name of the country or territory, lower case. Generally corresponds to the ISO 3166 English-language short name, but may be simplified or reflect a previously allocated name
`domainCount` - `Int64!`	The number of domains with hostnames resolving to IP addresses associated with the country
`hostCount` - `Int64!`	The number of hostnames resolving to IP addresses associated with the country

Example

{
  "countryCode": "abc123",
  "netGeoCountry": "abc123",
  "domainCount": 123,
  "hostCount": 123
}

Types

CountryIPCount

Description

Country code and its number of IP addresses from the company's footprint that are geolocated in the country

Fields

Field Name	Description
`countryCode` - `String!`	The country as a two-letter code where the IP address is located
`netGeoCountry` - `String`	The country where the IP address is located
`ipCount` - `Int64!`	The number of IP addresses associated with the country

Example

{
  "countryCode": "abc123",
  "netGeoCountry": "abc123",
  "ipCount": 123
}

Types

DataDictionary

Fields

Field Name	Description
`industryCodes` - `[DictionaryValue!]!`	The NAICS codes this API knows about
`riskLevels` - `[DictionaryValue!]!`	How to map scores to risk levels
`severityLabels` - `[DictionaryValue!]!`
`findingCodes` - `[DictionaryValue!]!`	Finding codes and summaries. Finding code is an integer that represents the specific type of a finding.
Arguments `showHidden` - `Boolean`
`findingDescriptions` - `[DictionaryValue!]!`	Finding codes and descriptions. Finding code is an integer that represents the specific type of a finding.
Arguments `showHidden` - `Boolean`
`insightCodes` - `[DictionaryValue!]!`	Insight finding codes and summaries
`attackSurfaceCodes` - `[DictionaryValue!]!`	Attack surface finding codes and summaries
`questionnaireGroups` - `[DictionaryValue!]!`	Questionnaire group names and their associated finding codes. Finding codes are represented as comma separated strings of integers.

Example

{
  "industryCodes": [DictionaryValue],
  "riskLevels": [DictionaryValue],
  "severityLabels": [DictionaryValue],
  "findingCodes": [DictionaryValue],
  "findingDescriptions": [DictionaryValue],
  "insightCodes": [DictionaryValue],
  "attackSurfaceCodes": [DictionaryValue],
  "questionnaireGroups": [DictionaryValue]
}

Types

Detail

Description

A complete finding detail result. Part of the DetailInfo type, returned by the findingInfo query.

Not every field is associated with every finding code. A list of finding codes, and their associated fields, can be found here. Standard fields on every detail are bvid, status, statusText, findingCode, findingHash, variant, assessmentDateBegin, assessmentDateEnd, observationTimesSeen, observationTimestampFirst, observationTimestampLast.

Fields

Field Name	Description
`bvid` - `UUID`	The unique BlueVoyant identifier (BV ID) of the company. A standard field.
`status` - `String`	The status of the finding detail. It can be either 'open' or 'closed'. A standard field.
`statusText` - `String`	A slightly more descriptive status. It can be 'No Longer Observed', 'Closed by Analyst', 'False Positive', or 'Closed', or '' for open details. A standard field.
`findingCode` - `Int`	Finding code is an integer that represents the specific type of a finding. See the dictionary query and the DataDictionary type. A standard field.
`findingHash` - `String`	An ID of int64 type that is unique for a BV ID, variant, and finding code. A standard field.
`variant` - `Int64`	Used to uniquely identify each company footprint. A standard field.
`assessmentDateBegin` - `String`	The start of the scoring assessment period. A standard field.
`assessmentDateEnd` - `String`	The end of the scoring assessment period. A standard field.
`observationTimesSeen` - `Int`	The number of times observed during footprinting. A standard field.
`observationTimestampFirst` - `String`	The first time this entity was observed during footprinting. A standard field.
`observationTimestampLast` - `String`	The most recent time the entity was observed during footprinting. A standard field.
`requestingIp` - `String`	The IP address of the requesting entity.
`nameserverIp` - `String`	The IP address for the name server.
`answerIp` - `String`	The IP addess of the answering entity.
`qnames` - `[String]`	A list of all qualified names for the entity. These are the fully qualified names of an element, attribute, or identifier in an XML document.
`threatType` - `String`	The kind of threat this entity is. i.e. botnet, ransomware, malware, etc.
`domain` - `String`	The domain of this entity.
`blacklistedIp` - `String`	The blacklisted IP address of an entity.
`clientIp` - `String`	The client's IP address that is related to this entity.
`count` - `Int`	The number of vulnerabilities found.
`destPort` - `Int`	The destination port of the entity.
`details` - `String`	More details about some findings, specific to the finding code. For example it could list the CVE ID's the finding has.
`dkimSelector` - `String`	DKIM specifies the DNS location of the public key.
`encryptionType` - `String`	What kind of encryption this finding detail is using.
`ip` - `String`	The IP address of this finding.
`lastObservedInternalIp` - `String`	The last observed IP on the local network.
`lastObservedPublicIp` - `String`	The last observed public-facing IP.
`observationDates` - `String`	The list of dates this finding was observed.
`observationOpenStatus` - `String`	Whether or not we are still observing this finding.
`port` - `Int`	The port number of a finding.
`protocol` - `Int`	The protocol this finding used
`qname` - `String`	Qualified Name of the finding. These are the fully qualified names of an element, attribute, or identifier in an XML document.
`ransomwareCompanyName` - `String`	The name of the company allegedly affected by this ransomware attack.
`ransomwareCompanyUrl` - `String`	The URL of the company allegedly affected by this ransomware attack.
`ransomwareSiteName` - `String`	The common name of the site that claims this ransomware attack.
`record` - `String`	An SPF record identifies the mail servers and domains that are allowed to send email on behalf of your domain.
`scannedHost` - `String`	The IP of the host being scanned.
`scannedPort` - `Int`	The port of the host being scanned.
`serviceNames` - `String`	The name of the service running at this finding. e.g. beanstalkd, anyconnect, mysql, etc.
`srcPort` - `Int`	The port number the request is originating from.
`userAgent` - `String`	The User-Agent request header is a characteristic string that lets servers and network peers identify the application, operating system, vendor, and/or version of the requesting user agent.
`cname` - `String`	A Canonical Name or CNAME record is a type of DNS record that maps an alias name to a true or canonical domain name.
`serviceProvider` - `String`	The name of the service that was using this dangling DNS record.
`wildcard` - `Boolean`	Whether or not this dangling DNS record is a wildcard or not.

Example

{
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "status": "xyz789",
  "statusText": "xyz789",
  "findingCode": 123,
  "findingHash": 9039052908188215000,
  "variant": 123,
  "assessmentDateBegin": "2024-01-01T00:00:00Z",
  "assessmentDateEnd": "2024-01-30T00:00:00Z",
  "observationTimesSeen": 123,
  "observationTimestampFirst": "abc123",
  "observationTimestampLast": "xyz789",
  "requestingIp": "abc123",
  "nameserverIp": "abc123",
  "answerIp": "xyz789",
  "qnames": ["xyz789"],
  "threatType": "abc123",
  "domain": "xyz789",
  "blacklistedIp": "xyz789",
  "clientIp": "xyz789",
  "count": 123,
  "destPort": 987,
  "details": "xyz789",
  "dkimSelector": "xyz789",
  "encryptionType": "abc123",
  "ip": "xyz789",
  "lastObservedInternalIp": "xyz789",
  "lastObservedPublicIp": "xyz789",
  "observationDates": "xyz789",
  "observationOpenStatus": "abc123",
  "port": 987,
  "protocol": 987,
  "qname": "abc123",
  "ransomwareCompanyName": "xyz789",
  "ransomwareCompanyUrl": "abc123",
  "ransomwareSiteName": "xyz789",
  "record": "abc123",
  "scannedHost": "xyz789",
  "scannedPort": 123,
  "serviceNames": "xyz789",
  "srcPort": 123,
  "userAgent": "xyz789",
  "cname": "xyz789",
  "serviceProvider": "xyz789",
  "wildcard": false
}

Types

DetailFilter

Description

Part of the Finding type for detailInfo, used by the findingInfo query.

Fields

Input Field	Description
`detailStatus` - `String`	Deprecated. Use 'statuses' field.
`statuses` - `[DetailStatus!]`	Status can be 'open' or 'closed'
`statusTexts` - `[DetailStatusText!]`	Status text is a more descriptive status (for closed details)
`sortBy` - `[DetailSortBy]`	Contains the fields and direction you can sort by. NOTE: At present, sorting by multiple fields is not supported. Default = `null`

Example

{
  "detailStatus": "abc123",
  "statuses": ["closed"],
  "statusTexts": ["Open"],
  "sortBy": [DetailSortBy]
}

Types

DetailInfo

Description

This is the holder for details, part of the Finding type, from a findingInfo query, with pagination and counts

Fields

Field Name	Description
`details` - `[Detail]!`	Details (observations) associated with a finding
`limit` - `Int!`	Offset and limit echo back the parameters
`offset` - `Int!`	Limit and offset echo back the parameters
`pageLength` - `Int!`	The number of details returned per finding hash.
`totalCount` - `Int64!`	Total count available for paged return, per finding hash; negative if not counted; if not counted negative value is taken from the number of unique details

Example

{
  "details": [Detail],
  "limit": 123,
  "offset": 123,
  "pageLength": 987,
  "totalCount": 123
}

Types

DetailSortBy

Description

Part of the DetailFilter type, used by the findingInfo query.

Fields

Input Field	Description
`field` - `DetailsSorts!`	Field by which to sort findings. Which fields you can sort by are dependent on the finding code you are requesting.
`direction` - `SortDirection`	Direction in which to sort findings (asc/desc). Default = `asc`

Example

{"field": "assessmentDateBegin", "direction": "asc"}

Types

DetailStatus

Description

Input to statuses field in DetailFilter type, used by the findingInfo query.

Values

Enum Value	Description
`closed`	Filter on whether the detail is closed
`open`	Filter on whether the detail is open/active

Example

"closed"

Types

DetailStatusText

Description

Input to statusTexts field in DetailFilter type, used by the findingInfo query.

Values

Enum Value	Description
`Open`	The detail has status 'open'
`No_Longer_Observed`	A resolution when the detail has status 'closed'
`Closed_by_Analyst`	A resolution when the detail has status 'closed'
`False_Positive`	A resolution when the detail has status 'closed'

Example

"Open"

Types

DetailsSorts

Description

Field by which to sort finding details, used by the DetailSortBy type for the Detail type. Which fields you can sort by are dependent on the finding code you are requesting.

Values

Enum Value	Description
`assessmentDateBegin`	The start of the scoring assessment period. A standard field.
`assessmentDateEnd`	The end of the scoring assessment period. A standard field.
`findingCode`	Finding code is an integer that represents the specific type of a finding. See the dictionary query and the DataDictionary type. A standard field.
`findingHash`	An ID of int64 type that is unique for a BV ID, variant, and finding code. A standard field.
`variant`	Used to uniquely identify each company footprint. A standard field.
`observationTimesSeen`	The number of times observed during footprinting. A standard field.
`observationTimestampFirst`	The first time this entity was observed during footprinting. A standard field.
`observationTimestampLast`	The most recent time the entity was observed during footprinting. A standard field.
`domain`	The domain of this entity.
`status`	The status of the finding detail. Values are 'open' or 'closed'. (Sorts in string order.)
`statusText`	A slightly more descriptive status. Values are 'No Longer Observed', 'Closed by Analyst', 'False Positive', 'Closed', or '' for open details. (Sorts in string order.)
`bvid`	The unique BlueVoyant identifier (BV ID) of the company. A standard field.
`answerIp`	The IP address of the answering entity.
`blacklistedIp`	The blacklisted IP address of an entity.
`clientIp`	The client's IP address that is related to this entity.
`count`	The number of vulnerabilities found.
`destPort`	The destination port of the entity.
`details`	More details about some findings, specific to the finding code. For example it could list the CVE IDs the finding has. This field is in a stringified JSON format.
`dkimSelector`	DKIM specifies the DNS location of the public key.
`encryptionType`	What kind of encryption this finding detail is using.
`ip`	The IP of this finding.
`lastObservedInternalIp`	The last observed IP on the local network.
`lastObservedPublicIp`	The last observed public-facing IP.
`nameserverIp`	The IP for the name server.
`observationDates`	The list of dates this finding was observed.
`observationOpenStatus`	Whether or not we are still observing this finding.
`port`	The port number of a finding.
`protocol`	The protocol this finding used
`qname`	Qualified Name of the finding. These are the fully qualified names of an element, attribute, or identifier in an XML document.
`qnames`	A list of all qualified names for the entity. These are the fully qualified names of an element, attribute, or identifier in an XML document.
`ransomwareCompanyName`	The name of the company allegedly affected by this ransomware attack.
`ransomwareCompanyUrl`	The URL of the company allegedly affected by this ransomware attack.
`ransomwareSiteName`	The common name of the site that claims this ransomware attack.
`record`	An SPF record identifies the mail servers and domains that are allowed to send email on behalf of your domain.
`requestingIp`	IP of the requesting pDNS entity.
`scannedHost`	The IP of the host being scanned.
`serviceNames`	The name of the service running at this finding. e.g. beanstalkd, anyconnect, mysql, etc.
`srcPort`	The port number the request is originating from.
`threatType`	The kind of threat this entity is. i.e. botnet, ransomware, malware, etc.
`userAgent`	The User-Agent request header is a characteristic string that lets servers and network peers identify the application, operating system, vendor, and/or version of the requesting user agent.
`cname`	A Canonical Name or CNAME record is a type of DNS record that maps an alias name to a true or canonical domain name.
`serviceProvider`	The name of the service that was using this dangling DNS record.
`wildcard`	Whether or not this dangling DNS record is a wildcard or not.

Example

"assessmentDateBegin"

Types

DictionaryValue

Fields

Field Name	Description
`key` - `String!`
`value` - `String!`

Example

{
  "key": "xyz789",
  "value": "xyz789"
}

Types

DistinctVendorDependency

Fields

Input Field	Description
`search` - `String`	If you provide any substring in the search field the query will only return values that contain that substring.
`field` - `VendorDependencyDistinctField!`	An enumerated argument. The query will return unique values on the field you give it. [product, category, vendor, and companyName]. Default = `category`

Example

{"search": "xyz789", "field": "product"}

Types

DomainCountry

Description

Registration information plus a single country of resolution for a domain

Fields

Field Name	Description
`domainData` - `DomainInfo!`	Registration data for a domain, plus all countries of resolution
`countryHostData` - `DomainCountryHostData`

Example

{
  "domainData": DomainInfo,
  "countryHostData": DomainCountryHostData
}

Types

DomainCountryFilter

Description

Filters for domain/country of resolution records associated with a footprint

Fields

Input Field	Description
`countryCodes` - `[String!]`	Filter by exact, case-insensitive, two-letter (but not necessarily ISO 3166-1 alpha-2) country codes from IP addresses associated with hostnames in the domain. Associated with the countryCode field of the DomainCountry type.
`netGeoCountries` - `[String!]`	Filter by exact, case-insensitive, country names from IP addresses associated with hostnames in the domain. Associated with the netGeoCountryCode field of the DomainCountry type.

Example

{
  "countryCodes": ["abc123"],
  "netGeoCountries": ["abc123"]
}

Types

DomainCountryHostData

Description

Number of hostnames associated with each domain/country as determined by resolving the IP address of each hostname in the domain to a country

Fields

Field Name	Description
`netGeoCountry` - `String`	The name of the country or territory, lower case. Generally corresponds to the ISO 3166 English-language short name, but may be simplified or reflect a previously allocated name
`countryCode` - `String`	The country as a two-letter (not necessarily ISO) code
`hostCount` - `Int`	Number or hosts observed for this domain/country combination

Example

{
  "netGeoCountry": "xyz789",
  "countryCode": "abc123",
  "hostCount": 987
}

Types

DomainCountryInfo

Description

This is the holder for domain/country resolution records, from a companyInfo query, with pagination and counts

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`	Limit and offset echo back the parameters
`totalCount` - `Int64!`	Count of domain/country records matching filter regardless of whether they fit within limit
`pageLength` - `Int!`	Count of domain/country records returned
`domainCountries` - `[DomainCountry!]`	Domain/country of resolution records from domains in the company's footprint

Example

{
  "offset": 123,
  "limit": 123,
  "totalCount": 123,
  "pageLength": 987,
  "domainCountries": [DomainCountry]
}

Types

DomainCountrySortBy

Description

Fields/directions used to sort domain/country of resolution records

Fields

Input Field	Description
`field` - `DomainCountrySorts!`
`direction` - `SortDirection`

Example

{"field": "domain", "direction": "asc"}

Types

DomainCountrySorts

Description

Fields used to sort domain/country of resolution records

Values

Enum Value	Description
`domain`	Default sort field
`adminOrganization`
`registrantName`
`registrantOrganization`
`registrar`
`address`	Registration street address - the location of the organization that registered the domain
`state`	Registration state - the location of the organization that registered the domain
`country`	Registration country - the location of the organization that registered the domain
`netGeoCountry`	Country with hostname resolutions (whose IPs resolve to a particular country)
`countryCode`	Country code with hostname resolutions (whose IPs resolve to a particular country)
`hostCount`	Number of hostname resolutions for this domain/country

Example

"domain"

Types

DomainInfo

Description

Registration information and hostname resolution for a domain

Fields

Field Name	Description
`address` - `String`	Registration street address - the location of the organization that registered the domain
`certificates` - `[String]`
`city` - `String`	Registration city - the location of the organization that registered the domain
`country` - `String`	Registration country - the location of the organization that registered the domain
`domain` - `String!`	A domain belonging to the company
`emails` - `[String!]`
`nameServers` - `[String]`
`registrantName` - `String!`
`registrantOrganization` - `String!`
`registrar` - `String!`
`state` - `String`	Registration state - the location of the organization that registered the domain
`tags` - `[TagInfo!]`
`adminOrganization` - `String`
`hostCounts` - `[DomainCountryHostData!]`	Counts of observed hostnames under this domain, broken out by country based on geolocation of the returned IP

Example

{
  "address": "xyz789",
  "certificates": ["abc123"],
  "city": "abc123",
  "country": "abc123",
  "domain": "xyz789",
  "emails": ["abc123"],
  "nameServers": ["xyz789"],
  "registrantName": "abc123",
  "registrantOrganization": "xyz789",
  "registrar": "abc123",
  "state": "abc123",
  "tags": [TagInfo],
  "adminOrganization": "xyz789",
  "hostCounts": [DomainCountryHostData]
}

Types

DomainListInfo

Description

This is the holder for domains, from a companyInfo query, with pagination and counts

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`	Limit and offset echo back the parameters
`totalCount` - `Int64!`	Count of domains matching filter regardless of whether they fit within limit
`pageLength` - `Int!`	Count of domains returned
`domains` - `[DomainInfo!]`	Domains in the company's footprint

Example

{
  "offset": 123,
  "limit": 987,
  "totalCount": 123,
  "pageLength": 123,
  "domains": [DomainInfo]
}

Types

DomainSortBy

Description

Fields/directions used to sort domain records

Fields

Input Field	Description
`field` - `DomainSorts!`
`direction` - `SortDirection`

Example

{"field": "domain", "direction": "asc"}

Types

DomainSorts

Description

Fields used to sort domain records

Values

Enum Value	Description
`domain`	Default sort field
`adminOrganization`
`registrantName`
`registrantOrganization`
`registrar`
`address`	Registration street address - the location of the organization that registered the domain
`state`	Registration state- the location of the organization that registered the domain
`country`	Registration country - the location of the organization that registered the domain

Example

"domain"

Types

EVSortBy

Description

Fields/directions by which to sort EmergingVulnerability details

Fields

Input Field	Description
`field` - `EVSorts!`
`direction` - `SortDirection`

Example

{"field": "id", "direction": "asc"}

Types

EVSorts

Description

Fields available by which to sort EmergingVulnerability details; default: id/asc

Values

Enum Value	Description
`id`	Emerging vulnerability ID
`title`	Title of the emerging vulnerability
`description`	Description of the emerging vulnerability
`bvid`	The unique BlueVoyant identifier (BV ID) of the company.
`primaryName`	Primary name of the company
`portfolioName`
`firstEscalationDate`
`lastEscalationDate`
`thirdPartyAcknowledgedDate`
`thirdPartyMitigatedDate`
`emailsSent`	Number of notification emails sent regarding the associated company (third party), either to the company directly through its own case or via a bulk notification to the client

Example

"id"

Types

EVSummarySortBy

Fields

Input Field	Description
`field` - `EVSummarySorts!`
`direction` - `SortDirection`

Example

{"field": "id", "direction": "asc"}

Types

EVSummarySorts

Description

Fields available by which to sort emerging vulnerability summaries; default: title/asc

Values

Enum Value	Description
`id`
`title`
`notificationDate`
`versionIdentified`
`numOfThirdPartiesIdentified`
`numOfThirdPartiesNotified`
`numOfThirdPartiesAcknowledged`
`numOfThirdPartiesMitigated`

Example

"id"

Types

EmailSaasInsight

Description

Insight indicating that an email Saas solution was detected on a domain in a monitored company's footprint (or, with finding code 2000037, that no email security was detected for domain)

Fields

Field Name	Description
`bvid` - `UUID!`	The unique BlueVoyant identifier (BV ID) of the company associated with this insight
`domain` - `String!`	The company footprint's domain on which a Saas solution was detected
`match` - `String`	The term that matched and found the Saas solution
`findingCode` - `Int64!`	Finding code is an integer that represents the specific type of a finding. See the dictionary query and the DataDictionary type.
`category` - `String`	The category associated with the product
`vendor` - `String`	Name of the vendor providing the Saas solution
`product` - `String`	The SaaS solution product detected
`updatedTS` - `Time!`	The time the insight was last updated
`lastObservedTS` - `Time!`	The time the insight was last observed
`company` - `CompanyByService`	Company associated with the insight

Example

{
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "domain": "xyz789",
  "match": "xyz789",
  "findingCode": 123,
  "category": "xyz789",
  "vendor": "abc123",
  "product": "abc123",
  "updatedTS": "2024-02-06T20:24:21Z",
  "lastObservedTS": "2024-02-06T20:24:21Z",
  "company": Company
}

Types

EmailSaasInsightsInfo

Description

This is the holder for email Saas insights from the insightsInfo query, with pagination and counts

Fields

Field Name	Description
`EmailSaasInsights` - `[EmailSaasInsight!]`	An array of email SaaS insights with whatever filters applied.
`totalCount` - `Int64!`	The total number of objects that fit the filter given regardless of limit.
`pageLength` - `Int!`	The total amount of objects returned to user. Between zero and the limit provided.

Example

{
  "EmailSaasInsights": [EmailSaasInsight],
  "totalCount": 123,
  "pageLength": 987
}

Types

EmailSaasSort

Values

Enum Value	Description
`category`	The category associated with the product
`vendor`	The category associated with the product
`product`	The product detected
`updatedTS`	The time the insight was last updated (process date)
`findingCode`	Finding code is an integer that represents the specific type of a finding. See the dictionary query and the DataDictionary type.
`bvid`	The unique BlueVoyant identifier (BV ID) of the company associated with this insight
`companyName`	Primary name of the company
`portfolioName`	Name of the portfolio containing the company
`lastObservedTS`	The last time this specific insight was observed or validated

Example

"category"

Types

EmailSaasSortBy

Fields

Input Field	Description
`field` - `EmailSaasSort!`	Field by which to sort vendors. Default = `updatedTS`
`direction` - `SortDirection`	Direction in which to sort vendors (asc/desc). Default = `asc`

Example

{"field": "category", "direction": "asc"}

Types

EmergingVulnerability

Description

Information about emerging vulnerabilities detected for a company. Generally these are recently revealed vulnerabilities that our analysts have manually located in our data and are not yet available as findings. This is the company-specific detail.

Fields

Field Name	Description
`id` - `ID!`	Unique ID of the emerging vulnerability
`title` - `String!`	Title of the emerging vulnerability
`description` - `String`	Description of the emerging vulnerability
`bvid` - `UUID!`	BV ID of the associated company (third party)
`primaryName` - `String!`	Primary name of the associated company
`firstEscalationDate` - `String`
`lastEscalationDate` - `String`
`thirdPartyAcknowledgedDate` - `String`
`thirdPartyMitigatedDate` - `String`
`emailsSent` - `Int!`	Number of notification emails sent regarding the associated company (third party), either to the company directly through its own case or via a bulk notification to the client. If the number of emails sent is at least 1, the company is considered 'notified.'
`company` - `CompanyFromSearchResult`	Company associated with the emerging vulnerability. At this time, only companies currently in the client's external_regular portfolios appear here (type Company).

Example

{
  "id": 4,
  "title": "abc123",
  "description": "xyz789",
  "bvid": "15218dcb-f184-41f1-ac33-a5a3368afd9c",
  "primaryName": "abc123",
  "firstEscalationDate": "2022-11-30T21:15:13Z",
  "lastEscalationDate": "2022-11-30T21:15:13Z",
  "thirdPartyAcknowledgedDate": "2022-11-30T21:15:13Z",
  "thirdPartyMitigatedDate": "2022-11-30T21:15:13Z",
  "emailsSent": 123,
  "company": Company
}

Types

EmergingVulnerabilityDetailFilter

Description

Fields available by which to filter emerging vulnerability details (companies/third parties) under the EmergingVulnerabilitySummary type in the emergingVulnerabilitySummaryInfo query.

Fields

Input Field	Description
`bvids` - `[UUID!]`	BVIDs to filter on. Default = `null`
`minFirstEscalationDate` - `String`	Min first escalation date to filter on for emerging vulnerability details. Default = `null`
`maxFirstEscalationDate` - `String`	Max first escalation date to filter on for emerging vulnerability details. Default = `null`
`minLastEscalationDate` - `String`	Min last escalation date to filter on for emerging vulnerability details. Default = `null`
`maxLastEscalationDate` - `String`	Max last escalation date to filter on for emerging vulnerability details. Default = `null`
`thirdPartyAcknowledged` - `Boolean`	Filter upon the third party acknowledged boolean value. Default = `null`
`thirdPartyMitigated` - `Boolean`	Filter upon the third party mitigated boolean value. Default = `null`
`minEmailsSent` - `Int`	Filter on the minimum number of emails sent for emerging vulnerability details. If the number of emails sent is at least 1, the company is considered 'notified.'. Default = `null`
`maxEmailsSent` - `Int`	Filter on the maximum number of emails sent to filter sent for emerging vulnerability details. Default = `null`
`portfolioUuids` - `[UUID!]`	Limit displayed emerging vulnerabilities to those associated with companies currently in the specified external portfolios. Default = `null`
`attributes` - `[String!]`	Limit displayed emerging vulnerabilities to those associated with companies with the specified attributes in the client's external portfolios. Default = `null`

Example

{
  "bvids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "minFirstEscalationDate": "xyz789",
  "maxFirstEscalationDate": "abc123",
  "minLastEscalationDate": "abc123",
  "maxLastEscalationDate": "abc123",
  "thirdPartyAcknowledged": true,
  "thirdPartyMitigated": true,
  "minEmailsSent": 123,
  "maxEmailsSent": 987,
  "portfolioUuids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "attributes": ["abc123"]
}

Types

EmergingVulnerabilityFilter

Description

Fields available by which to filter emerging vulnerability details

Fields

Input Field	Description
`ids` - `[Int!]`
`titles` - `[String!]`	titles does a wildcard match on each provided title. Default = `null`
`bvids` - `[UUID!]`
`minFirstEscalationDate` - `String`
`maxFirstEscalationDate` - `String`
`minLastEscalationDate` - `String`
`maxLastEscalationDate` - `String`
`thirdPartyAcknowledged` - `Boolean`
`thirdPartyMitigated` - `Boolean`
`minEmailsSent` - `Int`	Filter on the minimum number of emails sent for emerging vulnerability details. If the number of emails sent is at least 1, the company is considered 'notified.'. Default = `null`
`maxEmailsSent` - `Int`	Filter on the maximum number of emails sent for emerging vulnerability details. Default = `null`
`portfolioUuids` - `[UUID!]`	Limit displayed emerging vulnerabilities to those associated with companies currently in the specified external portfolios. Default = `null`
`attributes` - `[String!]`	Limit displayed emerging vulnerabilities to those associated with companies with the specified attributes in the client's external portfolios. Default = `null`
`sortBy` - `[EVSortBy]`

Example

{
  "ids": [987],
  "titles": ["abc123"],
  "bvids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "minFirstEscalationDate": "xyz789",
  "maxFirstEscalationDate": "xyz789",
  "minLastEscalationDate": "abc123",
  "maxLastEscalationDate": "abc123",
  "thirdPartyAcknowledged": false,
  "thirdPartyMitigated": false,
  "minEmailsSent": 987,
  "maxEmailsSent": 123,
  "portfolioUuids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "attributes": ["xyz789"],
  "sortBy": [EVSortBy]
}

Types

EmergingVulnerabilityInfo

Description

This is the holder for emerging vulnerability details detected for a company, with pagination and counts

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`	Offset and limit echo back the parameters
`totalCount` - `Int!`	Count of emerging vulnerabilities matching filter regardless of whether they fit within limit
`pageLength` - `Int!`	Count of emerging vulnerabilities returned
`emergingVulnerabilities` - `[EmergingVulnerability!]`

Example

{
  "offset": 123,
  "limit": 987,
  "totalCount": 987,
  "pageLength": 987,
  "emergingVulnerabilities": [EmergingVulnerability]
}

Types

EmergingVulnerabilitySummary

Description

This is the emerging vulnerability summary, containing general information about the emerging vulnerability and the number of third parties (monitored companies) affected by it, if any.

Fields

Field Name	Description
`id` - `ID!`	Unique ID of the emerging vulnerability
`title` - `String!`	Title of the emerging vulnerability
`description` - `String`	Description of the emerging vulnerability
`notificationDetails` - `String`	Markdown text of the generic portion of the notification email sent to clients about the emerging vulnerability
`versionIdentified` - `Boolean`	Whether the version of the software affected by the emerging vulnerability was identified
`notificationDate` - `String`	Date the emerging vulnerability was published
`numOfThirdPartiesIdentified` - `Int!`	Number of companies (third parties) that have been identified as being affected by this emerging vulnerability
`numOfThirdPartiesNotified` - `Int!`	Number of companies (third parties) that have had at least one email sent regarding this emerging vulnerability, either to them directly through their own cases or via a bulk notification to the client
`numOfThirdPartiesAcknowledged` - `Int!`	Number of companies (third parties) that have acknowledged a notification of this emerging vulnerability
`numOfThirdPartiesMitigated` - `Int!`	Number of companies (third parties) that have mitigated this emerging vulnerability
`cves` - `[CVE!]`	Array of associated CVEs
`productsAffected` - `[String!]`	Array of products affected for the emerging vulnerability
`findingsFirstAddedTS` - `String`	Timestamp when any findings were first associated with the emerging vulnerability
`findingCodes` - `[Int64!]`	Array of finding codes associated with this emerging vulnerability
`emergingVulnerabilityInfo` - `EmergingVulnerabilityInfo`	Emerging vulnerability details (companies/third parties) associated with the emerging vulnerability
Arguments `sortBy` - `[EVSortBy]` Allows sorting of emergency vulnerability details based off of the fields in the EVSorts type `offset` - `Int` Offset is per emerging vulnerability (ID) `limit` - `Int` Limit is per emerging vulnerability (ID)

Example

{
  "id": "4",
  "title": "abc123",
  "description": "xyz789",
  "notificationDetails": "abc123",
  "versionIdentified": true,
  "notificationDate": "2022-11-30T21:15:13Z",
  "numOfThirdPartiesIdentified": 987,
  "numOfThirdPartiesNotified": 987,
  "numOfThirdPartiesAcknowledged": 987,
  "numOfThirdPartiesMitigated": 987,
  "cves": [CVE],
  "productsAffected": ["xyz789"],
  "findingsFirstAddedTS": "abc123",
  "findingCodes": [123],
  "emergingVulnerabilityInfo": EmergingVulnerabilityInfo
}

Types

EmergingVulnerabilitySummaryFilter

Description

Fields available by which to filter emerging vulnerability summary information. Null dates are assumed to indicate no restriction on date. Date in 'YYYY-MM-DD' format. Nulls for other parameters indicate no restriction in that dimension.

If portfolioUuids and attributes are used, emerging vulnerabilites will be limited to those associated with the companies in the portfolios or with the attributes. Without these filters, all emerging vulnerabilities (matching the other filters, if any) will be returned, regardless of whether any of the client's companies are affected by them. (In other words, with those filters, the number of third parties identified will be at least one.)

Fields

Input Field	Description
`ids` - `[Int!]`	Limit returned emerging vulnerability summaries to the specified IDs. Default = `null`
`titles` - `[String!]`	Limit returned emerging vulnerability summaries to the specified titles, with a wildcard search. Default = `null`
`minNotificationDate` - `String`
`maxNotificationDate` - `String`
`versionIdentified` - `Boolean`
`minNumOfThirdPartiesIdentified` - `Int`
`maxNumOfThirdPartiesIdentified` - `Int`
`minNumOfThirdPartiesNotified` - `Int`
`maxNumOfThirdPartiesNotified` - `Int`
`minNumOfThirdPartiesAcknowledged` - `Int`
`maxNumOfThirdPartiesAcknowledged` - `Int`
`minNumOfThirdPartiesMitigated` - `Int`
`maxNumOfThirdPartiesMitigated` - `Int`
`portfolioUuids` - `[UUID!]`	Limit returned emerging vulnerability summaries to those associated with companies currently in the specified (external_regular) portfolios. Default = `null`
`attributes` - `[String!]`	Limit returned emerging vulnerability summaries to those associated with companies with the specified attributes in the client's (external_regular) portfolios. Default = `null`
`sortBy` - `[EVSummarySortBy]`	Fields by which to sort emerging vulnerability summaries

Example

{
  "ids": [123],
  "titles": ["abc123"],
  "minNotificationDate": "xyz789",
  "maxNotificationDate": "abc123",
  "versionIdentified": true,
  "minNumOfThirdPartiesIdentified": 987,
  "maxNumOfThirdPartiesIdentified": 987,
  "minNumOfThirdPartiesNotified": 123,
  "maxNumOfThirdPartiesNotified": 123,
  "minNumOfThirdPartiesAcknowledged": 123,
  "maxNumOfThirdPartiesAcknowledged": 123,
  "minNumOfThirdPartiesMitigated": 123,
  "maxNumOfThirdPartiesMitigated": 123,
  "portfolioUuids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "attributes": ["abc123"],
  "sortBy": [EVSummarySortBy]
}

Types

EmergingVulnerabilitySummaryInfo

Description

This is the holder for emerging vulnerability summaries, with pagination and counts

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`	Offset and limit echo back the parameters
`totalCount` - `Int!`	Count of emerging vulnerability summaries matching filter regardless of whether they fit within limit
`pageLength` - `Int!`	Count of emerging vulnerability summaries returned
`emergingVulnerabilitySummaries` - `[EmergingVulnerabilitySummary!]`	Summary information about each emerging vulnerability, as well as affected companies/third parties

Example

{
  "offset": 987,
  "limit": 123,
  "totalCount": 123,
  "pageLength": 123,
  "emergingVulnerabilitySummaries": [
    EmergingVulnerabilitySummary
  ]
}

Types

EscalatedFindingCount

Description

Escalated finding types and counts returned from the caseStatistics query as part of the CaseStatistics type.

Fields

Field Name	Description
`findingCode` - `Int!`	Finding code is an integer that represents the specific type of a finding. See the dictionary query and the DataDictionary type.
`findingSummary` - `String!`
`findingAbbreviation` - `String`	Short mnemonic intended for critical findings only. Will be null, a lot.
`findingSeverity` - `RiskLevel!`
`zeroTolerance` - `Boolean`
`count` - `Int`	Number of escalated findings

Example

{
  "findingCode": 987,
  "findingSummary": "xyz789",
  "findingAbbreviation": "abc123",
  "findingSeverity": "low",
  "zeroTolerance": false,
  "count": 987
}

Types

EscalationPath

Description

Where the ROC will send escalations

Values

Enum Value	Description
`directTo3rdParty`
`viaClient`
`mixed`
`unset`

Example

"directTo3rdParty"

Types

ExposureData

Description

Fourth-party data breaches that may affect the company

Fields

Field Name	Description
`domain` - `String!`
`breachDate` - `String!`
`breachName` - `String`
`description` - `String`
`numberOfCompanyAccountsExposed` - `Int`

Example

{
  "domain": "abc123",
  "breachDate": "abc123",
  "breachName": "xyz789",
  "description": "abc123",
  "numberOfCompanyAccountsExposed": 123
}

Types

ExposureDataWithCompany

Description

A fourth party exposure datum paired with the company it's about

Fields

Field Name	Description
`exposureData` - `ExposureData!`
`company` - `Company!`

Example

{
  "exposureData": ExposureData,
  "company": Company
}

Types

ExposureDataWithCompanyInfo

Fields

Field Name	Description
`totalCount` - `Int64!`	Total amount of exposures by company.
`pageLength` - `Int!`	Count of exposures with applied offset and limit filter.
`exposures` - `[ExposureDataWithCompany!]`	list of fourth party exposures by company.

Example

{
  "totalCount": 123,
  "pageLength": 123,
  "exposures": [ExposureDataWithCompany]
}

Types

ExposureSort

Description

Fields available for sorting fourth party exposure items

Values

Enum Value	Description
`breachDate`
`breachName`
`description`
`breachCount`
`domain`

Example

"breachDate"

Types

Finding

Description

Part of the FindingInfo type, returned by the findingInfo query.

Fields

Field Name	Description
`findingCode` - `Int`	Finding code is an integer that represents the specific type of a finding. See the dictionary query and the DataDictionary type.
`findingHash` - `String`	An ID of int64 type that is unique for a BV ID, variant, and finding code
`detailInfo` - `DetailInfo`	Details (observations) associated with finding
Arguments `filter` - `DetailFilter` Filter or sort details `offset` - `Int` Skip offset detail items before returning up to limit, applied per finding hash `limit` - `Int` Skip offset detail items before returning up to limit, applied per finding hash
`category` - `RiskCategory`	A risk category for a finding
`findingEscalationStatus` - `FindingEscalationStatus`	The escalation status of the finding with respect to the client
`findingStatus` - `FindingStatus`	Whether the finding is open or closed
`inReviewTS` - `Time`
`escalatedToClientTS` - `Time`
`escalatedToVendorTS` - `Time`
`firstOverdueTS` - `Time`
`firstInDisputeTS` - `Time`
`firstPendingTS` - `Time`
`firstResolvedTS` - `Time`
`numberOfDetails` - `Int`
`numberDomainsAffected` - `Int`
`numberIpsAffected` - `Int`
`assetsAffected` - `Int`
`riskLevel` - `RiskLevel`	A bucketing of the risk level
`scoreImpact` - `Float`	The impact of a finding on the overall company risk score
`analyst_comment` - `String`
`summary` - `String`	A summary of the finding
`description` - `String`	A long description of the finding
`actionSummary` - `String`	A summary of the recommended action that should be taken to close the finding
`recommendation` - `String`	The recommended action that should be taken to close the finding
`zeroTolerance` - `Boolean`	Zero-tolerance findings are finding types that are often involved in ransomware incidents, or that can indicate a possible ongoing malware infection or a serious zero-day alert
`findingLastUpdated` - `String`
`findingTimeCreated` - `String`
`cases` - `[Case!]`	ServiceNOW cases associated with this finding
`messages` - `[Message!]`	Up to n messages between ROC and clients, in time order (most recent first)
Arguments `n` - `Int!` Maximum number of items to return per finding hash. Default: 0
`thirdPartyMessageInfo` - `FindingMessageInfo`	Messages between ROC and third party, in time order (most recent first). The limits and offset are applied per finding. This field is restricted to Monitored_Company (third-party) users with a third_party* role.
Arguments `offset` - `Int!` Skip offset message items before returning up to limit. Applied per finding `limit` - `Int` Skip offset message items before returning up to limit. Applied per finding
`evidence` - `RawJSON`	Evidence added by our Risk Operations Center
`recentActivity` - `[History!]`	Events or changes associated with this finding hash, in time order (most recent first)
Arguments `n` - `Int!` Maximum number of items to return per finding hash. Default: 0
`cpeCVE` - `[CPECVE!]`	CPE and CVEs known to relate to this finding
`domains` - `[DomainInfo!]`	Registration information about domains in this finding
`ips` - `[IPInfo!]`	Registration information about IP addresses/ranges in this finding
`portfolioName` - `String`
`portfolioUuid` - `UUID`
`isEscalated` - `Boolean`	Finding is escalated for this client
`isEscalatedAnyClient` - `Boolean`	Finding is escalated for any client. This field is restricted to Monitored_Company (third-party) users with a third_party* role.
`lastObserved` - `String`
`firstEscalatedTS` - `String`	First escalated timestamp on the finding's active case, if there is one
`lastEscalatedTS` - `String`	Last escalated timestamp on the finding's active case, if there is one
`automatedFollowUpCount` - `Int`	Number of automated follow-ups on the finding's active case, if there is one
`emailsSent` - `Int`	Number of follow-up emails sent on the finding's active case, if there is one
`daysSinceFirstEscalated` - `Int`	Number of days since the finding's active case, if there is one, was first escalated
`waitingFor` - `WaitingFor!`	If set, progress on the finding is blocked on this party
`thirdPartyDisposition` - `ThirdPartyDisposition`	The disposition set by the third party for dealing with the finding
`thirdPartyEscalationDueDate` - `Time`	The date set by the third party for dealing with the finding
`thirdPartyEscalationComment` - `String`	A comment set by the third party about the finding
`thirdPartyEscalationStatus` - `FindingEscalationStatus`	The escalation status of the finding from the perspective of the third party. This field is restricted to Monitored_Company (third-party) users with a third_party* role.
`company` - `Company!`

Example

{
  "findingCode": 123,
  "findingHash": 9039052908188215000,
  "detailInfo": DetailInfo,
  "category": "AdversarialThreats",
  "findingEscalationStatus": "Pending",
  "findingStatus": "open",
  "inReviewTS": "0",
  "escalatedToClientTS": "0",
  "escalatedToVendorTS": "0",
  "firstOverdueTS": "0",
  "firstInDisputeTS": "0",
  "firstPendingTS": "0",
  "firstResolvedTS": "0",
  "numberOfDetails": 987,
  "numberDomainsAffected": 987,
  "numberIpsAffected": 987,
  "assetsAffected": 123,
  "riskLevel": "low",
  "scoreImpact": 123.45,
  "analyst_comment": "abc123",
  "summary": "abc123",
  "description": "xyz789",
  "actionSummary": "abc123",
  "recommendation": "abc123",
  "zeroTolerance": false,
  "findingLastUpdated": "abc123",
  "findingTimeCreated": "xyz789",
  "cases": [Case],
  "messages": [
    {
      "source": "BlueVoyant Risk Service<[email protected]>",
      "message": "Some message in **markdown** here",
      "timestamp": "2023-11-27T15:28:10.642546+00:00"
    }
  ],
  "thirdPartyMessageInfo": FindingMessageInfo,
  "evidence": {"key1": [1, 2, 3], "key2": "strVal", "key3": true},
  "recentActivity": [History],
  "cpeCVE": [CPECVE],
  "domains": [DomainInfo],
  "ips": [IPInfo],
  "portfolioName": "abc123",
  "portfolioUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "isEscalated": false,
  "isEscalatedAnyClient": true,
  "lastObserved": "xyz789",
  "firstEscalatedTS": "2022-11-30T21:15:13Z",
  "lastEscalatedTS": "2022-12-01T19:10:10Z",
  "automatedFollowUpCount": 987,
  "emailsSent": 987,
  "daysSinceFirstEscalated": 987,
  "waitingFor": "BlueVoyant",
  "thirdPartyDisposition": "NotAPriority",
  "thirdPartyEscalationDueDate": "2024-02-06T00:00:00Z",
  "thirdPartyEscalationComment": "abc123",
  "thirdPartyEscalationStatus": "Pending",
  "company": Company
}

Types

FindingEscalationStatus

Description

The current state of ROC interaction with the finding

Values

Enum Value	Description
`Pending`
`Overdue`
`In_Dispute`
`Escalation_Resolved`
`Unset`
`Resolved_Not_Escalated`
`Risk_Accepted`
`Waiting_for_Third_Party_Response`
`In_Review`
`Escalated_to_Client`

Example

"Pending"

Types

FindingEscalationUpdateThirdParty

Description

Input to allow a third party to update the disposition of an escalated finding

Fields

Input Field	Description
`findingHash` - `String!`	An ID of int64 type that is unique for a BV ID, variant, and finding code
`disposition` - `ThirdPartyDisposition`	How/whether the third party/monitored company is dealing with the finding
`escalationDueDate` - `Time`	Date by which the third party plans to deal with the finding (thirdPartyEscalationDueDate field in findings)
`escalationComment` - `String`	Comment from the third party about the finding (thirdPartyEscalationComment field in findings)

Example

{
  "findingHash": 9039052908188215000,
  "disposition": "NotAPriority",
  "escalationDueDate": "2024-02-06",
  "escalationComment": "xyz789"
}

Types

FindingFilter

Description

null for no restriction

This doesn't include things no-one uses in the current risk API.

It also doesn't include things that just filter companies.

Where a field is specified, only select rows with a value matching one of those in the set specified. Only return rows for which all per-field constraints are met.

Fields

Input Field	Description
`findingCodes` - `[Int!]`	Finding code is an integer that represents the specific type of a finding. See the dictionary query and the DataDictionary type. Default = `null`
`findingHashes` - `[String!]`	An ID of int64 type that is unique for a BV ID, variant, and finding code. Default = `null`
`riskLevels` - `[RiskLevel!]`	A bucketing of the risk level. Default = `null`
`riskCategories` - `[RiskCategory!]`
`statuses` - `[FindingStatus!]`	Whether the finding is open or closed. Default = `null`
`escalationStatuses` - `[FindingEscalationStatus!]`	The escalation status of the finding with respect to the client. Default = `null`
`thirdPartyDispositions` - `[ThirdPartyDisposition!]`	The disposition set by the third party for dealing with the finding. Default = `null`
`thirdPartyEscalationStatuses` - `[FindingEscalationStatus!]`	The escalation status of the finding from the perspective of the third party. This field is restricted to Monitored_Company (third-party) users with a third_party* role. Default = `null`
`waitingFors` - `[WaitingFor!]`
`isEscalated` - `Boolean`	Whether the finding has been escalated for the client. Default = `null`
`isEscalatedAnyClient` - `Boolean`	Whether the finding has been escalated for any client. This field is restricted to Monitored_Company (third-party) users with a third_party* role. Default = `null`
`zeroTolerance` - `Boolean`
`sortBy` - `[FindingSortBy]`
`minLastObservedTS` - `String`
`maxLastObservedTS` - `String`
`minFirstEscalatedTS` - `Time`	Filter to findings with an active case that was first escalated on or after timestamp. Default = `null`
`maxFirstEscalatedTS` - `Time`	Filter to findings with an active case that was first escalated before or on timestamp. Default = `null`

Example

{
  "findingCodes": [987],
  "findingHashes": ["-5528334538427616940"],
  "riskLevels": ["low"],
  "riskCategories": ["AdversarialThreats"],
  "statuses": ["open"],
  "escalationStatuses": ["Pending"],
  "thirdPartyDispositions": ["NotAPriority"],
  "thirdPartyEscalationStatuses": ["Pending"],
  "waitingFors": ["BlueVoyant"],
  "isEscalated": false,
  "isEscalatedAnyClient": true,
  "zeroTolerance": true,
  "sortBy": [FindingSortBy],
  "minLastObservedTS": "2024-04-06T20:24:21Z",
  "maxLastObservedTS": "2024-05-06T00:00:00Z",
  "minFirstEscalatedTS": "2024-04-06T20:24:21Z",
  "maxFirstEscalatedTS": "2024-05-06T00:00:00Z"
}

Types

FindingInfo

Description

This is the holder for findings, from a findingInfo query, with pagination and counts

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`	Limit and offset echo back the parameters
`totalCount` - `Int!`	Count of findings matching filter regardless of whether they fit within limit
`pageLength` - `Int!`	Count of findings returned
`findings` - `[Finding!]`

Example

{
  "offset": 123,
  "limit": 987,
  "totalCount": 987,
  "pageLength": 123,
  "findings": [Finding]
}

Types

FindingMessage

Description

A finding message is a message from a client about a finding

Fields

Input Field	Description
`findingHash` - `String!`	An ID of int64 type that is unique for a BV ID, variant, and finding code
`message` - `String!`	Message to be appended to finding

Example

{
  "findingHash": 9039052908188215000,
  "message": "abc123"
}

Types

FindingMessageData

Description

This is a single message in the messages array of the FindingMessageInfo type

Fields

Field Name	Description
`messageSource` - `String!`	The source/sender of the message
`message` - `String!`	The message itself, in markdown format
`timestamp` - `Time!`	The timestamp of the message

Example

{
  "messageSource": "BlueVoyant Risk Service<[email protected]>",
  "message": "Some message in **markdown** here",
  "timestamp": "2025-01-14T19:53:12Z"
}

Types

FindingMessageInfo

Description

This is the holder for messages about a finding, with pagination and counts, returned by the thirdPartyMessageInfo part of the Finding type that is returned from the findingInfo query.

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters. Applied per finding
`limit` - `Int`	Offset and limit echo back the parameters. Applied per finding
`totalCount` - `Int64!`	Total count of messages
`pageLength` - `Int!`	Number of messages returned
`messages` - `[FindingMessageData!]`	Messages returned

Example

{
  "offset": 987,
  "limit": 987,
  "totalCount": 123,
  "pageLength": 987,
  "messages": [FindingMessageData]
}

Types

FindingSortBy

Fields

Input Field	Description
`field` - `FindingSorts!`	Field by which to sort findings
`direction` - `SortDirection`	Direction in which to sort findings (asc/desc). Default = `asc`

Example

{"field": "scoreImpact", "direction": "asc"}

Types

FindingSorts

Description

Fields available to sort findings by; default: scoreImpact

Values

Enum Value	Description
`scoreImpact`	The impact of a finding on the overall company risk score. Default sort field
`scoreImpactTotal`	Deprecated. Same as scoreImpact Use 'scoreImpact'
`primaryName`	Primary name of the company
`summary`
`assessmentDateBegin`	The start of the scoring assessment period.
`severityLabel`
`actionSummary`	A summary of the recommended action that should be taken to close the finding
`findingHash`	An ID of int64 type that is unique for a BV ID, variant, and finding code
`escalationStatus`	The escalation status of the finding with respect to the client (the findingEscalationStatus field)
`thirdPartyEscalationStatus`	The escalation status of the finding from the perspective of the third party
`attribute`
`portfolioName`
`riskCategory`
`status`
`firstEscalatedTS`	First escalated timestamp on the finding's active case, if there is one
`lastEscalatedTS`	Last escalated timestamp on the finding's active case, if there is one
`lastObservedTS`	Last observed timestamp on the finding
`automatedFollowUpCount`	Number of automated follow-ups on the finding's active case, if there is one
`emailsSent`	Number of follow-up emails sent on the finding's active case, if there is one
`daysSinceFirstEscalated`	Number of days since the finding's active case, if there is one, was first escalated
`zeroTolerance`
`assetsAffected`	Domains affected + IPs affected.
`findingTimeCreated`

Example

"scoreImpact"

Types

FindingStatus

Description

Closed findings are stored but do not affect score

Values

Enum Value	Description
`open`
`closed`

Example

"open"

Types

FirmographicData

Description

The firmographic data for a company

Fields

Field Name	Description
`employeeRange` - `String`
`revenueRange` - `String`
`naicsCode` - `String`
`naicsDescription` - `String`
`sicCode` - `String`
`sicDescription` - `String`
`companyDescription` - `String`
`website` - `String`
`city` - `String`
`state` - `String`
`country` - `String`
`industryCode` - `String`
`industryDescription` - `String`

Example

{
  "employeeRange": "abc123",
  "revenueRange": "abc123",
  "naicsCode": "abc123",
  "naicsDescription": "xyz789",
  "sicCode": "xyz789",
  "sicDescription": "abc123",
  "companyDescription": "xyz789",
  "website": "abc123",
  "city": "abc123",
  "state": "abc123",
  "country": "xyz789",
  "industryCode": "abc123",
  "industryDescription": "xyz789"
}

Types

Float

Description

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

Example

123.45

Types

FootprintSummary

Description

Summary information about a footprint, which is part of the Company type. Also see the DomainInfo and IPInfo types.

Fields

Field Name	Description
`totalIpCount` - `Int64`	Total number of unique IP addresses in the footprint
`totalIpRangeCount` - `Int`	Total number of IP ranges/CIDRs (records) in the footprint
`totalDomainCount` - `Int`	Total number of domains in the footprint
`totalCountryCount` - `Int`	Total number of countries associated with the geographical location of the IP addresses in the footprint
`countryCodes` - `[String!]`	A unique set of country codes associated with the geographical location of the IP addresses in the footprint
`countryIpCounts` - `[CountryIPCount!]`	Countries associated with the geographical location of the IP addresses from the footprint, and the number of IP addresses per country
`finalizedTS` - `Time`	The date this footprint version was completed and sent for scoring for the first time

Example

{
  "totalIpCount": 123,
  "totalIpRangeCount": 123,
  "totalDomainCount": 987,
  "totalCountryCount": 123,
  "countryCodes": ["GB", "US"],
  "countryIpCounts": [CountryIPCount],
  "finalizedTS": "2024-02-06T20:24:21Z"
}

Types

FourthPartyExposureInsights

Description

A collection of fourth party exposure organized by finding code. Includes finding code's description, summary, and assessment date.

Fields

Field Name	Description
`summary` - `String`	A brief summary of the finding code
`description` - `String`	A description of what the finding code is.
`assessmentDateEnd` - `String`	The most recent assessment date
`findingCode` - `Int64`	The finding code of these vendor discoveries.
`exposureData` - `[ExposureData]`	List of exposures of a specific finding code

Example

{
  "summary": "xyz789",
  "description": "xyz789",
  "assessmentDateEnd": "xyz789",
  "findingCode": 123,
  "exposureData": [ExposureData]
}

Types

FourthPartyExposureSortBy

Description

Specify sort field and direction when selecting fourthPartyExposure objects

Fields

Input Field	Description
`field` - `ExposureSort!`
`direction` - `SortDirection`

Example

{"field": "breachDate", "direction": "asc"}

Types

Function

Description

SCD portal/API functions that users can have, and that are used to manage SCD API access and portal functionality. Functions correspond to categories of API endpoints and GraphQL operations, and flow from the particular RolePolicyPermissions in a user's role(s). 'admin' will appear if the user has either temporary admin privileges from the adminOn mutation or permanent privileges from a role.

Fields

Field Name	Description
`name` - `String!`	Function name

Example

{"name": "xyz789"}

Types

GDD

Description

GDD Data are no longer available as of 2024-02-01

Fields

Field Name	Description
`familyVersion` - `[GDDFamilyVersion!]`	GDD Data are no longer available as of 2024-02-01.
`observations` - `[GDDObservations!]`	GDD Data are no longer available as of 2024-02-01.
`ips` - `[GDDIps!]`	List IPs as dotted quad strings if you want to limit to only matching IPs. Returns all IPs that have at least one observation in the specified time window GDD Data are no longer available as of 2024-02-01.
Arguments `only` - `[String!]`

Example

{
  "familyVersion": [GDDFamilyVersion],
  "observations": [GDDObservations],
  "ips": [GDDIps]
}

Types

GDDFamilyVersion

Description

GDD Data are no longer available as of 2024-02-01

Fields

Field Name	Description
`cpeType` - `CPEType!`
`isUnsupported` - `Boolean!`
`observationTimestampFirst` - `String!`
`observationTimestampLast` - `String!`
`cpeFamily` - `CPEFamily!`
`cpeVersion` - `String!`
`observationTimesSeen` - `Int!`
`uniqueIps` - `Int!`

Example

{
  "cpeType": "os_desktop",
  "isUnsupported": false,
  "observationTimestampFirst": "xyz789",
  "observationTimestampLast": "xyz789",
  "cpeFamily": "windows",
  "cpeVersion": "abc123",
  "observationTimesSeen": 123,
  "uniqueIps": 987
}

Types

GDDIps

Description

GDD Data are no longer available as of 2024-02-01

Fields

Field Name	Description
`cpeType` - `CPEType!`
`isUnsupported` - `Boolean!`
`observationTimestampFirst` - `String!`
`observationTimestampLast` - `String!`
`clientIp` - `String!`
`observationTimesSeen` - `Int!`

Example

{
  "cpeType": "os_desktop",
  "isUnsupported": true,
  "observationTimestampFirst": "abc123",
  "observationTimestampLast": "abc123",
  "clientIp": "abc123",
  "observationTimesSeen": 123
}

Types

GDDObservations

Description

GDD Data are no longer available as of 2024-02-01

Fields

Field Name	Description
`cpeType` - `CPEType!`
`isUnsupported` - `Boolean!`
`observationDate` - `String!`
`observationTimestampFirst` - `String!`
`observationTimestampLast` - `String!`
`numberOfDetails` - `Int!`

Example

{
  "cpeType": "os_desktop",
  "isUnsupported": true,
  "observationDate": "xyz789",
  "observationTimestampFirst": "xyz789",
  "observationTimestampLast": "abc123",
  "numberOfDetails": 123
}

Types

Group

Description

SCD portal/API groups that users can belong to, and that are used to manage SCD API access and portal functionality.

Fields

Field Name	Description
`uuid` - `UUID!`	Group ID in UUID format
`name` - `String!`	Group name
`description` - `String`	Description of group
`assignableFlag` - `Boolean!`	Whether group is assignable to users by client
`createdTS` - `String!`	Timestamp when created
`updatedTS` - `String!`	Timestamp when last updated
`createdBy` - `String!`	Username that created this item
`updatedBy` - `String!`	Username that last updated this item

Example

{
  "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "name": "abc123",
  "description": "xyz789",
  "assignableFlag": true,
  "createdTS": "xyz789",
  "updatedTS": "xyz789",
  "createdBy": "xyz789",
  "updatedBy": "xyz789"
}

Types

GroupFilter

Fields

Input Field	Description
`uuids` - `[UUID!]`	Filter groups by one or more IDs in UUID format. Default = `null`
`names` - `[String!]`	Filter groups by one or more names (wildcard matching). Default = `null`
`descriptions` - `[String!]`	Filter groups by one or more descriptions (wildcard matching). Default = `null`
`assignableFlag` - `Boolean`	Filter policy permissions by assignable flag (whether client can assign group to users). Default = `null`
`sortBy` - `[GroupSortBy]`	Sort returned groups by specified fields and directions

Example

{
  "uuids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "names": ["xyz789"],
  "descriptions": ["xyz789"],
  "assignableFlag": false,
  "sortBy": [GroupSortBy]
}

Types

GroupInfo

Description

This is the holder for groups, with pagination and counts

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`	Limit and offset echo back the parameters
`totalCount` - `Int!`	Count of groups matching filter regardless of whether they fit within limit
`pageLength` - `Int!`	Count of groups returned
`groups` - `[Group!]`	SCD portal/API groups

Example

{
  "offset": 123,
  "limit": 987,
  "totalCount": 123,
  "pageLength": 987,
  "groups": [Group]
}

Types

GroupSortBy

Fields

Input Field	Description
`field` - `GroupSorts!`	Field by which to sort groups
`direction` - `SortDirection`	Direction in which to sort groups (asc/desc). Default = `asc`

Example

{"field": "uuid", "direction": "asc"}

Types

GroupSorts

Description

Fields available by which to sort groups; default: uuid/asc

Values

Enum Value	Description
`uuid`	Group ID in UUID format
`name`	Name of group
`description`	Description of group
`assignableFlag`	Whether client can assign group to users

Example

"uuid"

Types

HistoricScore

Description

For now, this is only overall score (finding code 0) for a company on a particular date.

Fields

Field Name	Description
`scoreDate` - `String!`	Score is calculated based on data collected through the end of this date. Date is in 'YYYY-MM-DD' format
`findingCode` - `Int!`	Finding code is an integer that represents the specific type of a finding. Finding code 0 indicates the overall company score. See the dictionary query and the DataDictionary type.
`score` - `Float`
`findingStatusCode` - `Int`	A finding status code of 4 indicates low data/visibility; other codes indicate a valid score

Example

{
  "scoreDate": "2023-01-31",
  "findingCode": 0,
  "score": 94.72794,
  "findingStatusCode": 0
}

Types

History

Description

An event or change associated with a finding, returned from the recentActivity part of the Finding type, from the findingInfo query.

Fields

Field Name	Description
`id` - `String`	A unique ID for the event in UUID format
`message` - `String`	A short description of the change
`timestamp` - `String`	When the event occurred
`description` - `String`	A description of the change
`updateType` - `String`	The type of event or change, or the field that changed: 'analyst_comment', 'action_summary', 'Action Summary' (deprecated), 'finding_description', 'finding_status_code' (deprecated), 'resolution', 'Escalation Status' (deprecated in favor of 'resolution'). Deprecated values may still be found in older history items.
`updateValue` - `String`	The new value after the change

Example

{
  "id": "b605fdf7-dbce-4b42-bdbf-9c052f0a2a71",
  "message": "abc123",
  "timestamp": "2022-07-06T20:23:47.942826Z",
  "description": "abc123",
  "updateType": "xyz789",
  "updateValue": "abc123"
}

Types

HostingProvider

Description

The providers used by a company to host its domains and subdomains

Fields

Field Name	Description
`hostingProvider` - `String!`
`assetPercentage` - `Float!`	The number of hostnames that have been observed to be hosted within a given hosting provider relative to the total number of hostnames associated with the entity.
`hostnameCount` - `Int!`	The number of distinct DNS qnames
`resolutionPercentage` - `Float!`	The number of observations that were resolved by a given hosting provider (identified by IP address) relative to the total number of resolved observations for all hosting providers associated with the entity.

Example

{
  "hostingProvider": "xyz789",
  "assetPercentage": 987.65,
  "hostnameCount": 987,
  "resolutionPercentage": 987.65
}

Types

HostingProviderInfo

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`	Limit and offset echo back the parameters
`totalCount` - `Int64!`	Count of providers matching filter regardless of whether they fit within limit
`pageLength` - `Int!`	Count of providers returned
`hostingProviders` - `[HostingProvider!]`

Example

{
  "offset": 987,
  "limit": 987,
  "totalCount": 123,
  "pageLength": 987,
  "hostingProviders": [HostingProvider]
}

Types

HostingProviderSortBy

Fields

Input Field	Description
`field` - `HostingProviderSorts!`
`direction` - `SortDirection`

Example

{"field": "hostingProvider", "direction": "asc"}

Types

HostingProviderSorts

Description

Fields available by which to sort hosting providers; default: hostingProvider/asc

Values

Enum Value	Description
`hostingProvider`	Default, case-insensitive sort
`assetPercentage`
`hostnameCount`
`resolutionPercentage`

Example

"hostingProvider"

Types

ID

Description

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

Example

"4"

Types

IPFilter

Description

Filters for IP address/range info associated with a footprint

Fields

Input Field	Description
`countryCodes` - `[String!]`	Filter by exact, case-insensitive, two-letter (ISO 3166-1 alpha-2) country codes
`netGeoCountries` - `[String!]`	Filter by exact, case-insensitive, country names associated with the location of IP addresses

Example

{
  "countryCodes": ["abc123"],
  "netGeoCountries": ["xyz789"]
}

Types

IPInfo

Description

Registration and other information about an IP address or range

Fields

Field Name	Description
`ipRange` - `String!`	IP range as a string, either "start - end" or "start" if a /32
`address` - `String`	Registration street address - the location of the organization that registered the IP address
`certificates` - `[String]`
`cidr` - `String`
`city` - `String`	Registration city - the location of the organization that registered the IP address
`cloudProviderInfo` - `[CloudProviderInfo!]`
`country` - `String`	Registration country - the location of the organization that registered the IP address
`countryCode` - `String`	The current geographical location of an IP address, as a two-letter country code
`emails` - `[String]`	Registration emails
`ipEnd` - `String`	Last IP address of range
`ipStart` - `String`	First IP address of range
`latitude` - `Float`
`longitude` - `Float`
`netGeoCountry` - `String`	The current geographical location of an IP address
`netName` - `String`	Name given to the network (IP range) when it is registered
`registrar` - `String`
`registrantName` - `String`
`registrantOrganization` - `String`	Organization that registered the IP address or range
`state` - `String`	Registration state - the location of the organization that registered the IP address
`subdomains` - `[Subdomain!]`
`tags` - `[TagInfo!]`
`adminOrganization` - `String`
`ipCount` - `Int64!`	The number of IP addresses in the IP range/CIDR

Example

{
  "ipRange": "abc123",
  "address": "xyz789",
  "certificates": ["abc123"],
  "cidr": "abc123",
  "city": "xyz789",
  "cloudProviderInfo": [CloudProviderInfo],
  "country": "xyz789",
  "countryCode": "xyz789",
  "emails": ["xyz789"],
  "ipEnd": "xyz789",
  "ipStart": "xyz789",
  "latitude": 123.45,
  "longitude": 123.45,
  "netGeoCountry": "xyz789",
  "netName": "xyz789",
  "registrar": "xyz789",
  "registrantName": "xyz789",
  "registrantOrganization": "abc123",
  "state": "abc123",
  "subdomains": [Subdomain],
  "tags": [TagInfo],
  "adminOrganization": "xyz789",
  "ipCount": 123
}

Types

IPListInfo

Description

This is the holder for IP addresses or ranges, from a companyInfo query, with pagination and counts

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`	Limit and offset echo back the parameters
`totalCount` - `Int64!`	Count of IP address/range records matching filter regardless of whether they fit within limit
`pageLength` - `Int!`	Count of IP address/range records returned
`ips` - `[IPInfo!]`	IP address/range records in the company's footprint

Example

{
  "offset": 123,
  "limit": 123,
  "totalCount": 123,
  "pageLength": 987,
  "ips": [IPInfo]
}

Types

IPSortBy

Fields

Input Field	Description
`field` - `IPSorts!`
`direction` - `SortDirection`

Example

{"field": "ipInt", "direction": "asc"}

Types

IPSorts

Description

Fields used to sort IP addresses or range records

Values

Enum Value	Description
`ipInt`	Sort results in numeric (integer order by starting IP) order (default sort)
`netName`	Name given to the network (IP range) when it is registered
`registrantOrganization`	Organization that registered the IP address or range
`address`	Registration street address - the location of the organization that registered the IP address
`state`	Registration state - the location of the organization that registered the IP address
`country`	Registration country - the location of the organization that registered the IP address
`netGeoCountry`	The current geographical location of the IP address
`countryCode`	The current geographical location of the IP address, as a two-letter (ISO 3166-1 alpha-2) country code
`ipCount`	The number of IP addresses in the IP range/CIDR

Example

"ipInt"

Types

ISODuration

Description

Duration in ISO 8601 format - PT[n]H[n]M[n]S

Example

"PT25H10M02S"

Types

InsightsInfo

Description

Expose our insights. Returned from insightsInfo query

** Experimental **

Fields

Field Name	Description
`fourthPartyExposure` - `ExposureDataWithCompanyInfo`	Return data about "fourth party" exposure of credentials relating to companies in data breaches startDate and endDate are used to filter by breachDate, but these filters are optional.
Arguments `sortBy` - `[FourthPartyExposureSortBy]` `limit` - `Int` `offset` - `Int!`
`pdnsVendorDependency` - `PdnsVendorDependencyInfo`	Returns records of pDNS of vendors that clients are dependent on. Start and end date are used to filter by last observed date. if the end date is before the start date it will be treated as absent - i.e results will be returned up to the present
Arguments `filter` - `VendorDependencyFilter` `sortBy` - `[PdnsVendorDependencySortBy]` `offset` - `Int!` `limit` - `Int`
`vendorDependency` - `VendorDependencyInfo`	Returns records of vendors that clients are dependent on. No date filtering is applied. If the distinct object is not null that means the query will only return distinct values of the field you submit. If you don't submit one it will default to category. If you request any of the fields that are not the distinct field the query will return an empty string, a zero, or a null depending on the datatype of the field.
Arguments `filter` - `VendorDependencyFilter` `distinct` - `DistinctVendorDependency` `sortBy` - `[VendorDependencySortBy]` `offset` - `Int!` `limit` - `Int`
`vendorDependencyLegacy` - `VendorDependencyLegacyInfo`	Returns records of vendors that clients are dependent on. Uses the old vendor dependency v1 data. Use distinct flag to get distinct vendors only. Not available to public api.
Arguments `filter` - `VendorDependencyLegacyFilter` `Distinct` - `Boolean` `sortBy` - `[VendorDependencyLegacySortBy]` `offset` - `Int!` `limit` - `Int`
`categorySummarizedCount` - `CategorySummarizedCountInfo`	Count of unique categories for a client/portfolios. No date filtering is applied.
Arguments `filter` - `CategorySummarizedCountFilter` `sortBy` - `[CategorySummarizedCountSortBy]` `offset` - `Int!` `limit` - `Int`
`vendorSummarizedCount` - `VendorSummarizedCountInfo`	Count of unique vendors associated with each category for the client/portfolios. No date filtering is applied.
Arguments `filter` - `VendorSummarizedCountFilter` `sortBy` - `[VendorSummarizedCountSortBy]` `offset` - `Int!` `limit` - `Int`
`productSummarizedCount` - `ProductSummarizedCountInfo`	Count of unique products associated with each vendor and category for the client/portfolios. No date filtering is applied.
Arguments `filter` - `ProductSummarizedCountFilter` `sortBy` - `[ProductSummarizedCountSortBy]` `offset` - `Int!` `limit` - `Int`
`companiesSummarizedCount` - `CompanySummarizedCountInfo`	Get a list of all unique companies and their count for each product, category, and vendor. No date filtering is applied.
Arguments `filter` - `CompanySummarizedCountFilter` `sortBy` - `[CompanySummarizedCountSortBy]` `offset` - `Int!` `limit` - `Int`
`vendorDependencyCountsPerCategory` - `VendorDependencyCountsPerCategoryInfo`	Per-category count of vendors, products, and companies (sorted by category), from vendor dependency insights. Can be additionally filtered by portfolios, attributes, and BV IDs from the top-level filter. No date filtering is applied.
Arguments `filter` - `VendorDependencyCountFilter` `offset` - `Int!` Not used `limit` - `Int` Not used
`vendorDependencyCountsPerVendor` - `VendorDependencyCountsPerVendorInfo`	Per-vendor count of products and companies (sorted by vendor), from vendor dependency insights. Can be additionally filtered by portfolios, attributes, and BV IDs from the top-level filter. No date filtering is applied.
Arguments `filter` - `VendorDependencyCountFilter` `offset` - `Int!` Not used `limit` - `Int` Not used
`vendorDependencyCountsPerProduct` - `VendorDependencyCountsPerProductInfo`	Per-product count of companies (sorted by product), from vendor dependency insights. Can be additionally filtered by portfolios, attributes, and BV IDs from the top-level filter. No date filtering is applied.
Arguments `filter` - `VendorDependencyCountFilter` `offset` - `Int!` Not used `limit` - `Int` Not used
`emailSaasInsights` - `EmailSaasInsightsInfo`	Returns email Saas insights detected on domains
Arguments `filter` - `VendorDependencyFilter` `sortBy` - `[EmailSaasSortBy]` `offset` - `Int!` `limit` - `Int`
`emailSaasDomainWithoutSecurity` - `EmailSaasInsightsInfo`	Returns insights for when no email Saas solution was detected for domains
Arguments `filter` - `VendorDependencyFilter` `sortBy` - `[EmailSaasSortBy]` `offset` - `Int!` `limit` - `Int`
`bannerBusterInsights` - `BannerBusterInsightsInfo`	Returns the banner buster insights (insights detected on IP addresses/ports) Start and end date are used to filter by last observed date. if the end date is before the start date it will be treated as absent - i.e results will be returned up to the present
Arguments `filter` - `VendorDependencyFilter` `sortBy` - `[BannerBusterSortBy]` `offset` - `Int!` `limit` - `Int`
`businessRisk` - `BusinessRiskInsightInfo`	Return data about "business risk events" that are relevant to a particular client Date filtering is on the date field. Note the portfolio and attribute filtering semantics are still evolving. EXPERIMENTAL
Arguments `filter` - `BusinessRiskFilter` `sortBy` - `[BusinessRiskSortBy!]` `offset` - `Int!` `limit` - `Int`
`cveCatalog` - `CVECatalogRollupInfo`	Return rolled up counts about how particular CVEs affect the client's portfolio of companies. This also mixes in generic info about cves that DON'T affect the customer. The filters filter over both the cves that are present and the ones that are not. Date filtering is currently unimplemented EXPERIMENTAL
Arguments `filter` - `CVECatalogRollupFilter` `sortBy` - `[CVECatalogSortBy!]` `offset` - `Int!` `limit` - `Int`
`cveCatalogGeneric` - `CVECatalogGenericInfo`	Information about all CVEs across all clients Date filtering is currently unimplemented
Arguments `sortBy` - `[CVECatalogGenericSortBy!]` `offset` - `Int!` `limit` - `Int`

Example

{
  "fourthPartyExposure": ExposureDataWithCompanyInfo,
  "pdnsVendorDependency": PdnsVendorDependencyInfo,
  "vendorDependency": VendorDependencyInfo,
  "vendorDependencyLegacy": VendorDependencyLegacyInfo,
  "categorySummarizedCount": CategorySummarizedCountInfo,
  "vendorSummarizedCount": VendorSummarizedCountInfo,
  "productSummarizedCount": ProductSummarizedCountInfo,
  "companiesSummarizedCount": CompanySummarizedCountInfo,
  "vendorDependencyCountsPerCategory": VendorDependencyCountsPerCategoryInfo,
  "vendorDependencyCountsPerVendor": VendorDependencyCountsPerVendorInfo,
  "vendorDependencyCountsPerProduct": VendorDependencyCountsPerProductInfo,
  "emailSaasInsights": EmailSaasInsightsInfo,
  "emailSaasDomainWithoutSecurity": EmailSaasInsightsInfo,
  "bannerBusterInsights": BannerBusterInsightsInfo,
  "businessRisk": BusinessRiskInsightInfo,
  "cveCatalog": CVECatalogRollupInfo,
  "cveCatalogGeneric": CVECatalogGenericInfo
}

Types

Int

Description

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Example

Types

Int64

Description

Int64 is an integer with 64 bits reserved so it can represent a number that is up to 2^64 in size

Example

Types

LicenseQuantity

Description

The client's purchased licenses, with totals by product name and description

Fields

Field Name	Description
`totalLicenseCount` - `Int!`	Total number of this type of license
`productName` - `String!`	The name of the product being sold
`productDescription` - `String!`	A short description of the service trying to be sold

Example

{
  "totalLicenseCount": 123,
  "productName": "abc123",
  "productDescription": "xyz789"
}

Types

Map

Description

Key/value pairs, where keys are strings and values can be any scalar, object or array

Example

{"key1": [1, 2, 3], "key2": "strVal", "key3": true}

Types

Measurement

Description

A time and associated value returned in a TimeSeries object

Fields

Field Name	Description
`date` - `String!`
`value` - `Float`

Example

{"date": "2023-09-01T22:42:50.000", "value": 123.45}

Types

Message

Description

This is a JSON blob containing the fields source, message, timestamp, returned in the messages field of the Finding type.

Example: {"source": "BlueVoyant Risk ServiceRiskService@bluevoyant.com", "message": "Some message in **markdown** here", "timestamp": "2023-11-27T15:28:10.642546+00:00"}

Example

{
  "source": "BlueVoyant Risk Service<[email protected]>",
  "message": "Some message in **markdown** here",
  "timestamp": "2023-11-27T15:28:10.642546+00:00"
}

Types

PdnsVendorDependency

Fields

Field Name	Description
`bvid` - `UUID!`	The unique BlueVoyant identifier (BV ID) of the company.
`qname` - `String`	The name of the pDNS entity.
`requestingIp` - `String`	IP address of the requesting pDNS entity.
`findingCode` - `Int64`	Finding code is an integer that represents the specific type of a finding. See the dictionary query and the DataDictionary type.
`category` - `String`	The category the of the specific vendor product (Endpoint Security, Email Security, Network Security, etc).
`vendor` - `String`	The name of the vendor.
`product` - `String`	The name of the product that the vendor is providing.
`updatedTS` - `Time!`	The time of last updating
`lastObservedTS` - `Time!`	The last time it was observed
`company` - `CompanyByService`	Company object with much more data for each vendor dependency

Example

{
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "qname": "abc123",
  "requestingIp": "xyz789",
  "findingCode": 123,
  "category": "abc123",
  "vendor": "xyz789",
  "product": "abc123",
  "updatedTS": "2024-02-06T20:24:21Z",
  "lastObservedTS": "2024-02-06T20:24:21Z",
  "company": Company
}

Types

PdnsVendorDependencyInfo

Fields

Field Name	Description
`pdnsVendorDependencies` - `[PdnsVendorDependency!]`	A list of pDNS vendor dependencies.
`totalCount` - `Int64!`	The total number of objects that fit the filter given regardless of limit.
`pageLength` - `Int!`	The total amount of objects returned to user. Between zero and the limit provided.

Example

{
  "pdnsVendorDependencies": [PdnsVendorDependency],
  "totalCount": 123,
  "pageLength": 123
}

Types

PdnsVendorDependencySort

Values

Enum Value	Description
`category`	The category associated with the product
`vendor`	The category associated with the product
`product`	The product detected
`updatedTS`	The time the insight was last updated (process date)
`findingCode`	Finding code is an integer that represents the specific type of a finding. See the dictionary query and the DataDictionary type.
`bvid`	The unique BlueVoyant identifier (BV ID) of the company associated with this insight
`companyName`	Primary name of the company
`portfolioName`	Name of the portfolio containing the company
`lastObservedTS`	The last time this specific insight was observed or validated

Example

"category"

Types

PdnsVendorDependencySortBy

Fields

Input Field	Description
`field` - `PdnsVendorDependencySort!`	Field by which to sort vendors. Default = `updatedTS`
`direction` - `SortDirection`	Direction in which to sort vendors (asc/desc). Default = `asc`

Example

{"field": "category", "direction": "asc"}

Types

PeerScore

Description

A set of scores associated with a finding code that indicates the risk category (or overall score) for a company's industry peers. A peer is defined as an organization in the same industry, and one that has a similar digital footprint size range. Part of the Company type (peerScores) that is returned from the companyInfo query.

Fields

Field Name	Description
`assessmentDateEnd` - `String!`	The end of the scoring assessment period
`findingCode` - `Int!`	Finding code is an integer that represents the type of finding. These finding codes all indicate the risk category or the overall score (0).
`riskCategory` - `RiskCategory`	Corresponding risk category for the finding code. A finding code of 0 indicates the overall company risk score.
`averageScore` - `Float`	The average score across all peers
`minimumScore` - `Float`	The minimum score of any peer
`maximumScore` - `Float`	The maximum score of any peer
`medianScore` - `Float`	The median score of all peer scores
`standardDeviation` - `Float`	The standard deviation from the mean score
`percentile25Score` - `Float`	25% of the peers are at or below this score
`percentile75Score` - `Float`	75% of the peers are at or below this score

Example

{
  "assessmentDateEnd": "2024-03-25",
  "findingCode": 987,
  "riskCategory": "AdversarialThreats",
  "averageScore": 987.65,
  "minimumScore": 987.65,
  "maximumScore": 123.45,
  "medianScore": 123.45,
  "standardDeviation": 123.45,
  "percentile25Score": 123.45,
  "percentile75Score": 123.45
}

Types

Portfolio

Fields

Field Name	Description
`portfolioUuid` - `UUID!`
`portfolioName` - `String!`
`portfolioType` - `PortfolioType!`

Example

{
  "portfolioUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "portfolioName": "xyz789",
  "portfolioType": "external_regular"
}

Types

PortfolioAttributeFilter

Description

Where a field is specified, only select companies with a value matching one of those in the set specified. Only return companies for which all per-field constraints are met.

Fields

Input Field	Description
`portfolioUuids` - `[UUID!]`
`attributes` - `[String!]`	Search on attributes is case-sensitive. Supply an empty string as a value to match companies with no attributes. Default = `null`
`bvids` - `[UUID!]`	The BV ID is the unique identifier for the company. Default = `null`

Example

{
  "portfolioUuids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "attributes": ["xyz789"],
  "bvids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ]
}

Types

PortfolioData

Fields

Field Name	Description
`portfolioName` - `String!`	Portfolio name
`portfolioType` - `PortfolioType!`	Portfolio type
`portfolioUuid` - `UUID!`	Portfolio ID
`companyCount` - `Int!`	Count of companies in the portfolio
`description` - `String!`	Portfolio description
`createdBy` - `String!`	Username that created this portfolio
`createdTS` - `String!`	Timestamp when created
`updatedBy` - `String!`	Username that last updated this portfolio
`updatedTS` - `String!`	Timestamp when last updated

Example

{
  "portfolioName": "xyz789",
  "portfolioType": "external_regular",
  "portfolioUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "companyCount": 987,
  "description": "xyz789",
  "createdBy": "xyz789",
  "createdTS": "xyz789",
  "updatedBy": "abc123",
  "updatedTS": "xyz789"
}

Types

PortfolioFilter

Description

Filter used by the portfolioInfo query

Fields

Input Field	Description
`portfolioTypes` - `[PortfolioType!]`	The portfolio type can include 'external_regular' or 'high_volume_monitoring'
`portfolioUuids` - `[UUID!]`	Filter portfolios by one or more uuids in UUID format
`portfolioNames` - `[String!]`	Filter portfolios by one or more names
`descriptions` - `[String!]`	A description of the portfolio
`sortBy` - `[PortfolioSortBy]`	Sort returned roles by specified fields and directions

Example

{
  "portfolioTypes": ["external_regular"],
  "portfolioUuids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "portfolioNames": ["xyz789"],
  "descriptions": ["xyz789"],
  "sortBy": [PortfolioSortBy]
}

Types

PortfolioInfo

Description

This is the holder for portfolios, with pagination and counts

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`	Offset and limit echo back the parameters
`totalCount` - `Int!`	Count of portfolios matching filter regardless of whether they fit within limit
`pageLength` - `Int!`	Number of portfolios returned
`portfolios` - `[PortfolioData!]`	List of portfolios for client

Example

{
  "offset": 987,
  "limit": 123,
  "totalCount": 123,
  "pageLength": 987,
  "portfolios": [PortfolioData]
}

Types

PortfolioSortBy

Fields

Input Field	Description
`field` - `PortfolioSorts!`	Field by which to sort portfolios
`direction` - `SortDirection`	Direction in which to sort contacts (asc/desc). Default = `asc`

Example

{"field": "portfolioUuid", "direction": "asc"}

Types

PortfolioSorts

Values

Enum Value	Description
`portfolioUuid`
`portfolioName`
`portfolioType`
`description`
`companyCount`

Example

"portfolioUuid"

Types

PortfolioToAdd

Description

Inputs to create portfolio

Fields

Input Field	Description
`portfolioName` - `String!`	Portfolio name
`portfolioType` - `PortfolioType!`	Portfolio type. Default = `external_regular`
`description` - `String`	Portfolio description

Example

{
  "portfolioName": "xyz789",
  "portfolioType": "external_regular",
  "description": "xyz789"
}

Types

PortfolioToUpdate

Description

Inputs to update a portfolio

Fields

Input Field	Description
`portfolioUuid` - `UUID!`	Portfolio ID
`portfolioName` - `String`	Portfolio name
`portfolioType` - `PortfolioType`	Portfolio type
`description` - `String`	Portfolio description

Example

{
  "portfolioUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "portfolioName": "xyz789",
  "portfolioType": "external_regular",
  "description": "abc123"
}

Types

PortfolioType

Description

A portfolio is a group of companies. Portfolio types reflect some of the services associated with a company under monitoring.

Values

Enum Value	Description
`external_regular`	Portfolio type for companies with either the "BlueVoyant Client Directed Remediation" or "BlueVoyant Directed Remediation" service.
`high_volume_monitoring`	Portfolio type for companies with the "BlueVoyant SCD-High Volume Monitoring" service. Only limited information is available for companies in this type of portfolio.

Example

"external_regular"

Types

PortfoliosAuditLog

Description

This is the holder for portfolio audit log data portfoliosAuditLog query, with pagination and counts

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`
`totalCount` - `Int!`	Count of portfolio audit log entries matching filter regardless of whether they fit within limit
`pageLength` - `Int!`	Count of results returned
`portfoliosAuditLog` - `[PortfoliosAuditLogData!]`	List of portfolios for client

Example

{
  "offset": 987,
  "limit": 987,
  "totalCount": 123,
  "pageLength": 123,
  "portfoliosAuditLog": [PortfoliosAuditLogData]
}

Types

PortfoliosAuditLogData

Fields

Field Name	Description
`portfolioName` - `String`	Portfolio name associated with this audit log entry, at the time the action was taken. Note that if the portfolio name has since changed, this would be an old name.
`portfolioUuid` - `UUID`	Portfolio UUID associated with this audit log entry.
`changedBy` - `String!`	Username associated with this audit log entry (the user who made the change)
`bvid` - `String`	BV ID of the associated change, if this was a company add, move, or delete action.
`primaryName` - `String`	Primary name of the company associated with the bvid, if this was a company add, move, or delete action.
`variant` - `String`	Variant of the associated change, if this was a company add, move, or delete action.
`actionTaken` - `String!`	Action taken: 'Company Moved', 'Company Added', 'Company Removed', 'Portfolio Updated', 'Portfolio Deleted', 'Portfolio Added'
`context` - `String!`	Context of the change that indicates what has been updated: 'Portfolio', 'Portfolio Type', 'Name', 'Description', 'Internal'
`beforeChange` - `String!`	Original value before the change was made.
`afterChange` - `String!`	New value after the change was made.
`changeTS` - `Time!`	Timestamp associated with audit log entry

Example

{
  "portfolioName": "xyz789",
  "portfolioUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "changedBy": "abc123",
  "bvid": "abc123",
  "primaryName": "abc123",
  "variant": "abc123",
  "actionTaken": "xyz789",
  "context": "xyz789",
  "beforeChange": "xyz789",
  "afterChange": "xyz789",
  "changeTS": "0"
}

Types

ProductByDomainDetection

Description

Insights about a product detected on a domain

Fields

Field Name	Description
`domain` - `String!`
`productName` - `String`
`type` - `String`

Example

{
  "domain": "xyz789",
  "productName": "xyz789",
  "type": "xyz789"
}

Types

ProductByDomainDetectionInfo

Description

A collection of fourth party exposure organized by finding code. Includes finding code's description, summary, and assessment date.

Fields

Field Name	Description
`summary` - `String`	A brief summary of the finding code
`description` - `String`	A description of what the finding code is.
`assessmentDateEnd` - `String`	The most recent assessment date
`findingCode` - `Int64`	The finding code of these vendor discoveries.
`domains` - `[ProductByDomainDetection]`	List of domains of a specific finding code

Example

{
  "summary": "abc123",
  "description": "xyz789",
  "assessmentDateEnd": "xyz789",
  "findingCode": 123,
  "domains": [ProductByDomainDetection]
}

Types

ProductByIPDetection

Description

Insights about a product detected on an IP address

Fields

Field Name	Description
`deviceName` - `String`
`deviceVersion` - `String`
`hostingServer` - `String`
`ip` - `String!`
`port` - `Int!`
`productName` - `String!`
`softwarePackage` - `String`
`softwareVersion` - `String`
`subdomain` - `String`
`title` - `String`

Example

{
  "deviceName": "xyz789",
  "deviceVersion": "abc123",
  "hostingServer": "xyz789",
  "ip": "abc123",
  "port": 987,
  "productName": "abc123",
  "softwarePackage": "abc123",
  "softwareVersion": "abc123",
  "subdomain": "abc123",
  "title": "xyz789"
}

Types

ProductByIPDetectionInsights

Description

A list of products of products by ip detection of a single finding code. Includes a summary, description, and most recent assessment date of the finding code.

Fields

Field Name	Description
`summary` - `String`	A brief summary of the finding code
`description` - `String`	A description of what the finding code is.
`assessmentDateEnd` - `String`	The most recent assessment date
`findingCode` - `Int64`	The finding code of these vendor discoveries.
`detectedProducts` - `[ProductByIPDetection]`	list of products by ip detection of a single finding code

Example

{
  "summary": "abc123",
  "description": "xyz789",
  "assessmentDateEnd": "xyz789",
  "findingCode": 123,
  "detectedProducts": [ProductByIPDetection]
}

Types

ProductSummarizedCountFilter

Fields

Input Field	Description
`portfolios` - `[String!]`	The portfolios to filter on.
`categories` - `[String!]`	The categories to filter on.
`vendors` - `[String!]`	The vendors to filter on.

Example

{
  "portfolios": ["xyz789"],
  "categories": ["xyz789"],
  "vendors": ["abc123"]
}

Types

ProductSummarizedCountInfo

Fields

Field Name	Description
`totalCount` - `Int!`	The total count of objects that match the user's request regardless of how many were returned.
`pageLength` - `Int!`	The amount of objects returned to the user.
`items` - `[ProductSummarizedCounts]`	The list of objects that match the user's request.

Example

{
  "totalCount": 123,
  "pageLength": 987,
  "items": [ProductSummarizedCounts]
}

Types

ProductSummarizedCountSort

Values

Enum Value	Description
`portfolioName`
`category`
`vendor`

Example

"portfolioName"

Types

ProductSummarizedCountSortBy

Fields

Input Field	Description
`field` - `ProductSummarizedCountSort!`	Field by which to sort vendors. Default = `portfolioName`
`direction` - `SummarizedSortDirection`	Direction in which to sort users (asc/desc). Default = `asc`

Example

{"field": "portfolioName", "direction": "asc"}

Types

ProductSummarizedCounts

Fields

Field Name	Description
`portfolio` - `String!`	The portfolio of this portfolio/client/category/vendor combination.
`category` - `String!`	The category of this portfolio/client/category/vendor combination.
`vendor` - `String!`	The vendor of this portfolio/client/category/vendor combination.
`totalCount` - `Int!`	The amount of products this portfolio/client/category/vendor combination contains.
`products` - `[String!]`	The list of products of this portfolio/client/category/vendor combination.

Example

{
  "portfolio": "xyz789",
  "category": "xyz789",
  "vendor": "abc123",
  "totalCount": 123,
  "products": ["abc123"]
}

Types

RawJSON

Description

Some arbitrary json

Example

{"key1": [1, 2, 3], "key2": "strVal", "key3": true}

Types

ResolutionPercentage

Fields

Field Name	Description
`percentage` - `Float`	A float 0-100 representing the percentage of tickets for all time resolved in threshold days or less
`thresholdDays` - `Int`	The resolved cases included in percentage all resolved in thresholdDays or less. A null threshold indicates that the category is unbounded, and thus reflects the all-time statistic

Example

{"percentage": 987.65, "thresholdDays": 987}

Types

Response

Description

Response holds the HTTP response when there is no data to return. Errors will still appear in the errors section of the GraphQL response.

Fields

Field Name	Description
`code` - `Int!`	HTTP response code
`message` - `String!`	Error or success message

Example

{"code": 123, "message": "abc123"}

Types

RiskCategory

Description

Our findings exist in one of these five categories. Each category has a corresponding score

Values

Enum Value	Description
`AdversarialThreats`	Finding code: 40000. Monitoring of adversarial attacks directed at the company from malicious infrastructure.
`EmailSecurity`	Finding code: 10000. Identification of incorrect configuration and best practices for email security, including use of anti-spoofing and spam protection. Findings cover the misconfiguration and lack of configuration of SPF, DKIM, and DMARC records.
`ITHygiene`	Finding code: 20000. Identification of misconfigured network infrastructure including, but not limited to, open ports and services, the use of file-sharing and torrent programs inside the company’s network, as well the installation and use of potentially unwanted programs.
`MaliciousActivity`	Finding code: 50000. Identification of traffic emanating from the company’s network to the darknet, company assets being listed on blacklists, and the existence of the company’s interactions with blacklisted (adversarial) infrastructure.
`Vulnerability`	Finding code: 30000. Identification of common vulnerabilities and exposures (CVEs) on server software, improper use of TLS/SSL certificates, and the existence of CVEs that are actively being exploited by threat actors.

Example

"AdversarialThreats"

Types

RiskEventCategory

Values

Enum Value	Description
`Financial`
`Foreign_Ownership_Control_or_Influence`
`Political_and_Regulatory`
`Infrastructure`
`Technology_and_Cyber_Security`
`Transportation_and_Distribution`
`Product_Quality_and_Design`
`Economic`
`Manufacturing_and_Supply`
`Environment`
`Compliance`
`Human_Capital`

Example

"Financial"

Types

RiskFilter

Description

Client risk filter, returned as part of RiskFiltersInfo from a riskFilterInfo query, or from riskFilterCreate or riskFilterUpdate mutations.

Fields

Field Name	Description
`riskFilterId` - `Int!`	Unique ID assigned to each risk filter
`description` - `String`	Description of risk filter
`matchRules` - `[RiskFilterMatchRule!]`	List of match rules associated with risk filter
`enabled` - `Boolean!`	Enabled status of risk filter
`updatedTS` - `Time`	Timestamp when risk filter was created or updated

Example

{
  "riskFilterId": 123,
  "description": "abc123",
  "matchRules": [RiskFilterMatchRule],
  "enabled": true,
  "updatedTS": "2024-02-06T20:24:21"
}

Types

RiskFilterFilter

Description

Fields available by which to filter risk filters from the riskFilterInfo query

Fields

Input Field	Description
`riskFilterIds` - `[Int!]`	Filter results by riskFilterId(s). Default = `null`
`descriptions` - `[String!]`	Filter results by description(s). Does a wildcard match on each provided description. Default = `null`
`enabled` - `Boolean`	Filter results by enabled status. Default = `null`

Example

{
  "riskFilterIds": [123],
  "descriptions": ["xyz789"],
  "enabled": true
}

Types

RiskFilterInfo

Description

This is the holder for RiskFilters from a riskFilterInfo query, with counts

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`	Limit and offset echo back the parameters
`totalCount` - `Int64!`	Count of risk filters matching filter regardless of whether they fit within limit
`pageLength` - `Int!`	Count of risk filters returned
`riskFilters` - `[RiskFilter!]`	Client risk filters

Example

{
  "offset": 987,
  "limit": 123,
  "totalCount": 123,
  "pageLength": 123,
  "riskFilters": [RiskFilter]
}

Types

RiskFilterMatchField

Description

Enums for risk filter match field. Part of RiskFilterMatchRule type.

Values

Enum Value	Description
`bvid`	The unique BlueVoyant identifier (BV ID) of a company
`findingCode`	Finding code is an integer that represents the specific type of a finding. See the dictionary query and the DataDictionary type.
`findingDescription`	A long description of a finding code
`findingHash`	An ID of int64 type that is unique for a BV ID, variant, and finding code
`findingSummary`	A short description of a finding code. See the dictionary query and the DataDictionary type.
`portfolioName`	The name of a portfolio containing companies monitored by the client
`primaryName`	The primary name of a company
`riskCategory`	A risk category for a finding. See the RiskCategory type.
`scoreImpact`	The impact of a finding on the overall company risk score

Example

"bvid"

Types

RiskFilterMatchRule

Description

Match rule for risk filters. Part of a RiskFilter type. Each rule has a match field, type, and value, and may be negated. Rules in the same risk filter are ANDed together.

Examples (matchField, matchType, matchValue):

findingCode regex "(10023|10024)"
portfolioName _eq "Tier 1"
scoreImpact _gte "10"

Fields

Field Name	Description
`riskFilterId` - `Int!`	ID of risk filter associated with match rule
`matchRuleId` - `Int!`	Unique ID assigned to each match rule
`matchField` - `RiskFilterMatchField`	Name of field being matched
`matchType` - `RiskFilterMatchType`	Type of match: <= (_lte), >= (_gte), == (_eq), != (_ne), regex
`matchValue` - `String!`	Value being matched/compared
`negated` - `Boolean!`	Whether the match rule is negated
`enabled` - `Boolean!`	Whether the match rule is enabled
`updatedTS` - `Time`	Timestamp match rule was created or updated

Example

{
  "riskFilterId": 987,
  "matchRuleId": 987,
  "matchField": "bvid",
  "matchType": "_lte",
  "matchValue": "xyz789",
  "negated": false,
  "enabled": false,
  "updatedTS": "2024-02-06T20:24:21"
}

Types

RiskFilterMatchRuleToAdd

Description

Contains info to create new match rule. Used by riskFilterCreate and riskFilterUpdate mutations. Only very limited validation is performed on the matchValue.

Fields

Input Field	Description
`matchField` - `RiskFilterMatchField!`	Name of field being matched
`matchType` - `RiskFilterMatchType!`	Type of match: <= (_lte), >= (_gte), == (_eq), != (_ne), regex
`matchValue` - `String!`	Value of matchField being matched/compared
`negated` - `Boolean!`	Whether match rule should be negated
`enabled` - `Boolean!`	Whether match rule should be enabled

Example

{
  "matchField": "bvid",
  "matchType": "_lte",
  "matchValue": "xyz789",
  "negated": true,
  "enabled": true
}

Types

RiskFilterMatchRuleToDelete

Description

Contains ID of match rule to be deleted. Used by riskFilterUpdate mutation.

Fields

Input Field	Description
`matchRuleId` - `Int!`	ID of match rule to be deleted

Example

{"matchRuleId": 987}

Types

RiskFilterMatchRuleToUpdate

Description

Contains match rule info to be updated. Used by riskFilterUpdate mutation. At least one field other than matchRuleId must be provided. Only very limited validation is performed on the matchValue.

Fields

Input Field	Description
`matchRuleId` - `Int!`	ID of match rule to be updated
`matchField` - `RiskFilterMatchField`	Name of field to be compared
`matchType` - `RiskFilterMatchType`	Type of match: <= (_lte), >= (_gte), == (_eq), != (_ne), regex
`matchValue` - `String`	Value of matchField being matched/compared
`negated` - `Boolean`	Whether the match rule is negated
`enabled` - `Boolean`	Whether the match rule is enabled

Example

{
  "matchRuleId": 123,
  "matchField": "bvid",
  "matchType": "_lte",
  "matchValue": "abc123",
  "negated": true,
  "enabled": false
}

Types

RiskFilterMatchType

Description

Enums for risk filter match rules' match type. Part of RiskFilterMatchRule type.

Values

Enum Value	Description
`_lte`	Value found in matchField is less than or equal to matchValue
`_gte`	Value found in matchField is greater than or equal to matchValue
`_eq`	Value found in matchField is equal to matchValue
`_ne`	Value found in matchField is not equal to matchValue
`regex`	Value found in matchField matches the regular expression in matchValue

Example

"_lte"

Types

RiskFilterSortBy

Description

Holder for the risk filter sort fields for the riskFilterInfo query

Fields

Input Field	Description
`field` - `RiskFilterSorts!`
`direction` - `SortDirection`

Example

{"field": "riskFilterId", "direction": "asc"}

Types

RiskFilterSorts

Description

Fields available to sort risk filters by in the riskFilterInfo query; default: riskFilterId

Values

Enum Value	Description
`riskFilterId`	Unique ID assigned to each risk filter
`description`	Description of risk filter
`enabled`	Enabled status of risk filter
`updatedTS`	Timestamp when risk filter was created or updated

Example

"riskFilterId"

Types

RiskFilterToAdd

Description

Contains details of risk filter to be created. Used by riskFilterCreate mutation.

Fields

Input Field	Description
`description` - `String!`	Description of risk filter
`enabled` - `Boolean`	Whether to enable risk filter
`matchRules` - `[RiskFilterMatchRuleToAdd!]`	Match rules for risk filter

Example

{
  "description": "abc123",
  "enabled": true,
  "matchRules": [RiskFilterMatchRuleToAdd]
}

Types

RiskFilterToDelete

Description

Contains details of risk filter to be deleted for risk filter. Used by riskFilterDelete mutation.

Fields

Input Field	Description
`riskFilterId` - `Int!`	ID of risk filter to be deleted
`force` - `Boolean`	Must be true to delete risk filters containing match rules

Example

{"riskFilterId": 987, "force": false}

Types

RiskFilterToUpdate

Description

Contains info to be updated for risk filter. Used by riskFilterUpdate mutation.

Fields

Input Field	Description
`riskFilterId` - `Int!`	ID of risk filter to be updated
`description` - `String`	New description for risk filter
`enabled` - `Boolean`	Update enabled status of risk filter
`matchRulesToAdd` - `[RiskFilterMatchRuleToAdd!]`	Add new match rule(s) to risk filter
`matchRulesToDelete` - `[RiskFilterMatchRuleToDelete!]`	Delete match rule(s) from risk filter. Only match rule ID needs to be provided
`matchRulesToUpdate` - `[RiskFilterMatchRuleToUpdate!]`	Update match rule(s) for a risk filter. Must provide match rule ID and at least one other field

Example

{
  "riskFilterId": 987,
  "description": "abc123",
  "enabled": true,
  "matchRulesToAdd": [RiskFilterMatchRuleToAdd],
  "matchRulesToDelete": [RiskFilterMatchRuleToDelete],
  "matchRulesToUpdate": [RiskFilterMatchRuleToUpdate]
}

Types

RiskLevel

Description

A bucketing of the risk level

Values

Enum Value	Description
`low`
`medium`
`high`
`critical`

Example

"low"

Types

Role

Description

SCD portal/API role - contains RolePolicyPermissions for access to API endpoints and GraphQL operations, and RoleResourcePermissions for access to resources.

Fields

Field Name	Description
`uuid` - `UUID!`	Role ID in UUID format
`name` - `String!`	Role name
`description` - `String!`	Description of role
`configurableFlag` - `Boolean!`	Whether clients can configure the role
`assignableFlag` - `Boolean!`	Whether clients can assign the role to users
`extensionFlag` - `Boolean!`	Whether role is an add-on to another role, or a primary role. Only one primary role can be assigned to a user.
`defaultFlag` - `Boolean!`	Whether role is the default role assigned to users created through Okta
`clientUuid` - `UUID!`	Client UUID associated with the role
`createdTS` - `String!`	Timestamp when created
`updatedTS` - `String!`	Timestamp when last updated
`createdBy` - `String!`	Username that created this item
`updatedBy` - `String!`	Username that last updated this item
`policyPermissions` - `[RolePolicyPermission!]`	Policy permissions control the API endpoints and GraphQL operations available to the role
`resourcePermissions` - `[RoleResourcePermission!]`	Resource permissions control the resources (companies and portfolios) available to the role
`users` - `[User!]`	Users that have this role

Example

{
  "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "name": "abc123",
  "description": "abc123",
  "configurableFlag": false,
  "assignableFlag": false,
  "extensionFlag": true,
  "defaultFlag": false,
  "clientUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "createdTS": "abc123",
  "updatedTS": "xyz789",
  "createdBy": "abc123",
  "updatedBy": "abc123",
  "policyPermissions": [RolePolicyPermission],
  "resourcePermissions": [RoleResourcePermission],
  "users": [User]
}

Types

RoleFilter

Fields

Input Field	Description
`uuids` - `[UUID!]`	Filter roles by one or more IDs in UUID format. Default = `null`
`names` - `[String!]`	Filter roles by one or more names (wildcard matching). Default = `null`
`descriptions` - `[String!]`	Filter roles by one or more descriptions (wildcard matching). Default = `null`
`configurableFlag` - `Boolean`	Filter roles by configurable flag (whether admin users can configure the role). Default = `null`
`assignableFlag` - `Boolean`	Filter roles by assignable flag (whether admin users can assign the role to users). Default = `null`
`extensionFlag` - `Boolean`	Filter roles by extension flag (true if an extension/add-on; false if a primary role). Default = `null`
`defaultFlag` - `Boolean`	Whether role is the default role assigned to users created through Okta. Default = `null`
`policyPermissionIds` - `[Int!]`	Filter roles by one or more policy permission IDs. Default = `null`
`policyPermissionNames` - `[String!]`	Filter roles by one or more policy permission names (wildcard matching). Default = `null`
`policyPermissionDescriptions` - `[String!]`	Filter roles by one or more policy permission descriptions (wildcard matching). Default = `null`
`policyPermissionExtensionFlag` - `Boolean`	Filter roles by policy permission extension flag (true if an extension/add-on; false if a primary policy permission). Default = `null`
`resourcePermissionIds` - `[Int!]`	Filter roles by one or more resource permission IDs. Default = `null`
`resourcePermissionDescriptions` - `[String!]`	Filter roles by one or more resource permission descriptions (wildcard matching). Default = `null`
`resourcePermissionAllFlag` - `Boolean`	Filter roles by resource permission all flag (true if permission applies to all resources of the specified type). Default = `null`
`resourcePermissionResourceTypes` - `[RoleResourceType!]`	Filter roles by one or more resource permission resource types (company, portfolio). Default = `null`
`resourcePermissionPropertyTypes` - `[RoleResourcePropertyType!]`	Filter roles by one or more resource permission property types (portfolioUuid, bvid, attribute). Default = `null`
`resourcePermissionPropertyValues` - `[String!]`	Filter roles by one or more resource permission property values. Default = `null`
`resourcePermissionAllowedActions` - `[RoleResourceAllowedAction!]`	Filter roles by one or more allowed actions (view, update). Default = `null`
`sortBy` - `[RoleSortBy]`	Sort returned roles by specified fields and directions

Example

{
  "uuids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "names": ["xyz789"],
  "descriptions": ["abc123"],
  "configurableFlag": true,
  "assignableFlag": false,
  "extensionFlag": false,
  "defaultFlag": true,
  "policyPermissionIds": [123],
  "policyPermissionNames": ["abc123"],
  "policyPermissionDescriptions": [
    "abc123"
  ],
  "policyPermissionExtensionFlag": true,
  "resourcePermissionIds": [123],
  "resourcePermissionDescriptions": [
    "xyz789"
  ],
  "resourcePermissionAllFlag": true,
  "resourcePermissionResourceTypes": ["portfolio"],
  "resourcePermissionPropertyTypes": ["portfolioUuid"],
  "resourcePermissionPropertyValues": [
    "abc123"
  ],
  "resourcePermissionAllowedActions": ["view"],
  "sortBy": [RoleSortBy]
}

Types

RoleInfo

Description

This is the holder for roles, with pagination and counts

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`	Limit and offset echo back the parameters
`totalCount` - `Int!`	Count of roles matching filter regardless of whether they fit within limit
`pageLength` - `Int!`	Count of roles returned
`roles` - `[Role!]`	SCD portal/API roles

Example

{
  "offset": 987,
  "limit": 987,
  "totalCount": 123,
  "pageLength": 123,
  "roles": [Role]
}

Types

RolePolicyPermission

Description

Policy permissions associated with roles. Policy permissions control access to API endpoints and GraphQL operations, fields (selections) and arguments. See Function for the categories of endpoints and operations available to the user. See RoleResourcePermission to further restrict access to individual resources.

Fields

Field Name	Description
`id` - `Int!`	Policy permission ID
`roleUuid` - `UUID`	Role ID in UUID format
`name` - `String!`	Name of policy permission
`description` - `String!`	Description of policy permission
`assignableFlag` - `Boolean!`	Whether policy permission is assignable to roles by client
`extensionFlag` - `Boolean!`	Whether policy permission is an add-on to other policy permissions or roles, or a primary policy permission. Only one primary policy permission can be assigned to a role.
`clientUuid` - `UUID`	Client UUID associated with policy permission
`createdTS` - `String!`	Timestamp when created
`updatedTS` - `String!`	Timestamp when last updated
`createdBy` - `String!`	Username that created this item
`updatedBy` - `String!`	Username that last updated this item

Example

{
  "id": 123,
  "roleUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "name": "xyz789",
  "description": "abc123",
  "assignableFlag": true,
  "extensionFlag": false,
  "clientUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "createdTS": "xyz789",
  "updatedTS": "xyz789",
  "createdBy": "xyz789",
  "updatedBy": "xyz789"
}

Types

RolePolicyPermissionFilter

Fields

Input Field	Description
`ids` - `[Int!]`	Filter policy permissions by one or more IDs. Default = `null`
`names` - `[String!]`	Filter policy permissions by one or more names (wildcard matching). Default = `null`
`descriptions` - `[String!]`	Filter policy permissions by one or more descriptions (wildcard matching). Default = `null`
`assignableFlag` - `Boolean`	Filter policy permissions by assignable flag (whether client can assign permission to roles). Default = `null`
`extensionFlag` - `Boolean`	Filter policy permissions by extension flag (true if an extension/add-on; false if a primary policy permission). Default = `null`
`sortBy` - `[RolePolicyPermissionSortBy]`	Sort returned policy permissions by specified fields and directions

Example

{
  "ids": [987],
  "names": ["xyz789"],
  "descriptions": ["abc123"],
  "assignableFlag": true,
  "extensionFlag": false,
  "sortBy": [RolePolicyPermissionSortBy]
}

Types

RolePolicyPermissionInfo

Description

This is the holder for role policy permissions

Fields

Field Name	Description
`policyPermissions` - `[RolePolicyPermission!]`

Example

{"policyPermissions": [RolePolicyPermission]}

Types

RolePolicyPermissionLookup

Description

Policy permission associated with a role - controls access to API endpoints and GraphQL fields (selections) and arguments. This object is used to add a policy permission to a role by either its name or ID.

Fields

Input Field	Description
`id` - `Int`	Policy permission ID - include only this field or name
`name` - `String`	Name of policy permission - include only this field or id

Example

{"id": 123, "name": "abc123"}

Types

RolePolicyPermissionSortBy

Fields

Input Field	Description
`field` - `RolePolicyPermissionSorts!`	Field by which to sort policy permissions
`direction` - `SortDirection`	Direction in which to sort policy permissions (asc/desc). Default = `asc`

Example

{"field": "id", "direction": "asc"}

Types

RolePolicyPermissionSorts

Description

Fields available by which to sort policy permission; default: id/asc

Values

Enum Value	Description
`id`	Policy permission ID
`name`	Name of policy permission
`description`	Description of policy permissions
`assignableFlag`	Whether client can assign policy permission to roles
`extensionFlag`	Whether permission is an add-on to another policy permission, if true, or a primary policy permission

Example

"id"

Types

RoleResourceAllowedAction

Description

Allowed actions on individual resources, or all resources of the specified resource type, in role resource permissions. Allowed actions can only narrow the access provided by the role policy permissions, not broaden it. For instance, granting 'update' access to a company when a role's policy permission only allows the user to view companies will only have the effect of granting 'view' access to the company.

Values

Enum Value	Description
`view`	Individual resource or all resources of the associated resource type can only be viewed (if permitted by role policy permissions)
`update`	Individual resource or all resources of the associated resource type can be updated or viewed (if permitted by role policy permissions)

Example

"view"

Types

RoleResourcePermission

Description

Resource permission associated with roles. Resource permissions control access to individual resources (portfolio or company) by an associated property (portfolioUuid for portfolios, portfolioUuid, attribute, or bvid for companies), or allow access to all resources of a type (portfolio/company), at a particular action level (view/update). Resource permissions can only maintain or further narrow the access granted by a RolePolicyPermission, never broaden it.

Fields

Field Name	Description
`id` - `Int!`	Resource permission ID
`roleUuid` - `UUID`	Role ID in UUID format
`description` - `String!`	Description of resource permission
`resourceType` - `RoleResourceType!`	Resource type that can be accessed (company, portfolio)
`allFlag` - `Boolean!`	Can access all resources of this type if true
`propertyType` - `RoleResourcePropertyType`	Property type used to control access to resource (will be null if allFlag is true) (portfolioUuid, attribute, bvid). Only the 'portfolioUuid' property type can be used with the 'portfolio' resource type.
`propertyValue` - `String`	Property value used to control access to resource (will be null if allFlag is true)
`allowedAction` - `RoleResourceAllowedAction!`	Allowed action on the resource (view/update) (if permitted by role policy permission)
`createdTS` - `String!`	Timestamp when created
`updatedTS` - `String!`	Timestamp when last updated
`createdBy` - `String!`	Username that created this item
`updatedBy` - `String!`	Username that last updated this item
`inactiveFlag` - `Boolean!`	If true, permission is inactive

Example

{
  "id": 987,
  "roleUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "description": "abc123",
  "resourceType": "portfolio",
  "allFlag": false,
  "propertyType": "portfolioUuid",
  "propertyValue": "abc123",
  "allowedAction": "view",
  "createdTS": "abc123",
  "updatedTS": "xyz789",
  "createdBy": "abc123",
  "updatedBy": "xyz789",
  "inactiveFlag": true
}

Types

RoleResourcePermissionLookup

Description

Resource permission associated with role - controls access to individual resources (portfolio or company) by a property (portfolioUuid, attribute, bvid), or allows access to all resources of a type. This object is used to add resource permissions to roles. The resource permission can be created on the fly (or looked up by its values), or the ID of an existing permission can be provided.

Fields

Input Field	Description
`id` - `Int`	Resource permission ID - if known, include only this field
`description` - `String`	Description of resource permission
`resourceType` - `RoleResourceType`	Resource type that can be accessed (company, portfolio) - required unless ID is provided
`allFlag` - `Boolean`	Can access all resources of this type if true
`propertyType` - `RoleResourcePropertyType`	Property type used to control access to resource (must be null if allFlag is true, required otherwise, unless ID is provided). Values: portfolioUuid, attribute, bvid. Only portfolioUuid can be used with a portfolio resource type.
`propertyValue` - `String`	Property value used to control access to resource (must be null if allFlag is true, required otherwise, unless ID is provided)
`allowedAction` - `RoleResourceAllowedAction`	Allowed action on the resource (view/update) - required unless ID is provided

Example

{
  "id": 987,
  "description": "xyz789",
  "resourceType": "portfolio",
  "allFlag": false,
  "propertyType": "portfolioUuid",
  "propertyValue": "abc123",
  "allowedAction": "view"
}

Types

RoleResourcePropertyType

Description

Property types in role resource permissions. Access to a resource type can be limited by a property of the resource.

Values

Enum Value	Description
`portfolioUuid`	Portfolio UUID - can apply to 'portfolio' or 'company' resource type
`bvid`	Company ID - can apply only to 'company' resource type
`attribute`	Client-provided attribute - can apply only to 'company' resource type

Example

"portfolioUuid"

Types

RoleResourceType

Description

Resource types in role resource permissions. These are the objects that can be viewed or acted upon.

Values

Enum Value	Description
`portfolio`
`company`

Example

"portfolio"

Types

RoleSortBy

Fields

Input Field	Description
`field` - `RoleSorts!`	Field by which to sort roles
`direction` - `SortDirection`	Direction in which to sort roles (asc/desc). Default = `asc`

Example

{"field": "uuid", "direction": "asc"}

Types

RoleSorts

Description

Fields available by which to sort roles; default: uuid/asc

Values

Enum Value	Description
`uuid`	Role ID in UUID format
`name`	Name of role
`description`	Description of role
`assignableFlag`	Whether clients can assign the role to users
`configurableFlag`	Whether clients can configure the role
`extensionFlag`	Whether role is an extension/add-on to another role, or a primary role
`defaultFlag`	Whether role is the default role assigned to users created through Okta

Example

"uuid"

Types

RoleToAdd

Description

SCD portal/API role - used for creating new roles - contains policy permissions for access to API endpoints/functionality, and resource permissions for access to resources

Fields

Input Field	Description
`name` - `String!`	Role name
`description` - `String!`	Description of role
`policyPermissions` - `[RolePolicyPermissionLookup!]!`
`resourcePermissions` - `[RoleResourcePermissionLookup!]!`

Example

{
  "name": "abc123",
  "description": "xyz789",
  "policyPermissions": [RolePolicyPermissionLookup],
  "resourcePermissions": [RoleResourcePermissionLookup]
}

Types

RoleToUpdate

Description

SCD portal/API role - used for updating existing roles - contains policy permissions for access to API endpoints/functionality, and resource permissions for access to resources

Fields

Input Field	Description
`uuid` - `UUID!`	Role ID in UUID format
`name` - `String`	Role name
`description` - `String`	Description of role
`policyPermissionsToAdd` - `[RolePolicyPermissionLookup!]`
`policyPermissionsToDelete` - `[RolePolicyPermissionLookup!]`
`resourcePermissionsToAdd` - `[RoleResourcePermissionLookup!]`
`resourcePermissionsToDelete` - `[RoleResourcePermissionLookup!]`
`replaceAllPermissionsFlag` - `Boolean`	If specified, replace all the user's permissions (of the same type) with those in resourcePermissionsToAdd and/or policyPermissionsToAdd

Example

{
  "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "name": "xyz789",
  "description": "abc123",
  "policyPermissionsToAdd": [RolePolicyPermissionLookup],
  "policyPermissionsToDelete": [
    RolePolicyPermissionLookup
  ],
  "resourcePermissionsToAdd": [
    RoleResourcePermissionLookup
  ],
  "resourcePermissionsToDelete": [
    RoleResourcePermissionLookup
  ],
  "replaceAllPermissionsFlag": true
}

Types

Score

Description

Score details for the overall score (finding code 0), used in Company riskScore

Fields

Field Name	Description
`scoreDate` - `String`	Score is calculated based on data collected through the end of this date. Accordingly this will usually be yesterday's date, in YYYY-MM-DD format
`findingCode` - `Int`	Finding code is an integer that represents the specific type of a finding. Finding code 0 indicates the overall company score. See the dictionary query and the DataDictionary type.
`findingCount` - `Int`	Was never available for overall score
`score` - `Float`	Score can be from 0 to 100, or null if not scored
`riskLevel` - `RiskLevel`	A bucketing of the risk level
`scoreImpact` - `Float`	Was never available for overall score
`scorePercentile` - `Float`	This has never actually been a peer percentile, but a percentile of all scores
`findingStatus` - `ScoreStatus`	Values: valid or lowData

Example

{
  "scoreDate": "2024-01-01",
  "findingCode": 0,
  "findingCount": 123,
  "score": 123.45,
  "riskLevel": "low",
  "scoreImpact": 987.65,
  "scorePercentile": 123.45,
  "findingStatus": "valid"
}

Types

ScoreHVM

Description

HVM companies (CompanyHVM) can only display the company's risk level, not the entire Score object

Fields

Field Name	Description
`riskLevel` - `RiskLevel`	A bucketing of the risk level

Example

{"riskLevel": "low"}

Types

ScoreStatus

Description

Status of the overall company score. If lowData, BlueVoyant could not find enough company assets to make an accurate assessment

Values

Enum Value	Description
`valid`
`lowData`

Example

"valid"

Types

SecurityDevice

Description

Information about a security device found in a footprint

Fields

Field Name	Description
`ip` - `String`
`averageTotalResolutionPerDay` - `Int`	A rolling 5-day average of observed resolution count per IP.
`resolutionDiversity` - `Int`	A rolling 5-day average of distinct qnames requested per IP.
`lastUpdated` - `String`

Example

{
  "ip": "xyz789",
  "averageTotalResolutionPerDay": 987,
  "resolutionDiversity": 123,
  "lastUpdated": "xyz789"
}

Types

SecurityDeviceInfo

Description

A collection of security devices organized by finding code. Includes finding code's description, summary, and assessment date.

Fields

Field Name	Description
`summary` - `String`	A brief summary of the finding code
`description` - `String`	A description of what the finding code is.
`assessmentDateEnd` - `String`	The most recent assessment date
`findingCode` - `Int64`	The finding code of these vendor discoveries.
`devices` - `[SecurityDevice]`	List of devices of a specific finding code

Example

{
  "summary": "xyz789",
  "description": "abc123",
  "assessmentDateEnd": "abc123",
  "findingCode": 123,
  "devices": [SecurityDevice]
}

Types

ServiceSetup

Description

A client's service, associated quotas, and current usage

Fields

Field Name	Description
`name` - `String!`	The name of the service
`productName` - `String`	The name of the license (product) associated with the service
`enforceCompanyQuota` - `Boolean!`	Indicates whether the maximum number of allowed companies for this service (companyQuota) is being enforced
`companyQuota` - `Int!`	The maximum number of allowed companies for this service
`companyCount` - `Int`	The current number of companies for this service subject to the quota (companyQuota)
`enforceCompanyChurn` - `Boolean!`	Indicates whether the maximum churn rate for companies ((1 + companyChurnPercent/100) * companyQuota) for this service is being enforced
`companyChurnPercent` - `Float!`	The churn rate for companies for this service as a percentage, e.g. if companyChurnPercent is 5, companyChurnCount cannot exceed (1 + companyChurnPercent/100) * companyQuota during the last companyChurnDays if enforceEntityChurn is true, so if companyQuota is 100 and companyChurnDays is 90, up to 105 different companies can be swapped in and out of this service during any 90-day period.
`companyChurnDays` - `Int!`	The period in days over which the churn rate for this service (companyChurnPercent) applies
`companyChurnCount` - `Int`	The current number of distinct companies that were in this service at any time during the latest churn period (not including any companies that remained in portfolios for less than 24 hours)
`enforceMaxCompanyAdditions` - `Boolean!`	Indicates whether the maximum number of additions of companies (maxEntityAdditions) during the additions period (companyAdditionsDays) across this service is being enforced
`maxCompanyAdditions` - `Int!`	The maximum number of distinct companies that can be added to this service during the additions period (companyAdditionsDays)
`companyAdditionsDays` - `Int!`	The period in days over which the maximum number of distinct companies added for this service (maxEntityAdditions) applies
`companyAdditionsCount` - `Int`	The current number of distinct companies added to this service at any time during the latest additions period (not including any companies that remained in portfolios for less than 24 hours)
`excludeMyCompany` - `Boolean!`	If excludeMyCompany is true and the "My Company" company (the bvid field) is present, it is not subject to quotas (companyCount), churn rate (companyChurnCount), or maximum additions (companyAdditionsCounts) limits.

Example

{
  "name": "abc123",
  "productName": "abc123",
  "enforceCompanyQuota": true,
  "companyQuota": 987,
  "companyCount": 987,
  "enforceCompanyChurn": false,
  "companyChurnPercent": 987.65,
  "companyChurnDays": 123,
  "companyChurnCount": 123,
  "enforceMaxCompanyAdditions": false,
  "maxCompanyAdditions": 123,
  "companyAdditionsDays": 123,
  "companyAdditionsCount": 123,
  "excludeMyCompany": false
}

Types

SortDirection

Description

Direction to sort (ascending or descending)

Values

Enum Value	Description
`asc`	Ascending order, nulls first
`desc`	Descending order, nulls last

Example

"asc"

Types

String

Description

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Example

"xyz789"

Types

Subdomain

Fields

Field Name	Description
`name` - `String`
`recordType` - `String`

Example

{
  "name": "abc123",
  "recordType": "abc123"
}

Types

SummarizedSortDirection

Values

Enum Value	Description
`asc`	Ascending order, nulls first
`desc`	Descending order, nulls last

Example

"asc"

Types

TagInfo

Fields

Field Name	Description
`tagValue` - `String!`
`updatedTS` - `String`
`updatedByUser` - `String!`	Use 'updatedBy'
`updatedBy` - `String!`
`source` - `String`

Example

{
  "tagValue": "abc123",
  "updatedTS": "abc123",
  "updatedByUser": "xyz789",
  "updatedBy": "xyz789",
  "source": "abc123"
}

Types

ThirdPartyDisposition

Values

Enum Value	Description
`NotAPriority`
`Unreproducible`
`BadFootprint`
`FalsePositive`
`WillResolve`
`RefuseToResolveOther`
`HasResolved`
`NeedsSupport`
`Unset`

Example

"NotAPriority"

Types

Time

Description

A date or time

Example

"0"

Types

TimeSeries

Description

A series of date/timestamps and associated values within the specified date range associated with an AvailableTimeSeries object and returned by a timeseries query

Fields

Field Name	Description
`startDate` - `String!`	The start of the date range. Date is in 'YYYY-MM-DD' format
`endDate` - `String!`	The end of the date range. Date is in 'YYYY-MM-DD' format
`portfolioUuids` - `[UUID!]`	The portfolioUUids used to filter results, if specified
`portfolioType` - `PortfolioType`	The portfolioType used to filter results
`attributes` - `[String!]`	The attributes used to filter results, if specified
`bvids` - `[UUID!]`	The BV IDs used to filter results, if specified
`measurements` - `[Measurement!]!`	A series of date/timestamps within the specified date range and associated values

Example

{
  "startDate": "2023-01-31",
  "endDate": "2023-03-31",
  "portfolioUuids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "portfolioType": "external_regular",
  "attributes": ["abc123"],
  "bvids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "measurements": [Measurement]
}

Types

TopTenInfo

Description

A collection of fourth party exposure organized by finding code. Includes finding code's description, summary, and assessment date.

Fields

Field Name	Description
`summary` - `String`	A brief summary of the finding code
`description` - `String`	A description of what the finding code is.
`assessmentDateEnd` - `String`	The most recent assessment date
`findingCode` - `Int64`	The finding code of these vendor discoveries.
`assets` - `[Asset]`	List of exposures of a specific finding code

Example

{
  "summary": "abc123",
  "description": "xyz789",
  "assessmentDateEnd": "abc123",
  "findingCode": 123,
  "assets": [Asset]
}

Types

TopVendorByCategory

Fields

Field Name	Description
`vendor` - `String!`	The name of the vendor.
`count` - `Int!`	Count of company/product per category for the customer.

Example

{"vendor": "xyz789", "count": 987}

Types

TopVendorsByCategoryInfo

Fields

Field Name	Description
`topVendorsByCategory` - `[TopVendorByCategory!]`	Returns the top three occurrence vendors per category for the customer.
`category` - `String!`	The category we are checking the top occurrence of vendors for.

Example

{
  "topVendorsByCategory": [TopVendorByCategory],
  "category": "xyz789"
}

Types

UUID

Description

A UUID is a 128 bit (16 byte) Universal Unique IDentifier as defined in RFC 4122.

Example

"94416a86-6816-47dd-a9e4-a4793ac5b7b4"

Types

User

Description

SCD portal/API user, that is part of the UserInfo type returned by the userInfo query, and is returned by the myUser query and user-related mutations, and is part of the Role type.

Fields

Field Name	Description
`uuid` - `UUID!`	User's UUID
`username` - `String!`	Login/username (must be an email address)
`firstName` - `String!`	First name
`lastName` - `String!`	Last name
`email` - `String!`	Email address
`status` - `UserStatus!`	Okta status. Users must have ACTIVE status to use the portal.
`userType` - `String!`	Okta user type
`userCategory` - `UserCategory!`	User category (External/External_Test/Internal). External (non-BlueVoyant) users are only allowed to view other external users
`userClass` - `UserClass!`	User class (Client/Monitored_Company). Monitored_Company users are only allowed to see the company in the bvid field
`bvid` - `UUID`	BV ID for the company that user is allowed to view if user is a Monitored_Company user
`primaryName` - `String`	Primary name of the company that user is allowed to view if user is a Monitored_Company user (has bvid field set)
`jobTitle` - `String`	Job title
`businessPhoneNumber` - `String`	Primary/business phone number
`mobilePhoneNumber` - `String`	Mobile phone number
`ssoManagedFlag` - `Boolean!`	Whether the user is under SSO management. If so, most user fields cannot be changed from this API.
`lastLoginTS` - `String`	Last time user logged in with Okta (to portal)
`createdTS` - `String!`	Timestamp when created
`updatedTS` - `String!`	Timestamp when last updated
`createdBy` - `String!`	Username that created this item
`updatedBy` - `String!`	Username that last updated this item
`roles` - `[Role!]`	Roles that the user has
`groups` - `[Group!]`	Groups that the user has
`functions` - `[Function!]`	Functions that the user has access to in the portal
`temporaryAdminFlag` - `Boolean!`	Whether the user currently has temporary admin privileges from the adminOn mutation. This will be false if the user has a permanent admin role.
`temporaryAdminExpirationTS` - `String`	The expiration time if the user currently has temporary admin privileges from the adminOn mutation. This will not be set if the user has a permanent admin role.

Example

{
  "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "username": "xyz789",
  "firstName": "abc123",
  "lastName": "xyz789",
  "email": "xyz789",
  "status": "STAGED",
  "userType": "abc123",
  "userCategory": "External",
  "userClass": "Client",
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "primaryName": "xyz789",
  "jobTitle": "xyz789",
  "businessPhoneNumber": "abc123",
  "mobilePhoneNumber": "xyz789",
  "ssoManagedFlag": false,
  "lastLoginTS": "abc123",
  "createdTS": "xyz789",
  "updatedTS": "xyz789",
  "createdBy": "xyz789",
  "updatedBy": "abc123",
  "roles": [Role],
  "groups": [Group],
  "functions": [Function],
  "temporaryAdminFlag": false,
  "temporaryAdminExpirationTS": "2023-09-29T18:59:37Z"
}

Types

UserCategory

Description

User categories, which are part of the User type and the UserFilter filter

Values

Enum Value	Description
`External`	User is associated with a client. External users are only allowed to view other external users
`External_Test`	User is a test user, which behaves more or less like an external user
`Internal`	User is internal to BlueVoyant

Example

"External"

Types

UserClass

Description

User classes, which are part of the User type and the UserFilter filter

Values

Enum Value	Description
`Client`	User is a regular client user
`Monitored_Company`	User is limited to viewing a single company

Example

"Client"

Types

UserClientAdd

Description

Input to add a new client to an existing SCD portal user (if user does not have a client) from userClientAdd. This endpoint is limited to superadmins.

Fields

Input Field	Description
`userUuid` - `UUID!`	Must specify the user UUID
`clientUuid` - `UUID!`	Must specify the client UUID to be added
`roleUuids` - `[UUID!]!`	Role UUIDs - one or more role UUIDs that user should have

Example

{
  "userUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "clientUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "roleUuids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ]
}

Types

UserClientDelete

Description

Input to remove the client (if it's the only one) from an existing SCD portal user from userClientDelete (for instance if the user should no longer have SCD portal access, but should keep access to other BlueVoyant portals). Admins may not specify the clientUuid.

Fields

Input Field	Description
`userUuid` - `UUID!`	Must specify the user UUID to remove the client from
`clientUuid` - `UUID`	If superadmin, can specify the client UUID to be removed; defaults to the current clientUuid

Example

{
  "userUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "clientUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
}

Types

UserClientSetDefault

Description

Input to set the default client for an SCD portal user from userClientSetDefault. Admins can set only the userUuid. Non-admin users may not set any arguments.

Fields

Input Field	Description
`userUuid` - `UUID`	If superadmin or admin, can specify the user UUID. Other users can only set their own default.
`clientUuid` - `UUID`	If superadmin, can specify the new default client UUID; defaults to the current clientUuid. It must already be one of the user's clients.

Example

{
  "userUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "clientUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
}

Types

UserFilter

Description

Filter users in the userInfo query

Fields

Input Field	Description
`uuids` - `[UUID!]`	Filter users by one or more IDs in UUID format. Default = `null`
`usernames` - `[String!]`	Filter users by one or more usernames. Default = `null`
`usernamesWildcard` - `[String!]`	Filter users by one or more usernames, with wildcard matching. Default = `null`
`firstNames` - `[String!]`	Filter users by one or more first names, with wildcard matching. Default = `null`
`lastNames` - `[String!]`	Filter users by one or more last names, with wildcard matching. Default = `null`
`statuses` - `[UserStatus!]`	Filter users by one or more Okta statuses. Default = `null`
`userCategories` - `[UserCategory!]`	Filter users by one or more user categories. External users (those associated with a client), can only see 'External' users. Any other values are ignored. Default is null (display all users) for users in the 'Internal' category. Default = `null`
`userClasses` - `[UserClass!]`	Filter users by one or more user classes. Default is 'Client' for users in the 'External' category (those associated with a client). Default is null (display all users) for users in the 'Internal' category. Default = `null`
`sortBy` - `[UserSortBy]`	Sort returned users by specified fields and directions

Example

{
  "uuids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "usernames": ["xyz789"],
  "usernamesWildcard": ["xyz789"],
  "firstNames": ["abc123"],
  "lastNames": ["abc123"],
  "statuses": ["STAGED"],
  "userCategories": ["External"],
  "userClasses": ["Client"],
  "sortBy": [UserSortBy]
}

Types

UserGroupsToUpdate

Description

Input to update SCD portal user's groups.

Fields

Input Field	Description
`userUuid` - `UUID!`	Must specify the user UUID to be updated
`groupUuidsToAdd` - `[UUID!]`	IDs of groups to add to user (in UUID format)
`groupUuidsToDelete` - `[UUID!]`	IDs of groups to delete from the user (in UUID format)

Example

{
  "userUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "groupUuidsToAdd": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "groupUuidsToDelete": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ]
}

Types

UserInfo

Description

This is the holder for users, with pagination and counts. Returned by the userInfo query

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`	Limit and offset echo back the parameters
`totalCount` - `Int!`	Count of users matching filter regardless of whether they fit within limit
`pageLength` - `Int!`	Count of users returned
`users` - `[User!]`	SCD portal/API users

Example

{
  "offset": 123,
  "limit": 987,
  "totalCount": 987,
  "pageLength": 987,
  "users": [User]
}

Types

UserRolesToUpdate

Description

Input to update SCD portal user's roles. The user must always have exactly one main role, but can have multiple extension roles.

Fields

Input Field	Description
`userUuid` - `UUID!`	Must specify the user UUID to be updated
`roleUuidsToAdd` - `[UUID!]`	IDs of roles to add to user (in UUID format)
`roleUuidsToDelete` - `[UUID!]`	IDs of roles to delete from the user (in UUID format)
`replaceAllRolesFlag` - `Boolean`	If specified, replace all the user's roles with those in roleUuidsToAdd

Example

{
  "userUuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "roleUuidsToAdd": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "roleUuidsToDelete": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "replaceAllRolesFlag": true
}

Types

UserSortBy

Description

Sort users in the UserFilter type

Fields

Input Field	Description
`field` - `UserSorts!`	Field by which to sort users
`direction` - `SortDirection`	Direction in which to sort users (asc/desc). Default = `asc`

Example

{"field": "uuid", "direction": "asc"}

Types

UserSorts

Description

Fields available in the UserSortBy type by which to sort users; default: uuid/asc

Values

Enum Value	Description
`uuid`	User's ID in UUID format
`username`	User's username/login
`firstName`	User's first name
`lastName`	User's last name
`email`	User's email address
`jobTitle`	User's job title
`status`	User's Okta status - sorted according to the order specifed in UserStatus
`userCategory`	User's category - sorted according to the order specifed in UserCategory. External users can only view other external users
`userClass`	User's class - sorted according to the order specifed in UserClass
`primaryName`	The primary name associated with the company in the bvid field, if user has Monitored_Company class
`lastLoginTS`	Last time user logged in with Okta (to portal)
`createdTS`	Timestamp when created
`updatedTS`	Timestamp when last updated

Example

"uuid"

Types

UserStatus

Description

User OKTA statuses

Values

Enum Value	Description
`STAGED`	User has been created but not activated
`PROVISIONED`	User has been activated but has not completed the activation/welcome flow
`ACTIVE`	User is active and has access to the system
`RECOVERY`	User's password has been reset but user has not completed reset flow
`LOCKED_OUT`	User is locked out after too many incorrect password attempts
`PASSWORD_EXPIRED`	User's password is expired and user must change it at the next login
`SUSPENDED`	User has been prevented from logging in
`DEPROVISIONED`	User has been deactivated and removed from assigned applications

Example

"STAGED"

Types

UserToAdd

Description

Input to create new SCD portal user

Fields

Input Field	Description
`firstName` - `String!`	First name
`lastName` - `String!`	Last name
`username` - `String!`	Login/username (must be an email address)
`email` - `String`	Email address (normally the same as username)
`jobTitle` - `String`	Job title
`businessPhoneNumber` - `String`	Primary/business phone number
`mobilePhoneNumber` - `String`	Mobile phone number
`roleUuids` - `[UUID!]!`	Role UUIDs - one or more role UUIDs that user should have
`groupUuids` - `[UUID!]`	Group UUIDs - zero or more group UUIDs that user should have

Example

{
  "firstName": "abc123",
  "lastName": "xyz789",
  "username": "xyz789",
  "email": "xyz789",
  "jobTitle": "xyz789",
  "businessPhoneNumber": "abc123",
  "mobilePhoneNumber": "xyz789",
  "roleUuids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ],
  "groupUuids": [
    "94416a86-6816-47dd-a9e4-a4793ac5b7b4"
  ]
}

Types

UserToUpdate

Description

Input to update SCD portal user

Fields

Input Field	Description
`uuid` - `UUID!`	Must specify the UUID to be updated
`firstName` - `String`	First name
`lastName` - `String`	Last name
`username` - `String`	Login/username (must be an email address)
`email` - `String`	Email address (normally the same as username)
`jobTitle` - `String`	Job title
`businessPhoneNumber` - `String`	Primary/business phone number
`mobilePhoneNumber` - `String`	Mobile phone number

Example

{
  "uuid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "firstName": "abc123",
  "lastName": "abc123",
  "username": "abc123",
  "email": "abc123",
  "jobTitle": "abc123",
  "businessPhoneNumber": "xyz789",
  "mobilePhoneNumber": "xyz789"
}

Types

VendorContact

Description

Vendor contacts are contacts AT the vendor/monitored company who receive escalations

Fields

Field Name	Description
`id` - `Int!`
`contactName` - `String!`	Full name of contact
`firstName` - `String!`	Use 'contactName'
`lastName` - `String!`	Use 'contactName'
`email` - `String!`	Contact's email address - unique for the client and BV ID
`jobTitle` - `String!`	Contact's job title
`businessPhoneNumber` - `String!`	Contact's phone number
`bvid` - `UUID!`	BV ID of the company for which contact receives escalations
`primaryName` - `String!`	Primary name of the company for which contact received escalations
`escalationPreference` - `AddressType!`	Recipient field for contact's email address: 'to' or 'cc' (primary/notification)
`addressType` - `AddressType!`	Use 'escalationPreference'
`mobilePhoneNumber` - `String!`	No longer supported
`customerProvided` - `Boolean!`	All contacts displayed here are provided by the client
`requirePortalProvision` - `Boolean!`	No longer supported
`source` - `String`	No longer supported
`createdTS` - `String!`	Timestamp when created
`updatedTS` - `String!`	Timestamp when last updated
`createdBy` - `String!`	Username that created this item
`updatedBy` - `String!`	Username that last updated this item

Example

{
  "id": 123,
  "contactName": "xyz789",
  "firstName": "xyz789",
  "lastName": "xyz789",
  "email": "abc123",
  "jobTitle": "xyz789",
  "businessPhoneNumber": "abc123",
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "primaryName": "abc123",
  "escalationPreference": "to",
  "addressType": "to",
  "mobilePhoneNumber": "xyz789",
  "customerProvided": true,
  "requirePortalProvision": true,
  "source": "abc123",
  "createdTS": "abc123",
  "updatedTS": "abc123",
  "createdBy": "xyz789",
  "updatedBy": "xyz789"
}

Types

VendorContactInfo

Fields

Field Name	Description
`offset` - `Int!`	Offset and limit echo back the parameters
`limit` - `Int`	Limit and offset echo back the parameters
`totalCount` - `Int!`	Count of contacts matching filter regardless of whether they fit within limit
`pageLength` - `Int!`	Count of contacts returned
`vendorContacts` - `[VendorContact!]`	Vendor contacts in the client's portfolios

Example

{
  "offset": 987,
  "limit": 123,
  "totalCount": 987,
  "pageLength": 123,
  "vendorContacts": [VendorContact]
}

Types

VendorContactToAdd

Description

Input to create a new vendor contact - a contact AT the vendor/monitored company who receives escalations

Fields

Input Field	Description
`contactName` - `String!`	Full name of contact
`email` - `String!`	Contact's email address - unique for the client and BV ID
`businessPhoneNumber` - `String`	Contact's phone number
`jobTitle` - `String`	Contact's job title
`bvid` - `UUID!`	BV ID of the company for which contact receives escalations
`escalationPreference` - `AddressType!`	Recipient field for contact's email address: 'to' or 'cc' (primary/notification)

Example

{
  "contactName": "abc123",
  "email": "xyz789",
  "businessPhoneNumber": "abc123",
  "jobTitle": "abc123",
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "escalationPreference": "to"
}

Types

VendorContactToUpdate

Description

Input to update a vendor contact - contact AT the vendor/monitored company who receives escalations

Fields

Input Field	Description
`id` - `Int!`
`contactName` - `String`	Full name of contact
`businessPhoneNumber` - `String`	Contact's phone number
`jobTitle` - `String`	Contact's job title
`bvid` - `UUID`	BV ID of the company for which contact receives escalations
`escalationPreference` - `AddressType`	Recipient field for contact's email address: 'to' or 'cc' (primary/notification)

Example

{
  "id": 123,
  "contactName": "xyz789",
  "businessPhoneNumber": "xyz789",
  "jobTitle": "abc123",
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "escalationPreference": "to"
}

Types

VendorDependency

Fields

Field Name	Description
`bvid` - `UUID`	The unique BlueVoyant identifier (BV ID) of the company.
`findingCode` - `Int64`	Finding code is an integer that represents the specific type of a finding. See the dictionary query and the DataDictionary type.
`category` - `String`	The category the of the specific vendor product (Endpoint Security, Email Security, Network Security, etc).
`vendor` - `String`	The name of the vendor.
`product` - `String`	The name of the product that the vendor is providing.
`updatedTS` - `Time`	The timestamp for when this entry was created or updated last.
`company` - `CompanyByService`	Company for each vendor dependency

Example

{
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "findingCode": 123,
  "category": "abc123",
  "vendor": "xyz789",
  "product": "xyz789",
  "updatedTS": "2024-02-06T20:24:21Z",
  "company": Company
}

Types

VendorDependencyCountFilter

Description

The additional filters to use for vendor dependency per-type counts (besides the portfolio/attribute/BV ID ones in the insightsInfo query).

Fields

Input Field	Description
`categories` - `[String!]`	The categories to filter on (with exact, case-sensitive matching)
`categoriesWildcard` - `[String!]`	The categories to filter on (with wildcard matching)
`vendors` - `[String!]`	The software/hardware vendors to filter on (with exact, case-sensitive matching)
`vendorsWildcard` - `[String!]`	The software/hardware vendors to filter on (with wildcard matching)
`products` - `[String!]`	The products to filter on (with exact, case-sensitive matching)
`productsWildcard` - `[String!]`	The products to filter on (with wildcard matching)

Example

{
  "categories": ["abc123"],
  "categoriesWildcard": ["xyz789"],
  "vendors": ["abc123"],
  "vendorsWildcard": ["abc123"],
  "products": ["abc123"],
  "productsWildcard": ["xyz789"]
}

Types

VendorDependencyCountsPerCategory

Description

Counts associated with a specific vendor dependency category

Fields

Field Name	Description
`category` - `String!`	The category
`vendorCount` - `Int64!`	The number of software/hardware vendors associated with this category and filters
`productCount` - `Int64!`	The number of products associated with this category and filters
`companyCount` - `Int64!`	The number of companies associated with this category and filters

Example

{
  "category": "abc123",
  "vendorCount": 123,
  "productCount": 123,
  "companyCount": 123
}

Types

VendorDependencyCountsPerCategoryInfo

Description

This is the holder for VendorDependencyCountsPerCategory, from vendorDependencyCountsPerCategory in the insightsInfo query, with pagination and counts

Fields

Field Name	Description
`totalCount` - `Int64!`	Total number of items that match the filters, regardless of limit
`pageLength` - `Int!`	The number of items returned
`totalCompanyCount` - `Int64!`	Total number of companies that match the filters, regardless of limit
`items` - `[VendorDependencyCountsPerCategory!]`	The list of objects returned from the request

Example

{
  "totalCount": 123,
  "pageLength": 987,
  "totalCompanyCount": 123,
  "items": [VendorDependencyCountsPerCategory]
}

Types

VendorDependencyCountsPerProduct

Description

Counts associated with a specific vendor dependency product

Fields

Field Name	Description
`product` - `String!`	The product
`companyCount` - `Int64!`	The number of companies associated with this product and filters

Example

{"product": "xyz789", "companyCount": 123}

Types

VendorDependencyCountsPerProductInfo

Description

This is the holder for VendorDependencyCountsPerProduct, from vendorDependencyCountsPerProduct in the insightsInfo query, with pagination and counts

Fields

Field Name	Description
`totalCount` - `Int64!`	Total number of items that match the filters, regardless of limit
`pageLength` - `Int!`	The number of items returned
`totalCompanyCount` - `Int64!`	Total number of companies that match the filters, regardless of limit
`items` - `[VendorDependencyCountsPerProduct!]`	The list of objects returned from the request

Example

{
  "totalCount": 123,
  "pageLength": 987,
  "totalCompanyCount": 123,
  "items": [VendorDependencyCountsPerProduct]
}

Types

VendorDependencyCountsPerVendor

Description

Counts associated with a specific vendor dependency software/hardware vendor

Fields

Field Name	Description
`vendor` - `String!`	The software/hardware vendor
`productCount` - `Int64!`	The number of products associated with this software/hardware vendor and filters
`companyCount` - `Int64!`	The number of companies associated with this software/hardware vendor and filters

Example

{
  "vendor": "xyz789",
  "productCount": 123,
  "companyCount": 123
}

Types

VendorDependencyCountsPerVendorInfo

Description

This is the holder for VendorDependencyCountsPerVendor, from vendorDependencyCountsPerVendor in the insightsInfo query, with pagination and counts

Fields

Field Name	Description
`totalCount` - `Int64!`	Total number of items that match the filters, regardless of limit
`pageLength` - `Int!`	The number of items returned
`totalCompanyCount` - `Int64!`	Total number of companies that match the filters, regardless of limit
`items` - `[VendorDependencyCountsPerVendor!]`	The list of objects returned from the request

Example

{
  "totalCount": 123,
  "pageLength": 123,
  "totalCompanyCount": 123,
  "items": [VendorDependencyCountsPerVendor]
}

Types

VendorDependencyDistinctField

Values

Enum Value	Description
`product`
`category`
`vendor`
`companyName`

Example

"product"

Types

VendorDependencyFilter

Fields

Input Field	Description
`categories` - `[String!]`	The category the of the specific vendor product (Endpoint Security, Email Security, Network Security, etc). Exact string matching.
`vendors` - `[String!]`	The name of the vendor. Exact string matching.
`products` - `[String!]`	The name of the product that the vendor is providing. Exact string matching.
`productsWildcard` - `[String!]`	Filters on provided products. Will enforce substring matching.
`vendorsWildcard` - `[String!]`	Filters on provided vendors. Will enforce substring matching.
`categoriesWildcard` - `[String!]`	Filters on provided categories. Will enforce substring matching.
`company` - `String`	The name of the company you would like to filter by.

Example

{
  "categories": ["abc123"],
  "vendors": ["xyz789"],
  "products": ["abc123"],
  "productsWildcard": ["xyz789"],
  "vendorsWildcard": ["abc123"],
  "categoriesWildcard": ["xyz789"],
  "company": "xyz789"
}

Types

VendorDependencyGlobalDistinct

Fields

Field Name	Description
`vendors` - `[String!]`	All unique vendors across all customers in vendor dependency v2.
`categories` - `[String!]!`	All unique categories across all customers in vendor dependency v2.
`products` - `[String!]`	All unique products across all customers in vendor dependency v2.

Example

{
  "vendors": ["abc123"],
  "categories": ["abc123"],
  "products": ["abc123"]
}

Types

VendorDependencyInfo

Fields

Field Name	Description
`globalDistinct` - `VendorDependencyGlobalDistinct`	This struct contains three of the vendor dependency fields: vendor, category, product. Each field will return all unique values for that field over all customers. Please note that NO filters from insightsInfo or vendorDependencyInfo are applied here.
`topThreeVendorsByCategory` - `[TopVendorsByCategoryInfo]`	Returns the top three vendors per category per customer. Categories are an exact string match.
Arguments `categories` - `[String!]`
`vendorDependencies` - `[VendorDependency!]`	A list of all of the vendor dependencies.
`totalCount` - `Int64!`	The total number of objects that fit the filter given regardless of limit.
`pageLength` - `Int!`	The total amount of objects returned to user. Between zero and the limit provided.

Example

{
  "globalDistinct": VendorDependencyGlobalDistinct,
  "topThreeVendorsByCategory": [TopVendorsByCategoryInfo],
  "vendorDependencies": [VendorDependency],
  "totalCount": 123,
  "pageLength": 987
}

Types

VendorDependencyLegacy

Fields

Field Name	Description
`bvid` - `UUID`	The unique BlueVoyant identifier (BV ID) of the company.
`findingCode` - `Int64`	Finding code is an integer that represents the specific type of a finding. See the dictionary query and the DataDictionary type.
`vendor` - `String`	The name of the vendor.
`updatedTS` - `Time`	The timestamp for when this entry was created or updated last.
`company` - `CompanyByService`	Company for each vendor dependency

Example

{
  "bvid": "94416a86-6816-47dd-a9e4-a4793ac5b7b4",
  "findingCode": 123,
  "vendor": "xyz789",
  "updatedTS": "2024-02-06T20:24:21Z",
  "company": Company
}

Types

VendorDependencyLegacyFilter

Fields

Input Field	Description
`vendors` - `[String!]`	The name of the vendor.
`company` - `String`	The name of the company you would like to filter by.

Example

{
  "vendors": ["xyz789"],
  "company": "abc123"
}

Types

VendorDependencyLegacyInfo

Fields

Field Name	Description
`vendorDependencyLegacies` - `[VendorDependencyLegacy!]`	A list of all of the vendor dependencies.
`totalCount` - `Int64!`	The total number of objects that fit the filter given regardless of limit.
`pageLength` - `Int!`	The total amount of objects returned to user. Between zero and the limit provided.

Example

{
  "vendorDependencyLegacies": [VendorDependencyLegacy],
  "totalCount": 123,
  "pageLength": 987
}

Types

VendorDependencyLegacySort

Values

Enum Value	Description
`vendor`
`updatedTS`
`findingCode`
`bvid`
`companyName`
`portfolioName`

Example

"vendor"

Types

VendorDependencyLegacySortBy

Fields

Input Field	Description
`field` - `VendorDependencyLegacySort!`	Field by which to sort vendors. Default = `updatedTS`
`direction` - `SortDirection`	Direction in which to sort users (asc/desc). Default = `asc`

Example

{"field": "vendor", "direction": "asc"}

Types

VendorDependencySort

Values

Enum Value	Description
`category`	The category associated with the product
`vendor`	Name of the vendor providing the product
`product`	The product detected
`updatedTS`	The time the insight was last updated (process date)
`findingCode`	Finding code is an integer that represents the specific type of a finding. See the dictionary query and the DataDictionary type.
`bvid`	The unique BlueVoyant identifier (BV ID) of the company associated with this insight
`companyName`	Primary name of the company
`portfolioName`	Name of the portfolio containing the company

Example

"category"

Types

VendorDependencySortBy

Fields

Input Field	Description
`field` - `VendorDependencySort!`	Field by which to sort vendors. Default = `updatedTS`
`direction` - `SortDirection`	Direction in which to sort vendors (asc/desc). Default = `asc`

Example

{"field": "category", "direction": "asc"}

Types

VendorDiscovery

Description

Vendors known to be used by a company

Fields

Field Name	Description
`vendorType` - `String`
`vendor` - `String`
`lastUpdated` - `String!`

Example

{
  "vendorType": "abc123",
  "vendor": "abc123",
  "lastUpdated": "xyz789"
}

Types

VendorDiscoveryInsights

Description

Vendor discovery insights have vendor discoveries of a specific finding code, and include its summary, description,

Fields

Field Name	Description
`summary` - `String`	A brief summary of the finding code
`description` - `String`	A description of what the finding code is.
`assessmentDateEnd` - `String`	The most recent assessment date
`findingCode` - `Int64`	The finding code of these vendor discoveries.
`vendorDiscovery` - `[VendorDiscovery]`	List of vendor discovery objects of a single finding code

Example

{
  "summary": "abc123",
  "description": "xyz789",
  "assessmentDateEnd": "xyz789",
  "findingCode": 123,
  "vendorDiscovery": [VendorDiscovery]
}

Types

VendorSummarizedCountFilter

Fields

Input Field	Description
`portfolios` - `[String!]`	The portfolios to filter on.
`categories` - `[String!]`	The categories to filter on.

Example

{
  "portfolios": ["xyz789"],
  "categories": ["abc123"]
}

Types

VendorSummarizedCountInfo

Fields

Field Name	Description
`totalCount` - `Int!`	The total count of objects that match the user's request regardless of how many were returned.
`pageLength` - `Int!`	The amount of objects returned to the user.
`items` - `[VendorSummarizedCounts]`	The list of objects returned to the user.

Example

{
  "totalCount": 987,
  "pageLength": 123,
  "items": [VendorSummarizedCounts]
}

Types

VendorSummarizedCountSort

Values

Enum Value	Description
`portfolioName`
`category`

Example

"portfolioName"

Types

VendorSummarizedCountSortBy

Fields

Input Field	Description
`field` - `VendorSummarizedCountSort!`	Field by which to sort vendors. Default = `portfolioName`
`direction` - `SummarizedSortDirection`	Direction in which to sort users (asc/desc). Default = `asc`

Example

{"field": "portfolioName", "direction": "asc"}

Types

VendorSummarizedCounts

Fields

Field Name	Description
`portfolio` - `String!`	The portfolio of this category/client/portfolio combintation.
`category` - `String!`	The category of this category/client/portfolio combintation.
`totalCount` - `Int!`	The amount of vendors of this category/client/portfolio combintation.
`vendors` - `[String!]`	The vendors of this category/client/portfolio combintation.

Example

{
  "portfolio": "xyz789",
  "category": "xyz789",
  "totalCount": 123,
  "vendors": ["abc123"]
}

Types

WaitingFor

Description

Progress is blocked on this party

Values

Enum Value	Description
`BlueVoyant`
`Client`
`Third_Party`
`Unset`

Example

"BlueVoyant"

Documentation by Anvil SpectaQL