Embedded SDK Integration Guide

The Snappt Embedded SDK allows applications to launch Snappt verification as a modal overlay within their applicant flow. No redirects, no popups, just a seamless iframe experience.

Prerequisites

Before integrating, you will need the following from your Snappt account team:

Your Client ID is bound to an API key that controls which companies and properties you can access. Snappt validates every SDK request against this configuration. If your key is scoped to a single property, only that property can be used.

Domain Allowlisting

Your Client ID is configured with a list of allowed domains. The SDK will only load on pages served from those domains. Snappt validates the request Origin and Referer headers against your allowlist.

Allowed domains support:

• Exact origins, for example https://apply.yourcompany.com
• Wildcard subdomains, for example *.yourcompany.com (matches https://apply.yourcompany.com, https://staging.yourcompany.com, and so on)

Contact your Snappt account team to configure your allowed domains.

1. Add the Script

Add the following <script> tag anywhere in your HTML page. This loads the Snappt SDK and makes the global Snappt object available. No other dependencies are required.

<script src="https://enterprise-api.snappt.com/embedded/v1.0.0.js?iframe=true&clientId=YOUR_CLIENT_ID"></script>

The script will not load if the clientId is missing, inactive, or if the page's origin is not in your allowed domains list. Use the Developer Tools > Network panel to inspect the response and get a detailed error message if the SDK fails to initialize.

2. Open the Verification Flow

Call Snappt.portal.show() to launch the applicant verification flow in a modal overlay. You must provide companyShortId and propertyShortId to identify the property.

var instance = Snappt.portal.show({
  companyShortId: 'YOUR_COMPANY_ID',
  propertyShortId: 'YOUR_PROPERTY_ID',
});

Pre-filling Applicant Data (Optional)

You can pass applicant information so they don't have to re-enter it. Providing an email address allows the user to skip the first step of the Snappt flow but still requires them to confirm a one-time code. If the applicant previously opened the portal, you can pass an applicantIdentifier to ensure their submissions are linked together - see Linking Subsequent Sessions below.

var instance = Snappt.portal.show({
  companyShortId: 'YOUR_COMPANY_ID',
  propertyShortId: 'YOUR_PROPERTY_ID',
  email: '[email protected]',
  firstName: 'Jane',
  lastName: 'Doe',
  phone: '5551234567',
  applicantIdentifier: // previous Snappt applicantDetailId, if available
});

Available Options

3. Register Event Handlers

The show() call returns an instance object. Use addEventListener('close', callback) to be notified when the modal closes. Your callback receives an event object with a type field indicating what happened, an applicantDetailId identifying the applicant for future Snappt.modal.opencalls, and additional type-specific metadata.

Event Types:

• application-complete: The applicant has successfully finished the verification flow and their application is processing.
  • event.payload.applicantId: the Snappt applicantId - can be used to check application status via the REST API and appears in webhooks.
• close: The applicant has closed the modal. If you have not received application-complete, the user exited the modal without completing the application flow.

instance.addEventListener('close', function (event) {
  const applicantIdentifier = e.applicantDetailId;
  
  // If your application allows users to re-open the modal or submit again,
  // save this value and pass it back in subsequent calls to `Snappt.portal.show`
  saveSnapptApplicantIdentifier(applicantIdentifier);

  if (event.type === 'application-complete') {
    // The applicant finished the flow! Their application is processing.
    // The Snappt applicantId attached to this event can be used to check
    // application status via our REST API and appears in webhooks.
    const applicantId = e.payload.applicantId;
    showConfirmation();
  }
  if (event.type === 'close') {
    // The applicant closed the modal. If you have not received application-complete,
    // the user has exited without finishing their application.
  }
});

Linking Subsequent Sessions (Recommended)

When the Snappt modal closes, the event you receive contains an applicantDetailId. This is a Snappt UUID representing the applicant, separate from their individual application submissions. If your app allows the user to re-open the Snappt modal or submit a second time, you should save this value (either to a cookie or to your database records) and pass it to subsequent calls to Snappt.portal.showin the applicantIdentifier field. This ensures that subsequent applications are linked together, and ensures your flow can benefit from future improvements like resuming partially complete sessionsand ensures your flow can benefit from future improvements like resuming partially complete sessions.

Attaching External IDs (Recommended)

If you have a stable identifier for the applicant or submission in your application, you can provide it as an externalIdwhen calling Snappt.portal.show. Snappt stores this identifier as an opaque value and includes it in outbound webhook payloads, making it easy to link Snappt applications back to your records in your system. You can also query our REST API (GET /applicants) by externalId.

You can also attach arbitrary structured context via externalMetadata, for example unit number, lead source, or internal flags.

Note: externalId is for attribution only - Snappt does not link or dedupe sessions by externalId, and there are no format constraints on the string value. Passing externalId makes debugging and handling webhooks easier.

var instance = Snappt.portal.show({
  companyShortId: 'YOUR_COMPANY_ID',
  propertyShortId: 'YOUR_PROPERTY_ID',
  email: '[email protected]',
  externalId: 'YOUR-INTERNAL-APP-ID-12345',
  externalMetadata: {
    unitNumber: '101A',
    leadSource: 'Website',
  },
});

4. Receive Results Server-Side (Webhooks)

The browser-side close event provides you with a Snappt applicantId if the user successfully completed the application flow. To receive results and link them back to your own records, configure a Snappt webhook.

Your webhook should verify the applicantDetailId or externalId match a record in your system, return a 200 status code, and then update your application state. If your webhook fails to respond in 30s or returns a non-200 status code, it will be retried hourly for 24 hours. (See Webhook Delivery and Retry Behavior)

Every webhook payload includes:

Pass externalId when you launch the modal, then key off it in your webhook handler.

Programmatic Control

You can control the modal directly through the instance:

instance.hide();  // Close the modal
instance.show();  // Re-open the modal

You can also remove event listeners:

function onClose(event) {
  console.log('Modal closed:', event.type);
}

instance.addEventListener('close', onClose);

// Later, if you no longer need the listener:
instance.removeEventListener('close', onClose);

Full Example

<head>
  <script src="https://enterprise-api.snappt.com/embedded/v1.0.0.js?iframe=true&clientId=YOUR_CLIENT_ID"></script>
</head>
<body>
  <button id="apply-btn">Start Application</button>
  <script>
    // In a full implementation, save this to your applicant modal or to a cookie
    let applicantIdentifier = undefined;

    document.getElementById('apply-btn').addEventListener('click', function () {
      var instance = Snappt.portal.show({
        companyShortId: 'YOUR_COMPANY_ID',
        propertyShortId: 'YOUR_PROPERTY_ID',
        email: '[email protected]',
        firstName: 'Jane',
        lastName: 'Doe',
        phone: '5551234567',
        externalId: 'YOUR-INTERNAL-APP-ID-12345',
        externalMetadata: { unitNumber: '101A', leadSource: 'Website' },
        applicantIdentifier: applicantIdentifier,
      });

      instance.addEventListener("close", (e) => {
        applicantIdentifier = e.applicantDetailId;

        if (e.type === "close") {
          // User exited the modal. If you have not received `application-complete`, the user
          // exited without completing their application.
          console.log("close")
        }
        if (e.type === "application-complete") {
          // User finished the application and their Snappt application is processing.
          // You can query for it using the externalId you provided or using the applicantId
          // returned on this event:
          const applicantId = e.payload.applicantId;
          console.log("applied!", {applicantId})
        }
      });
    });
  </script>
</body>

Error Handling

If the SDK cannot generate an applicant link (for example, invalid property, disabled property, or access denied), an error message will be displayed inside the modal. Common errors:

Troubleshooting