Skip to content

CRM integrations

Published screeners support CRM integrations through HTTP endpoints and a versioned browser message protocol. A CRM can embed a screener in an iframe or open it in a separate window, prefill known answers, and receive evaluated results to save to the client’s record. BDT does not store CRM credentials or write CRM records; the host application owns its input mapping and result persistence.

A screener only exchanges messages with CRMs its builder has allowed. In the screener editor, open Publish, enter each CRM origin under Allowed CRM origins (one per line, such as https://example.lightning.force.com), choose Save CRM origins, then publish. An origin is the scheme, host, and port the CRM page runs on, with no path. Other origins get the ordinary standalone screener: no prefill, no results, and a notice that the screener isn’t set up for them. This keeps a page on another site from collecting a person’s answers by opening the screener itself.

These existing public endpoints operate on a published screener ID, not the editable screener’s ID. No builder login is required.

Method Path Purpose
GET /api/published/screener/{publishedScreenerId} Published screener metadata including formSchema
POST /api/published/{publishedScreenerId}/evaluate Evaluate a JSON object of form answers
Terminal window
curl --fail-with-body https://YOUR-API-HOST/api/published/PUBLISHED-ID/evaluate \
-H 'Content-Type: application/json' \
-d '{"people":{"client":{"dateOfBirth":"1950-01-01"}},"simpleChecks":{"livesInPhiladelphiaPa":true}}'

The response is keyed by benefit ID:

{
"benefit-id": {
"name": "Example benefit",
"result": "UNABLE_TO_DETERMINE",
"check_results": {
"check-id0": {
"name": "ExampleCheck",
"aliasName": null,
"explanation": null,
"result": "UNABLE_TO_DETERMINE",
"module": "ExampleModule",
"version": "1.0.0",
"parameters": {},
"effectiveParameters": {},
"defaultedParameters": [],
"inputPaths": ["people.client.dateOfBirth"]
}
}
}
}

explanation is the author’s optional plain-language text for that check: plain text of up to 2,000 characters that can span multiple lines, or null when there is none.

Results are TRUE, FALSE, or UNABLE_TO_DETERMINE. They represent eligibility checks, not a submitted application or an approval. An unknown screener returns 404; evaluation failures return 500. The evaluation endpoint also returns 404 when the screener has no benefits. The API host can differ from the frontend host; use the API URL configured for your deployment.

Use the form’s configured keys to map CRM fields. A dotted form key such as people.client.dateOfBirth needs a nested object, not a literal dotted JSON key. Dates use YYYY-MM-DD, booleans use JSON booleans, and numbers use JSON numbers. Leave unknown answers omitted or null. Do not turn missing answers into false or zero. The API transforms the form’s keyed people object into library input arrays internally. For checklist inputs, null is unknown and [] is an explicit empty selection; the browser form normalizes its checklist answers before evaluation.

The reusable ES module is served by the BDT frontend at /integrations/host.js. Copy it into your own application when your CRM requires locally bundled modules. Create the adapter before navigating the iframe or opening the window so it can receive the screener’s ready message. The adapter adds an opaque integrationLaunch marker to reload an existing iframe for each new session; this marker contains no client information.

import { createCrmIntegration } from "https://YOUR-BDT-HOST/integrations/host.js";
const frame = document.querySelector("iframe");
const clientId = currentClient.id; // Pin this record for the lifetime of the session.
const connection = createCrmIntegration({
screenerUrl: "https://YOUR-BDT-HOST/screener/PUBLISHED-ID",
getTargetWindow: () => frame.contentWindow,
initialData: {
people: { client: { dateOfBirth: currentClient.birthDate ?? null } },
},
onResult: (message) => {
// Display/store this snapshot locally until the user chooses to save.
showScreeningResults(clientId, {
requestId: message.requestId,
screenerId: message.screenerId,
evaluatedAt: message.evaluatedAt,
results: message.results,
nextSteps: message.nextSteps,
});
},
onError: () => showEvaluationError(),
});
frame.src = connection.url;
// Call connection.dispose() when the host view is closed or its client changes.

dispose() also sends disconnect to an open screener. The screener then stops sending results and tells the user it’s no longer connected, so staff don’t keep working in a window whose answers the CRM ignores.

The host helper functions in this snippet (showScreeningResults and showEvaluationError) belong to your CRM UI. onError receives a code:

Code Meaning
INITIALIZATION_FAILED The browser blocked sending prefill to the screener window
CONNECTION_TIMEOUT No screener connected within connectTimeoutMs (default 30 seconds), e.g. a wrong URL or a blocked frame/window
ORIGIN_MISMATCH The screener answered from another origin, given as origin, often after a redirect; no prefill was sent
SCREENER_UNAVAILABLE The published screener couldn’t be loaded, e.g. it was unpublished or the ID is wrong
ORIGIN_NOT_ALLOWED The published screener doesn’t list this CRM’s origin in its allowed CRM origins
EVALUATION_FAILED An evaluation failed; a later successful result replaces it
Downloading and bundling the adapter
also avoids a dependency on cross-origin module fetching permissions.

For a separate tab/window, keep a reference to the opened window:

let popup;
const connection = createCrmIntegration({
screenerUrl: "https://YOUR-BDT-HOST/screener/PUBLISHED-ID",
getTargetWindow: () => popup,
initialData: {},
onResult: (message) => showScreeningResults(clientId, message),
});
popup = window.open(connection.url, "_blank"); // Run from a user click.
if (!popup) connection.dispose(); // Show a popup-blocked message in your CRM.

The separate-window workflow needs window.opener: don’t use noopener, noreferrer, or a link opened manually in another tab. Deployment headers such as Cross-Origin-Opener-Policy can sever this relationship. Use the iframe workflow if your environment requires opener isolation. An iframe needs a hosting policy that permits the CRM origin in CSP frame-ancestors, and a CRM policy permitting the BDT origin in frame-src. CORS alone does not permit framing.

For custom integrations, navigate to:

https://YOUR-BDT-HOST/screener/PUBLISHED-ID?integrationOrigin=https%3A%2F%2FYOUR-CRM-HOST

integrationOrigin must be an exact HTTP(S) origin, including the port when needed, with no trailing slash or path. Use HTTPS in production. It opts the page into communication with its direct parent (iframe) or opener (window), and must be one of the screener’s allowed CRM origins. Both sides must check event.origin and event.source. Send to an exact targetOrigin; never use "*". No applicant data or CRM credentials belong in the URL. The configured origin is a messaging destination, not CRM authentication; your host/backend still authorizes reads and writes to client records.

Every message is a plain object with these envelope fields:

Field Value
channel "bdt.crm"
version 1
type One of the types below
screenerId Published screener ID
sessionId Random ID generated by the screener for this page load
requestId Host’s nonempty opaque correlation string (maximum 200 characters), except on ready
Direction Type Additional fields / behavior
Screener → host ready Repeated until initialized; send prefill for this sessionId
Host → screener initialize inputData: a JSON form-data object; use {} for no prefill
Screener → host initialized Prefill accepted; form loads and evaluates
Screener → host result inputData, results, evaluatedAt (ISO 8601 timestamp), optional nextSteps
Screener → host error code: see below
Host → screener disconnect Host closed the connection; screener stops and says so

Version 1 includes an optional, additive nextSteps field. Existing hosts may ignore it; no protocol version change or new handshake is required. The host adapter forwards the field unchanged in both object and JSON message modes. If nextSteps isn’t an object, the adapter drops that field and still delivers the result.

{
"nextSteps": {
"benefit-id": {
"status": "eligible",
"applyUrl": "https://example.org/apply",
"help": { "url": "https://example.org/help", "phone": "215-555-0100" },
"body": { "format": "markdown", "text": "Bring **proof of residence**." },
"unmetRequirements": [],
"note": null
}
}
}

Only decided benefits are included, keyed by their evaluation benefit IDs. Eligible entries contain application/help contacts and body; ineligible entries have status: "ineligible", unmetRequirements (each failed check’s explanation when it has one, otherwise its display name), and note with the same { format: "markdown", text } structure. Requirements are text to display, not identifiers: an explanation can be long and span multiple lines, and adding one changes the value, so don’t match on them. Use check_results in results to identify a check. Unused contacts and text fields are null; unused requirements are an empty array. Missing instructions remain empty rather than being invented.

Content comes from the first visible Next steps component in schema order, including nested groups, just like printing. It uses the screener’s saved copy, not current benefit defaults or content in an evaluation response. Hidden components are skipped. If none is visible, nextSteps is omitted. If the component uses whenComplete, nextSteps is {} until every benefit is decided. As with results, each new message replaces the previous snapshot: an omitted field or empty object must clear any previous instructions in the host.

The payload contains structured data, never rendered HTML. Treat Markdown as untrusted content: display it as plain text (as the examples do), or use a sanitizing Markdown renderer. Validate links before making them clickable. The screener emits only HTTP(S) application/help URLs, but hosts must still validate any saved snapshot they read; host.js exports safeHttpUrl for this. Save nextSteps alongside results only when the user chooses to save; the protocol does not change persistence authorization.

The screener repeats ready about every 500 ms until it’s initialized, so a host that starts listening late still connects. Ignore repeated ready messages for a session you’ve already initialized. If nothing initializes the screener within 10 seconds, it stops sending messages. It then shows the form unconnected, with a notice that results won’t be sent back.

The screener waits for initialization before displaying the connected form. It accepts one initialization per page load and rejects malformed data, unsafe prototype keys, mismatched origins/windows, and mismatched sessions. To start another client’s screening, create a fresh connection and navigate the frame or window again. Without a valid origin and parent/opener, it runs as an ordinary standalone screener and sends no integration messages.

A checkbox or text field can’t display an unknown answer, so it appears unchecked or empty. The connected screener still evaluates and returns a null or omitted prefill answer as null until the user changes that field.

The screener sends ready once the published screener has loaded. If it can’t be loaded, the screener replies to initialize with error and code: "SCREENER_UNAVAILABLE" instead of initialized. If the host’s origin isn’t allowed, it replies with code: "ORIGIN_NOT_ALLOWED" and sends nothing further. Otherwise error has code: "EVALUATION_FAILED".

result is sent after initial evaluation and after evaluated edits (normally debounced by one second). Multiple results per session are expected. Older in-flight responses are discarded once a newer evaluation has started. A result is a snapshot, not a completion event. Offer a host-side Save results action or implement your application’s explicit autosave policy. Do not treat the first result as final. A successful new evaluation clears the host’s error state; after an error, don’t save the old snapshot as the latest result.

Pin the CRM record in the host’s session rather than trusting a record ID in a result payload. On save, authorize that record through your CRM backend or its native authenticated API, and validate whichever result fields you persist. Use the opaque request ID to correlate a session, not as an authentication token. For audit history, save separate screening records with timestamps and the published screener ID. Browser messages are client-provided data; integrations requiring trusted decisions should re-evaluate the answers server-side.

  • Browser demo: run node examples/crm/browser/serve.mjs from the repository root, then open http://127.0.0.1:4174/demo.html. Enter a published BDT screener URL and test both iframe and separate-window modes. Individual client fields use a flat CRM schema; an explicit mapper converts them to nested screener data, including monthly-to-annual income conversion. Inspect field mapping shows the source record and generated prefill side by side. It prefills synthetic data and lets you save results to a browser-local demo record. Its record panel shows benefit statuses and timestamps, and restores saved results after a reload. Client fields and saved results share one record section; the embedded screener uses a full-width area with questions and live results side by side. The demo lives under examples/crm/browser/ and is not included in frontend deployments; its local server serves the same canonical adapter used by the frontend.
  • Salesforce: examples/crm/salesforce/ contains a community nonprofit client app with editable client profiles, screening intake, full Philadelphia example prefill, explicit result saving, and formatted saved-results cards. Intake includes income, housing, property taxes, age, family, and program enrollment; unanswered values remain unknown. Sales fields and actions are excluded from the custom client page. Follow its README to configure a development org, permissions, and your published screener. The adapter supports both iframe and separate-window screening. Verify your own screener’s mapping.

Salesforce supports cross-origin iframe messaging under Lightning Web Security. The example uses native getRecord and updateRecord for authenticated record access. Its adapter is copied into a local LWC module because Salesforce restricts third-party script loading.

Other CRMs can reuse the same adapter by providing their own input mapper and onResult/onError callbacks. Those callbacks are the extension points for CRM UI and storage; there is no provider registry or server-side CRM plugin runtime.

With the frontend dev server running and its example environment configured, run npx playwright test --project=crm-integrations from e2e/. These Chromium tests intercept the published APIs and verify prefill, edited results, explicit saving, failure recovery, and standalone behavior. The spec starts its own browser example server on a free port, so it doesn’t conflict with a demo server you already have running. They require no emulators or CRM account. Frontend unit tests also cover origin/source validation, correlation, one-time initialization, outdated responses, and listener cleanup.

Salesforce enables the host adapter’s serializeMessages: true option to send JSON envelopes across Lightning Web Security sandbox boundaries. The screener parses that initialization and returns JSON envelopes for the session. Object messages remain the default for other hosts; both formats use the same exact origin, source, session, and request checks.