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.
Allow your CRM’s origin
Section titled “Allow your CRM’s origin”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.
HTTP endpoints
Section titled “HTTP endpoints”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 |
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.
Browser host adapter
Section titled “Browser host adapter”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.
Message protocol (version 1)
Section titled “Message protocol (version 1)”For custom integrations, navigate to:
https://YOUR-BDT-HOST/screener/PUBLISHED-ID?integrationOrigin=https%3A%2F%2FYOUR-CRM-HOSTintegrationOrigin 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 |
Next steps in result messages
Section titled “Next steps in result messages”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.
Examples and adapter extension points
Section titled “Examples and adapter extension points”- Browser demo: run
node examples/crm/browser/serve.mjsfrom the repository root, then openhttp://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 underexamples/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.
Local verification
Section titled “Local verification”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.