Insert/Update IT System Record

Overview Endpoint Reference Responses

Overview

The PUT /api/hub/external-integration/it-systems/upsert endpoint inserts a new IT System record or updates an existing one. If a record with the supplied externalId already exists, it is updated; otherwise a new record is created.

What you can do

✓Insert a new IT System record or update an existing one in a single call

✓Supply the full record including locations, tags, contacts, external contacts, data subjects, data recipients, data elements, processing purposes, and risk scoring

Prerequisites

✓A valid OAuth 2.0 bearer token

Endpoint Reference

Method

PUT

Content-Type

application/json

URL

api/hub/external-integration/it-systems/upsert

Request Body

Location objects in the request body accept countryTwoLetterCode and stateShortValue only. The full location object is returned in the response. The risk object in the request accepts only inherentRiskSeverity and inherentRiskLikelihood; the full risk assessment is returned in the response.

{
  "name": "string",
  "notes": "string",
  "description": "string",
  "ownerIds": [
    "string"
  ],
  "externalId": "string",
  "externalDataSource": "string",
  "locations": [
    {
      "countryTwoLetterCode": "string",
      "stateShortValue": "string"
    }
  ],
  "tags": [
    {
      "groupName": "string",
      "tagValues": [
        {
          "value": "string",
          "externalId": "string"
        }
      ]
    }
  ],
  "dataRetention": {
    "value": "string",
    "summary": "string",
    "dataRetentionType": "enum: Days, Weeks, Months, Years, Other"
  },
  "contacts": [
    {
      "fullName": "string",
      "email": "string",
      "phone": "string",
      "address": "string",
      "city": "string",
      "location": {
        "countryTwoLetterCode": "string",
        "stateShortValue": "string"
      },
      "zip": "string",
      "role": "enum: see Contact Roles in Appendix"
    }
  ],
  "ownedBy": "string",
  "ownedById": "uuid",
  "dataSubjectVolumeName": "string",
  "externalContacts": [
    {
      "fullName": "string",
      "email": "string",
      "phone": "string",
      "address": "string",
      "city": "string",
      "location": {
        "countryTwoLetterCode": "string",
        "stateShortValue": "string"
      },
      "zip": "string",
      "role": "enum: see Contact Roles in Appendix"
    }
  ],
  "dataSubjectTypes": [
    {
      "identifier": "string",
      "dataSubjectType": "string",
      "category": "string",
      "dataSubjectLocations": [
        {
          "countryTwoLetterCode": "string",
          "stateShortValue": "string"
        }
      ]
    }
  ],
  "dataRecipientTypes": [
    {
      "identifier": "string",
      "category": "string",
      "dataRecipientType": "string",
      "dataRecipientLocations": [
        {
          "countryTwoLetterCode": "string",
          "stateShortValue": "string"
        }
      ]
    }
  ],
  "dataElementObjects": [
    {
      "identifier": "string",
      "dataElement": "string",
      "dataElementCategory": "string"
    }
  ],
  "processingPurposeObjects": [
    {
      "identifier": "string",
      "processingPurpose": "string",
      "processingPurposeCategory": "string"
    }
  ],
  "aiUsed": "enum: YES, NO, UNKNOWN, INCOMPLETE",
  "aiNotes": "string",
  "website": "string",
  "risk": {
    "inherentRiskSeverity": 1,
    "inherentRiskLikelihood": 3
  }
}

Sample curl Request

curl -X PUT \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <Auth Token>' \
  --header 'Content-Type: application/json' \
  --data '{ ... }' \
  'api/hub/it-systems/upsert'

Responses

Success Response

Code: 201

