Routing rules

Routing rules change where a submission goes based on its answers. Each rule has a list of conditions, and when a submission meets all of them the rule can:

• add addresses to the notification email, or replace its recipients
• send the person to a different page after submitting

For example, send sales enquiries to your sales team and thank them on a sales page, and copy anything that mentions “urgent” to whoever is on call.

Settings

Rules live in settings.routing.rules, a list of up to 20 rules.

{
  "rules": [
    {
      "name": "Sales",
      "conditions": [
        { "field": "topic", "operator": "equals", "value": "sales" }
      ],
      "notify_emails": ["sales@example.com"],
      "notify_mode": "replace",
      "redirect_url": "https://example.com/sales-thanks"
    },
    {
      "name": "Urgent",
      "conditions": [
        { "field": "message", "operator": "contains", "value": "urgent" }
      ],
      "notify_emails": ["oncall@example.com"]
    }
  ]
}

Set them in the form’s settings, for example over the API:

curl -X PATCH https://YOUR-QUICKFORMS-HOST/api/v1/forms/FORM_ID \
  -H "Authorization: Bearer $QUICKFORMS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"routing": {"rules": [{"name": "Sales", "conditions": [{"field": "topic", "operator": "equals", "value": "sales"}], "notify_emails": ["sales@example.com"], "notify_mode": "replace"}]}}}'

Sending settings.routing.rules replaces the whole list rather than merging into it.

Validation

A condition on a field the form doesn’t have gets a 422 on that condition, for example settings.routing.rules.0.conditions.0.field, with “Pick one of the form’s fields.” An unknown operator, an invalid email in notify_emails or a redirect_url that isn’t an http or https URL also gets a 422.

Operators

Conditions compare the field’s answer with value.

How answers are compared:

• Fields with several answers, such as checkboxes: equals matches when value is one of the chosen options, and not_equals when it isn’t. This comparison is case-sensitive. contains looks in the answers joined with , .
• Yes/no answers: a ticked checkbox counts as yes and an unticked one as empty, so use equals with yes, or is_set and is_empty.
• Missing fields count as empty.

The same conditions are used by destinations.

Notification recipients

The notification starts with its usual recipients: settings.notify.emails, or the team owner when that list is empty. Then every matching rule is applied in order:

• add appends the rule’s notify_emails to the recipients so far.
• replace swaps the recipients so far for the rule’s notify_emails.

A rule with no notify_emails doesn’t change the recipients. Duplicate addresses are sent one email. Because rules run in order, a later add rule adds to whatever an earlier replace rule left.

With the two rules above:

If the notification is switched off with settings.notify.enabled: false, routing rules don’t send one either. Rules only change the notification email: the autoresponder, the form webhook and destinations are not affected.

Redirects

The first matching rule with a redirect_url takes the place of the form’s settings.redirect_url for that submission.

• HTML form posts get a 303 redirect to it.

• JSON clients get it as redirect in the response:

  {
    "message": "Thanks! Your submission has been received.",
    "redirect": "https://example.com/sales-thanks",
    "id": "01J...",
    "sandbox": false,
    "spam": null,
    "deliveries": null
  }

  redirect is the form’s own redirect_url when no rule sets one, and null when neither is set.

A _redirect field is still honoured when its host is trusted. The rule’s redirect host counts as trusted, along with the form’s allowed origins. See redirects.

Testing rules

Send a sandbox submission. Its JSON response lists the deliveries that would have been sent, with each target, so you can check which addresses a set of answers reaches without sending anything.