# Upsert Business Partner Relations

Insert or update Business Partner Relations. Relations that are not listed in the request are not modified.

In D&B storages, not listed relations of class D&B Hierarchy
and one of type https://meta.cdq.com/Business_partner/relation/type/commercial_ultimate or https://meta.cdq.com/Business_partner/relation/type/domestic_commercial_ultimate, are marked as INACTIVE.


Endpoint: PUT /v4/storages/{storageId}/relations
Version: 5
Security: apiKey

## Path parameters:

  - `storageId` (string, required)
    Unique identifier of the Storage.
    Example: "72d6900fce6b326088f5d9d91049e3e6"

## Request fields (application/json):

  - `relations` (array, required)
    Batch of Business Partner relations.

  - `relations.startedAt` (string)
    Describe when this relationship was first established.
    Example: "2025-09-10T10:12:36Z"

  - `relations.endedAt` (string)
    Describe when this relationship ended.
    Example: "2025-09-10T10:12:36Z"

  - `relations.type` (object)
    Provides information about the type of the relationship between two Business Partners like:\ direct parent/child, ultimate parent, branch.

  - `relations.type.name` (string)
    Display name of the Business Partner Relation Type.
    Example: "Commercial ultimate"

  - `relations.type.technicalKey` (string)
    Technical Key of the Business Partner Relation Type.
    Example: "COMMERCIAL_ULTIMATE"

  - `relations.type.url` (string)
    URL to the documentation which summarizes all details of a [Business Partner Relation Type](https://meta.cdq.com/Business_partner/relation/type).
    Example: "https://meta.cdq.com/Business_partner/relation/type"

  - `relations.class` (object)
    Provides information about the classification of the relation.

  - `relations.class.name` (string)
    Display name of the Business Partner Relation Class.
    Example: "CDQ Hierarchy"

  - `relations.class.technicalKey` (string)
    Technical Key of the Business Partner Relation Class.
    Example: "BUSINESS_PARTNER_RELATION_CLASS_CDQ_HIERARCHY"

  - `relations.class.url` (string)
    URL to the documentation which summarizes all details of a [Business Partner Relation Class](https://meta.cdq.com/Business_partner/relation/class).
    Example: "https://meta.cdq.com/Business_partner/relation/class"

  - `relations.startNode` (object)
    Unique identifiers for Business Partner in the relation

  - `relations.startNode.externalId` (string)
    Arbitrary identifier type to mark customer IDs that are "external" from CDQ's perspective. This is the identifier a customer provides to identify its records.
    Example: "The ID managed in the customer's SAP systems."

  - `relations.startNode.dataSourceId` (string)
    Unique identifier for a Data Source of the Storage.
    Example: "648824a691d8d2503d65103e"

  - `relations.endNode` (object)
    Unique identifiers for Business Partner in the relation

  - `relations.deactivatedAt` (string)
    Describe when this relationship was deactivated. Read only.
    Example: "2025-09-10T10:12:36Z"

## Response 200 fields (application/json):

  - `numberOfProvidedRelations` (integer)
    Number of provided Business Partner Relations.
    Example: "10"

  - `numberOfInserts` (integer)
    Number of inserted Business Partners.
    Example: "10"

  - `numberOfUpdates` (integer)
    Number of updated Business Partners.
    Example: "10"

  - `numberOfFailed` (integer)
    Number of failed inserts.
    Example: "10"

  - `failures` (array)
    List of relations failed to be inserted or updated.

  - `failures.startNodeExternalId` (string)
    External ID of a Business Partner.
    Example: "78643267348"

  - `failures.endNodeExternalId` (string)
    External ID of a Business Partner.
    Example: "78643267348"

  - `failures.message` (string)
    Error message.
    Example: "Missing data source ID."