Quickstart
Prepare a configured journey, launch its graphical UI and receive the outcome on your backend.
Before you start
Talk to IDCanopy about the journey you want to build. We will provide your configured workflow, personalised handshake request and integration instructions, including the enabled steps, authentication and result delivery. Contact office@idcanopy.com to get started.
Agree which steps the process needs and how the result maps back to your application. You will need a backend, a browser page and an HTTPS webhook endpoint.
Use the handshake request and callback-verification instructions supplied for your configured integration. The example below illustrates the application-side launch pattern, not a universal SDK method or journey-creation schema.
1. Create the configured journey on your backend
Use the shared API environment and bearer token with the journey-creation request from your SDK instructions. Keep credentials and the full backend response on your server. The response supplies a uiHandle: the launch URL for the graphical journey.
Expose only the launch information your frontend needs through your own application backend. Do not build a hosted UI URL yourself or reuse the expired handle from another journey.
2. Launch the user interface
The following example uses a route in your application, POST /api/journeys, that creates a journey server-side and returns { "uiHandle": "..." }. This is an illustrative application route, not an IDCanopy endpoint or an SDK method.
<button id="start-journey">Start onboarding</button>
<p id="journey-message" role="status"></p>
<script type="module">
const button = document.querySelector("#start-journey");
const message = document.querySelector("#journey-message");
button.addEventListener("click", async () => {
button.disabled = true;
message.textContent = "Preparing your journey…";
try {
const response = await fetch("/api/journeys", { method: "POST" });
if (!response.ok) throw new Error("Journey creation failed");
const { uiHandle } = await response.json();
if (!uiHandle) throw new Error("Missing journey URL");
window.location.assign(uiHandle);
} catch {
message.textContent = "Could not start the journey. Please try again.";
button.disabled = false;
}
});
</script>For embedding instead of full-page navigation, assign the returned URL to your journey iframe. See Hosted UI for the pattern and its current limitations.
3. Let the user complete the journey
The UI guides the user through the configured steps. Do not treat an iframe load, navigation or browser analytics event as proof that identification or the whole journey succeeded.
4. Receive and verify the outcome
Receive the outcome on your backend webhook. Verify the delivery using the instructions supplied for your integration, correlate it with your application record and process retries without repeating business actions. Continue your application only after interpreting the verified result, including unsuccessful outcomes.
The webhook guide lists the currently documented signature and payload fields, with a pending-verification notice. No client-side completion event or public journey-status polling endpoint is documented here.
Check your integration
- Journey creation failures are shown without exposing credentials or sensitive backend data.
- The returned launch URL opens the expected configured process.
- Successful and unsuccessful results are correlated with the correct application record.
- Invalid callbacks are rejected and repeated valid deliveries do not repeat downstream actions.
QES can become part of a configured journey as that capability is integrated. The current QES test contract is separate and should not be substituted for the SDK journey-creation request.
Continue with the SDK reference for the integration surfaces and documentation boundaries.