{"id":28384113,"url":"https://github.com/plaid/idv-quickstart","last_synced_at":"2026-02-03T11:03:41.053Z","repository":{"id":92928166,"uuid":"607846873","full_name":"plaid/idv-quickstart","owner":"plaid","description":"Get up and running with Plaid Identity Verification in minutes","archived":false,"fork":false,"pushed_at":"2025-11-10T16:36:54.000Z","size":188,"stargazers_count":48,"open_issues_count":0,"forks_count":39,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-11-10T18:22:35.732Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/plaid.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-02-28T19:50:18.000Z","updated_at":"2025-11-10T16:36:59.000Z","dependencies_parsed_at":"2023-04-30T19:17:18.241Z","dependency_job_id":"2f0b61d3-892a-427d-8627-c7a2f0dae36e","html_url":"https://github.com/plaid/idv-quickstart","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/plaid/idv-quickstart","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plaid%2Fidv-quickstart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plaid%2Fidv-quickstart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plaid%2Fidv-quickstart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plaid%2Fidv-quickstart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plaid","download_url":"https://codeload.github.com/plaid/idv-quickstart/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plaid%2Fidv-quickstart/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29043700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T10:09:22.136Z","status":"ssl_error","status_checked_at":"2026-02-03T10:09:16.814Z","response_time":96,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-30T07:38:50.790Z","updated_at":"2026-02-03T11:03:41.025Z","avatar_url":"https://github.com/plaid.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Identity Verification Sample App\n\n## Background\n\nThis fictional used car marketplace application shows you how to verify a user's\nidentity using Plaid Identity Verification. This application uses NodeJS on the\nbackend, and vanilla JavaScript on the frontend.\n\n## Demo video\n\nFor a video tour and walkthrough of this sample app, check out the [Plaid Identity Verification: Demo Video](https://www.youtube.com/watch?v=5EZwC5w6KCw).\n\n# Installation\n\nWe recommend having node version 16.x.x or later before attempting to run this\napplication.\n\n## 1. Make sure you have access to Identity Verification\n\nFirst, if you haven't already done so, \n[sign up for your free Plaid API keys](https://dashboard.plaid.com/signup).\n\nYou may not have access to Identity Verification initially. Confirm your access\nin the Plaid Dashboard by looking for the \"Identity Verification\" product in the\nleft-hand nav bar, under the \"Products\" grouping. If it's not present, talk to \nyour account manager or [file a support ticket](https://dashboard.plaid.com/support)\nto request access to Identity Verification.\n\n## 2. Clone the repository\n\nUsing https:\n\n```\ngit clone https://github.com/plaid/idv-quickstart\ncd idv-quickstart\n```\n\nAlternatively, if you use ssh:\n\n```\ngit clone git@github.com:plaid/idv-quickstart.git\ncd idv-quickstart\n```\n\n## 3. Install the required packages\n\nRun `npm install` inside your directory to install of the Node packages required\nfor this application to run.\n\n## 4. Create an Identity Verification template if you don't have one already\n\n1. Head over to the \"Identity Verification\" section of the dashboard\n   (you can find it under \"Products\" in the left nav). If you don't see it, contact Sales or your Account Manager to request access.\n2. Switch the toggle on the upper right of your screen to Sandbox to set up a\n   template in Sandbox mode\n3. If there's already an Identity Verification template you want to use, you can\n   skip ahead to the next section.\n4. Otherwise, click the **New Template** button.\n5. Fill out the **Setup** form however you'd like. We checked **Attempt to auto-fill customer PII** because it's fun to see. :) Note that you are required to\nenter a real working URL as your privacy policy link. You should\n   also leave **Verify Phone Number with SMS** checked -- you would only uncheck\n   this if your application already verifies the user's phone number through a\n   separate mechanism.\n6. Pick any color you'd like on the **Design** screen.\n7. For the **Workflow**, you can configure  the behavior you'd like to see under Workflow Management.\n\n     PII Verification\n   - Data source verification works by comparing the user's verified phone number\n     and information again several data sources.\n   - Document verification asks your user to take pictures of documentation such\n     as drivers licenses or passports.\n   - Select whatever workflow you would like to see. **Fallback to document**\n     verification is a common option, but you could also select **Require both\n     data source and document verification** if you wish to experience the entire\n     Identity Verification process. You can always change this later.\n\n   Selfie Behavior \n   - Selfie check asks your user to verify they are a real person by capturing\n     footage of themselves on their phone. Sandbox mode doesn't use selfie so the\n     Selfie Behavior you select doesn't really matter.\n\n8. You can leave **Rulesets** with the default values for now, but we'll come\n   back to this soon.\n9. Click **Publish changes** and exit the editor.\n\n## 5. Set up your environment variables\n\nCopy `.env.template` to a new file called `.env`. Then open up `.env` in your\nfavorite code editor and fill out the values.\n\n```\ncp .env.template .env\n```\n\nYou can get your `PLAID_CLIENT_ID` and `PLAID_SECRET` values from the Keys section\nof the [Plaid dashboard](https://dashboard.plaid.com/developers/keys)\n\nYou can keep `sandbox` as your environment.\n\nFor `TEMPLATE_ID`, we'll need the ID of the Identity Verification template that\nyou created above. You can do this by selecting your template from the\n[templates screen](https://idv-playground.plaid.com/flow/templates/), selecting\nthe template you created, and then clicking the **Integration** button on top.\n\nYou can leave `DATA_SOURCE_ONLY_NO_SMS_ID` blank for now. We'll return to this in\na future step.\n\n**NOTE:** .env files are a convenient local development tool. Never run a\nproduction application using an environment file with secrets in it. Use some\nkind of Secrets Manager (provided by most commercial cloud providers) instead\n\n## 6. (Optional) Set up your webhook receiver\n\nThis application makes use of webhooks in certain flows so that it can receive\nmessages from Plaid that the user is done with their Identity Verification\nprocess. If you want to see this part of the application in action, you will\nneed to tell Plaid what webhook receiver it should send these messages to.\n\n### Step 1: Create a public endpoint for your webhook receiver\n\nThis webhook receiver will need to be available to the public in order for Plaid\nto communicate with it. If you don't wish to publish this sample application to\na public server, one common option is to use a tool like\n[ngrok](https://ngrok.com/) to open up a tunnel from the outside world to a\nspecific port running on `localhost`.\n\nThe sample application uses a separate server to receive webhooks running on\nport 8001, so if you have ngrok installed, you can run\n\n```\nngrok http 8001\n```\n\nto open up a tunnel from the outside world to this server. The final URL will be\nthe domain that ngrok has created, plus the path `/server/receive_webhook`. It\nwill probably look something like:\n\n`https://abde-123-4-567-8.ngrok.io/server/receive_webhook`\n\n### Step 2: Configure Plaid to talk to this endpoint\n\nUnlike many other Plaid products, you won't configure the webhook URL when\ncreating an Item. Instead, you'll use the Plaid dashboard at\nhttps://dashboard.plaid.com/team/webhooks to tell Plaid what endpoint to call\nwhen sending webhooks. From this page:\n\n- Click **New webhook**.\n- Select **Identity verification status updated** as the event. (That's\n  _status_, not _step_.)\n- Add the URL that you created in the previous step.\n- Click **Configure**\n\nYou can also repeat the process for the \"step updated\" and \"retried\" events if\nyou want to see them in action, although our application doesn't do anything\nwith these.\n\nAt this point, any webhooks called by Identity Verification will be sent to the\nURL you specified. If you ever restart ngrok and end up with a new domain, make\nsure to add the new webhook to the dashboard.\n\nThe code that is used to process these endpoints is contained in the\n`webhookServer.js` file.\n\n## 7. Run the application!\n\nYou can run your application by typing\n\n```\nnpm run watch\n```\n\non the command line. If there are no issues, you should see a message telling\nyou that you can open up http://localhost:8000/ to view your running app!\n\n# Running the application\n\nBaby You Can Buy My Car is a fictional marketplace app that requires users to\nverify their identity before they can fully sign up for the app. This sample\napplication simulates four different ways that a user could verify their\nidentity. Obviously, in a real app, you wouldn't present all four options to a\nuser; this is just for demonstration purposes.\n\nCreate an account or sign in with a existing account to start the process.\n\n## 1. The Standard flow\n\nThe Standard flow involves users verifying their identity through Link, the\nclient-side widget that Plaid provides to developers that handles most of the UI\nwork for you.\n\nTo activate the standard flow, click the **Verify My Identity** button. If you\nare running in Sandbox mode, Plaid Identity Verification will only accept one\nidentity, that of Leslie Knope with the values specified\n[here](https://plaid.com/docs/identity-verification/testing/). The UI in Sandbox\nmode will also give you these values in the upper-right side of the screen.\n\nWith Data Source verification, if you fill out these values correctly, your\nidentity will be accepted.\n\nIf you fill out these values incorrectly (and have selected the appropriate\nworkflow), Identity Verification will fall back to Document verification.\n\nIn Document verification, you will be asked to take pictures of an appropriate\npiece of identification using your phone. In the Sandbox environment, the\napplication will assume you always submit a valid drivers license\nwith the same name and date of birth as that of our test user. (Leslie Knope,\nJanuary 18, 1975)\n\nSo if you wish to see what a \"failed Data Source, but passed Documentation\" flow\nlooks like, try entering a different phone number, social security number,\nand/or address, but make sure to enter the correct name and birthday.\n\n### How it works\n\nYou should view the code for the full details, but essentially:\n\n1. If the client sees that our user's identification has not yet been verified\n   (just by checking our application's database), it requests a Link token from\n   the server.\n2. The server generates a Link token using the `/link/token/create` endpoint,\n   and passes this token back up to the client.\n3. Once the user is done with Link (either successfully or not), the client will\n   receive an Identity Verification session ID. It sends this session ID to the\n   server.\n4. The server then makes a call to `/identity_verification/get` with this\n   session ID. It will receive information about the user's verification\n   attempt, like whether it was successful or not, the userID associated with\n   this session, and information like the user's full name and mailing address.\n5. The server records the status of the user's verification attempt, this\n   session ID and, if the attempt was successful, additional details about the\n   user, in its database.\n6. Note that if you are using webhooks, your server will also receive this\n   verification session ID as a webhook. It will repeat steps 4 and 5 when that\n   happens, which technically isn't necessary.\n\n### Email address\n\nIf you have the user's email address, you should include it when creating the\nlink token in step 2 -- Identity Verification runs a number of different fraud\nchecks against this email. It is considered best practice to verify the user's\nemail address before submitting it, something we are not doing in our sample\napp.\n\n### Seeing Identity Verification details\n\nIf you want to see more details about a user's latest Identity Verification\nattempt, the best place to do this would be the Identity Verification section of\nthe Plaid Dashboard. Click into the verificaiton template you used in the demo. From there, you'll be able to see full details about every\nuser attempt by status: What they entered, why they might have failed, and you can perform\nimportant actions like ask your user to retry different steps.\n\nYou can also see details about a user's Identity Verification attempts by\nexpanding the \"Debug Tools\" section and clicking the \"See my most recent\nattempt\" button or the \"See all my IDV attempts\" button. The former will have\nour server make a call to `/identity_verification/get` (passing along the most\nrecent IDV session ID, which we fetch from our database). The latter will have\nour server make a call to `/identity_verification/list` (passing along the\nuser's ID).\n\nWe summarize these results on screen, but you can also look at your browser's\nJavaScript console to see the full object that gets returned from these calls.\n\nThese Debug Tools are there to demonstrate what kind of results you might get\nback from `/identity_verification/get` and `/identity_verification/list`. It\nwould be rare for a typical client application to make calls to these endpoints\nor share this information with the user.\n\n### Retrying Identity Verification attempts\n\nOnce a user has completed an Identity Verification attempt, they typically\ncannot retry it without you, the developer, initiating it on their behalf. To do\nthis, select the user's Identity Verification attempt in the Plaid dashboard\n(whether it has succeeded or failed) and click the **Request Retry** option\nunderneath their name. You can choose to retry the entire attempt from the\nbeginning, or perform a special Identity Verification flow.\n\nNote that requesting a retry will create a new Identity Verification session.\nYou can see a list of all of the user's Identity Verification sessions by\nlooking at the results of the `/identity_verification/list` call, as described\nabove.\n\n### Is Identity Verification Failing?\n\nAs you're testing Identity Verification, you might notice that your attempts\nstart to fail because your user failed the Risk Check. This is a check that\nlooks for risky behavior such as a user trying to verify multiple identities\nfrom the same device or the same IP address, something that commonly occurs when\nyou're testing Identity Verification.\n\nIf you want to allow this on a case-by-case basis, you can manually select the\nfailed Identity Verification attempt in the Plaid dashboard and then click\n**Override Result** in the **Potential Risks** section. Click the \"Verify my\nIdentity\" button again in the browser and your Identity Verification session\nwill succeed.\n\nIf you want to allow this permanently, you can edit the template in the Plaid\ndashboard:\n\n- Head back to the Identity Verification section of the Plaid dashboard\n- Select your template\n- Click **Open Editor**\n- In the Identity Verification editor, select the **Rulesets** section\n- Select **Risk Rules**\n- Change the Acceptable Risk Level of **Network Risk** from \"Medium Risk\" to\n  \"High Risk\"\n- Click **Publish Changes**\n\n## 2. The Pre-fill flow\n\nIn some cases, you might already have information about your user that Identity\nVerification will want, such as your user's full name, phone number, date of\nbirth, or mailing address. Rather than put your user through the trouble of\nentering this information a second time, you can \"kick-start\" your user's\nIdentity Verification process by sending this information to Plaid before\nstarting the Identity Verification flow.\n\nTo try out the pre-fill flow, click on the **Pre-fill some data** button. We'll\nsimulate entering the name, date of birth, and mailing address for our test\nuser. Then click the **Verify my identity** button. You'll notice that when you\nverify your user's identity this time, you'll have much fewer fields to fill\nout.\n\nNote that you have to add the user's information before starting the Identity\nVerification flow. You can't add it once the process has begun.\n\n### How it works\n\nAgain, make sure to view the code for the full details, but essentially:\n\n1. The server makes a call to `/identity_verification/create` to initiate an\n   Identity Verification session, adding in whatever information we already know\n   about the user.\n2. This call returns a Identity Verification session ID, which we store in our\n   database.\n3. Note that because of the way our application works, we already have a link\n   token generated before we make a call to `/identity_verification/create`.\n   This is fine -- there's no need to regenerate a new Link token.\n4. When the client runs Link, Identity Verification will see that the `user_id`\n   which was used to generate the Link token is the same as the `user_id` which\n   was used to create a Identity Verification session, and it won't ask the user\n   to enter information that it already received in step 1.\n5. We then proceed with steps 3-6 in the Standard flow. The Identity\n   Verification session ID received by Link and your webhooks will be the same\n   value as what was already generated in step 2.\n\n### Do I need to verify the information I send to Plaid?\n\nIt is not necessary for you to verify information like the user's name or\nmailing address before sending it to Plaid -- that's what Identity Verification\nis for (with the exception of the user's email address, which we recommend you\nverify). However, it should be made clear when you collect this information from\nthe user that they should be sending you legitimate data that will be used for\nidentity verification purposes.\n\n## 3. The Shareable URL flow\n\nTypically, when your users complete the Identity Verification process, they'll\ndo so within your application using Link, Plaid's client-side widget that\nhandles all of the UI work for you. But you also have the option of generating a\nURL that you can direct your users to in order to complete the process.\n\nThe most common scenario for using a shareable URL is when a company hasn't\nintegrated Identity Verification into their app, but needs to occasionally\nverify a user's identity on an ad hoc basis. For example, a customer's account\nmight be flagged for suspicious activity and your customer service team will\nwant to verify their identity as an extra security step. This is typically done\nthrough the Plaid dashboard:\n\n- On the panel for the Identity Verification template you created, click the\n  \"Create Verification\" button at the top\n- Add the user's customer reference (like their internal application ID) and\n  their email, if you have it.\n  - If you want to use the ID of your currently signed in user, you can find\n    their full ID by looking at the contents of the `get_basic_user_info` call\n    in your browser.\n- Click the \"Create verification link\" button\n- Copy-and-paste that link, and share it with your customer\n\nYou should be able to see your customer's Identity Verification status, along\nwith the data they entered, in the appropriate section of the panel for the\nIdentity Verification template. (\"In progress\", \"Passed\", \"Failed\", etc.)\n\n## 3a. The Generated Shareable URL flow\n\nIt's less common to use a shareable URL within your application if you've\nalready integrated the Plaid API -- most applications would prefer that their\nusers stay within their application via the Link widget rather than switch to\nanother tab or another browser. But we've included this process here for\ncompleteness.\n\nTo try generating a Shareable URL in the browser, click the **Generate a\nShareable URL** button. You will be given a URL to follow that opens up the\nIdentity Verification process in a new window.\n\nWhen you're done (assuming you have webhooks working), your client page should\nupdate after a few seconds to reflect your verified identity. If you don't have\nwebhooks working, you can click the **Simulate receiving a webhook** button to\ncomplete the process.\n\n### How it works\n\n1. The server makes a call to `/identity_verification/create` to initiate a\n   Identity Verification session, adding the `is_shareable: true` argument to\n   indicate that we want to generate a URL that can be shared with the user.\n2. This URL is then presented to the user, which they can open in a separate\n   window and complete the process.\n3. If you are using webhooks, your server will receive a `STATUS_UPDATED`\n   webhook with the Identity Verification session ID.\n4. The server can then make a call to `/identity_verification/get` with this\n   session ID and it will update your user's entry in the database accordingly.\n5. The client, meanwhile, is performing some simple polling to fetch this\n   database entry every few seconds. You're free to build something more\n   sophisticated in your app.\n6. If you don't have webhooks working, the `/server/fake_webhook` endpoint on\n   the server will pretend as though it has received a webhook for this user by\n   looking up the most recent Identity Verification session ID that we have\n   stored for this user. Then it will perform steps 4-5 with this session ID.\n\n## 4. The Backend-Only flow\n\nIn some cases, your application may already have all of the information you need\nto verify your user without any additional input from them. Alternately, you\nmight want to build a completely custom frontend without using Link. In these\nsituations, you can attempt to verify your user's identity completely on the\nserver.\n\nFor the backend-only flow to work, you'll need to make sure you're using an\nIdentity Verification template that is using the \"Data Source Only\" flow, and\ndoesn't require SMS verification.\n\nTo create a new template, follow the steps for creating an Identity Verification\ntemplate at the beginning of this readme, but with the following exceptions:\n\n1. Be sure to _uncheck_ **Verify Phone Number with SMS** in the Setup panel\n2. For the workflow, select **Data Source Only**\n\n**Warning:** You should only skip verifying your user's phone number in Identity\nVerification if your application is already performing this verification on its\nown.\n\nCopy the template ID for the template you just created, and paste that into your\n.env file as the value for the `DATA_SOURCE_ONLY_NO_SMS_ID` entry. If you're\nrunning `npm run watch`, the server should automatically restart.\n\nYou can then start the backend-only flow by checking the Terms of Service\ncheckbox, and then clicking the **Server-only verification** button. If you have\nwebhooks working, your application should update after a few seconds with your\nnewly identified user.\n\nIf you don't have webhooks working, you can click the **Simulate receiving a\nwebhook** button, and your application should update as well\n\nNote that Identity Verification sessions created this way will not show up in\nthe \"See all my IDV attempts\" results, because that call is made using your\noriginal Identity Verification template.\n\n### How it works\n\n1. The server makes a call to `/identity_verification/create` to initiate a\n   Identity Verification session, sending across all of the data Plaid would\n   need to verify the user's identity, including their name, address, phone\n   number, and last 4 digits of their social security number.\n   - We also include a `gave_consent: true` value to indicate that our user has\n     consented to their data being shared with Plaid for verification purposes.\n     (This is usually mentioned as part of your application's terms of service.\n     Please consult with your legal counsel on the actual wording to use -- our\n     law background consists of watching reruns of Judge Judy.)\n   - For this sample application, this data is hard-coded to that of our sandbox\n     user.\n2. If you are using webhooks, your server will receive a `STATUS_UPDATED`\n   webhook with the Identity Verification session ID.\n3. The server then makes a call to `/identity_verification/get` with this\n   session ID and it updates your user's entry in the database accordingly.\n4. Like in the previous flow, the client is just performing some simple polling\n   to re-fetch this database entry every few seconds.\n5. If you don't have webhooks working, the `/server/fake_webhook` endpoint on\n   the server will pretend as though it has received a webhook for this user by\n   looking up the most recent Identity Verification session ID that we have\n   stored for this user and then running steps 3-4.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplaid%2Fidv-quickstart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplaid%2Fidv-quickstart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplaid%2Fidv-quickstart/lists"}