REST Placeholders object – Personyze Developer Docs

For information about how REST API works, see rest main page.

A placeholder is a named region of your site that Personyze campaigns can render into. This object creates, renames and deletes them.

You can also manage placeholders in the panel, under Account settings → Main settings → Placeholders.

The endpoint URL is:

app.personyze.com/rest/placeholders

Columns

Column	Description
`id`	Assigned by Personyze. Returned by `POST`, and usable as `/rest/placeholders/{id}`.
`name`	The placeholder's name, as it appears in the panel. Mandatory on `POST`.
`html_id`	A CSS selector identifying the region on your page, e.g. `#sidebar` or `.promo-slot`.
`units_count_max`	How many content units may be shown in this placeholder at once. Defaults to `1`.

Insert example

curl --data '{"name": "Homepage banner", "html_id": "#banner"}' 'https://api:FD09908F25BECB09D78EBEA1DADFB618651F612D@app.personyze.com/rest/placeholders'

Returns the new placeholder's id as a number.

Select example

The whole list — placeholders are few, so reading them all is allowed:

curl 'https://api:FD09908F25BECB09D78EBEA1DADFB618651F612D@app.personyze.com/rest/placeholders'

By name:

curl 'https://api:FD09908F25BECB09D78EBEA1DADFB618651F612D@app.personyze.com/rest/placeholders/where/name=Homepage banner'

Update example

Send only the fields you want to change. At least one of name, html_id, units_count_max must be present, otherwise the request fails with Nothing to update.

curl -X PUT --data '{"html_id": "#main-banner"}' 'https://api:FD09908F25BECB09D78EBEA1DADFB618651F612D@app.personyze.com/rest/placeholders/14'

Delete example

curl -X DELETE 'https://api:FD09908F25BECB09D78EBEA1DADFB618651F612D@app.personyze.com/rest/placeholders/14'

Deleting a placeholder does not delete the campaigns that target it — they simply stop having a place to render.

Note on Wordpress keys

A Wordpress-scoped API key can only see and change placeholders whose name starts with Wordpress:. Attempting to create one under a different name fails with Name must begin with "Wordpress: ". Full-featured keys have no such restriction.