# Metadata and external_id

Both let you keep your own data on Vabu OS objects, so you do not need a mapping table.

## external_id

Every object accepts an `external_id`: the ID you use for the same thing in your system.

```json
{ "external_id": "your_order_8842" }
```

- It is unique per tenant, environment and resource type.
- Fetch an object by it: `GET /v1/{resource}/external/{external_id}`.
- You are never forced to create Vabu accounts for your users. A customer with an `external_id` is enough.

## metadata

Every object accepts `metadata`, a map of text keys to text values.

```json
{ "metadata": { "campaign": "launch-2026", "sales_rep": "amina" } }
```

| Limit | Value |
|---|---|
| Keys per object | 50 |
| Key length | 40 characters |
| Value length | 500 characters |

Metadata comes back unchanged. Filter lists with `metadata[key]=value`:

```http
GET /v1/orders?metadata[campaign]=launch-2026
```

Do not store secrets in metadata. It is returned in API responses and in webhook payloads.