---
title: "Add a content replacement rule to a placement"
type: reference
method: POST
path: /rest-api/placements/{placementId}/content-replacement/create.do
tag: "Placements"
---

# Add a content replacement rule to a placement

`POST https://YOUR-NETWORK-DOMAIN/rest-api/placements/{placementId}/content-replacement/create.do`

Adds a rule as the Add button of the placement's Content replacement card does: from then on every occurrence of 'target' in the markup the placement serves becomes 'replacement'. Matching is literal and case-sensitive, and rules run before macros are expanded, so a replacement may contain macros. 'target' is required, up to 255 characters, and must not repeat a target the placement already has (compared case-insensitively, as the database's unique key compares them); 'replacement' may be empty, which deletes the target from the markup, and holds up to 65,535 bytes. Rules take effect on the ad server's next cache reload and only while the placement's contentReplacementEnabled is true. Requires the PLACEMENT_CONTENT_REPLACEMENT permission and update rights on the placement's site. Parameters that were sent but not applied are listed in 'ignoredFields', each with its reason in 'ignoredFieldReasons'.

## Path params

| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| `placementId` | integer | yes | `4001` | Placement id |

## Form params

| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| `replacement` | string | no | `https://cdn.northwind.example/` | What every occurrence of the target becomes; may contain macros such as $$RANDOM$$. Empty or omitted on create removes the target from the markup. |
| `target` | string | no | `http://cdn.northwind.example/` | The exact text to find in every ad markup the placement serves — literal, no wildcards or regex; up to 255 characters, unique within the placement. Required on create. |

## Responses

- `200` — Rule added: {success, placementId, rule:{id, target, replacement}}
- `400` — Field errors under 'errors': target missing, blank, too long or already used; replacement too long
- `401` — Authentication error
- `403` — The role lacks PLACEMENT_CONTENT_REPLACEMENT, or no update rights on the placement's site
- `404` — The placement does not exist or is deleted

## Example request

```bash
curl --request POST \
  --url 'https://YOUR-NETWORK-DOMAIN/rest-api/placements/4001/content-replacement/create.do' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'replacement=https://cdn.northwind.example/' \
  --data-urlencode 'target=http://cdn.northwind.example/'
```

Source: https://epom.com/ad-server/docs/api/placements/post-placements-content-replacement-create