How to validate barcode scans 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.

We'll present this message to your users within the app
We'll present this message to your users within the app

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

Click on 'integrations' button at the top of the sheet
Click on 'integrations' button at the top of the sheet

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

Enter the Validation URL you'd like Orca Scan to integrate with
Enter the Validation URL you'd like Orca Scan to integrate with

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 an HTTP header with every request, allowing you to determine if the incoming request is from Orca Scan.


3. Test your Validation URL

Test your validation, if it works then you'll receive a 'passed' message
Test your validation, if it works then you'll receive a 'passed' message

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.

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

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.

Ready to start scanning?