Skip to content
/
Create a vendor

Create a vendor

Request

Creates a vendor in the caller's vendor directory from a curated writable request and returns the created record, scoped server-side to the caller's organization. Requires an Idempotency-Key header (enforced at the gateway); a replay with the same key returns the originally created vendor.

Bodyapplication/jsonrequired

Writable, curated subset for creating a vendor in the caller's directory.

It carries only the fields a caller may set at create time; the organization is derived from the caller's access token. Field types match the Vendor response (same enums, same contract_value minor-units and contract_end_date Timestamp representation) so input and output use the same shapes.

domainNamestringrequired

Primary domain name of the vendor (e.g. "acme.com"). Required; normalized and validated server-side, and deduplicated against the caller's existing directory (organization + domain_name) — a domain already present is rejected with ALREADY_EXISTS.

companyNamestring

Display name of the vendor company. Optional; resolved server-side when omitted.

vendorIdstring

Customer-defined free-text identifier for the vendor (the caller's own external reference, not the vendor's id). Optional.

isMonitoredboolean

Whether the vendor should be actively monitored. Optional; when omitted the vendor is created not monitored (consumes no monitoring slot).

riskLevelstring(RiskLevel)

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.
Default:"RISK_LEVEL_UNSPECIFIED"
Enum:"RISK_LEVEL_UNSPECIFIED""RISK_LEVEL_NONE""RISK_LEVEL_LOW""RISK_LEVEL_MEDIUM""RISK_LEVEL_HIGH""RISK_LEVEL_CRITICAL"
businessImpactstring(BusinessImpact)

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.
Default:"BUSINESS_IMPACT_UNSPECIFIED"
Enum:"BUSINESS_IMPACT_UNSPECIFIED""BUSINESS_IMPACT_NONE""BUSINESS_IMPACT_LOW""BUSINESS_IMPACT_MEDIUM""BUSINESS_IMPACT_HIGH""BUSINESS_IMPACT_CRITICAL"
dataTypesSharedArray of stringsrequired

Categories of data shared with the vendor. Optional; repeated.

accessTypesArray of stringsrequired

Types of access granted to the vendor. Optional; repeated.

contractValuestring, (int64)

Monetary value of the contract, in the minor units of the customer account's currency (e.g. cents for a USD account) — the same representation as Vendor.contract_value. Optional.

contractEndDatestring, (date-time)required

Date the vendor contract expires. Optional; absent when not set. Same representation as Vendor.contract_end_date.

dataRegionstring(DataRegion)

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.
Default:"DATA_REGION_UNSPECIFIED"
Enum:"DATA_REGION_UNSPECIFIED""DATA_REGION_US""DATA_REGION_EU""DATA_REGION_UK""DATA_REGION_CA""DATA_REGION_AU""DATA_REGION_APAC"
curl -i -X POST \
  https://docs.titanapi.securityscorecard.io/_mock/openapi.public/public/v1/vendors/create \
  -H 'Content-Type: application/json' \
  -d '{
    "domainName": "string",
    "companyName": "string",
    "vendorId": "string",
    "isMonitored": true,
    "riskLevel": "RISK_LEVEL_UNSPECIFIED",
    "businessImpact": "BUSINESS_IMPACT_UNSPECIFIED",
    "dataTypesShared": [
      "DATA_TYPE_SHARED_UNSPECIFIED"
    ],
    "accessTypes": [
      "ACCESS_TYPE_UNSPECIFIED"
    ],
    "contractValue": "string",
    "contractEndDate": "2019-08-24T14:15:22Z",
    "dataRegion": "DATA_REGION_UNSPECIFIED"
  }'

Responses

A successful response.

Bodyapplication/json
vendorobject(vendor.v1.Vendor)required

A vendor in the caller's vendor directory, curated for public API consumers.

Response
{
  "vendor": {
    "id": "string",
    "domainName": "string",
    "companyName": "string",
    "companyIndustryCategory": "string",
    "companyLogoUrl": "string",
    "lifecycleStatus": "VENDOR_LIFECYCLE_STATUS_UNSPECIFIED",
    "isMonitored": true,
    "dataRegion": "DATA_REGION_UNSPECIFIED",
    "riskLevel": "RISK_LEVEL_UNSPECIFIED",
    "dataTypesShared": [ … ],
    "businessImpact": "BUSINESS_IMPACT_UNSPECIFIED",
    "vendorId": "string",
    "accessTypes": [ … ],
    "contractValue": "string",
    "contractEndDate": "2019-08-24T14:15:22Z",
    "lastAssessedDate": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z",
    "score": 0,
    "grade": "PUBLIC_LETTER_GRADE_UNSPECIFIED"
  }
}