Entities — create, read, update, delete via API

These pages walk the two entity chains end to end: the demand side (advertiser → campaign → banner) and the supply side (site → zone → placement), then linking, activation and tag retrieval. Examples append $AUTH, the hash-authentication parameters (an X-Api-Key header works the same), and send parameters form-encoded (-d in curl), not as JSON, unless noted otherwise — see the API overview for authentication. Each entity page links every call to its full entry in the generated reference, which lists all of its fields with descriptions and an example request.

What this page does not cover. Capping, limits, targeting, price adjustment rules and bid floors, conversion actions, piggybacks and server-side trackers hang off these same entities but have their own endpoints — see Targeting, capping and limits and Network services and miscellaneous APIs. Pricing is spread over both (see the pricing notes at the end of the first). Third-party tracking codes are on their own page. For the exhaustive parameter table of any endpoint here, use the generated per-tag reference.

Who this is for

Developers and integrators who script an Epom account: network managers building out inventory and demand, publishers managing their own sites, advertisers managing their own campaigns, and admins. Every call runs with the permissions of the user it authenticates as, exactly as that user’s role works in the console.

Which page covers which entity

Page	Covers
Advertisers and campaigns via API	Advertisers: list, read, create, update, delete. Campaigns: CRUD, copy and move, the priority values, permission-gated settings
Banners (creatives) via API	Banners: CRUD, copy and move, every placementType and bannerType, uploading the creative file, creating each type from URLs, files by URL, rewriting landing URLs in bulk
Sites, zones and placements via API	Sites, Zones and Placements: CRUD per placement type, copy and move, serving domains, daisy chaining, content replacement
Linking, status, tracking codes and ad tags via API	Linking banners and placements, activation, approval and status with bulk labels, third-party tracking codes and getting the ad tag

Two create-or-update styles

The API mixes two conventions — know which one your entity uses:

Style	Entities	Create	Update
Single update.do endpoint	Advertiser, Site, Zone, Placement	Call without id	Call with id
Separate create.do / update.do	Campaign, Banner	POST .../create.do	POST .../{id}/update.do

Note: on the four update.do endpoints id is optional, and it is the only thing that tells an update from a create. A parameter the generated reference does not list for an endpoint is not read by it: the call still succeeds, and the name comes back in ignoredFields (see Parameters that were not applied).

Corner case: a deleted advertiser, campaign, banner or site answers 404 to a write as it does to a read — update, capping, limits, pricing, rules and VAST events alike — and so does a campaign or banner whose advertiser (or campaign) was deleted. The message names the entity (Banner 3001 not found.) and nothing is changed. Another customer’s deleted entity answers the same 404 body as an id that never existed, on reads too; only a live entity outside your shares is a 403.

Corner case: a value the database or the console would not take is a 400 naming the field, and nothing is saved. URLs (a banner’s url, imageBannerLink, videoFileLink, vastTagUrl, native click URLs, banners/urls.do, VAST trackers) follow the network’s strict / relaxed URL validation (a server-side setting, strict by default; ask Epom support or your account manager), as the console does. With strict validation, a URL needs a scheme and a host under a registered top-level domain, and tracker macros are accepted inside it: $$NAME$$, ${NAME}, {name}, {{name}}, [name], %%NAME%% and __NAME__. With relaxed validation, the console’s URL check passes any text, and the API’s passes any text except the schemes that run script or read local files — javascript:, vbscript:, livescript:, data:, blob:, file:, filesystem:, view-source: and jar: — which it refuses under either setting. A banner’s own links (url, imageBannerLink, videoFileLink) with whitespace in them are refused either way too.

Corner case: deletion verbs are inconsistent across entities — advertiser and banner deletes use HTTP DELETE, while campaign, site, zone and placement deletes are POST endpoints. Copy the method from the endpoint tables on each entity’s page rather than guessing; the wrong verb answers 405 {"success":false,"message":"This method is not allowed for the requested URL."}.

Related

• Advertisers and campaigns via API
• Banners (creatives) via API
• Sites, zones and placements via API
• Linking, status, tracking codes and ad tags via API
• API overview
• Targeting, capping and limits
• Network services and miscellaneous APIs
• Hierarchy and linking
• Banner types
• Placement types
• Invocation codes