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

# RTB impid gate: validate bid impression IDs

> Verifies that every bid.impid in the response corresponds to a valid imp.id in the originating OpenRTB request, catching phantom and mismatched bids.

The impid match gate cross-references impression IDs between the bid request and the bid response. Every bid in the response carries an `impid` field that identifies which impression slot it is competing for. If that `impid` does not appear in the request's `imp[].id` array, the bid references a slot that was never offered — a protocol violation that can trigger DSP penalties and waste auction capacity.

## Usage

```typescript theme={null}
import { createEngine, gates } from "@pecta/core";

const engine = createEngine({
  gates: [
    gates.rtb.tmaxGuard({ bufferMs: 15 }),
    gates.rtb.impidMatch(),
    // ...
  ],
  timeout: 15,
});
```

## What the gate checks

The gate reads `imp[].id` from `ctx.input` (the request) and iterates over every `seatbid[].bid[]` in `ctx.output` (the response). For each bid it checks:

1. **Missing impid** — the `bid.impid` field is absent or not a string → fails with `"bid missing impid"`
2. **Unknown impid** — the `bid.impid` value is not in the set of request impression IDs → fails with `"bid impid not present in request"`

When the gate fails, it includes the full set of valid impression IDs in `details.requestImps` so you can diagnose the mismatch:

```json theme={null}
{
  "name": "rtb.impid-match",
  "passed": false,
  "reason": "bid impid not present in request",
  "details": {
    "requestImps": ["imp-abc123", "imp-def456"]
  },
  "latency_ms": 1
}
```

## Skipping behaviour

The gate skips gracefully — returning `passed: true, skipped: true` — in two situations:

* The request has no `imp` objects (no impression IDs to validate against)
* The response contains no `seatbid[].bid[]` entries (no bids to check)

<Info>
  An empty response is not treated as a failure by this gate. Use a separate content gate if you want to enforce that a bidder must always return at least one bid.
</Info>

## Example: failing bid

```json theme={null}
{
  "id": "response-001",
  "seatbid": [
    {
      "bid": [
        {
          "id": "bid-1",
          "impid": "imp-UNKNOWN",
          "price": 1.50,
          "adomain": ["advertiser.com"]
        }
      ]
    }
  ]
}
```

The request only offered impression `imp-abc123`. The bid references `imp-UNKNOWN`, so the gate fails immediately on the first mismatched bid.

## Options

<ParamField path="name" type="string" default="rtb.impid-match">
  Override the gate's name in evaluation results and telemetry.
</ParamField>