Testing with dry_run

Listener does not have a separate sandbox or test mode environment. Your code talks to real workspaces with real data from day one. Instead of a sandbox, the API gives you tools that make that safe.

dry_run#

Every write accepts dry_run: true, in the JSON body or as a query parameter. The API runs the same validation and the same preview logic as the real write, then returns what it would store, without changing anything and without emitting events.

curl https://api.listener.com/v1/campaigns \
  -H "Authorization: Bearer $LISTENER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Acme Coffee Q4 host reads", "brand": "Acme Coffee", "dry_run": true}'

{
  "object": "dry_run",
  "resource": "campaign",
  "would_write": {
    "title": "Acme Coffee Q4 host reads",
    "brand": "Acme Coffee",
    "status": "upcoming"
  }
}

A dry run surfaces the same 400 errors a real write would (unknown show ids, bad dates, missing fields), so it is the right way to validate a payload in CI or before showing a confirmation step to a user.

confirm#

Writes that cannot be undone or that cost money need an explicit confirm: true as well:

• Deleting campaigns, clusters and shared reports.
• Publishing a shared report (it becomes a public URL).
• Refreshing cluster data or a metered platform (TikTok, X, Facebook, Instagram, Threads, LinkedIn), and filing Spotify or Apple data requests.
• Changing the network’s default EMV, which changes EMV figures across the workspace.
• Some edits only need it in certain cases: changing a show or network handle (the old public URL stops working) and editing a brand that several campaigns share. The reference marks these “Some changes need confirm”.

Without confirm, these answer 409 confirmation_required and change nothing. The error carries a preview of exactly what would happen, so you can show it to the user before repeating the request with confirm: true.

A safe development setup#

• Develop with a read-only key. The Read preset cannot change anything, so you can explore every endpoint freely.
• Add write scopes narrowly when you need them, for example only campaigns:write.
• Keep dry_run: true on by default in development builds of anything that writes, and turn it off deliberately.
• Use the Try it console in the API reference. It defaults writes to dry_run.
• Test webhooks with the test event. POST /v1/webhook-endpoints/{id}/test sends a webhook_endpoint.test event to your endpoint right away, without touching data.
• Use a test show for live writes. If you need to exercise real writes, do it against a show or campaign you created for testing, and delete it afterwards.