UpdateEntities1

Creates or updates primary entities, or updates parent entities and memberships for secondary entity sets.

Entities are flexible, low-overhead objects used to store domain-specific data like authorized sellers, store locations, or partner lists. Each entity has one primary entity set, and can also belong to secondary entity sets that act like collections.

Primary entity sets create and update canonical entity records. Entity lookup for primary sets uses the external id when provided, then title.

Secondary entity sets are configured as subsets of a parent primary entity set. Non-deleted rows update or create the parent entity in that primary set, then add it to the secondary set.

When replace_entities is true for a primary set, active entities in the target set that are not mentioned in this request will be marked as deleted. When it is true for a secondary set, unmentioned entities are only removed from that secondary set.

Secondary-set requests are atomic. A row with bhid must identify an existing active entity in the secondary set's parent primary set; missing or unavailable Bubblehouse IDs never create entities and never fall back to external ID or title.

Input

• entity_set string required

  API name of the target entity set.

  Entity sets are configured by the Bubblehouse team and define the type of entities they contain. Each entity set has a unique API name that you use to reference it. A primary entity set stores canonical entities; a secondary entity set stores campaign- or collection-specific membership within one parent primary set.

• entities array of Entity1 required

  Entities or membership rows to apply.

• replace_entities boolean optional

  Replace the target set with the provided rows.

  For primary sets, entities in the target set that are not included in this request will be marked as deleted.

  For secondary sets, active members that are not included in this request will be removed from the secondary set, but the entity itself remains active in its primary set.

  When false (default), entities not in this request are left unchanged.

• debug boolean optional

  True to make it easier to debug this call

  Normally, we do not guarantee that updates are processed synchronously. We might do that, or we might return success from this function immediately and queue processing until a later time. Passing "debug": true ensures that processing is immediate and synchronous, and will also fail the call on any warnings, making it easier to diagnose problems.

  Please ensure to never enable debug mode in production, or even during high-volume testing.

Output

A successful response has no meaningful properties and only contains an ok property always set to true:

{"ok": true}

{
  "entities": [
    {
      "alt_titles": [
        "Wal-Mart",
        "Walmart Supercenter"
      ],
      "id": "dealer-001",
      "title": "Walmart"
    },
    {
      "alt_titles": [
        "Target Store"
      ],
      "id": "dealer-002",
      "title": "Target"
    }
  ],
  "entity_set": "authorized-dealers"
}

{
  "ok": true
}

{
  "entities": [
    {
      "id": "dealer-001",
      "title": "Walmart"
    },
    {
      "id": "dealer-003",
      "title": "Best Buy"
    }
  ],
  "entity_set": "authorized-dealers",
  "replace_entities": true
}

{
  "ok": true
}

{
  "entities": [
    {
      "id": "dealer-001"
    },
    {
      "title": "Ace Hardware"
    }
  ],
  "entity_set": "spring-cleaning-eligible-dealers",
  "replace_entities": true
}

{
  "ok": true
}

{
  "entities": [
    {
      "id": "dealer-uk-001",
      "markets": [
        "en-GB"
      ],
      "title": "Tesco"
    },
    {
      "id": "dealer-us-001",
      "markets": [
        "en-US"
      ],
      "title": "Kroger"
    }
  ],
  "entity_set": "authorized-dealers"
}

{
  "ok": true
}

{
  "entities": [
    {
      "id": "dealer-global-001",
      "localizations": {
        "de-DE": {
          "alt_titles": [
            "GM Deutschland"
          ],
          "title": "Global Markt"
        },
        "en-GB": {
          "alt_titles": [
            "GM UK"
          ],
          "title": "Global Mart UK"
        }
      },
      "title": "Global Mart"
    }
  ],
  "entity_set": "authorized-dealers"
}

{
  "ok": true
}

Specific Errors

Global Errors