--- updatedAt: 2026-05-29T15:08:02.000Z agentTools: projectIndex: https://developer.onetrust.com/onetrust/llms.txt --- # Update Inventory by External ID Use this API to update the Inventory if already exists or create a new Inventory otherwise. ### Example Request `PUT https://{hostname}/api/inventory/v2/inventories/{type}/reference/{externalId}` `PUT https://trial.onetrust.com/api/inventory/v2/inventories/vendors/reference/43fd3a8d-3f6b-464e-bf43-3f0c6c592442` # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Privacy Automation - Data Mapping Automation", "version": "1.0", "contact": { "name": "OneTrust Support", "url": "https://my.onetrust.com/s/contactsupport" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "description": "The Data Mapping Automation APIs are used to manage structured records (assets, vendors, processing activities, and legal entities), define schema attributes, traverse parent–child hierarchies, and create cross-record relationships—including links to personal data." }, "servers": [ { "url": "https://{hostname}", "variables": { "hostname": { "default": "hostname", "description": "The OneTrust hostname such as app.onetrust.com, app-eu.onetrust.com, app-de.onetrust.com, app-uk.onetrust.com, app-apac.onetrust.com, trial.onetrust.com, or uat.onetrust.com." } } } ], "tags": [ { "name": "Inventory", "description": "APIs used to create and manage inventory records for supported schema types (processing-activities, vendors, assets, entities).", "externalDocs": { "description": "OpenAPI 3.1.0 - Download Definition", "url": "https://developer.onetrust.com/onetrust/openapi/privacy-automation-data-mapping-automation.json" } } ], "x-onetrust": { "spec-label": "OpenAPI 3.1.0", "links": [ "{'Data Mapping Automation Knowledge Base': 'https://my.onetrust.com/s/topic/0TO1Q000000ItRxWAK/data-mapping-automation'}" ] }, "x-readme": { "explorer-enabled": false, "proxy-enabled": false, "metrics-enabled": false }, "paths": { "/api/inventory/v2/inventories/{schemaName}/business-key": { "put": { "operationId": "upsertInventoryUsingPUT", "summary": "Update Inventory by External ID", "description": "Use this API to update the Inventory if already exists or create a new Inventory otherwise.\n\n### Example Request\n\n`PUT https://{hostname}/api/inventory/v2/inventories/{type}/reference/{externalId}`\n\n`PUT https://trial.onetrust.com/api/inventory/v2/inventories/vendors/reference/43fd3a8d-3f6b-464e-bf43-3f0c6c592442`", "tags": [ "Inventory" ], "parameters": [ { "name": "schemaName", "in": "path", "description": "The `name` property of the schema.", "required": true, "schema": { "type": "string", "enum": [ "processing-activities", "vendors", "assets", "entities" ] }, "example": "vendors" }, { "name": "generator", "in": "query", "description": "Optional generator type for the operation.", "required": false, "schema": { "type": "string" }, "example": "API_INTEGRATION" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "string", "oneOf": [ { "$ref": "#/components/schemas/AssetInventoryCreateRequest" }, { "$ref": "#/components/schemas/VendorInventoryCreateRequest" }, { "$ref": "#/components/schemas/EntityInventoryCreateRequest" }, { "$ref": "#/components/schemas/PAInventoryCreateRequest" } ] }, "examples": { "vendors": { "summary": "Vendor Upsert Request", "description": "vendors", "value": { "name": "Test Vendor", "organization": { "value": "aws", "id": "aebedb42-a4fe-4768-aac7-7be1b4c17184" }, "type": { "id": "cc11c8a5-bbb3-4377-a33d-52a23b1455f9", "value": "Regulatory", "seeded": true, "sequence": 0 } } }, "assets": { "summary": "Asset Upsert Request", "description": "assets", "value": { "name": "Test Asset", "organization": { "value": "aws", "id": "aebedb42-a4fe-4768-aac7-7be1b4c17184" }, "location": { "value": "US East", "id": "b2c4d6e8-1234-5678-9abc-def012345678" } } }, "entities": { "summary": "Entity Upsert Request", "description": "entities", "value": { "name": "Test Entity", "organization": { "value": "aws", "id": "aebedb42-a4fe-4768-aac7-7be1b4c17184" }, "primaryOperatingLocation": { "value": "US East", "id": "b2c4d6e8-1234-5678-9abc-def012345678" } } }, "processing-activities": { "summary": "Processing Activity Upsert Request", "description": "processing-activities", "value": { "name": "Test Processing Activity", "organization": { "value": "aws", "id": "aebedb42-a4fe-4768-aac7-7be1b4c17184" } } } } } } }, "responses": { "200": { "description": "OK - Inventory successfully created or updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpsertInventoryResponse" }, "example": { "data": { "id": "c79fb1a9-9406-4e9b-bff7-c72e635ee82b", "name": "Updated Inventory", "externalId": "ext-123" } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests. \nFor more information, see [API Rate Limits](https://developer.onetrust.com/onetrust/reference/rate-limits-overview).", "headers": { "Retry-After": { "schema": { "description": "The number of seconds after which requests will be allowed again.", "format": "int32" } }, "ot-period": { "schema": { "description": "The unit of time for which the rate limit applies", "enum": [ "HOUR", "MINUTE" ] } }, "ot-ratelimit-event-id": { "schema": { "description": "The unique identifier for the rate-limiting event.", "format": "uuid" } }, "ot-request-made": { "schema": { "description": "The number of requests made within the specified period.", "format": "int32" } }, "ot-requests-allowed": { "schema": { "description": "The number of requests allowed within the specified period.", "format": "int32" } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAUTH2": [ "INVENTORY", "INVENTORY_WRITE" ] } ] } } }, "components": { "schemas": { "ObjectReference": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "value": { "type": "string" }, "valueKey": { "type": "string" } } }, "AssetInventoryCreateRequest": { "type": "object", "properties": { "name": { "description": "Name of the inventory", "type": "string", "example": "Test Asset", "minLength": 1 }, "organization": { "description": "Organization reference", "example": { "value": "aws", "id": "01d5d6db-a3f0-424e-9956-cfa205dc8af7" }, "$ref": "#/components/schemas/ObjectReference" }, "location": { "description": "Location reference (required for assets)", "example": { "value": "US East", "id": "b2c4d6e8-1234-5678-9abc-def012345678" }, "$ref": "#/components/schemas/ObjectReference" } }, "required": [ "location", "name", "organization" ] }, "InventoryTypeReference": { "type": "object", "properties": { "id": { "description": "Unique identifier", "type": "string", "format": "uuid", "example": "cc11c8a5-bbb3-4377-a33d-52a23b1455f9" }, "value": { "description": "Display value", "type": "string", "example": "Regulatory" }, "seeded": { "description": "Whether the value is seeded", "type": "boolean", "example": true }, "sequence": { "description": "Sequence", "type": "integer", "format": "int32", "example": 0 }, "hint": { "description": "Optional hint", "type": "string", "example": "some-hint" }, "hintKey": { "description": "Optional hint key", "type": "string", "example": "someHintKey" } } }, "VendorInventoryCreateRequest": { "type": "object", "properties": { "name": { "description": "Name of the inventory", "type": "string", "example": "Test Vendor", "minLength": 1 }, "organization": { "description": "Organization reference", "example": { "value": "aws", "id": "01d5d6db-a3f0-424e-9956-cfa205dc8af7" }, "$ref": "#/components/schemas/ObjectReference" }, "type": { "description": "Type reference", "example": { "id": "cc11c8a5-bbb3-4377-a33d-52a23b1455f9", "value": "Regulatory", "seeded": true, "sequence": 0 }, "$ref": "#/components/schemas/InventoryTypeReference" } }, "required": [ "name", "organization", "type" ] }, "EntityInventoryCreateRequest": { "type": "object", "properties": { "name": { "description": "Name of the inventory", "type": "string", "example": "Test Entity", "minLength": 1 }, "organization": { "description": "Organization reference", "example": { "value": "aws", "id": "01d5d6db-a3f0-424e-9956-cfa205dc8af7" }, "$ref": "#/components/schemas/ObjectReference" }, "primaryOperatingLocation": { "description": "Primary operating location reference (required for entities)", "example": { "value": "US East", "id": "b2c4d6e8-1234-5678-9abc-def012345678" }, "$ref": "#/components/schemas/ObjectReference" } }, "required": [ "name", "organization", "primaryOperatingLocation" ] }, "PAInventoryCreateRequest": { "type": "object", "properties": { "name": { "description": "Name of the inventory", "type": "string", "example": "Test Processing Activity", "minLength": 1 }, "organization": { "description": "Organization reference", "example": { "value": "aws", "id": "01d5d6db-a3f0-424e-9956-cfa205dc8af7" }, "$ref": "#/components/schemas/ObjectReference" } }, "required": [ "name", "organization" ] }, "BulkUpsertInventoryResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organization": { "$ref": "#/components/schemas/ObjectReference" }, "businessOwners": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectReference" } }, "inventoryType": { "type": "string" }, "number": { "type": "integer", "format": "int64" }, "externalId": { "type": "string" }, "isNew": { "type": "boolean" }, "detailsUri": { "type": "string" }, "new": { "type": "boolean" } }, "required": [ "name", "organization" ] } }, "securitySchemes": { "OAUTH2": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://{hostname}/api/access/v1/oauth/token", "scopes": { "INVENTORY": "Inventory Scope gives the user access to read/write operations", "INVENTORY_READ": "Inventory Read Scope gives the user read-only access", "INVENTORY_WRITE": "Inventory Write Scope gives the user write access" } } } } } } } ``` # Sibling pages * [Get List of Inventories](https://developer.onetrust.com/onetrust/reference/getlistofinventoriesusingget.md) * [Get List of Inventories by Criteria](https://developer.onetrust.com/onetrust/reference/getlistofinventoriesbyfiltercriteriausingpost.md) * [Get Inventory by External ID](https://developer.onetrust.com/onetrust/reference/getinventorybyexternalidusingget.md) * [Get Inventory by ID](https://developer.onetrust.com/onetrust/reference/getinventorybyidusingget.md) * [Update Inventory by ID](https://developer.onetrust.com/onetrust/reference/updateinventoryusingput.md) * [Create Inventory](https://developer.onetrust.com/onetrust/reference/createinventoryusingpost.md) * [Delete Inventory](https://developer.onetrust.com/onetrust/reference/deleteinventoryusingdelete.md) * [Copy Inventory](https://developer.onetrust.com/onetrust/reference/copyinventoryusingpost.md) * [Update Inventory Status](https://developer.onetrust.com/onetrust/reference/updateinventorystatusbyidusingput.md)