> For the complete documentation index, see [llms.txt](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/oaa/templates/entity-enrichment-template.md).

# Entity Enrichment

Template for setting custom property values on existing entities in the Veza authorization graph

Use this template to set custom property values on existing entities in the Veza authorization graph using the [Open Authorization API](/4yItIzMvkpAvMVFAamTf/developers/api/oaa.md). Unlike other OAA templates that create new entities, the Entity Enrichment template adds metadata to entities that already exist from other integrations.

Entity enrichment is useful when you have supplemental data about entities that Veza already discovers through native integrations. For example, you might enrich AWS IAM roles with internal compliance metadata, or tag Okta users with cost center information from a custom source.

{% hint style="info" %}
The Entity Enrichment template sets arbitrary custom properties via API push. This is distinct from [Enrichment Rules](/4yItIzMvkpAvMVFAamTf/integrations/configuration/enrichment.md), which are UI-configured rules that set a fixed set of built-in Veza classification attributes (identity type, owner, privileged status, and criticality) at extraction time. Use this template when you need to attach custom metadata beyond those built-in attributes. For assigning entity owners (a built-in attribute), see [OAA Entity Owners](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/oaa-entity-owners.md).
{% endhint %}

The template has two sections:

* **Enriched entity property definitions** - declares the custom properties and their types for each entity type being enriched.
* **Enriched entities** - the list of existing entities to enrich, with values for each declared property.

To use the entity enrichment template, set the template type to `entity_enrichment` when creating a new data provider:

```bash
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"My Enrichment Provider","custom_template":"entity_enrichment"}'
```

## Sample payload

<details>

<summary>AWS IAM enrichment example</summary>

This example enriches AWS IAM roles with internal compliance metadata and AWS IAM users with a purpose description.

```json
{
  "enriched_entity_property_definitions": [
    {
      "entity_type": "AwsIamRole",
      "enriched_properties": {
        "my_company_id": "STRING",
        "company_purpose": "STRING",
        "is_compliance_validated": "BOOLEAN"
      }
    },
    {
      "entity_type": "AwsIamUser",
      "enriched_properties": {
        "company_purpose": "STRING"
      }
    }
  ],
  "enriched_entities": [
    {
      "type": "AwsIamRole",
      "id": "arn:aws:iam::339083562601:role/Administrator",
      "data_source_id": "339083562601:awsiam",
      "properties": {
        "my_company_id": "DCFB16CD-A044-4787-9165-1C926221F887",
        "company_purpose": "Built in Admin role",
        "is_compliance_validated": true
      }
    },
    {
      "type": "AwsIamRole",
      "id": "arn:aws:iam::650251689811:role/andrew_s3_all",
      "data_source_id": "339083562601:awsiam",
      "properties": {
        "my_company_id": "A3F40BAC-1871-4EFC-A0EE-CD77E3F513C27",
        "company_purpose": "Some role for Andrew",
        "is_compliance_validated": false
      }
    },
    {
      "type": "AwsIamUser",
      "id": "arn:aws:iam::339083562601:user/andrew",
      "data_source_id": "339083562601:awsiam",
      "properties": {
        "company_purpose": "Engineering service account"
      }
    }
  ]
}
```

</details>

## Top-level payload

