# Offboard a vendor

Offboards (archives) a vendor in the caller's vendor directory and returns the updated record, scoped server-side to the caller's organization. Retains history for audits; does not permanently delete. Idempotent: offboarding an already-offboarded vendor returns its current state. Requires an Idempotency-Key header (enforced at the gateway).

Endpoint: POST /public/v1/vendors/{id}/offboard
Version: Beta

## Path parameters:

  - `id` (string, required)
    Unique identifier of the vendor to offboard (bound from the {id} path parameter).

## Request fields (application/json):

  - `reason` (string)
    Optional caller-supplied audit reason recorded with the offboarding action.

## Response 200:

  - `200` (unknown)
    A successful response.

## Response 200 fields (application/json):

  - `vendor` (object, required)
    A vendor in the caller's vendor directory, curated for public API consumers.

  - `vendor.id` (string, required)
    Unique identifier of the vendor relationship. This is the id GetVendor takes and
ListVendors returns; it is not the customer-defined reference — see vendor_id.

  - `vendor.domainName` (string, required)
    Primary domain name of the vendor.

  - `vendor.companyName` (string)
    Display name of the vendor company.

  - `vendor.companyIndustryCategory` (string)
    Industry category of the vendor company.

  - `vendor.companyLogoUrl` (string)
    URL of the vendor company logo.

  - `vendor.lifecycleStatus` (string, required)
    Lifecycle state of a vendor as exposed on the public API.
- VENDOR_LIFECYCLE_STATUS_UNSPECIFIED: Default zero value; lifecycle status was not set.
- VENDOR_LIFECYCLE_STATUS_NEW: Newly added vendor, not yet onboarded.
- VENDOR_LIFECYCLE_STATUS_ONBOARDED: Vendor is active and monitored.
- VENDOR_LIFECYCLE_STATUS_OFFBOARDED: Vendor has been offboarded (archived).
- VENDOR_LIFECYCLE_STATUS_UNVETTED: Tracked but not monitored: holds metadata only, consumes no monitoring slot.
    Enum: "VENDOR_LIFECYCLE_STATUS_UNSPECIFIED", "VENDOR_LIFECYCLE_STATUS_NEW", "VENDOR_LIFECYCLE_STATUS_ONBOARDED", "VENDOR_LIFECYCLE_STATUS_OFFBOARDED", "VENDOR_LIFECYCLE_STATUS_UNVETTED"

  - `vendor.isMonitored` (boolean, required)
    Whether the vendor is actively monitored.

  - `vendor.dataRegion` (string)
    Data region where a vendor operates, as exposed on the public API.
- DATA_REGION_UNSPECIFIED: Default zero value; data region was not set.
- DATA_REGION_US: United States.
- DATA_REGION_EU: European Union.
- DATA_REGION_UK: United Kingdom.
- DATA_REGION_CA: Canada.
- DATA_REGION_AU: Australia.
- DATA_REGION_APAC: Asia-Pacific.
    Enum: "DATA_REGION_UNSPECIFIED", "DATA_REGION_US", "DATA_REGION_EU", "DATA_REGION_UK", "DATA_REGION_CA", "DATA_REGION_AU", "DATA_REGION_APAC"

  - `vendor.riskLevel` (string)
    Risk level assigned to a vendor, as exposed on the public API.
- RISK_LEVEL_UNSPECIFIED: Default zero value; risk level was not set.
- RISK_LEVEL_NONE: No assessed risk to the vendor relationship.
- RISK_LEVEL_LOW: Minor or well-mitigated exposure.
- RISK_LEVEL_MEDIUM: Moderate exposure that warrants periodic monitoring.
- RISK_LEVEL_HIGH: Significant exposure requiring active oversight.
- RISK_LEVEL_CRITICAL: Severe exposure requiring immediate remediation.
    Enum: "RISK_LEVEL_UNSPECIFIED", "RISK_LEVEL_NONE", "RISK_LEVEL_LOW", "RISK_LEVEL_MEDIUM", "RISK_LEVEL_HIGH", "RISK_LEVEL_CRITICAL"

  - `vendor.dataTypesShared` (array, required)
    Categories of data shared with the vendor.

  - `vendor.businessImpact` (string)
    Business impact if a vendor is compromised, as exposed on the public API.
