Mesh API Documentation

Our vision at Mesh is to be the easiest and most trusted business identity provider on the internet. These developer documents are designed to make it as easy as possible for you to get started working with our APIs. We recommend starting with our one-hour Quick Start Guide that will take you through the core Mesh concepts you'll need to understand. If you have any questions, please reach out to us at support@mesh.id. We're here to help.

Contact

Mesh Customer Support

support@mesh.id

API Endpoints
https://app.mesh.id/graphql
Headers
# An API key should be passed as an Authorization header
Authorization: <YOUR_TOKEN_HERE>

Mesh - The Short Version

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.

About This Documentation

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.

Quick Start Guide - Professional License Verification

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

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.

Step 1 - Testing the API Key (5 mins)

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"
                    }
                ]
            }
        }
    }
}

Step 2 - Exploring the VOW (15 mins)

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"
            ]
          }
        }
      ]
    }
  }
}

Step 3 - Create Business (5 mins)

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"
    }
  }
}

Step 4 - Register Webhook (5 mins)

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"
    }
  }
}

Step 5a - Initiate the Mesh One-Click Verify User Interface (5 mins)

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.

Step 5b - Create VOW (10 mins)

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"
      }
    }
  }
}

Step 6 - Listen for Webhooks and Get Results (10 mins)

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"
            }
          ]
        }
      ]
    }
  }
}

Conclusion (2 mins)

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.

Appendix A: Sandbox (5 mins)

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.

Queries

getBusiness

Description

Retrieve a business entity i.e. the subject of Mesh verifications.

Response

Returns a Business

Arguments
Name Description
businessId - ID!

Example

Query
query getBusiness($businessId: ID!) {
  getBusiness(businessId: $businessId) {
    businessId
    aliases {
      ...BusinessAliasFragment
    }
  }
}
Variables
{"businessId": "4"}
Response
{
  "data": {
    "getBusiness": {
      "businessId": 4,
      "aliases": [BusinessAlias]
    }
  }
}

getBusinessByAlias

Description

Retrieve a business entity i.e. the subject of Mesh verifications using an alias.

Response

Returns a Business

Arguments
Name Description
namespace - String!
identifier - String!

Example

Query
query getBusinessByAlias(
  $namespace: String!,
  $identifier: String!
) {
  getBusinessByAlias(
    namespace: $namespace,
    identifier: $identifier
  ) {
    businessId
    aliases {
      ...BusinessAliasFragment
    }
  }
}
Variables
{
  "namespace": "abc123",
  "identifier": "xyz789"
}
Response
{
  "data": {
    "getBusinessByAlias": {
      "businessId": 4,
      "aliases": [BusinessAlias]
    }
  }
}

getCustomer

Description

Retrieve the details of a customer using the UUID customerId.

Response

Returns a Customer

Arguments
Name Description
customerId - ID!

Example

Query
query getCustomer($customerId: ID!) {
  getCustomer(customerId: $customerId) {
    customerId
    status
    customerName
    customerUrl
    customerLogo
    entitlements
    vows {
      ...VowConfigFragment
    }
  }
}
Variables
{"customerId": 4}
Response
{
  "data": {
    "getCustomer": {
      "customerId": "4",
      "status": "ACTIVE",
      "customerName": "abc123",
      "customerUrl": "abc123",
      "customerLogo": "xyz789",
      "entitlements": ["abc123"],
      "vows": [VowConfig]
    }
  }
}

getDocumentation

Response

Returns a String

Arguments
Name Description
docPath - String!

Example

Query
query getDocumentation($docPath: String!) {
  getDocumentation(docPath: $docPath)
}
Variables
{"docPath": "abc123"}
Response
{"data": {"getDocumentation": "abc123"}}

getUser

Description

Retrieve the details of a specific User within your account.

Response

Returns a User

Arguments
Name Description
userId - ID!

Example

Query
query getUser($userId: ID!) {
  getUser(userId: $userId) {
    userId
    customerId
    customer {
      ...CustomerFragment
    }
    emailAddress
    status
    role
    allowEditing
    fullName
    firstName
    lastName
  }
}
Variables
{"userId": 4}
Response
{
  "data": {
    "getUser": {
      "userId": "4",
      "customerId": "4",
      "customer": Customer,
      "emailAddress": "xyz789",
      "status": "INVITED",
      "role": "ADMIN",
      "allowEditing": true,
      "fullName": "xyz789",
      "firstName": "xyz789",
      "lastName": "abc123"
    }
  }
}

getVowAlias

Description

Get a specific VowAlias using the alias string.

Response

Returns a VowAliasCreateResult

Arguments
Name Description
alias - String!

Example

Query
query getVowAlias($alias: String!) {
  getVowAlias(alias: $alias) {
    alias
    vowId
    customerId
  }
}
Variables
{"alias": "abc123"}
Response
{
  "data": {
    "getVowAlias": {
      "alias": "xyz789",
      "vowId": "abc123",
      "customerId": "abc123"
    }
  }
}

getVowConfig

Description

Get a specific vowConfig by ID

Response

Returns a VowConfig

Arguments
Name Description
vowId - String!

Example

Query
query getVowConfig($vowId: String!) {
  getVowConfig(vowId: $vowId) {
    vowId
    vowConfigId
    description
    items {
      ...VowConfigItemFragment
    }
    redirectSettings {
      ...RedirectFragment
    }
  }
}
Variables
{"vowId": "xyz789"}
Response
{
  "data": {
    "getVowConfig": {
      "vowId": "abc123",
      "vowConfigId": "abc123",
      "description": "xyz789",
      "items": [VowConfigItem],
      "redirectSettings": Redirect
    }
  }
}

getWorkflowVerification

Description

Retrieve the details of a specific verification workflow order using its UUID orderId. This query is commonly used in response to a Mesh webhook notification that the status of a verification order has changed.

Response

Returns a WorkflowVerification

Arguments
Name Description
orderId - ID!

Example

Query
query getWorkflowVerification($orderId: ID!) {
  getWorkflowVerification(orderId: $orderId) {
    orderId
    vowId
    businessId
    userId
    items {
      ...VerificationSpecFragment
    }
    orderStatus
    labels
    title
    jurisdictions
    orderCreationTime
    lastUpdatedTime
    orderCompletionTime
  }
}
Variables
{"orderId": "4"}
Response
{
  "data": {
    "getWorkflowVerification": {
      "orderId": "4",
      "vowId": "4",
      "businessId": "4",
      "userId": 4,
      "items": [VerificationSpec],
      "orderStatus": "awaitingInventory",
      "labels": ["abc123"],
      "title": "xyz789",
      "jurisdictions": ["xyz789"],
      "orderCreationTime": AWSTimestamp,
      "lastUpdatedTime": AWSTimestamp,
      "orderCompletionTime": AWSTimestamp
    }
  }
}

