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.
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 asapproved
orrejected
.
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
- Step 1 - Testing the API Key (5 mins): Make sure that our Mesh account is working, and begin exploring the API.
- Step 2 - Exploring the VOW (15 mins): A quick tour of the core concept in Mesh verifications, the Verification Order Workflow.
- Step 3 - Create Business (5 mins): Before we can perform a verification, we must tell Mesh who is being verified.
- Step 4 - Register Webhook (5 mins): We will need some way for Mesh to notify us that a verification order workflow has completed.
- Step 5 - Initiating a Verification Order workflow will follow one of two paths, depending on your desired integration pattern:
- Step 5a - Initiate the Mesh One Click User Interface (5 mins): Use our pre-built, optimized user interface for the fastest and most accurate results.
- Step 5b - Create VOW (10 mins): Build your own user interface, and call our API to initiate the VOW.
- Step 6 - Listen for Webhook Notifications and Get Results (10 mins): Wait for Mesh to complete the verification, and retrieve the results.
Pre-Requisites
Contact your Mesh customer success representative to create your Mesh account and get access to our sandbox so you can follow along with this quick-start guide using a sample verification workflow.
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 thevows
available to you or to have a newvow
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:
- 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.
- 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.
- 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).
- 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 totrue
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 andvsku
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 andvsku
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 avow
. -
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.
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.
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
.
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
getUser
Description
Retrieve the details of a specific User
within your account.
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
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.
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.
Response
Returns a SubmitWorkflowVerificationResult!
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 |
---|---|
|
|
|
|
|
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
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.
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.
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 |
---|---|
|
|
|
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 |
---|---|
|
|
|
Example
"VALID"
InviteUserInput
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 |
---|---|
|
|
|
|
|
|
|
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 |
---|---|
|
|
|
|
|
|
|
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 |
---|---|
|
|
|
|
|
|
|
|
|
Example
"requested"
Pagination
Description
An input type representing pagination parameters for list-type queries.
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
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 |
---|---|
|
|
|
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 |
---|---|
|
|
|
|
|
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.
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.
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
VowAliasCreateResult
Description
Type that describes a VowAlias
object returned from the getVowAlias
query.
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
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 |
---|---|
|
|
|
|
|
|
|
|
|
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 |
---|---|
|
|
|
|
|
|
|
|
|
Example
"awaitingInventory"