{
  "internalId": "uuid",
  "name": "string",
  "notes": "string",
  "description": "string",
  "identifier": "string",
  "accountId": "uuid",
  "created": "timestamp",
  "ownerIds": [
    "string"
  ],
  "externalId": "string",
  "externalDataSource": "string",
  "locations": [
    {
      "countryName": "string",
      "countryTwoLetterCode": "string",
      "countryThreeLetterCode": "string",
      "countryRegionName": "string",
      "globalRegionName": "string",
      "stateName": "string",
      "stateShortValue": "string",
      "provinceName": "string",
      "provinceShortValue": "string"
    }
  ],
  "tags": [
    {
      "groupName": "string",
      "tagValues": [
        {
          "value": "string",
          "externalId": "string"
        }
      ]
    }
  ],
  "dataRetention": {
    "value": "string",
    "description": "string",
    "summary": "string",
    "dataRetentionType": "enum: Days, Weeks, Months, Years, Other"
  },
  "contacts": [
    {
      "fullName": "string",
      "email": "string",
      "phone": "string",
      "address": "string",
      "city": "string",
      "location": {
        "countryName": "string",
        "countryTwoLetterCode": "string",
        "countryThreeLetterCode": "string",
        "countryRegionName": "string",
        "globalRegionName": "string",
        "stateName": "string",
        "stateShortValue": "string",
        "provinceName": "string",
        "provinceShortValue": "string"
      },
      "zip": "string",
      "role": "enum: see Contact Roles in Appendix"
    }
  ],
  "ownedBy": "string",
  "ownedById": "uuid",
  "dataSubjectVolumeName": "string",
  "externalContacts": [
    {
      "fullName": "string",
      "email": "string",
      "phone": "string",
      "address": "string",
      "city": "string",
      "location": {
        "countryName": "string",
        "countryTwoLetterCode": "string",
        "countryThreeLetterCode": "string",
        "countryRegionName": "string",
        "globalRegionName": "string",
        "stateName": "string",
        "stateShortValue": "string",
        "provinceName": "string",
        "provinceShortValue": "string"
      },
      "zip": "string",
      "role": "enum: see Contact Roles in Appendix"
    }
  ],
  "dataSubjectTypes": [
    {
      "identifier": "string",
      "dataSubjectType": "string",
      "category": "string",
      "dataSubjectLocations": [
        {
          "countryName": "string",
          "countryTwoLetterCode": "string",
          "countryThreeLetterCode": "string",
          "countryRegionName": "string",
          "globalRegionName": "string",
          "stateName": "string",
          "stateShortValue": "string",
          "provinceName": "string",
          "provinceShortValue": "string"
        }
      ]
    }
  ],
  "dataRecipientTypes": [
    {
      "identifier": "string",
      "category": "string",
      "dataRecipientType": "string",
      "dataRecipientLocations": [
        {
          "countryName": "string",
          "countryTwoLetterCode": "string",
          "countryThreeLetterCode": "string",
          "countryRegionName": "string",
          "globalRegionName": "string",
          "stateName": "string",
          "stateShortValue": "string",
          "provinceName": "string",
          "provinceShortValue": "string"
        }
      ]
    }
  ],
  "dataElementObjects": [
    {
      "identifier": "string",
      "dataElement": "string",
      "dataElementCategory": "string"
    }
  ],
  "processingPurposeObjects": [
    {
      "identifier": "string",
      "processingPurpose": "string",
      "processingPurposeCategory": "string"
    }
  ],
  "aiUsed": "enum: YES, NO, UNKNOWN, INCOMPLETE",
  "aiNotes": "string",
  "website": "string",
  "risk": {
    "calculatedRisk": "MEDIUM",
    "userEvaluatedRisk": null,
    "inherentRisk": "MEDIUM_REVIEW",
    "residualRisk": null,
    "inherentRiskSeverity": 1,
    "inherentRiskLikelihood": 3
  }
}

Error Responses

Code: 400 Bad Request

Code: 401 Unauthorized

Code: 403 Forbidden

Code: 404 Not Found

TrustArc · Hub API — PUT /api/hub/external-integration/it-systems/upsert · support.trustarc.com

Search

Insert/Update IT System Record