listNotifications

Description

Lists the currently configured notifications for a user. Results are paginated.

Response

Returns a ListNotificationResults!

Arguments
Name Description
search - ListNotificationInput
pagination - ContinuationInput

Example

Query
query listNotifications(
  $search: ListNotificationInput,
  $pagination: ContinuationInput
) {
  listNotifications(
    search: $search,
    pagination: $pagination
  ) {
    nextContinuation
    notifications {
      ...NotificationFragment
    }
  }
}
Variables
{
  "search": ListNotificationInput,
  "pagination": ContinuationInput
}
Response
{
  "data": {
    "listNotifications": {
      "nextContinuation": "xyz789",
      "notifications": [Notification]
    }
  }
}

listUsers

Description

List the Users within your account.

Response

Returns [User!]

Example

Query
query listUsers {
  listUsers {
    userId
    customerId
    customer {
      ...CustomerFragment
    }
    emailAddress
    status
    role
    allowEditing
    fullName
    firstName
    lastName
  }
}
Response
{
  "data": {
    "listUsers": [
      {
        "userId": "4",
        "customerId": "4",
        "customer": Customer,
        "emailAddress": "xyz789",
        "status": "INVITED",
        "role": "ADMIN",
        "allowEditing": false,
        "fullName": "abc123",
        "firstName": "abc123",
        "lastName": "abc123"
      }
    ]
  }
}

listVowConfigs

Description

List the available vowConfigs for the current customer.

Response

Returns [VowConfig]

Example

Query
query listVowConfigs {
  listVowConfigs {
    vowId
    vowConfigId
    description
    items {
      ...VowConfigItemFragment
    }
    redirectSettings {
      ...RedirectFragment
    }
  }
}
Response
{
  "data": {
    "listVowConfigs": [
      {
        "vowId": "xyz789",
        "vowConfigId": "abc123",
        "description": "xyz789",
        "items": [VowConfigItem],
        "redirectSettings": Redirect
      }
    ]
  }
}

queryWorkflowVerifications

Description

Search for a list of verification workflow orders using one or more search terms. Note that retrieving items for the orders will take longer than omitting that value.

Response

Returns a QueryWorkflowVerifications!

Arguments
Name Description
search - QueryWorkflowVerificationInput!

Example

Query
query queryWorkflowVerifications($search: QueryWorkflowVerificationInput!) {
  queryWorkflowVerifications(search: $search) {
    orders {
      ...WorkflowVerificationFragment
    }
    pagination {
      ...PaginationFragment
    }
  }
}
Variables
{"search": QueryWorkflowVerificationInput}
Response
{
  "data": {
    "queryWorkflowVerifications": {
      "orders": [WorkflowVerification],
      "pagination": Pagination
    }
  }
}

validateInvite

Description

Mesh-only internal query used for customer user onboarding.

Response

Returns an Invite

Arguments
Name Description
inviteId - ID

Example

Query
query validateInvite($inviteId: ID) {
  validateInvite(inviteId: $inviteId) {
    inviteId
    inviteStatus
    inviteExpiration
    emailAddress
    userId
    customer {
      ...CustomerFragment
    }
  }
}
Variables
{"inviteId": 4}
Response
{
  "data": {
    "validateInvite": {
      "inviteId": "4",
      "inviteStatus": "VALID",
      "inviteExpiration": AWSTimestamp,
      "emailAddress": "abc123",
      "userId": "xyz789",
      "customer": Customer
    }
  }
}

viewApiKeys

Description

Retrieve a list of API keys for this Customer. Note that the API secret cannot be viewed after creation, and is not returned.

Response

Returns [ApiKeyResult]!

Arguments
Name Description
input - ViewKeysInput

Example

Query
query viewApiKeys($input: ViewKeysInput) {
  viewApiKeys(input: $input) {
    apiKeyId
    name
    status
    message
  }
}
Variables
{"input": ViewKeysInput}
Response
{
  "data": {
    "viewApiKeys": [
      {
        "apiKeyId": "4",
        "name": "xyz789",
        "status": "active",
        "message": "abc123"
      }
    ]
  }
}

whoami

Description

The whoami query is a convenient way to retrieve fundamental information about your User, the associated Customer, and the verification order workflow (VOW) configurations set up for your account.

Response

Returns a User!

Example

Query
query whoami {
  whoami {
    userId
    customerId
    customer {
      ...CustomerFragment
    }
    emailAddress
    status
    role
    allowEditing
    fullName
    firstName
    lastName
  }
}
Response
{
  "data": {
    "whoami": {
      "userId": 4,
      "customerId": 4,
      "customer": Customer,
      "emailAddress": "abc123",
      "status": "INVITED",
      "role": "ADMIN",
      "allowEditing": true,
      "fullName": "xyz789",
      "firstName": "abc123",
      "lastName": "abc123"
    }
  }
}

Mutations

cancelVerifactionOrder

Response

Returns a CancelVerificationOrderResult!

Arguments
Name Description
input - CancelVerificationOrderInput

Example

Query
mutation cancelVerifactionOrder($input: CancelVerificationOrderInput) {
  cancelVerifactionOrder(input: $input) {
    successful
    errorMessages
  }
}
Variables
{"input": CancelVerificationOrderInput}
Response
{
  "data": {
    "cancelVerifactionOrder": {
      "successful": false,
      "errorMessages": ["xyz789"]
    }
  }
}

createApiKey

Description

Create a new API key. Note that the API secret key can only be viewed during creation.

Response

Returns a CreateKeyResult!

Arguments
Name Description
input - NamedKeyInput!

Example

Query
mutation createApiKey($input: NamedKeyInput!) {
  createApiKey(input: $input) {
    name
    key
    apiKeyId
  }
}
Variables
{"input": NamedKeyInput}
Response
{
  "data": {
    "createApiKey": {
      "name": "xyz789",
      "key": "xyz789",
      "apiKeyId": "xyz789"
    }
  }
}

createBusinessAlias

Description

Create a new BusinessAlias for a Business entity.

Response

Returns a Business!

Arguments
Name Description
businessId - ID!
alias - BusinessAliasInput!

Example

