> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update entity attributes

> Update only custom attributes on an entity — merge new keys or replace the full attributes map. Triggers entity_updated risk matrices when configured.

## Overview

Updates **only** `attributes` on an entity without touching other profile fields. Supports two modes:

| Mode                  | Behavior                                                                            |
| --------------------- | ----------------------------------------------------------------------------------- |
| **`merge`** (default) | Shallow merge: sent keys overwrite or create values; **keys not sent are kept**     |
| **`replace`**         | Full replace: the body `attributes` object becomes the entire map (`{}` clears all) |

Attributes are stored **verbatim** — nested objects act as categories and are returned as sent, same as [Update entity](/en/api-reference/entities/update):

```json theme={null}
{
  "mode": "merge",
  "attributes": {
    "contact": { "phone": "+54..." },
    "otro_grupo": { "branchCode": "AR-01" }
  }
}
```

<Note>Merge is shallow at the top level: sending a category object (e.g. `contact`) overwrites that whole category. Inner keys not included are dropped. Use `replace` for a full rewrite.</Note>

When the assigned risk matrix includes an **`entity_updated`** trigger, rules run after a successful patch (respecting `skipRulesExecution` and matrix `watchFields`). Webhook **`entity.updated`** is emitted with `changes.attributes`.

## Endpoint

```
PATCH http://api.gu1.ai/entities/{id}/attributes
```

## Authentication

Requires `entities:edit` (legacy fallback: `entities:write`).

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Path Parameters

<ParamField path="id" type="string" required>
  UUID of the entity.
</ParamField>

## Request Body

<ParamField body="attributes" type="object" required>
  Attribute map. Stored verbatim: scalar/array values at the root are uncategorized; nested objects act as categories.
</ParamField>

<ParamField body="mode" type="string" default="merge">
  `merge` — additive patch (default). `replace` — full overwrite.
</ParamField>

<ParamField body="skipRulesExecution" type="boolean">
  When `true`, skips risk matrix execution after the update.
</ParamField>

## Response

| Field                        | Type   | Description                               |
| ---------------------------- | ------ | ----------------------------------------- |
| `data.entityId`              | string | Entity UUID                               |
| `data.mode`                  | string | `merge` or `replace` applied              |
| `data.attributes`            | object | Final attributes after the patch          |
| `data.updatedAt`             | string | ISO 8601 timestamp                        |
| `data.rulesExecutionSummary` | object | Risk matrix run summary (when applicable) |

## Examples

### Merge (default)

```bash theme={null}
curl -X PATCH "https://api.gu1.ai/entities/{id}/attributes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "contact": { "phone": "+54115550000" }
    }
  }'
```

Existing keys not included in the request remain unchanged.

### Full replace

```bash theme={null}
curl -X PATCH "https://api.gu1.ai/entities/{id}/attributes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "replace",
    "attributes": {
      "commercial": { "mcc": "5411" }
    }
  }'
```

Keys that existed before but are omitted from `attributes` are **removed**.

## Errors

| HTTP | Code               | When                                           |
| ---- | ------------------ | ---------------------------------------------- |
| 404  | `ENTITY_NOT_FOUND` | Entity missing or wrong org                    |
| 400  | validation         | Invalid body (e.g. `attributes` not an object) |