How to validate scans with your system in real-time

A Validation URL allows your system to inspect data entered from the Orca Scan mobile app before it is saved to your sheet. This not only allows you to reject invalid data but also provide meaningful feedback to the user about how to resolve the issue.

Quick example

Suppose a user scans a QR Code containing an email address and enters some data. We'll HTTP POST the following to your Validation URL:

{ "___orca_sheet_name": "Vehicle Checks", "___orca_user_email": "hidden@requires.https", "barcode": "hello@orcascan.com" "notes": "Something important!" }

If your system responds with a JSON object containing a title and message in the following format:

{ "title": "Try again", "message": "Please provide more information" }

We'll present that to the user within the app, preventing them from saving the changes until the issue is resolved.

Orca Scan validation error example

Issues are considered resolved when your Validation URL returns an HTTP 200 response with no body. At that point, changes are applied to your sheet and the user is able to progress to the next task.

1. Edit Sheet Integrations

Opening the sheet integration menu

A Validation URL can only be set on sheets created at cloud.orcascan.com. To add a Validation URL, select the sheet you would like to validate, then open the Integration Settings.

2. Add your Validation URL

Sheet validation URL input

Now enter the Validation URL you would like Orca Scan to call as items are updated. Please note: this URL must be publicly accessible.

Security

You can provide a secret that will be sent to your server as a HTTP header with every request, allowing you to determine if the incoming request is from Orca Scan.

3. Test your Validation URL

Sheet validation test passed

You can now test the Validation URL by clicking the Test button. This will HTTP POST a JSON object to your server containing randomly generated data and display the result.

To test an error, simply have your endpoint return a JSON object containing a title and message and hit test again.

Sheet validation test failed

4. Save the changes

Finally, save the changes and you're done. You can now select that sheet in the Orca Scan mobile app and test it.

Validation URL questions?

We're happy to help you get up and running, chat with us live or drop us an email.