---
title: "Start monitoring a vendor"
method: POST
path: "/vendor/monitor"
tags: ["vendors"]
---

# Start monitoring a vendor

`POST /vendor/monitor`

## Request

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

Request will fail if you are currently monitoring all the vendors you are licensed for in CyberRisk.

If your account keeps the vendor without monitoring it, the vendor keeps its portfolios, tier, labels and attributes.
The labels param adds labels. It does not replace them.
The tier param replaces the tier.

## Query parameters

- `id` integer
- `hostname` string
- `labels` string[]
- `tier` integer
- `wait_for_scan` boolean

## Response `200`

The vendor was successfully added to the monitored list

- Vendor: A vendor
  - `assessment_status` 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 automated score of the vendor without questionnaire. Omitted if no current scanning score.
  - `categoryScores` 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
  - `category_risk_counts` CategoryRiskCounts: The count of risks, broken down by category, then by severity
    - `attack_surface` RiskCounts: The count of risks for this vendor, broken down by severity
      - `critical` integer
      - `high` integer
      - `low` integer
      - `medium` integer
    - `brand_protection` RiskCounts: The count of risks for this vendor, broken down by severity
      - `critical` integer
      - `high` integer
      - `low` integer
      - `medium` integer
    - `brand_reputation` RiskCounts: The count of risks for this vendor, broken down by severity
      - `critical` integer
      - `high` integer
      - `low` integer
      - `medium` integer
    - `data_leakage` RiskCounts: The count of risks for this vendor, broken down by severity
      - `critical` integer
      - `high` integer
      - `low` integer
      - `medium` integer
    - `dns` RiskCounts: The count of risks for this vendor, broken down by severity
      - `critical` integer
      - `high` integer
      - `low` integer
      - `medium` integer
    - `email_security` RiskCounts: The count of risks for this vendor, broken down by severity
      - `critical` integer
      - `high` integer
      - `low` integer
      - `medium` integer
    - `encryption` RiskCounts: The count of risks for this vendor, broken down by severity
      - `critical` integer
      - `high` integer
      - `low` integer
      - `medium` integer
    - `ip_domain_reputation` RiskCounts: The count of risks for this vendor, broken down by severity
      - `critical` integer
      - `high` integer
      - `low` integer
      - `medium` integer
    - `network_security` RiskCounts: The count of risks for this vendor, broken down by severity
      - `critical` integer
      - `high` integer
      - `low` integer
      - `medium` integer
    - `operational_risk` RiskCounts: The count of risks for this vendor, broken down by severity
      - `critical` integer
      - `high` integer
      - `low` integer
      - `medium` integer
    - `phishing` RiskCounts: The count of risks for this vendor, broken down by severity
      - `critical` integer
      - `high` integer
      - `low` integer
      - `medium` integer
    - `questionnaires` RiskCounts: The count of risks for this vendor, broken down by severity
      - `critical` integer
      - `high` integer
      - `low` integer
      - `medium` integer
    - `vulnerability_management` RiskCounts: The count of risks for this vendor, broken down by severity
      - `critical` integer
      - `high` integer
      - `low` integer
      - `medium` integer
    - `website_security` RiskCounts: The count of risks for this vendor, broken down by severity
      - `critical` integer
      - `high` integer
      - `low` integer
      - `medium` integer
  - `domain_count_active` integer: The total number of active domains for this vendor.
  - `domain_count_inactive` integer: The total number of inactive domains for this vendor.
  - `domain_count_total` integer: The total number of domains for this vendor.
  - `first_monitored` string: The date that this vendor was monitored by your organization.
  - `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.
  - `industry_average_score` integer: The average overall score for the industry this vendor falls into.
  - `industry_group` string: The industry group this vendor falls into.
  - `industry_sector` string: The industry sector this vendor falls into. Industry sectors contain multiple industry groups.
  - `labels` string[]: The labels applied to the vendor. If no labels are present this field will be omitted.
  - `last_assessed` 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 if the vendor has no stage.
  - `name` string: The name of the vendor
  - `note` string: The note applied to the vendor. If no note is applied this field will be omitted
  - `overallScore` integer: The current score of the vendor including automated and questionnaire. Omitted if no current overall score.
  - `overall_risk_counts` RiskCounts: The count of risks for this vendor, broken down by severity
    - `critical` integer
    - `high` integer
    - `low` integer
    - `medium` integer
  - `portfolios` string[]: The portfolios applied to the vendor. If no portfolios are applied this field will be omitted
  - `primary_hostname` string: The primary hostname of the vendor
  - `questionnaireScore` integer: The current questionnaire score of the vendor. Omitted if no current questionnaire score.
  - `reassessment_date` string, date-time: Optional date of the next scheduled assessment for the vendor.
  - `score` integer: NOTE: deprecated (use AutomatedScore). The current automated score of the vendor. A -1 value represents no current score for the vendor.
  - `scores_by_epoch` ScoreByEpoch[]: Overall scores and category scores by epoch. Broken down into now, 1 month ago, 3 months ago, and 1 year ago.
    - `attack_surface` integer
    - `brand_protection` integer: DEPRECATED: Use operational_risk
    - `brand_reputation` integer: DEPRECATED: Use operational_risk
    - `data_leakage` integer
    - `dns` integer
    - `email_security` integer
    - `encryption` integer
    - `epoch` 'now' | '1 month ago' | '3 months ago' | '1 year ago': The name of the epoch the scores are for
    - `ip_domain_reputation` integer
    - `network_security` integer
    - `operational_risk` integer
    - `overall` integer
    - `phishing` integer: DEPRECATED: Use ip_domain_reputation
    - `questionnaires` integer
    - `vulnerability_management` integer
    - `website_security` integer
    - `when` string, date-time: The date of this epoch
  - `tier` integer: The tier applied to the vendor. If no tier is applied to the vendor this field will be omitted
  - `vendor_metadata` VendorMetadata: Various pieces of metadata for the vendor
    - `annual_revenue` integer
    - `employee_count` integer
    - `legal_name` string
    - `location_city` string
    - `location_country` string
    - `location_postcode` string
    - `market_cap` integer

## Other responses

- `202`: The vendor does not currently exist in the system and has been scheduled for addition
- `402`: You are not permitted to monitor the vendor for licensing reasons.
- `404`: The vendor was not found.
- `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)