{"id":25553841,"url":"https://github.com/docusign/extension-app-data-verification-reference-implementation","last_synced_at":"2026-02-02T21:17:37.083Z","repository":{"id":240149899,"uuid":"795727989","full_name":"docusign/extension-app-data-verification-reference-implementation","owner":"docusign","description":"This reference implementation models several data verification use cases.","archived":false,"fork":false,"pushed_at":"2025-05-15T20:41:39.000Z","size":148,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-31T03:43:36.158Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HCL","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/docusign.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":"2024-05-03T22:49:41.000Z","updated_at":"2025-04-24T23:20:56.000Z","dependencies_parsed_at":"2024-05-17T01:46:24.746Z","dependency_job_id":"0a6e2110-5714-4422-a8b4-c0a085bad696","html_url":"https://github.com/docusign/extension-app-data-verification-reference-implementation","commit_stats":null,"previous_names":["docusign/extension-app-data-verification-reference-implementation"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/docusign/extension-app-data-verification-reference-implementation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docusign%2Fextension-app-data-verification-reference-implementation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docusign%2Fextension-app-data-verification-reference-implementation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docusign%2Fextension-app-data-verification-reference-implementation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docusign%2Fextension-app-data-verification-reference-implementation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/docusign","download_url":"https://codeload.github.com/docusign/extension-app-data-verification-reference-implementation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docusign%2Fextension-app-data-verification-reference-implementation/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263901401,"owners_count":23527403,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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-02-20T12:02:06.116Z","updated_at":"2026-02-02T21:17:37.076Z","avatar_url":"https://github.com/docusign.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Data Verification Extension App Reference Implementation\n## Introduction\nThis reference implementation models seven data verification use cases:\n* [Bank account owner verification](https://developers.docusign.com/extension-apps/extension-app-reference/extension-contracts/bank-account-owner-verification/)\n* [Bank account verification](https://developers.docusign.com/extension-apps/extension-app-reference/extension-contracts/bank-account-verification/)\n* [Business FEIN verification](https://developers.docusign.com/extension-apps/extension-app-reference/extension-contracts/business-fein-verification/)\n* [Email address verification](https://developers.docusign.com/extension-apps/extension-app-reference/extension-contracts/email-address-verification/)\n* [Phone verification](https://developers.docusign.com/extension-apps/extension-app-reference/extension-contracts/phone-verification/)\n* [SSN verification](https://developers.docusign.com/extension-apps/extension-app-reference/extension-contracts/ssn-verification/)\n* [Postal address verification](https://developers.docusign.com/extension-apps/extension-app-reference/extension-contracts/postal-address-verification/)\n\nEach use case corresponds to a separate extension app manifest located in the [manifests](/manifests/) folder of this repository.\n\nFor an example of a reference implementation with multiple extensions, see the [Data IO and Data Verification Reference Implementation](https://github.com/docusign/extension-app-data-io-and-verification-reference-implementation/).\n\n## Authentication\nThis reference implementation supports two [authentication](https://developers.docusign.com/extension-apps/build-an-extension-app/it-infrastructure/authorization/) flows:\n* [Authorization Code Grant](https://developers.docusign.com/extension-apps/build-an-extension-app/it-infrastructure/authorization/#authorization-code-grant) – required for public extension apps\n* [Client Credentials Grant](https://developers.docusign.com/extension-apps/build-an-extension-app/it-infrastructure/authorization/#client-credentials-grant) – available to private extension apps. See [Choosing private distribution instead of public](https://developers.docusign.com/extension-apps/extension-apps-101/choosing-private-distribution/)\n\n*Private extension apps can use either authentication method, but public extension apps must use Authorization Code Grant.*\n\n## Hosted Version (no setup required)\nYou can use the hosted version of this reference implementation by directly uploading the appropriate manifest file located in the [manifests/hosted/](/manifests/hosted/) folder of this repo to the Docusign Developer Console. See [Upload your manifest and create the data verification app](#3-upload-your-manifest-and-create-the-data-verification-app).\n\n**Note:** The provided manifests include `clientId` and `clientSecret` values used in the sample authentication connection. These do not authenticate to a real system, but the hosted reference implementation requires these exact values.\n\n## Choose your setup: local or cloud deployment\nIf you want to run the app locally using Node.js and ngrok, follow the [Local setup instructions](#local-setup-instructions) below.\n\nIf you want to deploy the app to the cloud using Docker and Terraform, see [Deploying an extension app to the cloud with Terraform](terraform/README.md). This includes cloud-specific setup instructions for the following cloud providers:\n- [Amazon Web Services](https://aws.amazon.com/)\n- [Microsoft Azure](https://azure.microsoft.com/)\n- [Google Cloud Platform](https://cloud.google.com/)\n\n## Local setup instructions\n\n### Video Walkthrough\n[![Reference implementation videos](https://img.youtube.com/vi/_4p7GWK5aoA/0.jpg)](https://youtube.com/playlist?list=PLXpRTgmbu4or5pJIFg6h1bg1Gt4wZTYbT\u0026feature=shared)\n\n### 1. Clone the repository\nRun the following command to clone the repository:\n```bash\ngit clone https://github.com/docusign/extension-app-data-verification-reference-implementation.git\n```\n\n### 2. [Install and configure Node.js and npm on your machine.](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)\n\n### 3. Generate secret values\n- If you already have values for `JWT_SECRET_KEY`, `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`, and `AUTHORIZATION_CODE`, you may skip this step.\n\nThe easiest way to generate a secret value is to run the following command:\n```bash\nnode -e \"console.log(require('crypto').randomBytes(64).toString('hex'));\"\n```\n\nYou will need values for `JWT_SECRET_KEY`, `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`, and `AUTHORIZATION_CODE`.\n\n### 4. Set the environment variables for the cloned repository\n- If you're running this in a development environment, create a copy of `example.development.env` and save it as `development.env`.\n- If you're running this in a production environment, create a copy of `example.production.env` and save it as `production.env`.\n- Replace `JWT_SECRET_KEY`, `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`, and `AUTHORIZATION_CODE` in `development.env` or `production.env` with your generated values. These values will be used to configure the sample proxy's mock authentication server.\n\n### 5. Install dependencies\nRun the following command to install the necessary dependencies:\n```bash\nnpm install\n```\n### 6. Running the proxy server\n#### Development mode:\nStart the proxy server in development mode by running the command:\n```bash\nnpm run dev\n```\n\nThis will create a local server on the port in the `development.env` file (port 3000 by default) that listens for local changes that trigger a rebuild.\n\n#### Production mode:\nStart the proxy server in production mode by running\nnpm run build\nnpm run start\n\nThis will start a production build on the port in the `production.env` file (port 3000 by default).\n\n## Setting up ngrok\n### 1. [Install and configure ngrok for your machine.](https://ngrok.com/docs/getting-started/)\n### 2. Start ngrok\nRun the following command to create a public accessible tunnel to your localhost:\n\n```bash\nngrok http \u003cPORT\u003e\n```\n\nReplace `\u003cPORT\u003e` with the port number in the `development.env` or `production.env` file.\n\n### 3. Save the forwarding address\nCopy the `Forwarding` address from the response. You’ll need this address in your `manifest.json` file.\n\n```bash\nngrok\n\nSend your ngrok traffic logs to Datadog: https://ngrok.com/blog-post/datadog-log\n\nSession Status                online\nAccount                       email@domain.com (Plan: Free)\nUpdate                        update available (version 3.3.1, Ctrl-U to update)\nVersion                       3.3.0\nRegion                        United States (us)\nLatency                       60ms\nWeb Interface                 http://127.0.0.1:4040\nForwarding                    https://bbd7-12-202-171-35.ngrok-free.app -\u003e http:\n\nConnections                   ttl     opn     rt1     rt5     p50     p90\n                              0       0       0.00    0.00    0.00    0.00\n```\n\nIn this example, the `Forwarding` address to copy is `https://bbd7-12-202-171-35.ngrok-free.app`.\n\n## Create an extension app\n### 1. Prepare your app manifest\nChoose a manifest from the [manifests](/manifests/) folder based on the appropriate data verification use case. Replace `\u003cPROXY_BASE_URL\u003e` in your .manifest.json file with the ngrok forwarding address in the following sections:\n- `connections.params.customConfig.tokenUrl`\n- `connections.params.customConfig.authorizationUrl`\n- `actions.params.uri`\n\nUpdate the following variables in your .manifest.json file with the corresponding environment variables:\n- Set the `clientId` value in your .manifest.json file to the same value as `OAUTH_CLIENT_ID`.\n- Set the `clientSecret` value in your .manifest.json file to the same value as `OAUTH_CLIENT_SECRET`.\n### 2. Navigate to the Docusign [Developer Console](https://devconsole.docusign.com/)\nLog in with your Docusign developer credentials and create a new app.\n### 3. Upload your manifest and create the data verification app\n[Create your extension app](https://developers.docusign.com/extension-apps/build-an-extension-app/create/)\n\n## Test the extension app\nThis reference implementation uses mock data to simulate how data can be verified against a database. [Test your extension](https://developers.docusign.com/extension-apps/build-an-extension-app/test/) using the sample data in [sampleData.ts](src/constants/sampleData.ts).\n\nRequest bodies much match the appropriate [action contract](https://developers.docusign.com/extension-apps/extension-app-reference/app-manifest-reference/action/):\n* [Bank account owner verification](https://developers.docusign.com/extension-apps/extension-app-reference/action-contracts/bank-account-owner-verification/#request) example JSON request body:\n  ```\n  {\n    \"firstName\": \"Eliza\",\n    \"lastName\": \"Monroe\",\n    \"accountNumber\": \"123456789\",\n    \"accountType\": \"checking\",\n    \"routingNumber\": \"987654321\"\n  }\n  ```\n* [Bank account verification](https://developers.docusign.com/extension-apps/extension-app-reference/action-contracts/bank-account-verification/#request) example JSON request body:\n  ```\n  {\n    \"accountNumber\": \"123456789\",\n    \"accountType\": \"checking\",\n    \"routingNumber\": \"987654321\"\n  }\n  ```\n* [Business FEIN verification](https://developers.docusign.com/extension-apps/extension-app-reference/action-contracts/business-fein-verification/#request) example JSON request body:\n  ```\n  {\n    \"businessName\": \"VistaPeak Ventures\",\n    \"fein\": \"11-1111111\"\n  }\n  ```\n* [Email address verification](https://developers.docusign.com/extension-apps/extension-app-reference/action-contracts/email-address-verification/#request) example JSON request body:\n  ```\n  {\n    \"email\": \"theo.clarkson@gmail.com\"\n  }\n  ```\n* [Phone verification](https://developers.docusign.com/extension-apps/extension-app-reference/action-contracts/phone-verification/#request) example JSON request body:\n  ```\n  {\n    \"phoneNumber\": \"1234567890\",\n    \"region\": \"1\"\n  }\n  ```\n* [SSN verification](https://developers.docusign.com/extension-apps/extension-app-reference/action-contracts/ssn-verification/#request) example JSON request body:\n  ```\n  {\n    \"socialSecurityNumber\": \"111-11-1111\",\n    \"firstName\": \"Nora\",\n    \"lastName\": \"Bentley\",\n    \"dateOfBirth\": \"1975-09-08\"\n  }\n  ```\n\n* [Postal address verification](https://developers.docusign.com/extension-apps/extension-app-reference/extension-contracts/postal-address-verification#request/) There are two actions required by the postal address data verification extension contract.\n  * Verify.Version1.PostalAddress: This action will return the verified address with a successful response if the request body exactly matches an entry in the sample database.\n\n    Example JSON request body:\n\n    **Note:** \"street2\" is an optional parameter.\n    ```\n    {\n      \"street1\": \"123 Main St\",\n      \"street2\": \"Apt 4B\",\n      \"locality\": \"Springfield\",\n      \"subdivision\": \"IL\",\n      \"countryOrRegion\": \"US\",\n      \"postalCode\": \"62701-1234\"\n    }\n\n    ```\n\n  * Typeahead.Version1.PostalAddress: This action will return a list of suggested addresses based on if the sample database contains one or more partial matches to the request body.\n\n    Example JSON request body:\n\n    **Note:** \"street2\" is an optional parameter.\n\n    ```\n    {\n      \"street1\": \"123 Main St\",\n      \"street2\": \"Apt 4B\",\n      \"locality\": \"Springfield\",\n      \"subdivision\": \"IL\",\n      \"countryOrRegion\": \"US\",\n      \"postalCode\": \"62701\"\n    }\n\n    ```\n    Example JSON response:\n    ```\n    {\n      \"suggestions\": [{\n        \"street1\": \"123 Main St\",\n        \"street2\": \"Apt 4B\",\n        \"locality\": \"Springfield\",\n        \"subdivision\": \"IL\",\n        \"countryOrRegion\": \"US\",\n        \"postalCode\": \"62701-1234\"\n      }]\n    }\n    ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocusign%2Fextension-app-data-verification-reference-implementation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdocusign%2Fextension-app-data-verification-reference-implementation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocusign%2Fextension-app-data-verification-reference-implementation/lists"}