Query
mutation createBusinessAlias(
  $businessId: ID!,
  $alias: BusinessAliasInput!
) {
  createBusinessAlias(
    businessId: $businessId,
    alias: $alias
  ) {
    businessId
    aliases {
      ...BusinessAliasFragment
    }
  }
}
Variables
{
  "businessId": "4",
  "alias": BusinessAliasInput
}
Response
{
  "data": {
    "createBusinessAlias": {
      "businessId": "4",
      "aliases": [BusinessAlias]
    }
  }
}

createVowAlias

Description

Create a new VowAlias for an existing VOW. An alias is a custom URL that a customer may define that points to one of the customer's vowIds (verification order workflow design). The alias must be unique across all customers, and this operation will fail if the alias is already in use.

Response

Returns a String

Arguments
Name Description
input - VowAliasCreateInput!

Example

Query
mutation createVowAlias($input: VowAliasCreateInput!) {
  createVowAlias(input: $input)
}
Variables
{"input": VowAliasCreateInput}
Response
{"data": {"createVowAlias": "xyz789"}}

createVowConfig

Description

Mesh use only. Creates a new verification order workflow. VowConfig assembly is currently not self-service and is performed by Mesh. A self-service product is planned for the future.

Response

Returns a String

Arguments
Name Description
input - VowConfigInput!

Example

Query
mutation createVowConfig($input: VowConfigInput!) {
  createVowConfig(input: $input)
}
Variables
{"input": VowConfigInput}
Response
{"data": {"createVowConfig": "abc123"}}

deleteBusinessAlias

Description

Delete a BusinessAlias from a Business entity.

Response

Returns a Business!

Arguments
Name Description
businessId - ID!
alias - BusinessAliasInput!

Example

Query
mutation deleteBusinessAlias(
  $businessId: ID!,
  $alias: BusinessAliasInput!
) {
  deleteBusinessAlias(
    businessId: $businessId,
    alias: $alias
  ) {
    businessId
    aliases {
      ...BusinessAliasFragment
    }
  }
}
Variables
{
  "businessId": "4",
  "alias": BusinessAliasInput
}
Response
{
  "data": {
    "deleteBusinessAlias": {
      "businessId": "4",
      "aliases": [BusinessAlias]
    }
  }
}

deleteVowAlias

Description

Delete a VowAlias.

Response

Returns a String

Arguments
Name Description
input - VowAliasDeleteInput!

Example

Query
mutation deleteVowAlias($input: VowAliasDeleteInput!) {
  deleteVowAlias(input: $input)
}
Variables
{"input": VowAliasDeleteInput}
Response
{"data": {"deleteVowAlias": "xyz789"}}

inviteUser

Description

Invite a new User to the customer account.

Response

Returns a User!

Arguments
Name Description
input - InviteUserInput!

Example

Query
mutation inviteUser($input: InviteUserInput!) {
  inviteUser(input: $input) {
    userId
    customerId
    customer {
      ...CustomerFragment
    }
    emailAddress
    status
    role
    allowEditing
    fullName
    firstName
    lastName
  }
}
Variables
{"input": InviteUserInput}
Response
{
  "data": {
    "inviteUser": {
      "userId": "4",
      "customerId": 4,
      "customer": Customer,
      "emailAddress": "abc123",
      "status": "INVITED",
      "role": "ADMIN",
      "allowEditing": false,
      "fullName": "abc123",
      "firstName": "xyz789",
      "lastName": "xyz789"
    }
  }
}

reinviteUser

Description

Send a new invitation to a User.

Response

Returns a User!

Arguments
Name Description
input - ReinviteUserInput!

Example

Query
mutation reinviteUser($input: ReinviteUserInput!) {
  reinviteUser(input: $input) {
    userId
    customerId
    customer {
      ...CustomerFragment
    }
    emailAddress
    status
    role
    allowEditing
    fullName
    firstName
    lastName
  }
}
Variables
{"input": ReinviteUserInput}
Response
{
  "data": {
    "reinviteUser": {
      "userId": "4",
      "customerId": "4",
      "customer": Customer,
      "emailAddress": "xyz789",
      "status": "INVITED",
      "role": "ADMIN",
      "allowEditing": true,
      "fullName": "xyz789",
      "firstName": "abc123",
      "lastName": "xyz789"
    }
  }
}

requestBusiness

Description

Request the creation of a new Business or business entity. If zero Business exists with the provided aliases, a new Business is created. If exactly one Business exists that matches one or more of the provided aliases, that Business is updated. If more than one Business exists that has one or more of the aliases provided the request will be rejected.

Response

Returns a Business!

Arguments
Name Description
input - RequestBusinessInput!

Example

Query
mutation requestBusiness($input: RequestBusinessInput!) {
  requestBusiness(input: $input) {
    businessId
    aliases {
      ...BusinessAliasFragment
    }
  }
}
Variables
{"input": RequestBusinessInput}
Response
{
  "data": {
    "requestBusiness": {
      "businessId": 4,
      "aliases": [BusinessAlias]
    }
  }
}

revokeApiKey

Description

Revoke an Api key

Response

Returns an ApiKeyResult!

Arguments
Name Description
input - KeyInput!

Example

Query
mutation revokeApiKey($input: KeyInput!) {
  revokeApiKey(input: $input) {
    apiKeyId
    name
    status
    message
  }
}
Variables
{"input": KeyInput}
Response
{
  "data": {
    "revokeApiKey": {
      "apiKeyId": "4",
      "name": "abc123",
      "status": "active",
      "message": "xyz789"
    }
  }
}

submitWorkflowVerification

Description

Submit a new verification workflow order.

Arguments
Name Description
input - WorkflowVerificationInput

Example

Query
mutation submitWorkflowVerification($input: WorkflowVerificationInput) {
  submitWorkflowVerification(input: $input) {
    successful
    errorMessages
    order {
      ...WorkflowVerificationFragment
    }
  }
}
Variables
{"input": WorkflowVerificationInput}
Response
{
  "data": {
    "submitWorkflowVerification": {
      "successful": false,
      "errorMessages": ["abc123"],
      "order": WorkflowVerification
    }
  }
}

updateNotification

Description

Update the notifications for a user. Administrator permissions are needed to update another user within the customer account.

Response

Returns a Notification!

Arguments
Name Description
userId - ID
input - NotificationInput!

Example

