---
title: "Add a VAST companion to a video banner"
type: reference
method: POST
path: /rest-api/banner/{bannerId}/vast/companions.do
tag: "VAST"
---

# Add a VAST companion to a video banner

`POST https://YOUR-NETWORK-DOMAIN/rest-api/banner/{bannerId}/vast/companions.do`

Adds a companion ad to a video banner, as the console's Companions grid does, without a file upload. type STATIC takes an image (JPEG, GIF or PNG) from externalCreativeLink, which is downloaded and stored, and reads its size from the image; IFRAME takes the frame's externalCreativeLink with width and height; HTML_STATIC takes markup with width and height; HTML_TEMPLATE takes a Video Companion templateId with width and height. Needs the VAST Companion Ads permission and update rights on the banner's advertiser. Answers with the banner's companions and the new one's id.

## Path params

| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| `bannerId` | integer | yes | `5001` | Video banner id |

## Form params

| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| `type` | string | no | `STATIC` | Companion resource type |
| `externalCreativeLink` | string | no | `https://cdn.northwind.example/companion-300x250.png` | Image URL for STATIC, frame URL for IFRAME |
| `markup` | string | no | `<a href="https://northwind.example">Shop now</a>` | HTML markup for HTML_STATIC |
| `templateId` | integer | no | `12` | Video Companion template id for HTML_TEMPLATE |
| `width` | integer | no | `300` | Conditionally required — for IFRAME, HTML_STATIC and HTML_TEMPLATE companions. Width in pixels |
| `height` | integer | no | `250` | Conditionally required — for IFRAME, HTML_STATIC and HTML_TEMPLATE companions. Height in pixels |

## Responses

- `200` — {success:true, id, companions:[…]}; success:false with 'errors' naming the missing or invalid field
- `400` — The banner is not a video banner, the template is not a Video Companion template, or type STATIC while file storage is off
- `401` — Authentication error
- `403` — The VAST Companion Ads permission is off, or no update rights on the banner
- `404` — The banner does not exist or is deleted

## Example request

```bash
curl --request POST \
  --url 'https://YOUR-NETWORK-DOMAIN/rest-api/banner/5001/vast/companions.do' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'type=STATIC' \
  --data-urlencode 'externalCreativeLink=https://cdn.northwind.example/companion-300x250.png' \
  --data-urlencode 'markup=<a href="https://northwind.example">Shop now</a>'
```

Source: https://epom.com/ad-server/docs/api/vast/post-banner-vast-companions