---
title: "List monitored vendors"
method: GET
path: "/vendors"
tags: ["vendors"]
---

# List monitored vendors

`GET /vendors`

## Request

- Base URL: `https://cyber-risk.upguard.com/api/public`
- URL: `https://cyber-risk.upguard.com/api/public/vendors`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/upguard/apis/upguard-cyberrisk-api/docs/vendors/get.ts> (a function with typed inputs; its response is checked against the schema)

If the include_ad_hoc_reports parameter is set to true then vendors with ad hoc reports available will also be returned.

Required API key permissions: `VendorRisk` (select when creating API key in Account Settings)

## Query parameters

- `include_ad_hoc_reports` boolean
- `page_token` string
- `page_size` integer
- `labels` string[]
- `include_risks` boolean

## Response `200`

A list of vendors

- VendorsResponsePayloadBody
  - `next_page_token` string: The token to be used to retrieve the next page of results. Will not be returned if there are no more results.
  - `total_results` integer: The total number of vendors found.
  - `vendors` MonitoredVendor[]: The list of vendors found
    - `assessmentStatus` string: Assessment status for the vendor. Possible values are Published, In progress, Not assessed. The field will be omitted for non monitored vendors.
    - `attributes` object: The attributes applied to the vendor. If no attributes are applied this field will be omitted
    - `automatedScore` integer: The current automated score of the vendor without questionnaire. Omitted if no current scanning score.
    - `category_scores` CategoryScores: A collection of category scores for a vendor
      - `attackSurface` integer
      - `brandProtection` integer: DEPRECATED: Use operationalRisk
      - `brandReputation` integer: DEPRECATED: Use operationalRisk
      - `dataLeakage` integer
      - `dns` integer
      - `emailSecurity` integer
      - `encryption` integer
      - `ipDomainReputation` integer
      - `networkSecurity` integer
      - `operationalRisk` integer
      - `phishing` integer: DEPRECATED: Use ipDomainReputation
      - `questionnaires` integer
      - `vulnerabilityManagement` integer
      - `websiteSecurity` integer
    - `id` integer: The id of the vendor. Its possible for a hostname to change which vendor it belongs to for a number of reasons (eg. Company's legal entity changes, improved data quality, etc...). For this reason, do not assume a hostname will always return the same vendor id.
    - `labels` string[]: Labels that the vendor is currently associated with.
    - `lastAssessed` string, date-time: Date of the last assessment for the vendor. The field will be omitted if no published assessment is present.
    - `lifecycle_stage` string: The lifecycle stage of the vendor in your account: procurement, onboarding, in_use, offboarding or archived. Omitted for vendors that are not monitored, or if the vendor has no stage.
    - `monitored` boolean: Indicates whether the vendor is monitored or not.
    - `name` string: The name of the vendor
    - `overallScore` integer: The current score of the vendor including automated and questionnaire. Omitted if no current overall score.
    - `primary_hostname` string: The primary hostname of the vendor
    - `questionnaireScore` integer: The current questionnaire score of the vendor. Omitted if no current questionnaire score.
    - `risks` VendorsRisk[]: Optional list of risks for the vendor. Note that this is a summary list of risks and does not take into account risk waivers. To have a precise view of a vendor risks use the /risks/vendors endpoint.
      - `category` string: The risk category identifier
      - `description` string: Description of the risk
      - `finding` string: A short description of the finding
      - `id` string: The risk identifier
      - `riskSubtype` string: The subtype of the risk, e.g. the subtype of the verified_vuln:CVE-2021-34473 is CVE-2021-34473. This field will be empty if the risk has no subtype, e.g. for wp_version_exposed, or for generic risks like verified_vuln:* where the subtype is only determined when the full risk is specified.
      - `riskType` string: The type of the risk, e.g. the type of the verified_vuln:CVE-2021-34473 is verified_vuln
      - `severity` string: The risk severity
    - `score` integer: NOTE: deprecated (use OverallScore). The current score of the vendor. A -1 value represents no current score for the vendor.
    - `tier` integer: Tier currently assigned to the vendor. Omitted if no tier is assigned to the vendor.

## Other responses

- `422`: An invalid parameter was supplied or a mandatory parameter was missing
- `429`: Too many requests have been made to this endpoint.
- `500`: An internal system error occurred

---

[API](https://skmtc.dev/upguard/apis/upguard-cyberrisk-api.md) - [All operations](https://skmtc.dev/upguard/apis/upguard-cyberrisk-api/llms.txt) - [OpenAPI document](https://skmtc.dev/upguard/apis/upguard-cyberrisk-api/revisions/d044bf6dc61e?raw)