Query
mutation updateNotification(
  $userId: ID,
  $input: NotificationInput!
) {
  updateNotification(
    userId: $userId,
    input: $input
  ) {
    userId
    timezone
    notifications {
      ...NotificationConfigFragment
    }
  }
}
Variables
{"userId": 4, "input": NotificationInput}
Response
{
  "data": {
    "updateNotification": {
      "userId": "abc123",
      "timezone": "xyz789",
      "notifications": [NotificationConfig]
    }
  }
}

updateStatusVowAlias

Description

Update the status of a VowAlias.

Response

Returns a String

Arguments
Name Description
input - VowAliasUpdateStatusInput!

Example

Query
mutation updateStatusVowAlias($input: VowAliasUpdateStatusInput!) {
  updateStatusVowAlias(input: $input)
}
Variables
{"input": VowAliasUpdateStatusInput}
Response
{"data": {"updateStatusVowAlias": "abc123"}}

updateUser

Description

Update the role or status of a User

Response

Returns a User!

Arguments
Name Description
input - UserUpdateInput!

Example

Query
mutation updateUser($input: UserUpdateInput!) {
  updateUser(input: $input) {
    userId
    customerId
    customer {
      ...CustomerFragment
    }
    emailAddress
    status
    role
    allowEditing
    fullName
    firstName
    lastName
  }
}
Variables
{"input": UserUpdateInput}
Response
{
  "data": {
    "updateUser": {
      "userId": "4",
      "customerId": 4,
      "customer": Customer,
      "emailAddress": "abc123",
      "status": "INVITED",
      "role": "ADMIN",
      "allowEditing": true,
      "fullName": "abc123",
      "firstName": "abc123",
      "lastName": "abc123"
    }
  }
}

Subscriptions

subscribeToKey

Description

Subscribe to an API key using its name.

Response

Returns an ApiKeyResult

Arguments
Name Description
name - String!

Example

Query
subscription subscribeToKey($name: String!) {
  subscribeToKey(name: $name) {
    apiKeyId
    name
    status
    message
  }
}
Variables
{"name": "abc123"}
Response
{
  "data": {
    "subscribeToKey": {
      "apiKeyId": "4",
      "name": "xyz789",
      "status": "active",
      "message": "xyz789"
    }
  }
}

subscribeToWorkflowVerification

Description

Subscribe to changes for a workflow verification request

Response

Returns a WorkflowVerification

Arguments
Name Description
workflowVerificationId - ID!

Example

Query
subscription subscribeToWorkflowVerification($workflowVerificationId: ID!) {
  subscribeToWorkflowVerification(workflowVerificationId: $workflowVerificationId) {
    orderId
    vowId
    businessId
    userId
    items {
      ...VerificationSpecFragment
    }
    orderStatus
    labels
    title
    jurisdictions
    orderCreationTime
    lastUpdatedTime
    orderCompletionTime
  }
}
Variables
{"workflowVerificationId": "4"}
Response
{
  "data": {
    "subscribeToWorkflowVerification": {
      "orderId": "4",
      "vowId": "4",
      "businessId": 4,
      "userId": "4",
      "items": [VerificationSpec],
      "orderStatus": "awaitingInventory",
      "labels": ["xyz789"],
      "title": "xyz789",
      "jurisdictions": ["xyz789"],
      "orderCreationTime": AWSTimestamp,
      "lastUpdatedTime": AWSTimestamp,
      "orderCompletionTime": AWSTimestamp
    }
  }
}

Types

AWSTimestamp

Description

The AWSTimestamp scalar type provided by AWS AppSync, represents the number of seconds that have elapsed since 1970-01-01T00:00Z. Negative values are also accepted and these represent the number of seconds till 1970-01-01T00:00Z. Timestamps are serialized and deserialized as integers. The minimum supported timestamp value is -31557014167219200 which corresponds to -1000000000-01-01T00:00Z. The maximum supported timestamp value is 31556889864403199 which corresponds to 1000000000-12-31T23:59:59.999999999Z.

Example
AWSTimestamp

ActiveStatus

Description

The status of an API key.

Values
Enum Value Description

active

revoked

all

Example
"active"

ApiKeyResult

Description

Represents an API key. Note that the API secret key can only be viewed during creation and is not returned.

Fields
Field Name Description
apiKeyId - ID The UUID of the API key.
name - String! The name of the API key.
status - ActiveStatus! The status of the API key.
message - String A message describing the date and time the API key was created.
Example
{
  "apiKeyId": 4,
  "name": "xyz789",
  "status": "active",
  "message": "xyz789"
}

Boolean

Description

Built-in Boolean

Business

Description

A Business is a business entity that is the subject of Mesh verifications.

Fields
Field Name Description
businessId - ID! A UUID uniquely representing the business entity. businessId values are unique to the customer, i.e. two Mesh customers verifying the same business entity will reference the business entity using different businessId values.
aliases - [BusinessAlias!] Customers may define any number of BusinessAlias for a business entity that are meaningful to them. For example, a customer may assign an internal identifier of their own as an alias.
Example
{"businessId": 4, "aliases": [BusinessAlias]}

BusinessAlias

Description

Defines an instance of a business entity BusinessAlias. The customer may choose any namespace and identifier for aliases that they wish to assign to a business entity.

Fields
Field Name Description
namespace - String! The namespace of the alias is any string that the customer can use to differentiate between different types of alias. For example billingEmail may indicate the alias is an email address that the customer uses for billing purposes.
identifier - String! The value of the alias within the defined namespace.
Example
{
  "namespace": "xyz789",
  "identifier": "abc123"
}

BusinessAliasInput

Description

Defines a BusinessAlias input for use when creating a BusinessAlias. The customer may choose any namespace and identifier for aliases that they wish to assign to a business entity.

Fields
Input Field Description
namespace - String! The namespace of the alias is any string that the customer can use to differentiate between different types of alias. For example billingEmail may indicate the alias is an email address that the customer uses for billing purposes.
identifier - String! The value of the alias within the defined namespace.
Example
{
  "namespace": "abc123",
  "identifier": "xyz789"
}

CancelVerificationOrderInput

Description

Used to cancel a WorkflowVerification

Fields
Input Field Description
orderId - ID! The UUID of the workflow verification order.
Example
{"orderId": "4"}

CancelVerificationOrderResult

Fields
Field Name Description
successful - Boolean! Indicates whether the order was successfully cancelled.
errorMessages - [String] A list of error messages if the order was not successfully cancelled.
Example
{
  "successful": true,
  "errorMessages": ["xyz789"]
}

ContinuationInput

Description

