Although the Mesh API is powerful, the fundamental concepts you need to know are simple:

• VSKU: Mesh offers distinct verification products, or Verification SKUs (VSKU). You can think of VSKUs as items in a shopping cart.
• VOW: Mesh assembles VSKUs, or building blocks, into a Verification Order Workflow (VOW). You can think of the VOW as a pre-defined shopping list (of VSKUs) that is used repeatedly when a verification is to be performed.
• Business Entity: The subject of a Verification Order Workflow is a Business Entity, such as a business, sole proprietor, or professional to be verified.
• Verification Order: A Verification Order is an instance of a VOW. You can think of a VOW as a shopping cart that you can 'check out' with. A Verification Order can be placed by you the customer through our API, or by the business entity itself through our dynamic, no-code user interface (UI).
• Claims: The inputs provided by you, the customer (or by the business entity through our UI) are called claims i.e. the information that the business entity claims to be true and that Mesh will verify.
• Results: The outputs of a verification, obtained by Mesh from authoritative sources and matched to the claims, are called results.
• Policies: The rules for matching claims and results, and evaluation the quality of the match, are know as policies. Mesh has item policies that apply to individual VSKUs, and order policies that apply to the entire VOW.
• Labels: The outcomes of policy decisions are labels. An example of a label is license_number_mismatch_major, applied when the license number claim is significantly different from the license number result. Mesh applies item labels to individual VSKUs, and order labels to the overall order itself. Order labels therefore represent the final outcome of the verification order, such as approved or rejected.

Our Quick Start Guide provides a worked example of a professional license verification VOW that will explain all of these concepts in more detail, and how they fit together, and should take about 1 hour to complete.

This API guide explains how to use Mesh's GraphQL API to interact with our system:

• How to submit verification orders.
• How to retrieve verification order results.
• How to create business entities to be verified.
• How to manage users in your account.
• How to configure notification types that you wish to receive as verification orders complete.
• How to interrogate the design of VSKUs and VOW Configurations to understand what claims are required and what results are returned.

The details of what each VSKU and VOW Configuration does, including the policies and labels applied during verification, are described in the companion Mesh Vow Configuration Documentation (provided separately). Please work with your Mesh account representative to obtain the Vow Configuration Documentation that is relevant to your account.

This guide is intended for developers who are familiar with GraphQL and have a basic understanding of how to interact with APIs. If you are new to GraphQL, we recommend reviewing the GraphQL documentation before proceeding.

Approximate time needed - 1 hour

About This Guide (1 min)

This guide will show you how to use the Mesh API for a simple professional license verification use case. The example uses a fictitious company called Circle Home. Circle is an online marketplace where consumers (homeowners) can find service providers such as architects, general contractors, electricians, and plumbers. The example will show how a Circle developer uses the Mesh API to perform professional license verification.

What We Will Cover

• Step 1 - Testing the API Key (5 mins): Make sure that our Mesh account is working, and begin exploring the API.
• Step 2 - Exploring the VOW (15 mins): A quick tour of the core concept in Mesh verifications, the Verification Order Workflow.
• Step 3 - Create Business (5 mins): Before we can perform a verification, we must tell Mesh who is being verified.
• Step 4 - Register Webhook (5 mins): We will need some way for Mesh to notify us that a verification order workflow has completed.
• Step 5 - Initiating a Verification Order workflow will follow one of two paths, depending on your desired integration pattern:
• Step 5a - Initiate the Mesh One Click User Interface (5 mins): Use our pre-built, optimized user interface for the fastest and most accurate results.
• Step 5b - Create VOW (10 mins): Build your own user interface, and call our API to initiate the VOW.
• Step 6 - Listen for Webhook Notifications and Get Results (10 mins): Wait for Mesh to complete the verification, and retrieve the results.

Pre-Requisites

Contact your Mesh customer success representative to create your Mesh account and get access to our sandbox so you can follow along with this quick-start guide using a sample verification workflow.

The first thing our Circle developer needs to do is check that their Mesh API key is working as expected. We'll use a basic whoami query to learn about the Circle Mesh account.

This query tells us a lot about our Mesh user account through which we are calling the API:

Field	Description
userId	The unique user ID that created the API key. All calls Circle makes with this API key will belong to the same user ID.
status	The status of the user account. This should be ACTIVE.

The customer (see Customer) block in the response also tells us a bit more about the Mesh customer account belonging to Circle:

Field	Description
customerName	The customer's business name, or Circle Home in our example.
customerId	The unique identifier for Circle's customer account. All Circle's calls with any API key will belong to this customer ID.
status	The status of Circle's customer account. This should be ACTIVE.

You will also notice that we have something called vows (see VowConfig) in our response. Let's explore those in more detail in the next step.

Query: whoami

