Using Veryfi Lens Instant App or App Clip

You can launch our Android Instant App or iOS App Clip to process a document directly from your WhatsApp bot.

Steps:

Create a Call-to-Action (CTA) component in your WhatsApp bot.
Refer to the WhatsApp documentation:
- Interactive CTA URL Messages

Set the action URL based on the user's device:

iOS:

https://appclip.apple.com/id?p=com.veryfi.Lens-Demo.Clip&${urlParams}

Android:

https://whatsapp-bot.veryfi.com/instantapp/?${urlParams}

Build the URL parameters with the desired Lens configuration:

const urlParams = new URLSearchParams({
    documentType,
    showDocumentTypes,
    autoDocDetectionAndCropIsOn,
    blurDetectionIsOn,
    locationServicesIsOn,
    webhook,
    uploadWithoutProcessingIsOn,
    tags,
    externalId,
    campaignId,
    userId,
    username: encodeURIComponent(username),
    clientId: encodeURIComponent(clientId),
    key: encryptedApiKey,
    cropLayoutIsOn,
    cropLayoutBorderColor,
    cropLayoutStroke,
    cropLayoutCornerRadius,
    cropLayoutWidth,
    cropLayoutHeight,
    cropLayoutTipMessage
});

Parameters

Parameter	Description
`documentType`	Type of document to capture (e.g., "receipt", "long_receipt" or "other").
`showDocumentTypes`	Show document type selection screen (set 1 for true or set 0 for false).
`autoDocDetectionAndCropIsOn`	Enable automatic document detection and cropping (set 1 for true or set 0 for false).
`blurDetectionIsOn`	Enable blur detection before capturing (set 1 for true or set 0 for false).
`locationServicesIsOn`	Enable location tracking during capture (set 1 for true or set 0 for false).
`dataExtractionEngine`	Set to "api" to use the Veryfi Data Extraction API. Set to "none" if you want to control when and where the Veryfi API is called for data extraction.
`externalId`	Add a unique reference identifier for a scan, allowing you to easily map the document back to your system
`campaignId`	Link the document to an existing campaign on your system
`userId`	A unique identifier from your database. This value is used to generate the device_user_uuid for multi-account detection.
`tags`	Optional list of custom tags for Veryfi to use in tagging submitted documents
`uploadWithoutProcessingIsOn`	If dataExtractionEngine is `none` it will upload the package to our servers but will defer the processing to the webhook, default: true
`webhook`	A url that will be used instead of the one owned by Veryfi to send the package data
`cropLayoutIsOn`	Enable or disable the crop layout feature (set 1 for true or set 0 for false).
`cropLayoutBorderColor`	Hex color value for crop layout border (e.g., "#FFFFFF00" for transparent).
`cropLayoutStroke`	Width of crop layout border in pixels.
`cropLayoutCornerRadius`	Corner radius of crop layout in pixels.
`cropLayoutWidth`	Width of crop layout as a percentage of screen width.
`cropLayoutHeight`	Height of crop layout as a percentage of screen height.
`cropLayoutTipMessage`	Custom message to display in the crop layout.
`username`	Veryfi username (URL-encoded).
`clientId`	Veryfi Client ID (URL-encoded).
`key`	Encrypted Veryfi API key.

note

Crop Layout Parameters: All crop layout parameters (cropLayoutIsOn, cropLayoutBorderColor, cropLayoutStroke, cropLayoutCornerRadius, cropLayoutWidth, cropLayoutHeight, cropLayoutTipMessage) are optional. For detailed information about these settings, see the Crop Layout Customization section in the mobile settings documentation. And only work if autoDocDetectionAndCropIsOn is disabled

🔐 Encrypting the apiKey Parameter

To securely send your Veryfi API key in the Lens Instant App or App Clip URL, you must encrypt it using our public key.

Note: Only the Instant App or App Clip (holding the corresponding private key) can decrypt it.

1. Download the Public Key

Download the Lens Instant App / App Clip public key here:

📄 veryfi_lens_public.pem

2. Encrypt the API Key in Your Backend

Use RSA-OAEP with SHA-256 to encrypt the API key. This example shows how to do it in Node.js:

// crypto/encryptKey.js
import crypto from "crypto";
import fs from "fs";

// Convert buffer to URL-safe Base64 (base64url)
const b64u = (buf) =>
  Buffer.from(buf).toString("base64")
    .replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "~");

export function encryptApiKeyForApp(publicKeyPem, apiKeyPlaintext) {
  const ciphertext = crypto.publicEncrypt(
    {
      key: publicKeyPem,
      padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
      oaepHash: "sha256",
    },
    Buffer.from(apiKeyPlaintext, "utf8")
  );
  return b64u(ciphertext); // URL-safe string
}

// Example usage:
const publicKeyPem = fs.readFileSync("./veryfi_lens_public.pem", "utf8");
const encryptedKey = encryptApiKeyForApp(publicKeyPem, process.env.VERYFI_API_KEY);

console.log("Encrypted key:", encryptedKey);

4. How it Looks in WhatsApp

Below is an example of how this Call-to-Action (CTA) button with the encrypted key parameter will appear inside a WhatsApp conversation:

📸 Screenshot Example

iOS
Android

5. Payload sent to the webhook

5.1 If `uploadWithoutProcessingIsOn = true` and `dataExtractionEngine = none`, then the payload will contain the data to find the document location so that you can process it via API:

{
  "data": {
    "bucket": "veryfi-lens-uploads",
    "document_type": "receipt",
    "external_id": "your-external-id",
    "img_original_path": "path/to/original/image.jpg",
    "img_stitched_pdf_path": "path/to/stitched.pdf",
    "img_thumbnail_path": "path/to/thumbnail.jpg",
    "package_path": "path/to/package.zip",
    "upload_time_s": 3,
    "img_paths": ["path/to/image1.jpg", "path/to/image2.jpg"]
  },
  "device_id": "ed259234-5610-33b7-ab5b-4b2bc3f2cac2",
  "document_type": "receipt",
  "package_id": "package-456",
  "campaignId": "18",
  "userId": "184",
  "sessionId": "c06b3c81c5b14177",
  "status": "success"
}

5.2 If `dataExtractionEngine = api`, then the full processed response will be sent:

{
    "data": {"total":6.6,"invoice_number":"04814","subtotal":6.36,"currency_code":"USD","total_pages":1,"date":"2023-03-21 19:31:00","payment":{"card_number":"0115","display_name":"Visa ***0115","type":"visa"},"reference_number":"VDCBJ-81080","accounting_entry_type":"debit","id":339981080,"vendors":["Walmart","Walmart"],"vendor":{"raw_name":"Walmart","country_code":"US","lng":-122.109695,"category":"Department Store","name":"Walmart","map_url":"https:\/\/www.google.com\/maps\/search\/?api=1&query=Walmart+600+SHOWERS+DR+MOUNTAIN+VIEW+CA+94040+TR#+TE#+OP#","raw_address":"600 SHOWERS DR\nMOUNTAIN VIEW CA 94040","type":"Department Store","phone_number":"650-917-0796","web":"survey.walmart.com","external_id":null,"external_ids":[],"lat":37.400925,"logo":"https:\/\/cdn.veryfi.com\/logos\/us\/218078496.jpeg","logo_name":"walmart","address":"600 SHOWERS DR\nMOUNTAIN VIEW CA 94040\nTR#\nTE#\nOP#"},"pdf_url":"https:\/\/scdn.veryfi.com\/receipts\/a1c6bdc6fd6aa87b\/c54e174e-051c-4fbe-8d23-9ce22a1f6d18\/50f12835-8c90-4e6f-9e1d-cb2beb115c14.pdf?Expires=1754964211&Signature=SxCEMd~FWMCSMf3I0cwvptq8PzewiVwKC7tqE6ZFsA4Y5KsfUcMED4gW~o8Acy9R6Wpz7gJ4OBm9atpTklpVO8GKpv~KDWHEBe1JvKJqaIJlz-v2lBc8-IV7luQ1BpmKf02TqLiRJh6jPQBPQKntR-CimpLe-KWx6Q5zfaoijSwdQPU-ptqVY909bL-gVsgW0aIjnm4dRgX5JFKTmkh1uNp~PCsVP9E9oojuMlIHUtQUV~bndtLkg1yetknEyWdt8UWa8TlRn4VEhyx22dAP5Q96anBLWqVS8AgZdEKdsr0MBn1TnPe2YQ3yKjI1iSxGlXsquNxs~IwLmg6ySgiAuQ__&Key-Pair-Id=APKAJCILBXEJFZF4DCHQ","img_url":"https:\/\/scdn.veryfi.com\/receipts\/a1c6bdc6fd6aa87b\/c54e174e-051c-4fbe-8d23-9ce22a1f6d18\/74025bbc-333e-40b9-be4b-f1e22a89c031.jpg?Expires=1754964211&Signature=PPzCOpX8NQOxdrKzXPc4XZ0YqlpDDt029BQAWQzkoaPidLkyLpzZycWSIJ8XgrNahfXNgDNZwrM5wlRLPZ0c7nv5aUV4BX9y-NLBeBGy-gOc6pvXnGmnfBoQn8DCooXuiVlKZdTj9W-wlgnWW5hJYCO4qxZpRfZoOtNRubAJyjOvRPHHsUtj0ThqmyZnOwLJEwQ7SCSGa8NJcFtWma~iNZajUm67bdip1vvNpx~rRBktclQFOzFhCc11l2FuN9aEDe6jd6Zx-BPRqdmr8uqP60sOYMZSZNPY3Tolot7AfB5eQ6YwvDyFZxnJ5ObgP94Msu4AJxIvqkzf24OP7JkrwQ__&Key-Pair-Id=APKAJCILBXEJFZF4DCHQ","model":"2.71.0","document_type":"receipt","tax":0.24,"vending_person_number":"009009","ocr_text":"Give us feedback @ survey.walmart.com\nThank you! ID #:7SHKC5SPH95\nWalmart >\n650-917-0796 Mgr:RENARDO\n600 SHOWERS DR\nMOUNTAIN VIEW CA 94040\nST# 02280 OP# 009009 TE# 09 TR# 04814\nLAYS\t002840020129 F\t3.68 N\nPEPSI\t001200003066 F\t2.48 X\nCRV FEE\t068113176540 F\t0.10 X\nCKOUT BAGTAX 000000001101K\t0.10 0\n\tSUBTOTAL\t6.36\nTAX 1 9.125 %\t0.24\n\tTOTAL\t6.60\nVISA TEND\t6.60\nVISA CREDIT **** **** **** 0115 I O\nAPPROVAL # 905081\nREF # 1042000314\nTRANS ID - 303081090537310\nVALIDATION - 255L\nPAYMENT SERVICE - E\nAID A0000000031010\nAAC 350129A87930283E\nTERMINAL # SC010046\n*NO SIGNATURE REQUIRED\n03\/21\/23\t19:31:00\nCHANGE DUE\t0.00\n# ITEMS SOLD 4\nTC# 5223 1066 2522 3267 4171\n\nWalmart+\nBecome a member 1\nScan for free 30-day trial\nLow Prices You Can Trust. Every Day.\n03\/21\/23 19:31:00\n***CUSTOMER COPY***","default_category":"Job Supplies","is_document":true,"is_blurry":[],"exch_rate":1,"is_duplicate":true,"category":"Supplies","meta":{"owner":"usename.001","pages":[{"language":["en"],"screenshot":{"score":0.92,"type":null},"height":3821,"is_blurry":{"score":0.9713826952327509,"value":false},"width":1838}],"processed_pages":1,"device_id":"093B9C56-D1FA-4965-B005-EEA03F379900","device_user_uuid":null,"source":"lens.receipt","language":["en"],"source_documents":[{"width":1838,"height":3821,"size_kb":2184}],"ocr_score":0.971,"total_pages":1},"document_reference_number":"5223 1066 2522 3267 4171","created_date":"2025-08-12 01:48:25","line_items":[{"id":1557156984,"category":"Supplies","text":"LAYS\t002840020129 F\t3.68 N","description":"LAYS","type":"food","full_description":"LAYS","sku":"002840020129","quantity":1,"order":0,"total":3.68,"tags":[]}],"tags":[],"ship_to":{"address":null,"name":null,"parsed_address":null},"total_weight":null,"barcodes":[{"type":"QRCODE","data":"http:\/\/walmart.com\/plusgiftcard"},{"type":"CODE39","data":"GCTTIOQI$+8FN 2S"}],"total_quantity":4,"duplicate_of":258263850,"guest_count":null,"is_transaction":false,"tax_lines":[{"base":null,"rate":9.125,"order":0,"code":"1","total_inclusive":null,"total":0.24,"name":null}],"vending_person":"RENARDO","img_thumbnail_url":"https:\/\/scdn.veryfi.com\/receipts\/a1c6bdc6fd6aa87b\/c54e174e-051c-4fbe-8d23-9ce22a1f6d18\/thumbnail.jpg?Expires=1754964211&Signature=Ah~Ey~w8QG7eyr1zfrGcTd5Mu6bQDdm~W45g9fSYzRHKQLFy5yVJjcXH589zLaF7dTP3c5qAk4y28ZvkqpUG4ztylk2W5XTiik~82kWOm1z71nBs2qa5q~e2-aHV4bb9iU9xL8ZlmIuiBHwvZ7SUSteHmBShmlIY758CTjowiQ9t6lx1bmrcNxl5HwRq6bA7iQkxBwGWAYzJ~r3AwdNktfr57iZpYiBt5p69vMIYRArTrWAgH7yMlubMOAuyuwSZ98E7r5v5K9KmNy1RXX6ZiUVRMsvPcEHyPQAKIVF2R4g9Dzt6Q5O4VCJ-jt~Q-ZxF4j69gBUvhDALXtFPxt2rVg__&Key-Pair-Id=APKAJCILBXEJFZF4DCHQ","is_money_in":false,"img_blur":false,"is_approved":false,"status":"processed","img_file_name":"339981080.jpg","updated_date":"2025-08-12 01:48:31","store_number":"02280"},
    "document_type": "receipt",
    "package_id": "fScdb8nKkXprWL7MCvUn",
    "status": "done",
    "device_id": "093B9C56-D1FA-4965-B005-EEA03F379900",
    "campaignId": "18",
    "userId": "184",
    "sessionId": "c06b3c81c5b14177",
    "is_emulator": true
}

Important Notes

note

Do not send the raw API key in the URL.
The encryption must be done on your backend, never in frontend code.
The encrypted value is already URL-safe (base64url); avoid double-encoding.

Steps:​

Parameters​

🔐 Encrypting the apiKey Parameter​

1. Download the Public Key​

2. Encrypt the API Key in Your Backend​

4. How it Looks in WhatsApp​

📸 Screenshot Example​

5. Payload sent to the webhook​

5.1 If uploadWithoutProcessingIsOn = true and dataExtractionEngine = none, then the payload will contain the data to find the document location so that you can process it via API:​

5.2 If dataExtractionEngine = api, then the full processed response will be sent:​

Important Notes​