Used in queries that support continuation tokens. A continuation token is returned with each query, that must be passed back to the server to get the next page of results.

Fields
Input Field Description
limit - Int! The number of results to return in a page.
continuation - String The continuation token returned by the previous query.
Example
{"limit": 123, "continuation": "abc123"}

CreateKeyResult

Description

Represents an API key that is the result of creating an API key. Note that this is the only object that will contain the API secret key. All subsequent operations will not return the secret key.

Fields
Field Name Description
name - String! The name of the API key.
key - String! The secret key of the API key.
apiKeyId - String! The UUID of the API key.
Example
{
  "name": "abc123",
  "key": "abc123",
  "apiKeyId": "abc123"
}

Customer

Description

A Customer is the entity that engages Mesh to perform validations of Business entities.

Fields
Field Name Description
customerId - ID! UUID representing the customer.
status - CustomerStatus! The current status of the Customer.
customerName - String! The name of the customer.
customerUrl - String The URL of the customer's website.
customerLogo - String A URL to the customer's logo.
entitlements - [String] An entitlement is a permission granted to a Customer by Mesh, per the customer agreement and order form, to perform specific types of verifications in specific regions.
vows - [VowConfig!] The list of verification order workflow (VOW) configurations that the customer has access to. Each VOW configuration defines the verification steps and claims that are required to verify a business entity. Every order is created from a VOW configuration.
Example
{
  "customerId": "4",
  "status": "ACTIVE",
  "customerName": "abc123",
  "customerUrl": "abc123",
  "customerLogo": "xyz789",
  "entitlements": ["xyz789"],
  "vows": [VowConfig]
}

CustomerStatus

Description

Allowed states for a customer.

Values
Enum Value Description

ACTIVE

INACTIVE

Example
"ACTIVE"

ID

Description

Built-in ID

Example
4

Int

Description

Built-in Int

Example
987

Invite

Description

An object representing a user invitation in the Customer account. Used for Mesh-only internal queries.

Fields
Field Name Description
inviteId - ID! UUID representing the invitation.
inviteStatus - InviteStatus! The status of the invitation.
inviteExpiration - AWSTimestamp! The expiration date and time of the invitation, expressed as epoch time.
emailAddress - String! The email address to which the invitation was sent.
userId - String! The UUID of the user who has been sent the invitation.
customer - Customer The Customer account to which the invitation is associated.
Example
{
  "inviteId": "4",
  "inviteStatus": "VALID",
  "inviteExpiration": AWSTimestamp,
  "emailAddress": "xyz789",
  "userId": "xyz789",
  "customer": Customer
}

InviteStatus

Description

The status of a user invitation in the Customer account

Values
Enum Value Description

VALID

INVALID

Example
"VALID"

InviteUserInput

Description

Defines the input for the inviteUser mutation.

Fields
Input Field Description
emailAddress - String! The email address of the user to be invited.
role - UserRole! The role to be assigned to the user.
Example
{"emailAddress": "abc123", "role": "ADMIN"}

KeyInput

Description

Defines the input parameters for the revokeApiKey mutation.

Fields
Input Field Description
apiKeyId - ID! The UUID of the API key to be revoked.
Example
{"apiKeyId": "4"}

ListNotificationInput

Description

Provides the parameters for the listNotifications query.

Fields
Input Field Description
userId - String The UUID of the user for whom notifications are being queried.
Example
{"userId": "xyz789"}

ListNotificationResults

Description

The results of a notification query.

Fields
Field Name Description
nextContinuation - String Used with pagination. The next continuation token to be used in the next query.
notifications - [Notification!]! The list of notifications that match the search criteria.
Example
{
  "nextContinuation": "abc123",
  "notifications": [Notification]
}

NamedKeyInput

Description

Defines the input parameters for the createApiKey mutation.

Fields
Input Field Description
name - String! The name of the API key to be created.
Example
{"name": "abc123"}

Notification

Description

Defines the notification settings for a specific user in the customer's account.

Fields
Field Name Description
userId - String! UUID representing the user.
timezone - String! The user's preferred timezone.
notifications - [NotificationConfig!]! The user's notification configurations.
Example
{
  "userId": "xyz789",
  "timezone": "xyz789",
  "notifications": [NotificationConfig]
}

NotificationChannel

Description

The available channels on which customers may opt to receive verification notifications.

Values
Enum Value Description

EMAIL

SMS

SLACK

WEBHOOK

Example
"EMAIL"

NotificationConfig

Description

Describes the configuration of a notification channel.

Fields
Field Name Description
notificationChannel - NotificationChannel! The channel on which the notification will be sent.
notificationTypes - [NotificationType!]! The types of notifications that will be sent on the channel.
phoneNumber - String Only for use with SMS notifications. A phone number that is able to receive text messages.
emailAddress - String Used only for email notifications.
hookUrl - String Used for Slack and webhook notifications. An endpoint owned by the customer that can receive notifications.
channel - String Optional for Slack notifications. The name of the Slack channel to which notifications will be sent.
secret - String Optional for webhook notifications. A secret value that is added to Mesh notifications to confirm the authenticity of the notification.
Example
{
  "notificationChannel": "EMAIL",
  "notificationTypes": ["verificationCompleted"],
  "phoneNumber": "xyz789",
  "emailAddress": "xyz789",
  "hookUrl": "abc123",
  "channel": "xyz789",
  "secret": "xyz789"
}

NotificationConfigInput

Description

Provides the parameters for the updateNotification mutation.

Fields
Input Field Description
notificationChannel - NotificationChannel! The notification channels through which notifications will be received.
notificationTypes - [NotificationType!]! The types of notifications that will be received on the channel.
phoneNumber - String Only for use with SMS notifications. A phone number that is able to receive text messages.
emailAddress - String Used only for email notifications.
hookUrl - String Used for Slack and webhook notifications. An endpoint owned by the customer that can receive notifications.
channel - String Optional for Slack notifications. The name of the Slack channel to which notifications will be sent.
secret - String Optional for webhook notifications. A secret value that is added to Mesh notifications to confirm the authenticity of the notification.
Example
{
  "notificationChannel": "EMAIL",
  "notificationTypes": ["verificationCompleted"],
  "phoneNumber": "xyz789",
  "emailAddress": "xyz789",
  "hookUrl": "abc123",
  "channel": "abc123",
  "secret": "xyz789"
}

NotificationInput

Description

Used as input to the updateNotification mutation.