query TestAPIKey{
    whoami{
        # Get some basic information about the Mesh user account
        userId
        # Gives us the status of the user.
        status
        # Get some basic information about the Mesh customer account
        customer{
            # The name of the customer account.
            customerName
            # A UUID representing the customer account.
            customerId
            # The status of the customer account.
            status
            # We'll talk about VOWs in Step 2!
            vows{
                vowId
                vowConfigId
            }
        }
    }
}

Example Code Snippet

curl \
--location 'https://app.mesh.id/graphql' \
--header 'Content-Type: application/json' \
--data '{"query":"query TestAPIKey{\r\n    whoami{\r\n \r\n userId\r\n status\r\n \r\n customer{\r\n customerName\r\n customerId\r\n status\r\n vows{\r\n vowId\r\n vowConfigId\r\n}\r\n }\r\n }\r\n}","variables":{}}'

Response

{
    "data": {
        "whoami": {
            "userId": "96cbb50d-8a15-46f8-a9d4-19e93610cbe2",
            "status": "ACTIVE",
            "role": "ADMIN",
            "customer": {
                "customerName": "Circle Home",
                "customerId": "76a9defa-3036-48c8-837e-8f60fe46257d",
                "status": "ACTIVE",
                "vows": [
                    {
                        "vowId": "86506334-46ff-4933-85de-4b858c126ab1",
                        "vowConfigId": "vow-pro-licensing@1.0"
                    }
                ]
            }
        }
    }
}

In Step 1, our Circle developer confirmed that their API key is working and obtained some basic information about their account. In the response, we saw that the customer account refers to a vow or Verification Order Workflow.

The Verification Order Workflow, or vow, is the most important concept to understand when working with Mesh. A vow specifies the type and number of verifications Mesh will run on a business. Each vow also has a policy, which describes the business decisions that Mesh will determine based on the combined results of all verifications in the vow.

You can think of a vow like a shopping cart on an e-commerce website. A shopping cart (vow) contains many items you wish to purchase. Each item in the shopping cart is an individual verification. In keeping with the online shopping paradigm, we call these items a Verification Store Keeping Unit, or vsku. An example of a vsku is a single professional license verification. You will explore these in more detail in the following steps.

To verify a business, we create (check out) a vow (shopping cart) containing the vskus (items) that represent the verifications you wish to purchase about the business. Mesh will fulfill the vow and return (ship) the business decision to you.

Note: vows currently must be configured by Mesh. Work with your customer success representative to understand the vows available to you or to have a new vow configured.

List VOW Configurations

Let's look at the vow configurations that Circle Home has access to. We use the listVowConfigs query to see what vow configurations are available to Circle Home. We can also get this information from whoami.

In this quick start professional license verification example, Mesh has configured Circle Home with only one vow configuration, vow-pro-licensing@1.0. This is Mesh's standard professional license verification vow configuration.

Field	Description
vowId	A unique ID representing the vow, used when submitting orders to tell Mesh what verifications to perform, and the policy Mesh will apply to the results.
vowConfigId	A unique string providing a more meaningful description of the vow. In our example, Circle is using Mesh's standard vow-pro-licensing@1.0 verification order workflow.
description	Additional information about the vow.

Query: listVowConfigs

query ListVowConfigs {
    listVowConfigs {
        vowId
        vowConfigId
        description
    }
}

Example Code Snippet

curl \
--location 'https://app.mesh.id/graphql' \
--header 'Content-Type: application/json' \
--data '{"query":"query ListVowConfigs {\r\n listVowConfigs {\r\n vowId\r\n vowConfigId\r\n description\r\n }\r\n}","variables":{}}'

Response

{
  "data": {
    "listVowConfigs": [
      {
        "vowId": "86506334-46ff-4933-85de-4b858c126ab1",
        "vowConfigId": "vow-pro-licensing@1.0",
        "description": "Mesh standard professional license verification vow."
      }
    ]
  }
}

Get a Specific VOW Configuration

You can get information about a specific vow configuration using the getVowConfig query. The same information is also available from listVowConfigs and whoami. Let's drill further into the structure of a vow.

Following the shopping cart analogy, you can see that the vow specifies the items, or vskus, that are accepted by the vow. The Mesh standard professional license vow accepts only one vsku with the identifier v-pro-license@1.0, which is Mesh's standard professional license verification item.

We'll go into vsku structure in more detail in the following example.

Query: getVowConfig

query GetVowConfig($vowId: String!){
                getVowConfig(vowId: $vowId){
                    # A vow is like a shopping cart. It describes the verifications to be performed. The vowId is Circle's specific instance of this vow design.
                    vowId
                    # The vowConfigId is a unique string that describes the vow configuration design. In this case, it's the standard professional license verification vow.
                    vowConfigId
                    description
                    # The shopping cart contains items, or vskus, each of which is an individual verification
                    items{
                        vskuId
                        vspecId
                        isRepeatable
                        isRequired
                    }
                }
            }
            
            

