Skip to main content

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:​

  1. Create a Call-to-Action (CTA) component in your WhatsApp bot.

  2. Refer to the WhatsApp documentation:

  3. 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}

  4. 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​

ParameterDescription
documentTypeType of document to capture (e.g., "receipt", "long_receipt" or "other").
showDocumentTypesShow document type selection screen (set 1 for true or set 0 for false).
autoDocDetectionAndCropIsOnEnable automatic document detection and cropping (set 1 for true or set 0 for false).
blurDetectionIsOnEnable blur detection before capturing (set 1 for true or set 0 for false).
locationServicesIsOnEnable location tracking during capture (set 1 for true or set 0 for false).
dataExtractionEngineSet 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.
externalIdAdd a unique reference identifier for a scan, allowing you to easily map the document back to your system
campaignIdLink the document to an existing campaign on your system
userIdA unique identifier from your database. This value is used to generate the device_user_uuid for multi-account detection.
tagsOptional list of custom tags for Veryfi to use in tagging submitted documents
uploadWithoutProcessingIsOnIf dataExtractionEngine is none it will upload the package to our servers but will defer the processing to the webhook, default: true
webhookA url that will be used instead of the one owned by Veryfi to send the package data
cropLayoutIsOnEnable or disable the crop layout feature (set 1 for true or set 0 for false).
cropLayoutBorderColorHex color value for crop layout border (e.g., "#FFFFFF00" for transparent).
cropLayoutStrokeWidth of crop layout border in pixels.
cropLayoutCornerRadiusCorner radius of crop layout in pixels.
cropLayoutWidthWidth of crop layout as a percentage of screen width.
cropLayoutHeightHeight of crop layout as a percentage of screen height.
cropLayoutTipMessageCustom message to display in the crop layout.
usernameVeryfi username (URL-encoded).
clientIdVeryfi Client ID (URL-encoded).
keyEncrypted 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​

WhatsApp Lens iOS 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:​

{
  "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"
}
Here’s an Example of How to Call the Veryfi Data Extraction API​
const response = await axios({
            method: "POST",
            url: "https://api.veryfi.com/api/v8/partner/documents/",
            headers: {
                "Content-Type": "application/json",
                "Accept": "application/json",
                "CLIENT-ID": credentials.clientId,
                "AUTHORIZATION": `apikey ${credentials.username}:${credentials.apiKey}`,
            },
            data: {
                bucket: bucket,
                package_path: packagePath,
                document_type: documentType,
                device_data: {meta: {upload_time_s: uploadingTime}},
                external_id: externalId,
            }
        });

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.