Server Side Validation

This article covers the what Server Side Validation is and how it is configured. An example of where to user server side validation could include validating an address is within your desired state or postcode. 

Configuration

Add your custom URL or a hosted API endpoint and secret to the form summary page. This will allow you to call this endpoint once prior to submission and once before your workflow begins. 

Validation Fails

If the validation fails on the first call prior to the submission the user will be shown a failure modal. This can be used to include an informative error message explaining why the form failed the validation. For example, "The address you are using is not within the expected Postcode."

If the validation fails on the second call prior to the workflow then an email will be sent to the notification email address configured for the app that the form is being submitted.  

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

For a failure, return a 400 status code and a JSON payload with a user-friendly error message in the body. For a success, you can 200 status code. 

Example

For an example of Server Side Validation check out our GitHub link here, 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(),
  }),
})

console.log('z', z)

function post(req, res) {
  // Custom submission validation. You can use any validation library (or not) that you like 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 One Blink 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": "[email protected]",
    "email": "[email protected]",
    "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
  }
}

Note: The first call prior to submission will not include the submission ID, Submission timestamp, secret, IP address, User and device information.

Get Help

If you have any questions or would like assistance with setting up your Server Side Validation please contact us via this support portal or email [email protected]. We are happy to assist in any way we can.