Example Code Snippet

curl \
--location 'https://app.mesh.id/graphql' \
--header 'Content-Type: application/json' \
--data '{"query":"query GetVowConfig($vowId: String!){\r\n getVowConfig(vowId: $vowId){\r\n \r\n vowId\r\n vowConfigId\r\n description\r\n \r\n items{\r\n vskuId\r\n vspecId\r\n isRepeatable\r\n isRequired\r\n}\r\n}\r\n}","variables":{"vowId":"86506334-46ff-4933-85de-4b858c126ab1"}}'

Response

{
  "data": {
    "getVowConfig": {
      "vowId": "86506334-46ff-4933-85de-4b858c126ab1",
      "vowConfigId": "vow-pro-licensing@1.0",
      "description": "Mesh standard professional license verification vow.",
      "items": [
        {
          "vskuId": "v-pro-license@1.0",
          "vspecId": "11fb7baf-7027-4a74-9ff5-f3576e539703",
          "isRepeatable": true,
          "isRequired": true
        }
      ]
    }
  }
}

Drill into VSKU Details

So now we understand a bit more about vows. Let's dig a bit more into vskus and what they contain.

Field	Description
vskuId	A unique descriptive identifier for the vsku design. For instance, Mesh's standard professional license verification, the vskuId is v-pro-license@1.0.
vspecId	A unique identifier for this item in the vow configuration. In complex vow configurations, it is possible for the same vskuId to appear more than once. Each appearance of the vksuId has a different vspecId.
isRepeatable	If true the vow will accept multiple instances of the vsku. This means the Circle developer can include more than one professional license in the same vow, which is useful where Mesh verifies a business with more than one professional license. If false the vow will accept only one instance of the vsku.
isRequired	If true the vow must contain at least one instance of this vsku. If false, the vsku is optional. In our example, the Circle developer must include at least one professional license vsku.
inputClaims	The input fields for the vsku, or to put it another way, the information that the business claims to be true. When submitting a vsku for verification, you will populate these fields. For instance, in our professional license verification example, inputClaims will include the licenseNumber the business claims to have.
outputResults	The output fields that Mesh will return when the verification is completed, or the results of this individual verification. For instance, in our professional license verification example, outputResults will include the verified license information found in authoritative government records.

The details of the inputClaims and outputResults vary from vsku to vsku. Let's look at the specific example of the professional license verification vsku. First, the input claims that must be provided with the vsku.

inputClaim	Description
licenseIdentifier	The license number or identifier assigned to the professional license to be verified.
licenseeName	The name of the person or business to whom the license was issued.
licenseType	The top-level category of license Mesh will verify, for example homeServices. To understand permissible licenseType values, work with your customer success representative.
licenseSubType	The specific license type Mesh will verify, such as electrician. To understand permissible licenseSubType values, work with your customer success representative.
jurisdiction	A two-character standard State abbreviation for the administrative area that issued the license. Mesh supports professional license verification in all 50 US states, Puerto Rico and the District of Columbia.

When Mesh has completed the verification, Mesh will return the specific outputResults for each vsku. For our standard professional license vsku, these are:

outputResult	Description
licenseIdentifier	The verified license number or identifier assigned to the professional license Mesh has verified. The result may be different to the claim.
licenseeName	The verified name of the person or business to whom the license was issued. The result may be different to the claim.
licenseType	The top-level category of license that Mesh verified, for example homeServices. The result will be the same as the claim.
licenseTypeAsIs	The specific license type that Mesh found on the verified license, using the particular terminology of the licensing authority, which will vary from jurisdiction to jurisdiction.
licenseStatus	A normalized value across all license types and jurisdictions. Either ACTIVE if the license is valid or INACTIVE if the license is expired or in some other negative status.
licenseStatusAsIs	The specific status found on the license according to the licensing authority's terminology.
licenceExpirationDate	The date on which the license expires.
licenseIssuedDate	If available, the date on which the licensing authority issued the license. Not all licensing authorities maintain this data.
jurisdiction	The administrative area in which the license is issued. This will be the same as the claim.

Query: getVowConfig

query GetVowConfig($vowId: String!){
                getVowConfig(vowId: $vowId){
                    # We now ask the API to return the inputClaims and outputResults for the professional license vsku
                    vowId
                    items{
                        vskuId
                        vspecId
                        isRepeatable
                        isRequired
                        vsku{
                            inputClaims
                            outputResults
                        }
                    }
                }
            }
            
            

Example Code Snippet

curl \
--location 'https://app.mesh.id/graphql' \
--header 'Content-Type: application/json' \
--data '{"query":"query GetVowConfig($vowId: String!){\r\n getVowConfig(vowId: $vowId){\r\n vowId\r\n items{\r\n vskuId\r\n vspecId\r\n isRepeatable\r\n isRequired\r\n vsku{\r\n inputClaims\r\n outputResults\r\n }\r\n }\r\n }\r\n}","variables":{"vowId":"86506334-46ff-4933-85de-4b858c126ab1"}}'