Fields
Input Field Description
timezone - String! The preferred timezone to be used with the notification.
notifications - [NotificationConfigInput!]! The notification configurations to be updated.
Example
{
  "timezone": "xyz789",
  "notifications": [NotificationConfigInput]
}

NotificationType

Description

The notification types that customers may opt to receive.

Values
Enum Value Description

verificationCompleted

verificationCompletedNegative

verificationCompletedPositive

verificationUpdated

Example
"verificationCompleted"

OrderItemStatus

Description

Indicates the status of an individual order item in the workflow (e.g. a professional license). requested means that authoritative records that match the item have been requested but not yet fulfilled; fulfilled means the records have been retrieved, but not yet evaluated; adjudicated means that the claims in the item have been evaluated against authoritative records and verification labels applied; and notFound means that no authoritative records could be item could be found.

Values
Enum Value Description

requested

fulfilled

adjudicated

notFound

cancelled

Example
"requested"

Pagination

Description

An input type representing pagination parameters for list-type queries.

Fields
Field Name Description
total - Int! The maximum number of results that are available
nextOffset - String The value to pass back into the offset parameter to receive the next set of results
Example
{"total": 987, "nextOffset": "abc123"}

PaginationInput

Description

Used in queries that support paginated results.

Fields
Input Field Description
limit - Int! The number of results to return in a page.
offset - Int! The offset from which to start returning results, calculated as the limit (page size) multiplied by the page number. For example, if the pagination limit (page size) is 10, then the second page offset is 20, third page offset is 30, etc.
Example
{"limit": 123, "offset": 123}

ParameterInput

Description

Generic input type for defining parameters.

Fields
Input Field Description
name - String! The name of the parameter.
value - String! The value of the parameter.
Example
{
  "name": "xyz789",
  "value": "abc123"
}

QueryWorkflowVerificationInput

Description

An input type for defining the parameters of the queryWorkflowVerifications query.

Fields
Input Field Description
searchTerms - [String!] An array of strings representing the search terms to be used to find verification workflow orders, for example the business name or license number
orderBy - String Criteria for sorting the results.
pagination - PaginationInput Paging parameters for the query.
Example
{
  "searchTerms": ["abc123"],
  "orderBy": "abc123",
  "pagination": PaginationInput
}

QueryWorkflowVerifications

Description

The return type for the queryWorkflowVerifications query, providing a list of WorkflowVerification objects and pagination information.

Fields
Field Name Description
orders - [WorkflowVerification!] The list of verification workflow orders that match the search criteria.
pagination - Pagination! The pagination information for the query.
Example
{
  "orders": [WorkflowVerification],
  "pagination": Pagination
}

Redirect

Description

A Redirect can be configured in a verification order workflow configuration to redirect a business entity user to another URI at the conclusion of the verification workflow in the Mesh user interface. In other words, this is the URI that is loaded when the final verification order is submitted by the business entity user.

Fields
Field Name Description
redirectUri - String! The URI that is the target for the redirect at the conclusion of the verification workflow.
includeUser - Boolean Specifies whether to include an "ID" query parameter with the businessId, providing the redirect URI with information about which Business just completed the flow. Defaults to false
Example
{
  "redirectUri": "xyz789",
  "includeUser": false
}

RedirectInput

Description

Input type for defining a Redirect in a verification order workflow configuration.

Fields
Input Field Description
redirectUri - String! The URI that is the target for the redirect at the conclusion of the verification workflow.
includeUser - Boolean Specifies whether to include an "ID" query parameter with the businessId, providing the redirect URI with information about which Business just completed the flow. Defaults to false
Example
{
  "redirectUri": "abc123",
  "includeUser": false
}

ReinviteUserInput

Description

Defines the input for the reinviteUser mutation.

Fields
Input Field Description
userId - ID! The UUID of the user to be reinvited.
Example
{"userId": "4"}

RequestBusinessInput

Description

Defines a Business input for use when creating a Business.

Fields
Input Field Description
emailAddress - String The email address of the business entity. If business entity notifications are enabled this email address will be used to send verification updates to the business entity.
preverifiedEmail - Boolean Mesh verifies possession of the email address using a one time passcode. If the email address has already been verified, the customer may ask Mesh to skip email address verification.
aliases - [BusinessAliasInput!] Customers may define any number of BusinessAlias for a business entity that are meaningful to them. For example, a customer may assign an internal identifier of their own as an alias.
Example
{
  "emailAddress": "abc123",
  "preverifiedEmail": true,
  "aliases": [BusinessAliasInput]
}

String

Description

Built-in String

Example
"abc123"

SubmitWorkflowVerificationResult

Description

The result of submitting a verification workflow order. If the order was successful, successful will be true and the order field will contain the details of the order. If the order was not successful, successful will be false and the errorMessages field will contain a list of error messages.

Fields
Field Name Description
successful - Boolean! Indicates whether the order was successfully submitted.
errorMessages - [String] A list of error messages if the order was not successfully submitted.
order - WorkflowVerification The details of the order if the order was successfully submitted.
Example
{
  "successful": true,
  "errorMessages": ["abc123"],
  "order": WorkflowVerification
}

User

Description

A User is an entity that has been invited to a Customer account.

Fields
Field Name Description
userId - ID! A UUID representing the user.
customerId - ID! The UUID of the Customer account to which the User belongs.
customer - Customer! The name of the Customer account to which the User belongs.
emailAddress - String! The email address of the User.
status - UserStatus! The current status of the User.
role - UserRole! The role assigned to the User.
allowEditing - Boolean Not in use.
fullName - String Deprecated. The full name of the User.
firstName - String The first name of the User.
lastName - String The last name of the User.
Example
{
  "userId": "4",
  "customerId": "4",
  "customer": Customer,
  "emailAddress": "xyz789",
  "status": "INVITED",
  "role": "ADMIN",
  "allowEditing": false,
  "fullName": "abc123",
  "firstName": "xyz789",
  "lastName": "xyz789"
}

UserRole

Description

Describes the assigned role of the user.

Values
Enum Value Description

ADMIN

MEMBER

Example
"ADMIN"

UserStatus

Description

Describes the user status. INVITED indicates a user that has been invited to the Mesh application but has not yet accepted the invitation. ACTIVE indicates a user that has accepted the invitation.

Values
Enum Value Description

INVITED

ACTIVE

INACTIVE

Example
"INVITED"

UserUpdateInput

Description

Defines the input for the updateUser mutation.

