ads

PATCH /v1/ads/analytics/views/{view_id}

Rename, re-save or schedule a saved view (za-286).

All ads endpoints

All developer docs →

Zinn®, our Viking, hammering at his anvil beside an API endpoint sending events to several listeners.

Authentication

Send an API key as a bearer token. The key must carry the ads.view permission; a key without it is refused with 403, not 404.

This endpoint takes no organisation id. Your key already identifies the organisation it belongs to, and the response is scoped to it.

Try it

Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.

curl -X PATCH https://api.zinndigital.com/v1/ads/analytics/views/{view_id} \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -d '{  }'

Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console

Details

Gated on ads.view; any e-mail field needs ads.manage (422 viewMailManage), and so does name, params or chart on a view that is e-mailed (422 viewMailedManage): that is what its recipients receive (the name is their subject line). Every recipient must be a member of the view's organisation whose role grants ads.view there, checked when it is scheduled and again at every send (a member who loses it stops receiving it). Only the fields sent change. mail_cadence daily sends at 06:00 UTC each day, weekly on Monday at 06:00 UTC, monthly on the 1st at 06:00 UTC, by a Temporal workflow; "" stops the e-mail. Each copy is in the recipient's own language and carries the view's headline figures, its top 10 leaderboard rows, a link to the view and the whole leaderboard as CSV. An organisation not in good standing is skipped for that period and resumes once it is. A refusal is per recipient: the others are still mailed, a retried send mails only the recipients not yet mailed that period, and a recipient refused 3 times is left until the next period (mail_last_error recipientRefused); while a refused recipient has had fewer than 3 refusals the view is retried within the hour. mail_last_sent_at moves only when a copy is accepted, and a period in which nobody received a copy is never reported as sent. Every copy carries its recipient's own one-click unsubscribe (List-Unsubscribe + List-Unsubscribe-Post, and a line in the body), /v1/public/ads/views/u/{token}. Audit action ads.saved_view.save.

Parameters

NameTypeRequiredWhat it is
view_id (path)stringYes—

Request body

NameTypeRequiredWhat it is
namestringNo—
paramsAdsSavedViewParamsNoThe /ads/analytics filters, exactly the analytics API's query parameters (only those set).
chartAdsSavedViewChartNo—
mail_cadenceAdsSavedViewCadenceNo—
mail_recipientsstring[]No—

Response

NameTypeRequiredWhat it is
dataAdsSavedViewYes—

Errors this endpoint can return

401 · 403 · 404 · 422 · 429