Response

{
  "data": {
    "getVowConfig": {
      "vowId": "86506334-46ff-4933-85de-4b858c126ab1",
      "items": [
        {
          "vskuId": "v-pro-license@1.0",
          "vspecId": "11fb7baf-7027-4a74-9ff5-f3576e539703",
          "isRepeatable": true,
          "isRequired": true,
          "vsku": {
            "inputClaims": [
              "licenseIdentifier",
              "jurisdiction",
              "licenseeName",
              "licenseCategory",
              "licenseType"
            ],
            "outputResults": [
              "licenseIdentifier",
              "jurisdiction",
              "licenseeName",
              "licenseCategory",
              "licenseTypeAsIs",
              "licenseStatus",
              "licenseStatusAsIs",
              "licenseExpirationDate",
              "licenseIssuedDate"
            ]
          }
        }
      ]
    }
  }
}

Now that we know the vow and vsku concepts, we can begin preparing to submit a verification.

A vow must be related to the entity that Mesh will verify. We call this the Business Entity rather than a business because not every subject of a Mesh verification is actually a business. For example, many electricians and plumbers that Circle Home must verify are sole proprietors carrying licenses in their own name. Mesh supports two methods to define the business entity:

1. Create a Business Entity as a separate step: This method is helpful for customers that wish to define business entities in Mesh ahead of submitting verifications for that entity.
2. Create a Business Entity in line with creating a verification order: This is a more common pattern, and reduces the number of API calls customers must make to submit an order.

This quick start guide will use the first, longer method to demonstrate the process of creating a business entity. However, the same parameters used in this step can be used inline with the verification order creation.

Let's take a look at the RequestBusiness step.

RequestBusiness

When we create a Business Entity we have a few options for how to define the entity.

1. We can provide an email address (which will also be used to send notifications), which may be flagged as a pre-verified email address (skipping a one-time-passcode challenge).
2. We can provide one or more aliases, such as Circle Home's unique internal identifier for the business.

Parameter	Description
emailAddress	The email address used by the Professional for authentication and notifications.
preverifiedEmail	Tells Mesh that you have verified that the Professional possesses the email address. If true, Mesh will skip email verification. If false, Mesh will send a one-time passcode (OTP) to the Professional's email to verify possession. If the Professional has pre-existing data in Mesh systems, due to being verified previously by Mesh, we will always ask for a one-time passcode regardless of this setting, to prevent unauthorized access to sensitive data.
aliases	An array of aliases that the customer wishes to assign to the business entity, such as an internal identifier. Aliases have a namespace and an identifier.

IMPORTANT: You must only set the preverifiedEmail flag to true if you can guarantee that the business entity is in possession of the email address. Anyone with the correct URL can imitate an end user and submit a verification fraudulently if email verification is skipped.

The response contains the businessId that uniquely identifies the Business in the Mesh network. You will need to use this when creating the vow.

Mutation: requestBusiness

mutation requestBusiness($input: RequestBusinessInput!) {
    requestBusiness(input: $input) {
        businessId
        aliases {
            namespace
            identifier
        }
    }
}

Input

{
  "emailAddress": "user@businessentity.com",
  "preverifiedEmail": false,
  "aliases": [{
    "namespace": "circleHomeId",
    "identifier": "1234567890"
  }]
}

Example Code Snippet

curl \
--location 'https://app.mesh.id/graphql' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation RequestBusiness($input: RequestBusinessInput!) {\r\n requestBusiness(input: $input){\r\n businessId\r\n }\r\n}","variables":{"input":{"emailAddress":"user@businessentity.com","preverifiedEmail":false,"aliases":[{"namespace":"circleHomeId","identifier":"1234567890"}]}}}'

Response

{
  "data": {
    "requestBusiness": {
      "businessId": "24ecf72d-bee7-4c78-a94e-0b6709fd3ee5"
    }
  }
}

Mesh supports many channels for customers to receive updates about their verification orders. You can configure Mesh to send updates by email, Slack, SMS, and webhook.

You can configure each channel to receive only certain notification types. For example, you might configure the webhook channel to receive all notifications but configure an email channel to receive only negative outcome notifications, such as a business failing validation.

For our quick-start example, the Circle Home developer will configure two channels: (1) an email notification channel and (2) a webhook channel for programmatic updates. The webhook will receive notifications when Mesh completes a verification order workflow and when Mesh detects a change in status through continuous monitoring, such as a license expiring.

updateNotifications

Our Circle developer uses updateNotifications to modify their notifications. Every use of updateNotifications will overwrite any previous settings configuration.

Our example configures two notification channels that will receive verificationResultsUpdated notifications, one for email and one for webhooks. The API also supports Slack and SMS.

