Our vision at Mesh is to be the easiest and most trusted business identity provider on the internet.
\nThese 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.
\nIf you have any questions, please reach out to us at support@mesh.id. We're here to help.
\nAlthough the Mesh API is powerful, the fundamental concept is simple. As a Mesh customer, you will submit a Verification Order Workflow (vow) describing the number and type of verifications Mesh needs to perform for a single Professional entity (the business, sole proprietor, or professional that Mesh will verify). The API is primarily concerned with submitting and retrieving the results of Verification Order Workflows.
Jump to the Quick Start Guide for a worked example of a professional license verification vow.
All requests require an active API key. Please contact support@mesh.id to receive an active API key.
\nAn API key should be passed as an Authorization header of an HTTP Request in the following manner:
Authorization: <MESH_API_KEY>\nHost: https://app.mesh.id/graphql\n\nThis query tells us a lot about our Mesh user account through which we are calling the API:
\nThe customer block in the response also tells us a bit more about the Mesh customer account belonging to Circle:
You will also notice that we have something called vows in our response. Let's explore those in more detail in the next step.
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.
Let's 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.
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.
So now we understand a bit more about vows. Let's dig a bit more into vskus and what they contain.
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.
When Mesh has completed the verification, Mesh will return the specific outputResults for each vsku. For our standard professional license vsku, these are:
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.
\n\nNote:
\nvowscurrently must be configured by Mesh. Work with your customer success representative to understand thevowsavailable to you or to have a newvowconfigured.
Let's look at the vow configurations that Circle Home has access to.
Each Professional is identified by an email address that is also used to send notifications. The inputs to the Create Professional step are:
\n\n\nIMPORTANT: You must only set the
\npreverifiedEmailflag totrueif you can guarantee that the user 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.
Now that we know the vow and vsku concepts, we can begin preparing to submit a verification.
When you submit a vow, you must first declare 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.
Let's take a look at the CreateBusiness step.
\n","_postman_id":"b9e53a64-5cd2-4003-824d-351643f5bc87","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":"{{MESH_API_KEY}}"}]},"isInherited":true,"source":{"_postman_id":"31de4fda-3698-44fc-b51f-a1765ce7f509","id":"31de4fda-3698-44fc-b51f-a1765ce7f509","name":"Mesh API Documentation","type":"collection"}}},{"name":"Step 4 - Register Webhook (5 mins)","item":[{"name":"UpdateNotifications","id":"37a5fde1-f772-4394-9b73-ac2288bdbb51","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"graphql","graphql":{"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":"{\r\n \"input\": {\r\n \"notifications\": [\r\n {\r\n \"emailAddress\": \"circle+home@mesh.id\",\r\n \"notificationChannel\": \"EMAIL\",\r\n \"notificationTypes\": \"verificationResultsUpdated\" \r\n },\r\n {\r\n \"notificationChannel\": \"WEBHOOK\",\r\n \"notificationTypes\": \"verificationResultsUpdated\",\r\n \"hookUrl\": \"my-webhook-endpoint.circle.com\"\r\n\r\n }\r\n ],\r\n \"timezone\": \"America/Los_Angeles\"\r\n }\r\n}"}},"url":"https://app.mesh.id/graphql","description":"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, one for email and one for webhooks. The API also supports Slack and SMS.
\nLet's examine the $input parameters:
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.
\nYou 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.
\nFor 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.
\n","_postman_id":"79dd12f6-5145-4203-82e6-b05022bfd099","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":"{{MESH_API_KEY}}"}]},"isInherited":true,"source":{"_postman_id":"31de4fda-3698-44fc-b51f-a1765ce7f509","id":"31de4fda-3698-44fc-b51f-a1765ce7f509","name":"Mesh API Documentation","type":"collection"}}},{"name":"Step 5a - Initiate the Mesh One-Click Verify User Interface (5 mins)","item":[],"id":"4c4cbe1f-1d65-441d-bff1-308e49a9b8a3","description":"Let's recap where our Circle developer is:
\nThey now know about the vow configurations and vsku requirements available to them.
They have created a businessId for the Business they wish to verify.
They have registered email and webhook notifications ready to receive updates as Mesh fulfills the vow.
They are now ready to create a verification order workflow.
\nThe 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.
You can launch the One-Click Verify user interface from the desired location in your online experience with the following Javascript:
\n// TBD\n\nWe also support a hosted version of our One-Click Verify form. Mesh will create a customer-friendly URL, including your company's brand and logo, and host your verification workflow for you. The URL will be of the form:
\nhttps://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.
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.
Our Circle developer is now ready to create a vow.
The Create Order request utilizes the identifiers we retrieved and examined in the previous steps. It also includes the specific claims the Professional asserts that Mesh will verify.
\nIn the example provided, the Professional has submitted only one professional license vsku.
Each item in the array is specified as follows:
\nThe Mesh API returns the following:
\nThe order information includes the following:
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":"{{MESH_API_KEY}}"}]},"isInherited":true,"source":{"_postman_id":"31de4fda-3698-44fc-b51f-a1765ce7f509","id":"31de4fda-3698-44fc-b51f-a1765ce7f509","name":"Mesh API Documentation","type":"collection"}},"urlObject":{"protocol":"https","path":["graphql"],"host":["app","mesh","id"],"query":[],"variable":[]}},"response":[{"id":"1bda09e1-5b2b-41ee-8482-8e038a7a0bf7","name":"Success","originalRequest":{"method":"POST","header":[],"body":{"mode":"graphql","graphql":{"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":"{\r\n \"input\": {\r\n \"vowId\": \"86506334-46ff-4933-85de-4b858c126ab1\",\r\n \"professionalId\": \"24ecf72d-bee7-4c78-a94e-0b6709fd3ee5\",\r\n \"items\": [\r\n {\r\n \"vspecId\": \"11fb7baf-7027-4a74-9ff5-f3576e539703\",\r\n \"claims\": [\r\n {\r\n \"name\": \"licenseSubtype\",\r\n \"value\": \"plumbers\"\r\n },\r\n {\r\n \"name\": \"licenseeName\",\r\n \"value\": \"Bob's Builders\"\r\n },\r\n {\r\n \"name\": \"jurisdiction\",\r\n \"value\": \"IA\"\r\n },\r\n {\r\n \"name\": \"licenseIdentifier\",\r\n \"value\": \"123456\"\r\n }\r\n ],\r\n \"jurisdiction\": \"IA\"\r\n }\r\n ]\r\n }\r\n}"}},"url":"https://app.mesh.id/graphql"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json;charset=UTF-8"},{"key":"Content-Length","value":"171"},{"key":"Connection","value":"keep-alive"},{"key":"Date","value":"Tue, 24 Oct 2023 06:13:01 GMT"},{"key":"x-amzn-RequestId","value":"f8515cc8-2704-4cd3-86a2-fec1b309fd7f"},{"key":"x-amzn-appsync-TokensConsumed","value":"73"},{"key":"Via","value":"1.1 2ac6b2644462a8466362b046856a127e.cloudfront.net (CloudFront), 1.1 94be61e339880d0097634de6934f7710.cloudfront.net (CloudFront)"},{"key":"X-Amz-Cf-Pop","value":"SFO5-C3"},{"key":"X-Amz-Cf-Pop","value":"SFO5-P2"},{"key":"X-Cache","value":"Miss from cloudfront"},{"key":"X-Amz-Cf-Id","value":"p3woAQ7nSgwM2uCcdxNTTaln2RHHCEP7wd9mOKDl-NSRdo0xrtd41Q=="}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"submitWorkflowVerification\": {\n \"errorMessages\": [],\n \"successful\": true,\n \"order\": {\n \"orderId\": \"f245337f-420a-4407-aa8d-336e4d019a8b\",\n \"orderStatus\": \"awaitingInventory\"\n }\n }\n }\n}"}],"_postman_id":"6de38e49-095d-4b5e-9828-0b4610c47903"}],"id":"11ad4a52-f61c-4324-9a04-f269b592632f","description":"Let's recap where our Circle developer is:
\nWe now know about the vow configurations and vsku requirements available to us.
We have created a businessId for the Business we wish to verify.
We have registered email and webhook notifications ready to receive updates as Mesh fulfills the vow.
We are now ready to create a verification order workflow.
\nWe 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.
\n\nLaunching December 2023 - Please be aware of this requirement when implementing Mesh through our API.
\n
Mesh's One-Click Verify user interface contains contractually mandated consent language to ensure that Mesh can fulfill verification orders where contact with the Business is required.
\nIf you wish to build your own user interface, you must include a minimal Consent Widget in your user interface. The widget is embedded in your flow in the same manner as the One-Click Verify user interface using the following Javascript:
\n// TBD\n\nThis minimal widget displays contractually required language and links to Mesh's privacy policy and terms of use. The widget returns a consentId that you must include when creating a vow, providing traceability of the terms and conditions your end user accepts.
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.
\nAn 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:
\nThe top-level information in the Get Order response contains information about the vow itself:
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.
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.
\nAs a security precaution, the webhook payload contains no useable data about the verification. When you receive the webhook notification, use the targetId contained to retrieve the current status of the vow as follows.
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:
\nVerification Order Workflows (vow)- the core concept behind Mesh that describes the number and type of verifications to be performed for a singel Professional
Verification Store Keeping Unit (vsku) - an individual verification that is part of a vow.
Professional - the business or individual that Mesh will verify, and will be the subject of a vow.
How to create a vow using Mesh's One-Click Verify user interface (recommended), or through a customer-built user interface and using Mesh's API.
How to subscribe to webhook updates, and call Mesh to get vow updates.
That's all you need to know! Everything else is a variation on the theme. Your required vow configuration might have different vsku items, with different policies, and different notifications, but the principles are the same.
As always support@mesh.id is here to help you.
\n","_postman_id":"880c29e0-8572-450b-8912-8c386220620d","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":"{{MESH_API_KEY}}"}]},"isInherited":true,"source":{"_postman_id":"31de4fda-3698-44fc-b51f-a1765ce7f509","id":"31de4fda-3698-44fc-b51f-a1765ce7f509","name":"Mesh API Documentation","type":"collection"}}}],"id":"7f67e0be-e86b-4643-a15b-aabfc124aae9","description":"Approximate time needed - 1 hour
\nThis guide will show you how to use the Mesh API for a simple professional license verification use case.
\nThe 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.
\nStep 1 - Testing the API Key (5 mins): Make sure that our Mesh account is working, and begin exploring the API.
\nStep 2 - Exploring the VOW (15 mins): A quick tour of the core concept in Mesh verifications, the Verification Order Workflow.
\nStep 3 - Create Business (5 mins): Before we can perform a verification, we must tell Mesh who is being verified.
\nStep 4 - Register Webhook (5 mins): We will need some way for Mesh to notify us that a verification order workflow has completed.
\nStep 5 - Initiating a Verification Order workflow will follow one of two paths, depending on your desired integration pattern:
\nStep 5a - Initiate the Mesh One Click User Interface (5 mins): Use our pre-built, optimized user interface for the fastest and most accurate results.
\nStep 5b - Create VOW (10 mins): Build your own user interface, and call our API to initiate the VOW.
\nStep 6 - Listen for Webhook Notifications and Get Results (10 mins): Wait for Mesh to complete the verification, and retrieve the results.
\nContact 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.
\n","event":[{"listen":"prerequest","script":{"id":"15c5638a-74cd-4c6c-ac56-6f9f0bb50e4d","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"16702932-6cb4-46dc-8035-191d0ebf50b9","type":"text/javascript","exec":[""]}}],"_postman_id":"7f67e0be-e86b-4643-a15b-aabfc124aae9","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":"{{MESH_API_KEY}}"}]},"isInherited":true,"source":{"_postman_id":"31de4fda-3698-44fc-b51f-a1765ce7f509","id":"31de4fda-3698-44fc-b51f-a1765ce7f509","name":"Mesh API Documentation","type":"collection"}}},{"name":"Concepts","item":[{"name":"Verification Order Workflow (VOW)","item":[],"id":"98274e1c-ae15-41d6-a997-52e038893812","description":"The most important concept to understand when working with Mesh is the Verification Order Workflow (VOW). When you need to verify a business, you will place a Verification Order Workflow specifying what type and number of verifications need to be applied to that business, and the decisions that will be made based on the results. Mesh will then fulfill the order by performing the verifications requested, and make the results available to you.
\nThe recommended way for you to create a Verification Order Workflow is through Mesh's verification user interface, which is designed to maximize accuracy and conversion rates (successful form submissions). This can be embedded in and launched from your application or website as a popup, or you can let Mesh create a no-code instance and manage this for you. Talk to your customer success representative about the right integration path for you.
\nVerification Order Workflows can also be created through the API, if you need total control of the user experience. We generally recommend this approach only for enterprise customers that are able to implement the same form validations and logic that comes out of the box with Mesh's user interface.
\nThe specification of what verifications will be performed, and the business decisions to be made, is defined in a Verification Order Workflow Configuration. You can use prebuilt Verification Order Workflow Configurations provided by Mesh, or specify your own. Designing your own VOW Configuration is not currently a self-service feature. Work with your customer success representative to understand the prebuilt VOW configurations or to design one to suit your needs.
\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"id":"8bc80837-27f3-46ed-a6cd-be115cfa2c47","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"d5c3a8fd-c2d5-41e8-8473-36ce0762e334","type":"text/javascript","exec":[""]}}],"_postman_id":"98274e1c-ae15-41d6-a997-52e038893812"},{"name":"Business Entity","item":[],"id":"060821b2-613d-4f4f-8108-a0b81f3b6b03","description":"A Business Entity is the subject of a Verification Order Workflow, in other words, the business being verified. We use the term Business Entity rather than \"business\" because Mesh supports verifications for individuals such as professional beauticians, or electricians.
\nEach Verification Order Workflow is concerned with the verification of exactly one Business Entity. However, a Business Entity can be the subject of more than one Verification Order Workflow.
\nA Business Entity may represent a business with many employees and officers. Each individual representing a Business Entity is a Business User, such that many Business Users may be associated with a single Business Entity.
\n","_postman_id":"060821b2-613d-4f4f-8108-a0b81f3b6b03","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"6eac8365-c5ab-4f88-bab5-0a415445f795","id":"6eac8365-c5ab-4f88-bab5-0a415445f795","name":"Concepts","type":"folder"}}}],"id":"6eac8365-c5ab-4f88-bab5-0a415445f795","description":"Let's explore some key concepts to know when working with Mesh.
\nYou can also skip ahead to the Quick Start Guide that will explain these concepts with a worked example for professional license verification.
\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"id":"912b7257-5b9b-4b82-8921-335765beb198","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"6469a339-c582-490e-9344-8265d1d2cd01","type":"text/javascript","exec":[""]}}],"_postman_id":"6eac8365-c5ab-4f88-bab5-0a415445f795"},{"name":"Glossary","item":[],"id":"5c3e6c22-ff95-43e2-b599-fc9dbea246b1","description":"","_postman_id":"5c3e6c22-ff95-43e2-b599-fc9dbea246b1","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":"{{MESH_API_KEY}}"}]},"isInherited":true,"source":{"_postman_id":"31de4fda-3698-44fc-b51f-a1765ce7f509","id":"31de4fda-3698-44fc-b51f-a1765ce7f509","name":"Mesh API Documentation","type":"collection"}}}],"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":"{{MESH_API_KEY}}"}]}},"event":[{"listen":"prerequest","script":{"id":"bfa0048b-b3bc-42a7-ab63-6cff55ff2283","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"341c55d8-f77e-41c5-98f0-11a066056dd4","type":"text/javascript","exec":[""]}}]}