Server Side Validation

Server-side validation allows you to validate a form submission using your own custom URL or hosted API endpoint. This can be useful when validation needs to happen outside of the form itself, such as checking that an address is within an expected state or postcode.

TABLE OF CONTENTS

• Configuring Server-Side Validation
• How validation works
• Validation responses
• Example
• Example request payload
• Getting Help

Configuring Server-Side Validation

To configure Server Side Validation, add your custom URL or hosted API endpoint and secret to the Developer Tools page on the form.

This endpoint is called twice:

• Once before the form is submitted
• Once before the workflow begins

How validation works

Server-side validation checks the submission before it continues through the expected submission process.

If validation succeeds, the form will be submitted as normal.

If validation fails before the form is submitted, the user will see a failure modal. This message should clearly explain why the validation failed. For example:

The address you are using is not within the expected Postcode.

If validation fails before the workflow begins, an email will be sent to the notification email address configured for the app that the form is being submitted through.

Validation responses

For failed validation, return a 400 status code and a JSON payload containing a user-friendly error message in the body.

For successful validation, return a 200 status code.

Example

For an example of Server Side Validation, view the Form Server Validation Example on GitHub, or see the example below.

const { z } = require('zod')

const bodySchema = z.object({
  submission: z.object({
    name: z.string(),
    age: z.number().optional(),
    email: z.string().email(),
  }),
})

function post(req, res) {
  // Custom submission validation. You can use any validation library, or no validation library, to validate your data.
  try {
    const { submission } = bodySchema.parse(req.body)

    // Validation passed, return 200 to proceed with form submission.
    return res.setStatusCode(200)
  } catch (error) {
    // A user-friendly error message can be shown to the user in OneBlink Forms
    // by returning a 400 status code and a JSON payload with a `message` property.
    // There is no character limit, however it is suggested to keep the message
    // short and clear.
    return res.setStatusCode(400).setPayload({
      message:
        'This is my custom friendly error message that will be shown to the user on failed validation',
    })
  }
}

module.exports = { post }

Example request payload

{
  "formsAppId": 1,
  "formId": 1,
  "externalId": "external identifier",
  "secret": "ssshhh",
  "submissionId": "85fad0a4-b778-4aea-a6e7-671d84d58156",
  "submissionTimestamp": "2018-01-01T00:00:00.000Z",
  "jobId": "29e8138d-b28c-49da-b357-f4974adbf0a6",
  "previousFormSubmissionApprovalId": "04dc6796-f593-47a6-ac21-5e00473d86a1",
  "submission": {
    "First_Name": "Jane",
    "Last_Name": "Smith"
  },
  "ipAddress": "86.124.75.76",
  "keyId": "",
  "user": {
    "userId": "81798353-7c7a-481b-89f2-8c5fb83209ca",
    "providerType": "Google",
    "providerUserId": "234891839120312839123",
    "username": "jane@smith.io",
    "email": "jane@smith.io",
    "firstName": "Jane",
    "lastName": "Smith",
    "fullName": "Jane Smith",
    "picture": "https://lh3.googleusercontent.com/a/AATXAJyQ6F_frDWNQguRuVrRmKKs22PYkXDTQlzgDRjp=s96-c"
  },
  "device": {
    "type": "BROWSER",
    "appCodeName": "Mozilla",
    "appName": "Netscape",
    "appVersion": "5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36",
    "cookieEnabled": true,
    "hardwareConcurrency": 12,
    "language": "en-GB",
    "maxTouchPoints": 0,
    "platform": "MacIntel",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36",
    "vendor": "Google Inc.",
    "webdriver": false
  }
}

The first call, which occurs before submission, will not include the submission ID, submission timestamp, secret, IP address, user information, or device information.

Getting Help

If you need any assistance with Server Side Validation, please reach out through the Report Issue menu or email support@oneblink.io.