Insert/Update a Business Process Record

Overview Endpoint Reference Responses

Overview

The PUT /api/hub/external-integration/business-processes/upsert endpoint creates a new Business Process 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

✓Create a new Business Process record or update an existing one in a single call

✓Supply the full record including IT Systems, data subjects, data recipients, retention, risk, and owner contact information

Prerequisites

✓A valid OAuth 2.0 bearer token

Endpoint Reference

Method

PUT

Content-Type

application/json

URL

api/hub/external-integration/business-processes/upsert

Request Body

{
  "name": "string",
  "notes": "string",
  "description": "string",
  "accountId": "uuid",
  "externalId": "string",
  "externalDataSource": "string",
  "locations": [
    {
      "countryTwoLetterCode": "string"
    }
  ],
  "tags": [
    {
      "groupName": "string",
      "tagValues": [
        {
          "value": "string",
          "externalId": "string"
        }
      ]
    }
  ],
  "dataRetention": {
    "value": "string",
    "description": "string",
    "summary": "string",
    "dataRetentionType": "enum: Days, Weeks, Months, Years, Other"
  },
  "status": "string",
  "dataSubjectVolumeName": "string",
  "securityControls": [
    "string"
  ],
  "otherSecurityControl": "string",
  "processingPurposeLegalBases": [
    {
      "processingPurpose": "string",
      "legalBasis": "string"
    }
  ],
  "businessProcessOwners": [
    {
      "department": "string",
      "role": "enum: see Company Roles in Appendix",
      "owningCompanyEntity": "string",
      "owningCompanyEntityId": "uuid",
      "ownerContact": {
        "fullName": "string",
        "email": "string",
        "phone": "string",
        "address": "string",
        "city": "string",
        "location": {
          "countryTwoLetterCode": "string"
        },
        "zip": "string",
        "role": "enum: see Contact Roles in Appendix"
      }
    }
  ],
  "aiUsed": "enum: YES, NO, UNKNOWN, INCOMPLETE",
  "aiNotes": "string",
  "dataSubjects": [
    {
      "identifier": "string",
      "dataSubjectType": "string",
      "category": "string",
      "dataSubjectLocations": [
        {
          "countryTwoLetterCode": "string"
        }
      ]
    }
  ],
  "dataRecipients": [
    {
      "identifier": "string",
      "category": "string",
      "dataRecipientType": "string",
      "dataRecipientLocations": [
        {
          "countryTwoLetterCode": "string"
        }
      ]
    }
  ],
  "itSystems": [
    {
      "internalId": "uuid"
    }
  ],
  "risk": {
    "inherentRiskSeverity": 1,
    "inherentRiskLikelihood": 3
  }
}

📋 Note: Location fields in the request body accept countryTwoLetterCode only. The full location object with additional fields is returned in the response.

Sample curl Request

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

Responses

Success Response

Code: 201 Created

{
  "internalId": "uuid",
  "name": "string",
  "notes": "string",
  "description": "string",
  "identifier": "string",
  "accountId": "uuid",
  "created": "timestamp",
  "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"
  },
  "status": "string",
  "dataSubjectVolumeName": "string",
  "securityControls": [
    "string"
  ],
  "otherSecurityControl": "string",
  "processingPurposeLegalBases": [
    {
      "processingPurpose": "string",
      "legalBasis": "string"
    }
  ],
  "businessProcessOwners": [
    {
      "department": "string",
      "role": "enum: see Company Roles in Appendix",
      "owningCompanyEntity": "string",
      "owningCompanyEntityId": "uuid",
      "ownerContact": {
        "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"
      }
    }
  ],
  "aiUsed": "enum: YES, NO, UNKNOWN, INCOMPLETE",
  "aiNotes": "string",
  "dataSubjects": [
    {
      "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"
        }
      ]
    }
  ],
  "dataRecipients": [
    {
      "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"
        }
      ]
    }
  ],
  "itSystems": [
    {
      "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": "Days"
      },
      "ownedBy": "string",
      "ownedById": "uuid",
      "dataSubjectVolumeName": "string",
      "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"
            }
          ]
        }
      ],
      "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/business-processes/upsert  ·  support.trustarc.com