Let's examine the $input parameters:

Field	Description
notificationChannel	Required. An enum value for the channel, one of EMAIL, SLACK, SMS, or WEBHOOK.
notificationTypes	Required. A list of enum values for all of the notification types that will be sent to this channel. The example specifies just one type for both channels, verificationResultsUpdated, which is generated every time any change is registered for a vow. Work with your customer success representative to understand notification types in more detail.
phoneNumber	For SMS notifications only
emailAddress	For email notifications only. The email address that will receive the notification.
hookUrl	For webhooks only. The URL to which Mesh should send a webhook notification.
channel	For Slack notifications only. The Slack channel to which notifications will be sent.
secret	Optional, for webhooks only. A secret that you can provide to help prevent DDOS attacks on your webhook endpoint.
timezone	Required. The timezone that Mesh will use for any time stamps in the notifications.

Mutation: updateNotifications

mutation UpdateNotification($input: NotificationInput!) {
    updateNotification(input: $input) {
        notifications {
            notificationTypes
            emailAddress
            hookUrl
            secret
        }
        timezone
    }
}

Input

{
              "input": {
                "notifications": [
                  {
                    "emailAddress": "mesh+updates@circle.com",
                    "notificationChannel": "EMAIL",
                    "notificationTypes": "verificationResultsUpdated"
                  },
                  {
                    "notificationChannel": "WEBHOOK",
                    "notificationTypes": "verificationResultsUpdated",
                    "hookUrl": "my-webhook-endpoint.circle.com"
            
                  }
                ],
                "timezone": "America/Los_Angeles"
              }
            }
            

Example Code Snippet

curl \
--location 'https://app.mesh.id/graphql' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation UpdateNotification($input: NotificationInput!) {\r\n updateNotification(input: $input) {\r\n notifications {\r\n notificationTypes\r\n emailAddress\r\n hookUrl\r\n secret\r\n }\r\n timezone\r\n }\r\n}","variables":{"input":{"notifications":[{"emailAddress":"mesh+updates@circle.com","notificationChannel":"EMAIL","notificationTypes":"verificationResultsUpdated"},{"notificationChannel":"WEBHOOK","notificationTypes":"verificationResultsUpdated","hookUrl":"my-webhook-endpoint.circle.com"}],"timezone":"America/Los_Angeles"}}}'

Response

{
  "data": {
    "updateNotification": {
      "notifications": [
        {
          "notificationTypes": [
            "verificationResultsUpdated"
          ],
          "emailAddress": "mesh+updates@circle.com",
          "hookUrl": null,
          "secret": null
        },
        {
          "notificationTypes": [
            "verificationResultsUpdated"
          ],
          "emailAddress": null,
          "hookUrl": "my-webhook-endpoint.circle.com",
          "secret": null
        }
      ],
      "timezone": "America/Los_Angeles"
    }
  }
}

Let's recap where our Circle developer is:

• They now know about the vow configurations and vsku requirements available to them.

• They have created a businessId for the Business they wish to verify.

• They have registered email and webhook notifications ready to receive updates as Mesh fulfills the vow.

They are now ready to create a verification order workflow.

Using Mesh's One-Click User Interface

The recommended method to create a vow is to use Mesh's One-Click Verify user interface. If you wish to use your own user interface, please skip to Step 5b.

The Mesh One-Click Verify user interface is optimized for conversion and accuracy, is mobile-ready and internationalized. The user interface is dynamically generated based on the vow configuration, and the result of careful user interaction monitoring from every verification flow ever performed across all of Mesh's customer base.

We've created a small library that you can utilize to display an overlay and launch a pop-up window with the Mesh One-Click Verify user interface.

The library is located at https://verify-ui.mesh.id/assets/mesh-verification.js and will create a global function init_mesh_verification that can be used to launch the One-Click Verify user interface.

It takes an object with the following properties:

• target - 'string' - What 'vowId' or 'alias' to launch for the One-Click Verify user interface.
• linkType - 'alias' | 'vowId' - Optional value to control the type of the 'target' parameter. Defaults to 'vowId'
• id - 'string' - Optional 'businessId' value to pre-fill the authentication for a 'businessId'
• useOverlay - 'boolean' - Optional value to display the overlay on your webpage while the popup is displayed. Defaults to 'true'
• onEvent - 'function' - Event handler that is invoked when milestones occur during the verification process.

onEvent types

Each invoke of the 'onEvent' function will receive an object with a 'event' and 'data' property. The following events can be emitted:

• page_opened - emitted when the popup is first loaded. No properties exist in the 'data' object.
• verification_complete - emitted when the user complete the verification. The 'data' object has the following properties - orderId, businessId and status.
• page_closed - emitted when the popup is closed. No properties exist in the 'data' object.

Example

You can launch the One-Click Verify user interface from the desired location in your online experience with the following Javascript:

const MESH_SCRIPT_SRC = 'https://verify-ui.mesh.id/assets/mesh-verification.js';
            const target = '86506334-46ff-4933-85de-4b858c126ab1'
            // supports 'alias' or 'vowId'
            const linkType = 'vowId'
            // optional parameter to identify the user
            const businessId = '24ecf72d-bee7-4c78-a94e-0b6709fd3ee5'
            const meshParams = {
              target,
              linkType,
              id: businessId,
              useOverlay: true,
              onEvent({ event, data }) {
                console.log('got event', event, data);
              },
            }
            
            let meshScriptLoaded = false
            if (!meshScriptLoaded) {
              let script = document.createElement('script');
              script.onload = function() {
                meshScriptLoaded = true;
                init_mesh_verification(meshParams);
              };
              script.src = MESH_SCRIPT_SRC;
              document.head.appendChild(script);
            } else {
              init_mesh_verification(meshParams);
            }
            

Mesh Hosted Solution

We also support a hosted version of our One-Click Verify form. Mesh will create a customer-friendly URL, known as an alias, including your company's brand and logo, and host your verification workflow for you. The URL will be of the form:

https://verify-ui.mesh.id/a/{your-company-name}/{any-desired-alias}

Each URL represents a different verification flow, auto-generated from the vow configuration behind it. You can have as many hosted workflows as you wish. Direct your end-users to the URL, and Mesh will take care of the rest.

You can create your own hosted URLs using the createVowAlias mutation.

After Launching the User Interface

Your Business end-user will complete the verification workflow using Mesh's dynamic user interface, submitting the vow to Mesh with no work on your part.

Skip to Step 6 to listen for Webhook updates and retrieve vow results.

Let's recap where our Circle developer is:

• We now know about the vow configurations and vsku requirements available to us.

• We have created a businessId for the Business we wish to verify.

• We have registered email and webhook notifications ready to receive updates as Mesh fulfills the vow.

We are now ready to create a verification order workflow.

We recommend using Mesh's One-Click Verify user interface (see Step 5a). However, you can also build your own user interface and create your vow with our API.

Creating a Verification Order

Our Circle developer is now ready to create an instance of a vow (place an order).

The submitWorkflowVerification request utilizes the identifiers we retrieved and examined in the previous steps. It also includes the specific claims the business entity asserts that Mesh will verify.

In the example provided, the business entity has submitted only one professional license vsku.

Field	Description
vowId	Required. Specifies the Verification Order Workflow Configuration to use for the order. We obtained this value in Step 2 for Circle Home. Work with your customer success representative to understand the Verification Order Workflow configurations available.
businessId	Required. Specifies the Business entity obtained in Step 3 that is the subject of the Verification Order Workflow.
items	Required: An array containing individual vsku verification objects. In our Circle Home example, the professional license vow only allows one or more professional license verification vsku items.

Each item in the array is specified as follows:

Field	Description
vspecId	Required. The identifier for the specific vsku you are requesting. Again, in the Circle Home example, the vow allows only one or more standard professional license vsku items. Other vow designs allow different vsku definitions.
claims	Required. Refers to the claims we explored in Step 2. The Circle developer will populate the claims provided by the professional here.
jurisdication	Required. The administrative area that applies to the license. Currently, Mesh only supports US state-level verification (including Puerto Rico and the District of Columbia).

The Mesh API returns the following:

Field	Description
errorMessages	Any error messages relevant to a failed submission.
successful	If true, the verification order has been submitted successfully and is being processed.
order	Contains information about the order itself after submission.

The order information includes the following:

Field	Description
orderId	A unique identifier for the order. We will need this later to retrieve order updates when we receive a webhook notification. Note that the webhook notification will tell you which orderId Mesh has updated so there is no need to persist this value other than for your logging and audit purposes.
orderStatus	The status of the order. On initial successful creation, the order will most likely be in awaitingInventory status. We explore status codes below in Get Order.

Mutation: submitWorkflowVerification

mutation CreateOrder($input: WorkflowVerificationInput) {
                submitWorkflowVerification(input: $input) {
                    errorMessages
                    successful
                    order {
                        orderId
                        orderStatus
                    }
                }
            }
            
            

Input

{
  "input": {
    "vowId": "86506334-46ff-4933-85de-4b858c126ab1",
    "businessId": "24ecf72d-bee7-4c78-a94e-0b6709fd3ee5",
    "items": [
      {
        "vspecId": "11fb7baf-7027-4a74-9ff5-f3576e539703",
        "claims": [
          {
            "name": "licenseType",
            "value": "plumbers"
          },
          {
            "name": "licenseeName",
            "value": "Bob's Builders"
          },
          {
            "name": "jurisdiction",
            "value": "IA"
          },
          {
            "name": "licenseIdentifier",
            "value": "123456"
          }
        ],
        "jurisdiction": "IA"
      }
    ]
  }
}

