Developer integration

You can embed DocuGuest directly into your own web application with a single <script> tag. The scanner runs inside an iframe on your page and reports back to your code via a JavaScript callback every time a document is scanned.

This page covers the embed script. If you need a server-to-server integration or a tailored connector for your platform, contact us.

Quick start

Add the script to any page where you want the scanner to appear, replacing ACTIVATION_CODE with the integration code from your DocuGuest dashboard:

<script src="https://docuguest.com/docuguest.js" data-code="ACTIVATION_CODE"></script>
<script>
document.addEventListener('DOMContentLoaded', function () {
    DocuGuest.start(function (type, result) {
        console.log('DocuGuest event:', type, result);
    });
});
</script>

That's it. When DocuGuest.start() is called, the scanner loads in an iframe placed where the <script> tag was. Every event from the scanner (camera ready, scan completed, errors, etc.) is delivered to your callback.

How it works

When the page loads, the embed script:

Creates an <iframe> next to the <script> tag (full width, 80vh tall, with camera permission).
Waits for you to call DocuGuest.start().
Loads the scanner inside the iframe using your activation code.
Forwards every message from the scanner to your callback.

You can call start and stop as many times as you need, for example to open and close the scanner in response to user actions.

API reference

The script exposes a global DocuGuest object with two methods.

`DocuGuest.start(callback, data)`

Opens the scanner inside the embedded iframe.

Parameter	Type	Description
`callback`	`Function`	Required. Called with `(type, payload)` for every event from the scanner.
`data`	`Object`	Optional. Context object forwarded to the scanner (booking ID, guest, etc.).

DocuGuest.start(function (type, result) {
    if (type === 'scan') {
        console.log('Document scanned:', result);
    }
}, {
    booking_id: '123',
    guest_name: 'John Doe',
});

The data object is sent to the scanner as soon as it signals that it's ready, and is attached to every scan stored on the DocuGuest backend so you can correlate scans with bookings or customers in your own system.

`DocuGuest.stop()`

Stops the scanner and clears the iframe (src is reset to about:blank). Use it when the user closes a modal or navigates away.

DocuGuest.stop();

Callback events

Your callback receives two arguments: an event type (string) and a payload (object). Three event types are emitted:

`scan_result`

Fired every time a document is processed, whether the read succeeded or not. This is the primary event; handle it to receive document data.

DocuGuest.start(function (type, payload) {
    if (type === 'scan_result') {
        if (payload.success) {
            console.log('Document data:', payload.data);
        } else {
            console.warn('Scan failed validation');
        }
    }
});

Payload:

Field	Type	Description
`success`	`boolean`	`true` if the document was read and parsed correctly, `false` if the OCR/MRZ check failed.
`data`	`object`	Extracted document fields (name, document number, date of birth, nationality, expiry, etc.).
`ocrText`	`string`	Raw OCR text extracted from the image. Useful for debugging.
`sent`	`boolean`	Whether the data has already been sent to your configured integration. Always `false` here.

`scan_sent`

Fired after a successful scan has been dispatched to your configured server-side integration. Only emitted when an integration is configured for the activation code and the send succeeded. Use it to confirm end-to-end delivery, not just a successful read.

DocuGuest.start(function (type, payload) {
    if (type === 'scan_sent') {
        console.log('Scan delivered to backend');
    }
});

Payload: identical shape to scan_result, with sent: true.

`error`

Fired when a scan attempt fails before producing a result (network error, image upload failure, server error, etc.). Distinct from a scan_result with success: false, which means the scan ran but the document could not be parsed.

DocuGuest.start(function (type, payload) {
    if (type === 'error') {
        console.error('Scan error:', payload.message);
    }
});

Payload:

Field	Type	Description
`message`	`string`	Human-readable description of the error.

Quick reference

Event	When	Payload
`scan_result`	A scan completes (success or parse failure)	`{success, data, ocrText, sent}`
`scan_sent`	A successful scan was forwarded to your integration	`{success, data, ocrText, sent}`
`error`	A scan attempt failed before producing a result	`{message}`

During development, log every event to inspect exact payload shapes:
DocuGuest.start(function (type, payload) {
  console.log('[DocuGuest]', type, payload);
});

Embedding patterns

Inline (default)

The iframe is inserted in-place where the <script> tag lives. This is the simplest setup: drop the script into a container and the scanner appears there.

<div id="scanner-container">
    <script src="https://docuguest.com/docuguest.js" data-code="ACTIVATION_CODE"></script>
</div>
<script>
    DocuGuest.start(function (type, result) { /* ... */ });
</script>

In a modal

If you'd rather keep the page clean and only show the scanner on demand, place the script inside a hidden modal and call start when the modal opens, stop when it closes.

<button onclick="openScanner()">Scan document</button>

<div id="scanner-modal" style="display:none">
    <button onclick="closeScanner()">Close</button>
    <script src="https://docuguest.com/docuguest.js" data-code="ACTIVATION_CODE"></script>
</div>

<script>
    function openScanner() {
        document.getElementById('scanner-modal').style.display = 'block';
        DocuGuest.start(function (type, result) {
            if (type === 'scan') closeScanner();
        });
    }
    function closeScanner() {
        DocuGuest.stop();
        document.getElementById('scanner-modal').style.display = 'none';
    }
</script>

Camera permissions

The iframe is created with allow="camera", which lets the scanner request access to the user's webcam. The browser will show its permission prompt the first time. For this to work:

The page hosting the embed must be served over HTTPS (browsers block camera access on HTTP).
The user must click Allow in the permission prompt.

If you embed on localhost for development, browsers treat it as secure and the camera will work without HTTPS.

Activation code

The data-code attribute identifies your integration. Every scan made through your embed is associated with this code, which lets you:

See all scans from your integration in the DocuGuest dashboard.
Track usage and billing.
Receive scans server-side via webhook (if configured).

Don't share your activation code publicly outside your own site. If it leaks, regenerate it from the dashboard.

Server-to-server and custom integrations

The embed covers most use cases. If you need something different (a server-side API, a connector for a specific PMS or CRM, white-label deployment, etc.), we can build it for you.