Contact Identity Verification

See the component in action in the live demo.

Run Plaid Identity Verification for a contact directly inside your own page. You create a short-lived IDV session on the server, then hand the returned token to the <contact-idv-session> component, which opens the Plaid IDV flow.

Step 1: Create an IDV session (Server)

In your server-side code, call contactCreateIdvSession in the GraphQL API. Pass the orgId the verification belongs to. Include contactId to verify an existing contact, or leave it blank to verify a brand-new one — the contact record is created or updated automatically when verification completes.

The mutation returns a token (the Plaid Link token) and the expiresAt timestamp after which the token can no longer be used.

Example

curl -X POST https://GRAPH_URL \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "query": "mutation ContactCreateIdvSession($input: ContactCreateIdvSession!) { contactCreateIdvSession(input: $input) { token expiresAt } }",
    "variables": {
      "input": {
        "orgId": "35dHMM4pFzIykUsys1CDyZ9Xtkz"
      }
    }
  }'

To verify an existing contact, include its id:

{
  "input": {
    "orgId": "35dHMM4pFzIykUsys1CDyZ9Xtkz",
    "contactId": "CONTACT_ID"
  }
}

Step 2: Load the contact session component (Client)

In your client-side code, load the contact script ideally in the <head> of your page.

<script type="module" src="https://js.clientloop.com/contact.iife.js"></script>

Then render the component with the token from Step 1. The component opens the Plaid IDV flow as soon as it has a token.

<contact-idv-session token="TOKEN"></contact-idv-session>

Selecting an environment

Set the optional env attribute to match the ClientLoop environment the IDV session was created in (Step 1). It defaults to prod; use stage when testing your integration against the ClientLoop staging environment:

<contact-idv-session token="TOKEN" env="stage"></contact-idv-session>

Omit env (or set it to prod) for production.

Step 3: Listen to events

The <contact-idv-session> component emits DOM CustomEvents as the contact moves through verification. They bubble and are composed, so you can attach a single listener on the element.

Event	When it fires
`contact-identity-loaded`	The Plaid identity-verification UI finished loading.
`contact-identity-complete`	Verification finished successfully (passed or pending review).
`contact-identity-closed`	The contact closed the identity-verification UI.

Usage

<contact-idv-session token="TOKEN"></contact-idv-session>
<div id="idv-thanks" hidden>Thanks — your identity has been verified.</div>

<script>
  const idv = document.querySelector('contact-idv-session');
  const thanks = document.getElementById('idv-thanks');

  idv.addEventListener('contact-identity-complete', () => {
    idv.hidden = true;
    thanks.hidden = false;
  });
</script>