---
title: "Create a header-bidding tag"
type: reference
method: POST
path: /rest-api/hb-tags.do
tag: "Header Bidding"
---

# Create a header-bidding tag

`POST https://YOUR-NETWORK-DOMAIN/rest-api/hb-tags.do`

Creates a tag on siteId with the fields in the body; anything left out takes the editor's default (refreshSeconds 0, bidTimeoutMs 1000, refreshForegroundOnly true, integration owned, everything else off). A slot names a placement of that site from GET /rest-api/hb-tags/placements and, for a banner, its sizes as ad unit ids from GET /rest-api/hb-tags/ad-units; domain must be one of GET /rest-api/hb-tags/domains. The response is the stored tag and its page code. Fields that were sent but not applied are listed in 'ignoredFields', each with its reason in 'ignoredFieldReasons'. Requires the HEADER_BIDDING_TAB_VISIBLE permission and access to the tag's site. UPDATE access to the site is needed.

## Body

A JSON body. An example, built from the field definitions:

```json
{
  "id": "1",
  "siteId": "139",
  "name": "Futbol24 — desktop",
  "domain": "ads.example.com"
}
```

## Responses

- `200` — {data: tag, code, ignoredFields, ignoredFieldReasons}
- `400` — Refused, the reason in msg or per field in errors — e.g. an unknown serving domain, a slot named twice, a placement of another site, refresh below 30 seconds
- `401` — Authentication error
- `403` — Insufficient permissions, naming the missing one

## Example request

```bash
curl --request POST \
  --url 'https://YOUR-NETWORK-DOMAIN/rest-api/hb-tags.do' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "1",
  "siteId": "139",
  "name": "Futbol24 — desktop",
  "domain": "ads.example.com"
}'
```

Source: https://epom.com/ad-server/docs/api/header-bidding/post-hb-tags