# Custom metadata

Source: https://agentboxd.com/docs/metadata

> Attach your own ids and fields to contacts, inboxes and threads, and filter on them.

Metadata links Agentboxd to your own systems. Put your CRM id on a contact, your team name on an inbox, or an order number on a thread. Your agent reads it back with the record and can look the rest up where it lives.

## Where it goes

| Object | Set with | Filter with |
| --- | --- | --- |
| Contact | `PATCH /v1/contacts/:id { metadata }` | `GET /v1/contacts?metadata.crm_id=hs_48213` |
| Inbox | `POST /v1/inboxes { metadata }` or `PATCH /v1/inboxes/:id { metadata }` | `GET /v1/inboxes?metadata.team=support` |
| Thread | `PATCH /v1/threads/:id { metadata }` | Read it on `GET /v1/threads/:id`. |

## Rules

- Values are strings, numbers, booleans or null.
- Updates are merged into what’s there. A `null` value deletes that key.
- Up to 50 keys per object; each value up to 1,000 characters.
- Filters are exact string matches: `?metadata.vip=true` matches the boolean `true` and the string `"true"`.

PATCH /v1/threads/:id:

```bash
curl -s -X PATCH https://api.agentboxd.com/v1/threads/$THREAD_ID \
  -H "Authorization: Bearer $AGENTBOXD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata":{"shopify_order":"1042","crm_ticket":null},"add_labels":["order"]}'
```

Threads also have their own `labels`, set with `add_labels` and `remove_labels` on the same route.

> **Note:** Store pointers, not records. A `crm_id` lets your agent fetch the current customer from your CRM; a copy of the customer would go stale and puts more of your data in more places.