Submission Handlers | Civio Engage Knowledge Base [Skip to content](#main) [ ![Civio Engage Knowledge Base](/civio-light.svg) ](https://nginx.deploy-lagoon-production.civio-engage-docs.dh1.amazee.io) [Product documentation](/articles) [Release notes](/releases) [Roadmap](/roadmap) [ Support portal ](https://nginx.deploy-lagoon-production.civio-engage-docs.dh1.amazee.io/portal/login) Toggle navigation [Product documentation](/articles) [Release notes](/releases) [Roadmap](/roadmap) [Support portal](https://nginx.deploy-lagoon-production.civio-engage-docs.dh1.amazee.io/portal/login) 1. [Home](/) › 2. [Product documentation](/articles) › 3. [Participation tools](/articles?category=13) › 4. Submission Handlers Submission Handlers =================== Updated 1 week ago · 5 min read Search Search A **submission handler** is something a participation tool does with each submission as it arrives. Two are available: send the submission to one or more email addresses, or post it to another system as JSON. Handlers are set on the individual participation tool, so one survey can email every response to a project inbox without affecting the other tools in the project. For how to build the tool itself, see [Create and edit a survey](/articles/9182830898191-Create-and-edit-a-survey) and [Create and edit poll](/articles/9184031782799-Create-and-edit-poll). How handlers work ----------------- A handler belongs to one participation tool and runs once for each new submission to it. A tool can hold several handlers, and every handler that is enabled runs. Handler What it does **Email** Sends an email containing submission data to one or more addresses. **HTTP Post** Sends the submission to a URL as a JSON request. **A handler acts on every new submission, including ones you later reject.** Handlers run as the submission arrives, which is before anyone moderates it, so a submission that is rejected or deleted afterwards has already been emailed or posted. Only new submissions are acted on. Editing a submission later does not run the handler again. Submissions brought in by an import do count as new, so an enabled handler acts on those too, and re-running the same import plan re-fires every enabled handler again on the submissions it updates, so importing the same file twice can send duplicate emails or HTTP posts. Finding the handlers on a participation tool -------------------------------------------- 1. Open the project, then the participation tool you want to add a handler to. 2. On the tool's overview screen, click **More...** 3. Click **Handlers**. The screen lists every handler on that tool with its type, whether it is enabled, when it was created and by whom. ![The More... menu open on a participation tool, with the Handlers option highlighted](https://engage.knowledge.civ.io/storage/D7FBr5adsXP8587vMDYpqPLMTuQI37AaVLRdHEjA.png) Adding a handler ---------------- 1. Click **+ Add submission handler**. 2. Enter a **Title** in the field at the top of the form. This is only used to identify the handler in the list. 3. Choose the **Handler**: **Email** or **HTTP Post**. The settings underneath change to suit the one you pick. 4. Fill in that handler's settings. 5. Leave **Enabled** ticked for the handler to start acting on new submissions as soon as you save. 6. Click **Save**. ![The Create submission handler form showing the Title field, the Handler list and the Enabled checkbox](https://engage.knowledge.civ.io/storage/YyYzOU150OGj3LOCNuFGDwNJy4Bb8iHUNToZCFBb.png) **Title** and **Handler** are required, as are the required settings on whichever handler you choose, so a partly filled form will not save. Emailing submission data ------------------------ The **Email** handler sends an email for each new submission. Every address you list gets its own copy. Field What to enter **Email addresses** One or more addresses, separated by commas. **Email subject** The subject line. Tokens can be used here. **Email body** The message, written in Markdown. Tokens can be used here. ![The Email handler settings with the Email addresses, Email subject and Email body fields](https://engage.knowledge.civ.io/storage/zNuw59F5XgtFkZ4jpDbdxfXHv6JukHBzzfOCv3Zx.png) The email goes out through the site's own email settings, the same as other platform email. See [Notifications in Civio Engage](/articles/notifications-in-civio-engage). Files uploaded as part of a submission are not attached to the email. Download those from the submission itself. Replacement tokens ------------------ Tokens are placeholders in curly brackets that are swapped for the submission's own data when the handler runs. `{survey:title}` becomes the tool's title, and `{question:your_email}` becomes the answer to that question. Expand **Replacement tokens** on the handler form to see every token available for that tool, then copy the token into your text exactly as shown. The list is built from the tool itself, so it includes a row for each of its questions. ![The expanded Replacement tokens panel listing the tokens available for a survey, including one per question](https://engage.knowledge.civ.io/storage/PSBwQiigPwmo5BIvNFjuH4i1pURAAthm3DaN8UZH.png) Token What it becomes `{submission:data}` Every answer, each under its question label `{submission:id}` The submission's ID `{submission:date}` The date and time of the submission `{submission:submitter_name}` The name on the submitter's account `{submission:submitter_email}` The email on the submitter's account `{survey:title}` The title of the participation tool `{project:title}` The title of the project it sits in `{question:...}` The answer to one question, named as it appears in the token list An anonymous submission has no account behind it, so the two submitter tokens come through empty. Tokens work in the email subject and body, and in the HTTP post body. Posting submission data to another system ----------------------------------------- The **HTTP Post** handler sends each submission to a URL as an HTTP POST request with a JSON body. Use it to pass submissions to a CRM, a records system or an automation tool. Field What to enter **Post URL** The address to post to. **Authentication type** **None**, **OAuth** or **JWT**. OAuth adds an **OAuth client** list; JWT adds a box for the bearer token. **Headers** Optional. One per line, in the format `Header: Value`. **Post body** The JSON to send, built with tokens. **Log response** Records the response and its status code against the handler, which is what you read when troubleshooting. ![The HTTP Post handler settings with the Post URL, Authentication type, Headers and Post body fields](https://engage.knowledge.civ.io/storage/1agCgC76leYX9VQnPFNsccIj13wErTpd23MGgQIO.png) A post body looks like this: ``` { "submission_id": "{submission:id}", "received_at": "{submission:date}", "project": "{project:title}", "name": "{question:your_name}", "email": "{question:your_email}" } ``` The body has to be valid JSON and the form will not save until it is. Take the token names from the **Replacement tokens** list on the same form. **The receiving system's details come from whoever runs it.** The URL, the authentication it expects and the shape of JSON it accepts are all set at that end, not in Civio Engage. This is a technical setup, so your development team or the receiving system's provider is the source of those values. Turning a handler off --------------------- Open the handler, untick **Enabled** and save. It keeps its settings and stops acting on new submissions. ![The Enabled checkbox on a submission handler, with its help text, highlighted](https://engage.knowledge.civ.io/storage/fH7aCBz8XbmXZiungZrpD2n4DtrB0i5fodGJSAyP.png) **Delete** removes the handler entirely. Submissions already collected are unaffected either way. Permissions ----------- Working with handlers needs the submission-handler permission. Administrators hold it, and so does the Project Manager role for participation tools in their team's projects. See [User roles](/articles/9176861358095-User-roles). If **Handlers** does not appear under **More...**, the account's role does not hold that permission. Related articles ---------------- - [Create and edit a survey](/articles/9182830898191-Create-and-edit-a-survey) - [Manage your project participation tools](/articles/9182279163663-Manage-your-project-participation-tools) - [View, moderate, and export participation tool submissions](/articles/9184083413647-View-moderate-and-export-participation-tool-submissions) - [Notifications in Civio Engage](/articles/notifications-in-civio-engage) Was this article helpful? ------------------------- Your feedback helps us prioritise what to rewrite. Yes No [ Back to Participation tools ](/articles?category=13) On this page ### Still need help? Raise a request in the support portal and track it to resolution. [ Submit a support request ](https://nginx.deploy-lagoon-production.civio-engage-docs.dh1.amazee.io/portal/login) Submit a support request through the [support portal](/portal) or email . © 2026 [Civio](https://civ.io) [Privacy Policy](/articles/privacy-policy) [Terms of Use](/articles/terms-of-use)