- BUSINESS_IMPACT_UNSPECIFIED: Default zero value; business impact was not set.
- BUSINESS_IMPACT_NONE: No material impact to the business if this vendor is compromised.
- BUSINESS_IMPACT_LOW: Limited, easily contained disruption.
- BUSINESS_IMPACT_MEDIUM: Noticeable disruption to some business functions.
- BUSINESS_IMPACT_HIGH: Significant disruption to core business functions.
- BUSINESS_IMPACT_CRITICAL: Severe, potentially existential disruption to the business.
    Enum: "BUSINESS_IMPACT_UNSPECIFIED", "BUSINESS_IMPACT_NONE", "BUSINESS_IMPACT_LOW", "BUSINESS_IMPACT_MEDIUM", "BUSINESS_IMPACT_HIGH", "BUSINESS_IMPACT_CRITICAL"

  - `vendor.vendorId` (string)
    Customer-defined free-text reference for the vendor. This is not the vendor-relationship
id — it cannot be passed to GetVendor; use id for that.

  - `vendor.accessTypes` (array, required)
    Types of access granted to the vendor.

  - `vendor.contractValue` (string)
    Monetary value of the contract, in the minor units of the customer account's
currency (e.g. cents for a USD account). Currency is the caller's account
currency; there is no per-vendor currency override.

  - `vendor.contractEndDate` (string, required)
    Date the vendor contract expires; absent when not set.

  - `vendor.lastAssessedDate` (string, required)
    Date the vendor was last assessed/reviewed; absent when never assessed.

  - `vendor.createdAt` (string, required)
    When the vendor was created.

  - `vendor.updatedAt` (string, required)
    When the vendor was last updated.

  - `vendor.score` (integer)
    Vendor's top-level security score (0-100). Absent when the vendor has no
associated scorecard.

  - `vendor.grade` (string)
    Letter grade classification for a curated public score.
    Enum: "PUBLIC_LETTER_GRADE_UNSPECIFIED", "PUBLIC_LETTER_GRADE_A", "PUBLIC_LETTER_GRADE_B", "PUBLIC_LETTER_GRADE_C", "PUBLIC_LETTER_GRADE_D", "PUBLIC_LETTER_GRADE_F"

## Response 400:

  - `400` (unknown)
    INVALID_ARGUMENT: the id is missing or not a valid identifier.

## Response 401:

  - `401` (unknown)
    UNAUTHENTICATED: access token is absent, malformed, or missing the required organization claim.

## Response 403:

  - `403` (unknown)
    PERMISSION_DENIED: access token does not include the vendor-directory.write scope.

## Response 404:

  - `404` (unknown)
    NOT_FOUND: no vendor with the given id exists within the caller's organization.

## Response default:

  - `default` (unknown)
    An unexpected error response.

## Response default fields (application/json):

  - `code` (integer, required)
    The status code, which should be an enum value of
[google.rpc.Code][google.rpc.Code].

  - `message` (string, required)
    A developer-facing error message, which should be in English. Any
user-facing error message should be localized and sent in the
[google.rpc.Status.details][google.rpc.Status.details] field, or localized
by the client.

  - `details` (array, required)
    A list of messages that carry the error details.  There is a common set of
message types for APIs to use.

  - `details.@type` (string)
    A URL/resource name that uniquely identifies the type of the serialized
protocol buffer message. This string must contain at least
one "/" character. The last segment of the URL's path must represent
the fully qualified name of the type (as in
`path/google.protobuf.Duration`). The name should be in a canonical form
(e.g., leading "." is not accepted).
In practice, teams usually precompile into the binary all types that they
expect it to use in the context of Any. However, for URLs which use the
scheme `http`, `https`, or no scheme, one can optionally set up a type
server that maps type URLs to message definitions as follows:
* If no scheme is provided, `https` is assumed.
* An HTTP GET on the URL must yield a [google.protobuf.Type][]
value in binary format, or produce an error.
* Applications are allowed to cache lookup results based on the
URL, or have them precompiled into a binary to avoid any
lookup. Therefore, binary compatibility needs to be preserved
on changes to types. (Use versioned type names to manage
breaking changes.)

Note: this functionality is not currently available in the official
protobuf release, and it is not used for type URLs beginning with
type.googleapis.com. As of May 2023, there are no widely used type server
implementations and no plans to implement one.
Schemes other than `http`, `https` (or the empty scheme) might be
used with implementation specific semantics.