Example Code Snippet

curl \
--location 'https://app.mesh.id/graphql' \
--header 'Content-Type: application/json' \
--data '{"query":"mutation CreateOrder($input: WorkflowVerificationInput) {\r\n submitWorkflowVerification(input: $input) {\r\n errorMessages\r\n successful\r\n order {\r\n orderId\r\n orderStatus\r\n }\r\n }\r\n}\r\n","variables":{"input":{"vowId":"86506334-46ff-4933-85de-4b858c126ab1","professionalId":"24ecf72d-bee7-4c78-a94e-0b6709fd3ee5","items":[{"vspecId":"11fb7baf-7027-4a74-9ff5-f3576e539703","claims":[{"name":"licenseSubtype","value":"plumbers"},{"name":"licenseeName","value":"Bob'\''s Builders"},{"name":"jurisdiction","value":"IA"},{"name":"licenseIdentifier","value":"123456"}],"jurisdiction":"IA"}]}}}'

Response

{
  "data": {
    "submitWorkflowVerification": {
      "errorMessages": [],
      "successful": true,
      "order": {
        "orderId": "f245337f-420a-4407-aa8d-336e4d019a8b",
        "orderStatus": "awaitingInventory"
      }
    }
  }
}

Now that the vow has been created and submitted, Mesh will begin to fulfill the order.

Our Circle Home developer created webhook registrations in Step 4, and their system is waiting for updates.

As a security precaution, the webhook payload contains no usable data about the verification. When you receive the webhook notification, use the targetId contained to retrieve the current status of the vow as follows.

Get Workflow Order

You can retrieve the details of a Verification Order Workflow at any point after creation. You will typically do this in response to a webhook notification.

An order may not be complete depending on the time required to perform a validation. The following status codes describe the state of the Verification Order Workflow:

Status	Definition
awaitingInventory	Newly created orders are awaitingInventory. Inventory is Mesh's term for factual data, records, and other assets that Mesh retrieves to perform verifications. Mesh needs more factual data for the system to begin the verification process.
awaitingAdjudication	Mesh has sourced all required factual data, and the order verification process has started.
complete	The Verification Order Workflow is complete.
monitoring	If you have specified ongoing monitoring, a completed Verification Order Workflow will enter this status after being completed.

The top-level information in the Get Order response contains information about the vow itself:

Field	Description
orderId	The unique identifier representing the vow that we used to retrieve the status.
orderStatus	See above.
labels	These represent the business outcome determined by the vow policy. The standard professional license verification vow policy requires that all professional licenses have a normalized ACTIVE status and have no name or license number mismatches. In the example, we see the policy applied a label approved. All of this Professional's licenses have passed validation.

Each vsku item in the vow also contains (1) the result fields we explored in Step 2, and (2) labels that apply to the vsku itself.

In the example, the professional license vsku returned with the label professional_license_verified, indicating that the license is valid and can be trusted.

Query: getWorkflowVerification

query GetOrder($orderId: ID!) {
    getWorkflowVerification(orderId: $orderId) {
        orderId
        orderStatus
        labels
        orderCreationTime
        businessId
        items {
            itemStatus
            jurisdiction
            labels
            vsku
            vspecId
            results {
                name
                value
            }
            claims {
                name
                value
            }
        }
    }
}

Example Code Snippet

curl --location 'https://app.mesh.id/graphql' \
--header 'Content-Type: application/json' \
--data '{"query":"query GetOrder($orderId: ID!) {\r\n  getWorkflowVerification(orderId: $orderId) {\r\n orderId\r\n orderStatus\r\n labels\r\n  orderCreationTime\r\n businessId\r\n items {\r\n itemStatus\r\n jurisdiction\r\n labels\r\n  vsku\r\n  vspecId\r\n results {\r\n name\r\n value\r\n }\r\n claims {\r\n  name\r\n value\r\n }\r\n  }\r\n }\r\n}\r\n","variables":{"orderId":"f245337f-420a-4407-aa8d-336e4d019a8b"}}'

Response

