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

# Custom parameters

> Attach your own key/value tags to ad requests and break your reporting down by them. Built for resellers who need per-sub-publisher attribution.

A custom parameter is a key/value tag you attach to an ad request. Adgentek stores it on the
decision, the impression and the click, so your reporting can be broken down by whatever the
value was.

The common use is **sub-publisher attribution**: if you resell inventory to downstream
publishers, send a different value per publisher and your reporting splits requests,
impressions, clicks and revenue per value. That is what lets you reconcile payouts.

<Note>
  Custom parameters are **reporting only**. They do not affect targeting, pricing or which ad is
  selected. Nothing you send here changes the auction.
</Note>

## Sending a parameter

Add a `custom` object to the `/get-ad` request body:

```bash theme={null}
curl -X POST https://api.adgentek.ai/ad-server/v1/get-ad \
  -H "X-MCP-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slot_id": "your-slot-id",
    "surface_type": "conversational",
    "context": { "messages": [{ "role": "user", "content": "..." }] },
    "custom": { "sub_id": "downstream-publisher-42" }
  }'
```

Both keys and values must be **strings**. Numbers and nested objects are not accepted — send
`"depth": "3"` rather than `"depth": 3`.

See [REST API](/publishers/integrations/rest-api) for the rest of the request contract.

<Warning>
  The JavaScript SDK does **not** support custom parameters. `AdgentekAds.showAd()` and
  `getAd()` have no way to pass a `custom` object, so if you integrate through the SDK you
  cannot use this feature yet. Sub-publisher attribution currently requires calling
  `/get-ad` directly.
</Warning>

## Registering a key

Sending a parameter is enough to have it stored and visible, but a key has to be **registered**
before it becomes a reporting dimension you can group by.

Register keys on the **Custom Parameters** screen in your publisher settings. Each key is scoped
to your organization and has:

| Field          | Purpose                                                        |
| -------------- | -------------------------------------------------------------- |
| Key name       | The name you send on the wire. Choose it carefully, see below. |
| Display name   | The label shown in reporting. Safe to change at any time.      |
| Allowed values | Optional. When set, values outside the list are not indexed.   |
| Indexed        | Whether the key is available as a reporting dimension.         |

You can have up to **20 indexed keys** per organization. Keys beyond that can still be sent and
stored, they just are not available to group by.

<Warning>
  **Decide the key name before you start sending traffic.** The wire name is what your historical
  reporting is keyed on, so changing it later splits your history into two dimensions that cannot
  be combined. Pick one, write it down, and keep it.
</Warning>

## Seeing the breakdown

Once a key is registered and indexed, it appears as a dimension in the publisher Report Builder,
where you can group requests, impressions, clicks and revenue by its values.

Values you send before registering a key are still stored on the underlying records, but they do
not appear as a reporting dimension until the key is registered.

## Guidance

* **Never send personal data.** No emails, phone numbers, or user identifiers. These values are
  stored on every event and are visible in reporting.
* **Keep the value set bounded.** One value per downstream publisher is the intended shape. A
  value that varies per request, such as a session or request id, produces a dimension with as
  many rows as you have traffic and is not usable for reporting.
* **Use lowercase names with underscores**, so they stay consistent across surfaces.
* **Register before launch** if you want the breakdown available from your first day of traffic.