| Field                                  | Type  | Description                                                                                |
| -------------------------------------- | ----- | ------------------------------------------------------------------------------------------ |
| `enriched_entity_property_definitions` | array | List of [property definitions](#enriched-entity-property-definitions) for each entity type |
| `enriched_entities`                    | array | List of [entities](#enriched-entities) to enrich with property values                      |

## Enriched entity property definitions

Each entry declares the custom properties that will be added to a specific entity type, along with their data types. Property types determine how Veza stores and indexes values. For example, `TIMESTAMP` properties enable relative date filters in queries (such as "last 90 days").

```json
"enriched_entity_property_definitions": [
  {
    "entity_type": "AwsIamRole",
    "enriched_properties": {
      "my_company_id": "STRING",
      "is_compliance_validated": "BOOLEAN"
    }
  }
]
```

### Property definition fields

| Field                 | Type       | Description                                                                            |
| --------------------- | ---------- | -------------------------------------------------------------------------------------- |
| `entity_type`         | string     | Veza entity type to enrich (e.g., `AwsIamRole`, `OktaUser`)                            |
| `enriched_properties` | dictionary | Map of property names to their types. See [supported types](#supported-property-types) |

### Supported property types

| Type          | Description                                                    |
| ------------- | -------------------------------------------------------------- |
| `STRING`      | Text value                                                     |
| `NUMBER`      | Numeric value (integer or float)                               |
| `BOOLEAN`     | `true` or `false`                                              |
| `TIMESTAMP`   | Date/time value. Enables relative date filters in Veza queries |
| `STRING_LIST` | List of string values                                          |

## Enriched entities

The list of existing entities to enrich with property values. Each entity must appear exactly once with all properties that should be set. Including an entity with no properties clears all enriched property values from that entity. Only entities in the list are updated; other entities are not affected.

```json
"enriched_entities": [
  {
    "type": "AwsIamRole",
    "id": "arn:aws:iam::339083562601:role/Administrator",
    "data_source_id": "339083562601:awsiam",
    "properties": {
      "my_company_id": "DCFB16CD-A044-4787-9165-1C926221F887",
      "is_compliance_validated": true
    }
  }
]
```

### Enriched entity fields

| Field            | Type       | Description                                                                                                                                                                                                                        |
| ---------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`           | string     | Veza entity type (must match an `entity_type` in the property definitions)                                                                                                                                                         |
| `id`             | string     | Veza unique ID for the entity. For AWS entities, this is the ARN. Each entity must appear only once in the list                                                                                                                    |
| `data_source_id` | string     | Veza data source ID for the entity. For AWS, combine the account ID with the data source type (e.g., `339083562601:awsiam`)                                                                                                        |
| `properties`     | dictionary | Map of property names to values. Keys must be defined in the property definitions, and values must match the declared type. Omitting a key that is defined in the property definitions removes that property value from the entity |

## Creating and updating enrichment data

To create the OAA provider and push enrichment data:

1. **Create the provider** with the `entity_enrichment` template type:

   ```bash
   curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
   -H "authorization: Bearer {API_KEY}" \
   -H "Content-Type: application/json" \
   --data '{"name":"Enrichment Provider","custom_template":"entity_enrichment"}'
   ```
2. **Create a data source** on the provider:

   ```bash
   curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources" \
   -H "authorization: Bearer {API_KEY}" \
   -H "Content-Type: application/json" \
   --data '{"name":"Enrichment Data Source"}'
   ```
3. **Push the enrichment payload** to the data source:

   ```bash
   curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources/{DATASOURCE_ID}:push" \
   -H "authorization: Bearer {API_KEY}" \
   -H "Content-Type: application/json" \
   --data "{\"json_data\": $(jq -Rs . payload.json)}"
   ```

   The push endpoint requires the payload as a JSON-encoded string in the `json_data` field. `jq -Rs .` reads `payload.json` and escapes it as a JSON string. See [OAA API Operations](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/rest-api/operations.md) for compression options.

Updates follow the same push workflow. Each push replaces the enrichment data for the entities included in the payload. Entities not included in the push are not affected.

## Limitations

**Property values vs. property definitions**: You can clear a property value by omitting its key in a subsequent push, or by including the entity with an empty `properties` object. This clears the stored value but does not remove the property definition from the entity type. Once a property name is defined for an entity type, the definition persists in the graph and cannot be removed.

**Provider deletion**: Deleting an enrichment provider does not remove enrichment data from the Veza graph. Data pushed through the provider remains associated with the enriched entities after the provider is deleted. Contact Veza support if you need to fully remove enrichment data from the graph.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/oaa/templates/entity-enrichment-template.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.