Insert/Update Third Party Record

Overview Endpoint Reference Responses

Overview

The PUT /api/hub/external-integration/third-parties/upsert endpoint inserts a new Third Party 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 Third Party record or update an existing one in a single call

✓Supply the full record including contacts, external contacts, industry sectors, contract dates, CCPA questions, company address, and contracts

Prerequisites

✓A valid OAuth 2.0 bearer token

Endpoint Reference

Method

PUT

Content-Type

application/json

URL

api/hub/external-integration/third-parties/upsert

Request Body

Location objects in the request body accept countryTwoLetterCode and stateShortValue only. The full location object 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"
        }
      ]
    }
  ],
  "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"
    }
  ],
  "role": "enum: see Company Roles in Appendix",
  "industrySectors": [
    {
      "sector": "enum: see Industry Sectors in Appendix",
      "name": "enum: see Industry Sectors in Appendix"
    }
  ],
  "type": "enum: see Third Party Types in Appendix",
  "contractStartDate": "date",
  "contractEndDate": "date",
  "owningCompanyEntityIds": [
    "uuid"
  ],
  "ccpaQuestions": [
    "enum: see CCPA Questions in Appendix"
  ],
  "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"
    }
  ],
  "website": "string",
  "publiclyTraded": true,
  "stockSymbol": "TDD",
  "revenueLowerBound": 1000000,
  "revenueUpperBound": 2499999,
  "employeeCountLowerBound": 20,
  "employeeCountUpperBound": 49,
  "companyAddress": {
    "fullName": null,
    "email": "test@tdd.com",
    "phone": "123-456-7890",
    "address": "123 Main Street",
    "city": "Vancouver",
    "location": {
      "countryTwoLetterCode": "CA",
      "stateShortValue": "BC"
    },
    "zip": "12345",
    "role": "Contact"
  },
  "contracts": [
    {
      "type": "COMPLIANCE",
      "name": "Compliance Certification or Attestation",
      "notes": "",
      "contractStartDate": null,
      "contractEndDate": null
    }
  ]
}

Sample curl Request

curl -X PUT \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <Auth Token>' \
  --header 'Content-Type: application/json' \
  --data '{ ... }' \
  'api/hub/third-parties/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"
    }
  ],
  "role": "enum: see Company Roles in Appendix",
  "industrySectors": [
    {
      "sector": "enum: see Industry Sectors in Appendix",
      "name": "enum: see Industry Sectors in Appendix"
    }
  ],
  "type": "enum: see Third Party Types in Appendix",
  "contractStartDate": "date",
  "contractEndDate": "date",
  "owningCompanyEntityIds": [
    "uuid"
  ],
  "ccpaQuestions": [
    "enum: see CCPA Questions in Appendix"
  ],
  "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"
    }
  ],
  "website": "string",
  "publiclyTraded": true,
  "stockSymbol": "TDD",
  "revenueLowerBound": 1000000,
  "revenueUpperBound": 2499999,
  "employeeCountLowerBound": 20,
  "employeeCountUpperBound": 49,
  "companyAddress": {
    "email": "test@tdd.com",
    "phone": "123-456-7890",
    "address": "123 Main Street",
    "city": "Vancouver",
    "location": {
      "countryName": "Canada",
      "countryTwoLetterCode": "CA",
      "countryThreeLetterCode": "CAN",
      "countryRegionName": null,
      "globalRegionName": "North America",
      "stateName": "British Columbia",
      "stateShortValue": "BC",
      "provinceName": "British Columbia",
      "provinceShortValue": "BC"
    },
    "zip": "12345",
    "role": "Contact"
  },
  "contracts": [
    {
      "type": "COMPLIANCE",
      "name": "Compliance Certification or Attestation",
      "notes": "",
      "contractStartDate": null,
      "contractEndDate": null
    }
  ]
}

Error Responses

Code: 400 Bad Request

Code: 401 Unauthorized

Code: 403 Forbidden

Code: 404 Not Found

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

Search

Insert/Update Third Party Record