{
  "data": {
    "getWorkflowVerification": {
      "orderId": "f245337f-420a-4407-aa8d-336e4d019a8b",
      "orderStatus": "complete",
      "labels": [
        "approved"
      ],
      "vowId": "15ac183c-9e64-4329-8a2c-ca3a84a6dbbe",
      "userId": "4bf48e80-0d18-4929-b3f0-38107c8661f2",
      "customerProfessionalId": null,
      "items": [
        {
          "itemStatus": "requested",
          "jurisdiction": "IA",
          "labels": [
            "professional_license_verified"
          ],
          "vsku": "v-pro-license-sandbox@1.0",
          "vspecId": "41b88699-8f06-4091-bd02-0fb34c3aa016",
          "results": [
            {
              "name": "licenseeName",
              "value": "Joes Plumbing"
            },
            {
              "name": "licenseIdentifier",
              "value": "123456"
            },
            {
              "name": "licenseCategory",
              "value": "homeServices"
            },
            {
              "name": "licenseTypeAsIs",
              "value": "Plumber"
            },
            {
              "name": "jurisdiction",
              "value": "IA"
            },
            {
              "name": "licenseStatus",
              "value": "Active"
            },
            {
              "name": "licenseStatusAsIs",
              "value": "Active"
            },
            {
              "name": "licenseExpirationDate",
              "value": "1698117758517"
            },
            {
              "name": "licenseIssuedDate",
              "value": "1692933758517"
            }
          ],
          "claims": [
            {
              "name": "licenseType",
              "value": "plumbers"
            },
            {
              "name": "licenseeName",
              "value": "Joes Plumbing"
            },
            {
              "name": "jurisdiction",
              "value": "IA"
            },
            {
              "name": "licenseIdentifier",
              "value": "123456"
            },
            {
              "name": "licenseCategory",
              "value": "homeServices"
            }
          ]
        }
      ]
    }
  }
}

This quick start guide has introduced you to the key concepts you need to understand, and the corresponding API calls needed to work with them. We have discussed:

• Verification Order Workflows (vow)- the core concept behind Mesh that describes the number and type of verifications to be performed for a single Professional

• Verification Store Keeping Unit (vsku) - an individual verification that is part of a vow.

• Professional - the business or individual that Mesh will verify, and will be the subject of a vow.

• How to create a vow using Mesh's One-Click Verify user interface (recommended), or through a customer-built user interface and using Mesh's API.

• How to subscribe to webhook updates, and call Mesh to get vow updates.

That's all you need to know! Everything else is a variation on the theme. Your required vow configuration might have different vsku items, with different policies, and different notifications, but the principles are the same.

As always support@mesh.id is here to help you.

Sandbox Functional Documentation

Introduction

The sandbox is a simulated environment designed to test various verification processes without affecting real data. It processes different types of events such as professional licenses, business risk verifications, insurance policies, and business presence on various platforms. Each scenario within these cases triggers specific actions and generates corresponding results and labels.

Case: Professional License

This case involves verifying professional licenses based on the license identifier provided. The license identifier can be one of the following:

Scenario 1: License Not Found

If the license identifier is "notfound", this will result in the item being marked as not found, and the label professional_license_not_found will be added.

Scenario 2: Invalid License

If the license identifier is "invalid", this will complete the item as matched but with inactive license details and specific dates.

Scenario 3: License Number Mismatch

If the license identifier is "numbermismatch", this will complete the item as matched but with a license_number_mismatch_minor label.

Scenario 4: Valid License

If the license identifier has other value, this will complete the item as matched with all complete license details and no additional labels.

Case: Business Verification

This case involves verifying business details based on the business name provided. The business name can be one of the following:

Scenario 1: Business Not Found

If the business name is "notfound", this will complete the item as not found. If the business name has other value, this will complete the item as matched with all complete business details and no additional labels.

Scenario 2: Business Name Mismatch

If the business name is "namemismatch", this will complete the item as matched with business details and add the label business_name_mismatch_minor.

Scenario 3: Valid Business Name

If the business name has other value, this will complete the item as matched with all complete business details and no additional labels.

Case: Business Risk Verification

This case involves verifying business details based the business name provided.

Liens

• If the business name includes the word "lien", a lien record will be generated with details such as type, jurisdiction, status, filing date, liability, and collateral.

Bankruptcies

• If the business name includes the word "bankrupt", a bankruptcy record will be generated with details such as filing date, jurisdiction, chapter, debtors, and case updates.

Litigations

• If the business name includes the word "litigation", a litigation record will be generated with details such as filing date, jurisdiction, status, judgments, case name, case type, and party type.

After add the corresponding record, the evaluation will be completed with the corresponding labels related to the issues detected.

Case: Insurance

This case involves generating insurance policies based on the email prefix of the insurance agent.

Scenario: Generate Insurance Policy

Based on the email prefix of the insurance agent, the insurance policy will be generated with a specific status and the item will be marked as matched. Here are the email prefixes and their corresponding statuses:

• COMPLIANCE_ISSUE: Prefix "compliance_issue"
• REQUIRES_REVIEW: Prefix "requires_review"
• EXPIRING: Prefix "expiring"
• EXPIRED: Prefix "expired"
• PENDING_CANCELLATION: Prefix "pending_cancellation"
• CANCELED: Prefix "canceled"
• UNKNOWN: Prefix "unknown"
• COMPLIANT: Any other prefix not listed above

Case: Business Presence

This case involves verifying the presence of a business on various platforms based on the business name provided.

Scenario 1: Business Not Found

If the business name is "notfound", this will complete the item as not found.

Scenario 2: Valid Business

If the business name has other value, this will complete the item as matched with all complete business details.