Fields
Input Field Description
userId - ID! The UUID of the user to be updated.
role - UserRole! The role to be assigned to the user.
status - UserStatus! The status to be assigned to the user.
Example
{
  "userId": "4",
  "role": "ADMIN",
  "status": "INVITED"
}

VerificationClaim

Description

A verification claim is an individual piece of information that the business entity claims to be true, for example a business name or address. Claims are compared to data in authoritative records to determine a match with the order item.

Fields
Field Name Description
name - String! The name of the claim, for example "businessName" or "businessAddress".
value - String The value of the claim, for example "Acme Corp" or "123 Main St".
Example
{
  "name": "xyz789",
  "value": "xyz789"
}

VerificationClaimInput

Description

An input type defining the specific claim inputs required to submit a new verification workflow order using the submitWorkflowVerification mutation.

Fields
Input Field Description
name - String! The name of the claim, for example "businessName" or "businessAddress".
value - String! The value of the input claim. For more complex claim types the input value will be expressed as a JSON string, as GraphQL inputs cannot use unions.
Example
{
  "name": "xyz789",
  "value": "xyz789"
}

VerificationSpec

Description

A verification specification defines the details of a particular VSKU within a verification workflow order. It includes the claims submitted by the business entity, the results of the verification, the decision and evaluation labels applied to the VSKU, and the status of the verification item.

Fields
Field Name Description
vspecId - ID! A vspecId is a UUID that can be used to allow the same VSKU to be used multiple times in a single verification order workflow configuration. Where a VSKU appears only once, the vspecId carries no special meaning.
vsku - String! The VSKU ID for this item. This is NOT a UUID, but a unique identifier for the VSKU within the Mesh system.
jurisdiction - String! The jurisdiction for this item, for example the country such as "US" (USA) or state such as "CA" (California).
claims - [VerificationClaim!]! The claims submitted by the business entity for this item. These are the data items that the business entity claims to be true.
results - [VerificationClaim!] The results of the verification process for this item. These are the data items that are returned from authoritative sources.
labels - [String!] The decision and evaluation labels applied to this order item by the item policy. Labels indicate decisions such as the quality of a license number match, e.g. license_number_mismatch_minor, or overall outcomes for the VSKU such as professional_license_verified. Item labels are used by the order policy to determine the overall status of the verification order workflow.
itemStatus - OrderItemStatus The status of this order item.
lastVerifiedTime - AWSTimestamp An epoch timestamp representing the time that this item was last verified.
Example
{
  "vspecId": "4",
  "vsku": "abc123",
  "jurisdiction": "abc123",
  "claims": [VerificationClaim],
  "results": [VerificationClaim],
  "labels": ["abc123"],
  "itemStatus": "requested",
  "lastVerifiedTime": AWSTimestamp
}

VerificationSpecInput

Description

An input type defining the specific VSKU inputs required to submit a new verification workflow order using the submitWorkflowVerification mutation.

Fields
Input Field Description
vspecId - ID! The UUID of the specific instance of a VSKU in the verification order workflow configuration.
jurisdiction - String! The jurisdiction in which the order item will be verified, for example a state such as "CA" (California).
claims - [VerificationClaimInput!]! The set of claims submitted by the business entity for this item. These are the data items that the business entity claims to be true, and must match the VSKU specification.
Example
{
  "vspecId": "4",
  "jurisdiction": "abc123",
  "claims": [VerificationClaimInput]
}

ViewKeysInput

Description

Defines the input parameters for the viewApiKeys query.

Fields
Input Field Description
limit - Int The maximum number of API keys to return.
status - ActiveStatus Restricts the keys returned to those with the defined status.
Example
{"limit": 123, "status": "active"}

VowAliasCreateInput

Description

Input type for creating a VowAlias.

Fields
Input Field Description
alias - String! The alias string to create.
vowId - String! The vowId that the alias points to.
Example
{
  "alias": "xyz789",
  "vowId": "abc123"
}

VowAliasCreateResult

Description

Type that describes a VowAlias object returned from the getVowAlias query.

Fields
Field Name Description
alias - String! The alias string.
vowId - String! The vowId that the alias points to.
customerId - String! The UUID of the customer that owns the alias.
Example
{
  "alias": "abc123",
  "vowId": "xyz789",
  "customerId": "abc123"
}

VowAliasDeleteInput

Description

Input type for deleting a VowAlias.

Fields
Input Field Description
alias - String! The alias string to delete.
Example
{"alias": "xyz789"}

VowAliasUpdateStatusInput

Description

Input type for updating the status of a VowAlias.

Fields
Input Field Description
alias - String! The alias string to update.
status - String! The new status of the alias.
Example
{
  "alias": "abc123",
  "status": "xyz789"
}

VowConfig

Description

A VowConfig is a verification order workflow configuration (i.e. template) that defines the verification order workflow that will be performed for a business entity. A VowConfig consists of VowConfigItems that define the VSKUs in the verification order, the order in which they are presented to the business entity, and the decision-making policy of the verification order workflow.

Fields
Field Name Description
vowId - String! AS UUID that uniquely identifies this VowConfig. Two VowConfig instances may have the same vowConfigId i.e. are based on the same template, but will have unique vowIds.
vowConfigId - String! An identifier (not a UUID) for the VowConfig design. The VowConfig design can be reused across many VowConfigs each of which will have a unique vowId but will share a vowConfigId.
description - String Human-readable description of the VowConfig.
items - [VowConfigItem] The set of VowConfigItems that define the verification order workflow. The order of the items in the array defines the order in which the VSKUs will be presented to the business entity.
redirectSettings - Redirect Defines the redirect behavior of the Mesh dynamically-generated user interface after final submission of a verification order by the user.
Example
{
  "vowId": "abc123",
  "vowConfigId": "xyz789",
  "description": "xyz789",
  "items": [VowConfigItem],
  "redirectSettings": Redirect
}

VowConfigInput

Description

Input type for defining a VowConfig. Important Note: VowConfig assembly is currently not self-service and is performed by Mesh. A self-service product is planned for the future.

Fields
Input Field Description
vowId - String! A UUID that uniquely identifies this VowConfig. Two VowConfig instances may have the same vowConfigId i.e. are based on the same template, but will have unique vowIds.
vowConfigId - String! An identifier (not a UUID) for the VowConfig design. The VowConfig design can be reused across many VowConfigs each of which will have a unique vowId but will share a vowConfigId.
description - String Human-readable description of the VowConfig.
redirectSettings - RedirectInput Defines the redirect behavior of the Mesh dynamically-generated user interface after final submission of a verification order by the user.
parameters - [ParameterInput] Configuration parameters required by the VOW configuration.
Example
{
  "vowId": "xyz789",
  "vowConfigId": "xyz789",
  "description": "abc123",
  "redirectSettings": RedirectInput,
  "parameters": [ParameterInput]
}

VowConfigItem

Description

A Verification Order Workflow Configuration Item (VowConfigItem) represents an instance of a VSKU in the VOW configuration, or 'design'. Customers may design their verification order workflows with VSKUs in any order (with some exceptions) by assigning VSKUs to VowConfigItems in the desired order.

Fields
Field Name Description
vskuId - String! The ID of the VSKU that this item will use. This is NOT a UUID, but a unique identifier for the VSKU within the Mesh system.
vsku - Vsku! The VSKU details for this item
vspecId - String! A vspecId is a UUID that can be used to allow the same VSKU to be used multiple times in a single verification order workflow configuration. Where a VSKU appears only once, the vspecId carries no special meaning.
isRequired - Boolean Specifies whether this item is required to place this verification order (default true). If a required VowConfigItem is not included in the verification order, the verification order will be rejected.
isRepeatable - Boolean Specifies whether this item can be included multiple times in an verification order (default false).
Example
{
  "vskuId": "abc123",
  "vsku": Vsku,
  "vspecId": "abc123",
  "isRequired": true,
  "isRepeatable": true
}

Vsku

Description

A VSKU (Verification SKU) is a type of verification item that can be included in a verification order. VSKUs are used to define the types of information that are collected during a verification order, the verifications performed, and the types of results that are returned.

Fields
Field Name Description
vskuId - String! A UUID that uniquely identifies this VSKU
type - VskuType! The type of VSKU, which defines how the VSKU is used and rendered in the Mesh user interface.
inputClaims - [String!]! A claim is a data item that the business entity being verified claims to be true, i.e. the input to the verification. Claims are compared against authoritative records during verification to determine if the record is a match to the claims. Claim fields and Result fields may have the same name, but they are two distinct namespaces and will contain different data.
outputResults - [String!]! A results is a data item that is returned from the verification process i.e. the output, and is typically obtained from authoritative sources. Claim fields and Result fields may have the same name, but they are two distinct namespaces and will contain different data.
Example
{
  "vskuId": "xyz789",
  "type": "document",
  "inputClaims": ["xyz789"],
  "outputResults": ["xyz789"]
}

VskuType

Description

Verification SKUs (VSKUs) are defined as having different types that describe their general usage and behavior when Mesh's dynamic user interface is rendered. A document VSKU is used for uploading documents. A field VSKU is a typical form-fill style VSKU that collects information in defined fields. The businessInfoWizard is a special case of a field VSKU that collects information using a data capture wizard. eSign VSKUs present documents for legal signature, and finally mobileVerification VSKUs verify possession of a phone number through one-time passcodes or similar means.

Values
Enum Value Description

document

field

businessInfoWizard

eSign

mobileVerification

Example
"document"

WorkflowVerification

Description

A verification workflow order is a request to verify a business entity, using verifications defined in the verification order workflow configuration (vowConfig). The order includes the details of the business entity, the items to be verified, the status of the order, and the results of the verification process.

Fields
Field Name Description
orderId - ID! The UUID of the verification workflow order.
vowId - ID! The UUID of the verification workflow configuration that this order is based on.
businessId - ID The UUID of the business entity that is the target of this verification.
userId - ID! The UUID of the user that submitted this verification order i.e. a business entity user, not a customer user.
items - [VerificationSpec!]! The items that are being verified in this order.
orderStatus - WorkflowVerificationStatus! The current status of this verification order workflow.
labels - [String!] The decision and evaluation labels applied to this order by the order policy. Order labels indicate the final decision making outcome, such as approved or rejected. They may also indicate where problems were encountered, such as business_issue or professional_license_issue.
title - String! The title of the business entity being verified. This is typically the name of the individual or business.
jurisdictions - [String!]! The set of all jurisdictions in which order items were verified. For example if a business entity submits two professional licenses, one from California and one from New York, the jurisdictions array would contain ["CA", "NY"].
orderCreationTime - AWSTimestamp! The epoch time that this verification order was created.
lastUpdatedTime - AWSTimestamp! The epoch time that this verification order was last updated.
orderCompletionTime - AWSTimestamp The epoch time that this verification order was completed.
Example
{
  "orderId": 4,
  "vowId": "4",
  "businessId": 4,
  "userId": 4,
  "items": [VerificationSpec],
  "orderStatus": "awaitingInventory",
  "labels": ["xyz789"],
  "title": "abc123",
  "jurisdictions": ["xyz789"],
  "orderCreationTime": AWSTimestamp,
  "lastUpdatedTime": AWSTimestamp,
  "orderCompletionTime": AWSTimestamp
}

WorkflowVerificationInput

Description

An input type required to submit a new verification workflow order using the submitWorkflowVerification mutation.

Fields
Input Field Description
orderId - ID The UUID of the order. This also functions as a idempotency key, so that an existing request with the same value will be disregarded and the details of the previously submitted order will be returned. This value must be specified as a 36-digit UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) and will be rejected if it is not.
vowId - ID! The vowId (or template) to use for the verification order, which defines the VSKU required or allowed in the order.
businessId - ID If provided, the verification order will be submitted for the business entity with this UUID businessId. Alternatively the customer may omit this value and request a new business entity be created using the business object.
business - RequestBusinessInput If provided, the verification order will be submitted and a new business entity created. Alternatively the customer may omit this value and specify a pre-existing business entity using the businessId field.
items - [VerificationSpecInput!]! The set of input types representing the order items to be verified by the verification order workflow. These must match the specification of the VSKUs in the vowConfig template.
Example
{
  "orderId": "4",
  "vowId": "4",
  "businessId": "4",
  "business": RequestBusinessInput,
  "items": [VerificationSpecInput]
}

WorkflowVerificationStatus

Description

Indicates the status of a verification order workflow. awaitingInventory means that the order has been submitted and is awaiting the retrieval of authoritative records; awaitingAdjudication means that the records have been retrieved and are awaiting evaluation; complete means that the order has been fully evaluated, verification labels applied, and this verification order workflow is not in a terminal completed state; and monitoring means that an initial verification has been performed and records are being monitored for changes (where customers opt for monitored verifications).

Values
Enum Value Description

awaitingInventory

awaitingAdjudication

complete

monitoring

cancelled

Example
"awaitingInventory"