api-quickstart.html

<!DOCTYPE html>

<html lang="en-us">
  <head>
    

    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=Edge">
    <meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>REST API - SheerID Developer Center</title>
    <link rel="stylesheet" href="/assets/css/just-the-docs.css">
    <link rel="stylesheet" href="/assets/css/landingStyle.css">
    <link rel="stylesheet" href="https://services.sheerid.com/docs/sheerid.css" type="text/css" />
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css" />
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.3.1/css/bootstrap.min.css" integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T" crossorigin="anonymous">
    <link rel="stylesheet" href="/assets/css/dropdownStyle.css">

    <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js" integrity="sha384-tsQFqpEReu7ZLhBV2VZlAu7zcOV+rXbYlF2cqB8txI/8aZajjp4Bqd+V6D5IgvKT" crossorigin="anonymous"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.7/umd/popper.min.js" integrity="sha384-UO2eT0CpHqdSJQ6hJty5KVphtPhzWj9WO1clHTMGa3JDZwrnQq4sF86dIHNDz0W1" crossorigin="anonymous"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.3.1/js/bootstrap.min.js" integrity="sha384-JjSmVgyd0p3pXB1rRibZUAYoIIy6OrQ6VrjIEaFf/nJGzIxFDsf4x0xIM+B07jRM" crossorigin="anonymous"></script>
    <script type="text/javascript" src="/assets/js/just-the-docs.js"></script>
</head>
  
  <div class="page-wrap">
    <header class="flex-row">
  <div class="left-items">
    <div id="menuToggle">
        <input type="checkbox" id="mobileMenuIcon"/>

        <!-- Burger Menu made by spans only and CSS style-->
        <span></span>
        <span></span>
        <span></span>

        <ul id="menu">
          <a class="link-mobile-menu menu-version">
            <li>Versions</li>
            <div class="arrow next"></div>
          </a>
          <div class="version-container">
           
          <a class="link-mobile-menu" href="http://developer.sheerid.com/" >
            <li>Latest (v2.0)</li>
            <div class="arrow next"></div>
          </a>
          
          <a class="link-mobile-menu" href="http://docs-v05.sheerid.com/" >
            <li>v0.5</li>
            <div class="arrow next"></div>
          </a>
          
          </div>
          
          <a class="link-mobile-menu" href="/rest-api" >
            <li>REST API reference</li>
            <div class="arrow next"></div>
          </a>
          
          <a class="link-mobile-menu" href="/jslib-api" >
            <li>JS library reference</li>
            <div class="arrow next"></div>
          </a>
          
          <a class="link-mobile-menu" href="/tutorials" >
            <li>tutorials</li>
            <div class="arrow next"></div>
          </a>
          
          <div id="search-mobile" class="search-mobile">
              <input type="text" class="search-input" placeholder="SEARCH" aria-label="Search" autocomplete="off" id="algoliaSearch">
          </div>
        </ul>
    </div>
    <a class="main-logo" href="/"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="118" height="26" viewBox="0 0 118 26">
    <defs>
        <path id="a" d="M.029 0H82.24v25.806H.03z"/>
        <path id="c" d="M.088.062h2.819v2.686H.087z"/>
    </defs>
    <g fill="none" fill-rule="evenodd">
        <g>
            <mask id="b" fill="#fff">
                <use xlink:href="#a"/>
            </mask>
            <path fill="#FFF" d="M57.81 14.534c.174-2.75 2.752-5.501 6.236-5.501 3.483 0 6.061 2.75 6.235 5.5H57.81zm-19.4 0c.173-2.75 2.751-5.501 6.235-5.501 3.483 0 6.06 2.75 6.235 5.5H38.41zm35.472 11.149h3.623V14.84c0-2.683.975-4.11 2.124-4.72.871-.442 2.055-.68 2.612-.68V5.806c-.905.035-3.378.103-4.911 2.209h-.069v-1.7h-3.38v8.558c-.337-5.211-4.76-9.067-9.8-9.067-4.82 0-8.87 3.341-9.724 8.03-.816-4.676-4.978-8.03-9.678-8.03-5.08 0-9.306 3.71-9.836 8.799v-.615c-.035-2.105-.452-3.599-1.219-4.822-1.393-2.106-3.832-3.362-6.827-3.362-.767 0-3.658 0-5.4 2.513h-.07V0h-3.622v16.464c-.477-1.561-1.546-2.96-3.095-3.99-.396-.288-1.771-1.145-4.81-1.742l-.122-.02C7.18 10.253 5.73 9.35 5.73 9.35c-.843-.553-1.367-1.55-1.367-2.602 0-1.77 2.049-3.265 4.472-3.265 1.09 0 2.143.297 2.965.836.957.628 1.506 1.514 1.506 2.43h3.488c0-2.067-1.11-3.98-3.046-5.25C12.335.572 10.636.082 8.835.082c-4.388 0-7.96 2.99-7.96 6.665a6.458 6.458 0 0 0 2.914 5.427c.201.13 2.052 1.29 5.28 1.885l.1.015c2.38.47 3.31 1.094 3.314 1.094l.133.097c1.198.784 1.884 1.903 1.884 3.069 0 2.256-2.47 4.093-5.506 4.093-1.33 0-2.615-.364-3.623-1.024-1.197-.786-1.883-1.904-1.883-3.07H0c0 2.316 1.248 4.463 3.425 5.891l.973-1.41-.972 1.41c1.6 1.049 3.524 1.603 5.568 1.603 4.185 0 7.712-2.395 8.71-5.626v5.391h3.624V14.874c0-3.77 2.055-5.841 5.085-5.841 4.808 0 4.808 4.414 4.808 5.875v10.685h3.622v-8.862c.523 4.873 4.658 8.874 9.767 8.874 2.995 0 7.42-1.53 9.266-6.385h-3.624c-.87 1.63-2.821 3.158-5.503 3.158-2.439 0-5.434-1.494-6.34-5.128h15.906c.75 4.634 4.77 8.355 9.696 8.355 2.995 0 7.42-1.53 9.266-6.385h-3.623c-.87 1.63-2.821 3.158-5.504 3.158-2.438 0-5.434-1.494-6.34-5.128h16.063l.009 8.433z" mask="url(#b)"/>
        </g>
        <path fill="#E01E45" d="M84.449.158v25.436h6.216V.158zM104.174 19.673l-5.58-5.501V6.928l5.58 5.502 8.026-7.914C108.845.106 103.866.104 101.042.104h-4.479v.008h-4.087v25.571h9.055c9.815 0 13.307-5.876 13.307-12.859 0-1.13-.099-2.247-.33-3.339l-10.334 10.188zM113.566 23.566h-.543v-.603h1.786v.603h-.539v2.082h-.704z"/>
        <g transform="translate(115.006 22.9)">
            <mask id="d" fill="#fff">
                <use xlink:href="#c"/>
            </mask>
            <path fill="#E01E45" d="M.088.062h.904L1.54 1.83h.006l.54-1.768h.908v2.686h-.648L2.37.738 2.362.73l-.588 2.018h-.466L.72.73.713.738l.022 2.01H.088z" mask="url(#d)"/>
        </g>
    </g>
</svg>
</a>
    
      <a class="main-menu-item" href="/rest-api" >REST API reference</a>
    
      <a class="main-menu-item" href="/jslib-api" >JS library reference</a>
    
      <a class="main-menu-item" href="/tutorials" >tutorials</a>
    
  </div>

  <div class="right-items">
    <div class="dropdown version">
      <button class="btn btn-secondary btn-sm dropdown-toggle button-link" type="button" id="dropdownMenuButton" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">v2.0</button>
      <div class="dropdown-menu menu" aria-labelledby="dropdownMenuButton">
        
        <a class="dropdown-item active version-link" href="http://developer.sheerid.com/">Latest (v2.0)</a>
        
        <a class="dropdown-item  version-link" href="http://docs-v05.sheerid.com/">v0.5</a>
        
      </div>
    </div>

    
    <div class="search">
      <div class="search-input-wrap">
        <input type="text" class="search-input hide" placeholder="Search" aria-label="Search" autocomplete="off" id="algoliaSearchDesktop">
        <img id="searchIcon" class="search-icon" src="https://23s6x22phk5q33910hihb4ku-wpengine.netdna-ssl.com/wp-content/uploads/2018/12/MagGlass_icon_45deg.png">
      </div>
    </div>
    <div class="js-search-results search-results-wrap"></div>
  </div>
  <script>
    $('.menu-version').on('click', function(){
	    $('.version-container').toggle();
    })
  </script>
  <script src="/assets/js/mobileMenu.js" ></script>
</header>

    <div class="side-bar">
  <div class="site-title fs-6 lh-tight">Developer Center</div>
  <span class="fs-3"><button class="js-main-nav-trigger navigation-list-toggle btn btn-outline" type="button" data-text-toggle="Hide">Menu</button></span>
  <div class="navigation main-nav js-main-nav">
    <nav>
  <ul class="navigation-list">
    
    
          <li class="navigation-list-item">
            
            <a href="https://pfd.github.io/introduction" class="navigation-list-link">What We Offer</a>
            
          </li>
        
      
          <li class="navigation-list-item">
            
            <a href="https://pfd.github.io/concepts" class="navigation-list-link">How it Works</a>
            
          </li>
        
      
          <li class="navigation-list-item">
            
            <a href="https://pfd.github.io/getting-started" class="navigation-list-link">Getting Started</a>
            
              
              <ul class="navigation-list-child-list ">
                
                  
              </ul>
            
          </li>
        
      
          <li class="navigation-list-item">
            
            <a href="https://pfd.github.io/program-settings" class="navigation-list-link">Program Settings</a>
            
              
              <ul class="navigation-list-child-list ">
                
                  
              </ul>
            
          </li>
        
      
          <li class="navigation-list-item">
            
            <a href="https://pfd.github.io/js-library" class="navigation-list-link">JavaScript Library</a>
            
          </li>
        
      
          <li class="navigation-list-item active">
            
            <a href="https://pfd.github.io/api-quickstart" class="navigation-list-link active">REST API</a>
            
          </li>
        
      
          <li class="navigation-list-item">
            
            <a href="https://pfd.github.io/tutorials" class="navigation-list-link">Tutorials</a>
            
              
              <ul class="navigation-list-child-list ">
                
                  
                    <li class="navigation-list-item ">
                      
                      <a href="https://pfd.github.io/tutorials/api-walkthrough" class="navigation-list-link">API Walkthrough</a>
                      
                    </li>
                  
                
                    <li class="navigation-list-item ">
                      
                      <a href="https://pfd.github.io/tutorials/verification-limit" class="navigation-list-link">Verification Limit</a>
                      
                    </li>
                  
                
                    <li class="navigation-list-item ">
                      
                      <a href="https://pfd.github.io/tutorials/webhooks" class="navigation-list-link">Creating Webhooks</a>
                      
                    </li>
                  
                
                    <li class="navigation-list-item ">
                      
                      <a href="https://pfd.github.io/tutorials/fetching-organizations" class="navigation-list-link">Searching Organizations</a>
                      
                    </li>
                  
                
              </ul>
            
          </li>
        
      
          <li class="navigation-list-item">
            
            <a href="https://pfd.github.io/reporting" class="navigation-list-link">Reporting</a>
            
              
              <ul class="navigation-list-child-list ">
                
                  
                    <li class="navigation-list-item ">
                      
                      <a href="https://pfd.github.io/reporting/glossary" class="navigation-list-link">Reporting Glossary</a>
                      
                    </li>
                  
                
              </ul>
            
          </li>
        
      
          <li class="navigation-list-item">
            
            <a href="https://pfd.github.io/reference" class="navigation-list-link">Reference</a>
            
          </li>
        
      
  </ul>
</nav>
  </div>
</div>

    
    <nav class="right-side-bar" id="nava">
      <div class="toc-title">table of contents</div>
      <ul class="toc-content-style">
<li class="toc-entry toc-h2"><a href="#basics">Basics</a>
<ul class="toc-sublist-style">
<li class="toc-entry toc-h3"><a href="#base-url">Base URL</a></li>
<li class="toc-entry toc-h3"><a href="#authentication">Authentication</a></li>
</ul>
</li>
<li class="toc-entry toc-h2"><a href="#retrieve-theme">Retrieve Theme</a></li>
<li class="toc-entry toc-h2"><a href="#retrieve-verification-segment">Retrieve Verification Segment</a></li>
<li class="toc-entry toc-h2"><a href="#verify-a-user">Verify a User</a>
<ul class="toc-sublist-style">
<li class="toc-entry toc-h3"><a href="#success">Success</a></li>
<li class="toc-entry toc-h3"><a href="#document-review">Document Review</a></li>
<li class="toc-entry toc-h3"><a href="#pending">Pending</a></li>
<li class="toc-entry toc-h3"><a href="#getting-current-status">Getting Current Status</a></li>
<li class="toc-entry toc-h3"><a href="#program-theme">Program Theme</a></li>
<li class="toc-entry toc-h3"><a href="#internationalization-i18n">Internationalization (i18n)</a></li>
<li class="toc-entry toc-h3"><a href="#errorid">ErrorId</a></li>
<li class="toc-entry toc-h3"><a href="#custom-css">Custom CSS</a></li>
</ul>
</li>
<li class="toc-entry toc-h2"><a href="#errors">Errors</a>
<ul class="toc-sublist-style">
<li class="toc-entry toc-h3"><a href="#recoverable-errors">Recoverable Errors</a></li>
<li class="toc-entry toc-h3"><a href="#non-recoverable-errors">Non Recoverable Errors</a></li>
</ul>
</li>
</ul>
    </nav>
    
  </div>
  <div class="main-content-wrap" id="maincontent">
    <div class="main-content">
      <div class="page-content">
        
        <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.6.3/css/all.css" integrity="sha384-UHRtZLI+pbxtHCWp1t77Bi1L4ZtiqrqD80Kn4Z8NTSRyMA2Fd33n5dQ8lWUE00s/" crossorigin="anonymous">
<link rel="stylesheet" href="/custom.css">

<div markdown="span" class="warning">
<i class="fa fa-exclamation-circle"></i> <b>Warning:</b>
This is a development preview.
</div>


        <div class="col-12 col-md-9 col-xl-8 py-md-3 pl-md-5 bd-content" role="main">
  <h1 class="bd-title" id="content">REST API</h1>
  <p class="bd-lead">For advanced implementations, you may use our REST API directly and bypass the JavaScript library as an API client. This section will introduce you to the basics of our REST API, including how to handle responses, errors, and to move successfully from step to step. See our <a href="/rest-api">REST API reference</a> for details.</p>
</div>

<h2 id="basics">Basics</h2>

<p>The SheerID API is organized around <a href="https://en.wikipedia.org/wiki/Representational_state_transfer">REST</a>.</p>

<h3 id="base-url">Base URL</h3>

<p>The base URL for the SheerID REST API is <code class="highlighter-rouge">https://services.sheerid.com/rest/v2/</code>.</p>

<p>The current version is <span id="api-version">2.0.0</span>.</p>

<h3 id="authentication">Authentication</h3>

<p>Certain endpoints require a Bearer Token for authentication. Retrieve your access token from
<a href="https://my.sheerid.com" target="_blank">MySheerID</a> under <em>Settings</em> »» <em>Access Tokens</em>.</p>

<div class="language-http highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nf">GET</span> <span class="nn">/rest/v2/info</span> <span class="k">HTTP</span><span class="o">/</span><span class="m">1.1</span>
<span class="na">Content-Type</span><span class="p">:</span> <span class="s">application/json</span>
<span class="na">Authorization</span><span class="p">:</span> <span class="s">Bearer {YOUR_ACCESS_TOKEN}</span>
</code></pre></div></div>

<script>
jQuery(function($){
    $.getJSON('https://services.sheerid.com/rest/v2/info').done(function(info) {
        $('#api-version').text(info.sheeridVersion);
    });
});
</script>

<h2 id="retrieve-theme">Retrieve Theme</h2>

<p>If you would like to use the CSS and messaging that you configured at <a href="https://my.sheerid.com" target="_blank">MySheerID</a>, then you must first fetch the
<a href="/api-quickstart#program-theme">program theme</a>. To do this, make a <code class="highlighter-rouge">GET</code> request to the  <code class="highlighter-rouge">/program/{programId}/theme</code> endpoint:</p>

<div class="language-http highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nf">GET</span> <span class="nn">/rest/v2/program/&lt;YOUR_PROGRAM_ID&gt;/theme</span> <span class="k">HTTP</span><span class="o">/</span><span class="m">1.1</span>
<span class="na">Host</span><span class="p">:</span> <span class="s">services.sheerid.com</span>
<span class="na">Content-Type</span><span class="p">:</span> <span class="s">application/json</span>
</code></pre></div></div>

<p>See <a href="/api-quickstart#program-theme">Program Theme</a> for
more information about what is contained in the program theme object, and <a href="/rest-api#program/getProgramTheme">Get Program Theme</a> for the
detailed API reference.</p>

<h2 id="retrieve-verification-segment">Retrieve Verification Segment</h2>

<p>Now we need to begin a verification. This will retrieve what kind of segment you will be verifying against (Student, Active Military, Inactive Military, Teacher, etc.).</p>

<p>To retrieve the initial step for your <a href="/concepts#flows">flow</a>, make the following <code class="highlighter-rouge">POST</code> request:</p>

<div class="language-http highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nf">POST</span> <span class="nn">/rest/v2/verification</span> <span class="k">HTTP</span><span class="o">/</span><span class="m">1.1</span>
<span class="na">Content-Type</span><span class="p">:</span> <span class="s">application/json</span>
<span class="na">Authorization</span><span class="p">:</span> <span class="s">Bearer &lt;YOUR_ACCESS_TOKEN&gt;</span>

<span class="p">{</span><span class="w">
    </span><span class="s2">"programId"</span><span class="p">:</span><span class="w"> </span><span class="s2">"&lt;YOUR_PROGRAM_ID&gt;"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>

<p>Response:</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
    </span><span class="s2">"verificationId"</span><span class="p">:</span><span class="w"> </span><span class="s2">"111111111111111111111111"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">Verification</span><span class="w"> </span><span class="err">ID</span><span class="w"> </span><span class="err">that</span><span class="w"> </span><span class="err">should</span><span class="w"> </span><span class="err">be</span><span class="w"> </span><span class="err">used</span><span class="w"> </span><span class="err">for</span><span class="w"> </span><span class="err">all</span><span class="w"> </span><span class="err">future</span><span class="w"> </span><span class="err">calls</span><span class="w">
    </span><span class="s2">"currentStep"</span><span class="p">:</span><span class="w"> </span><span class="s2">"collectStudentPersonalInfo"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">step</span><span class="w"> </span><span class="err">in</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">verification</span><span class="w"> </span><span class="err">flow</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">current</span><span class="w"> </span><span class="err">verification</span><span class="w"> </span><span class="err">is</span><span class="w"> </span><span class="err">on</span><span class="w">
    </span><span class="s2">"submissionUrl"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://services.sheerid.com/rest/v2/verification/111111111111111111111111/step/collectStudentPersonalInfo"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">URL</span><span class="w"> </span><span class="err">to</span><span class="w"> </span><span class="err">hit</span><span class="w"> </span><span class="err">for</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">current</span><span class="w"> </span><span class="err">step</span><span class="w">
    </span><span class="s2">"errorIds"</span><span class="p">:</span><span class="w"> </span><span class="p">[],</span><span class="w">
    </span><span class="s2">"segment"</span><span class="p">:</span><span class="w"> </span><span class="s2">"student"</span><span class="p">,</span><span class="w">
    </span><span class="s2">"subSegment"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>

<p>At this point a verification has begun and can be referenced with the <code class="highlighter-rouge">verificationId</code>, in the example case <code class="highlighter-rouge">111111111111111111111111</code>. This ID will be used for all
future interactions with this verification ID.</p>

<h2 id="verify-a-user">Verify a User</h2>

<p>Now that we have our step (in our demo case we are verifying a student, so our step is <code class="highlighter-rouge">collectStudentPersonalInfo</code>), we can submit a verification subject to verify.
We will be submitting a student for verification, so we will need to fill out this structure:</p>

<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
    </span><span class="s2">"firstName"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span><span class="w">
    </span><span class="s2">"lastName"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span><span class="w">
    </span><span class="s2">"birthDate"</span><span class="p">:</span><span class="w"> </span><span class="s2">"YYYY-MM-DD"</span><span class="p">,</span><span class="w">
    </span><span class="s2">"email"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span><span class="w">
    </span><span class="s2">"organization"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="s2">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span><span class="w">
        </span><span class="s2">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="w">
    </span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>

<p><a href="/jslib-api">Schemas for all verification subjects can be found here</a>.</p>

<p>Once all data has been collected, make a <code class="highlighter-rouge">POST</code> call to the URL collected in the previous step’s <code class="highlighter-rouge">submissionUrl</code> response with the data, e.g.</p>

<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
    </span><span class="s2">"firstName"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Randy"</span><span class="p">,</span><span class="w">
    </span><span class="s2">"lastName"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Random"</span><span class="p">,</span><span class="w">
    </span><span class="s2">"birthDate"</span><span class="p">:</span><span class="w"> </span><span class="s2">"YYYY-MM-DD"</span><span class="p">,</span><span class="w">
    </span><span class="s2">"email"</span><span class="p">:</span><span class="w"> </span><span class="s2">"name@example.com"</span><span class="p">,</span><span class="w">
    </span><span class="s2">"organization"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="s2">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w">
        </span><span class="s2">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Organization name"</span><span class="w">
    </span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>

<p>This example will cause an instant success response because it uses any name in the First Name field. The only string that wouldn’t work in this example is <code class="highlighter-rouge">REJECTED</code>.
Using <code class="highlighter-rouge">REJECTED</code> as the value for <code class="highlighter-rouge">firstName</code> would yield an unsuccessful verification and take you to the <code class="highlighter-rouge">docUpload</code> step.</p>

<p>To see comprehensive testing rules, see the <a href="/getting-started#test-program">Test Program</a> documentation.</p>

<h3 id="success">Success</h3>

<p>If the verification was successful, then you will receive a response like this:</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
    </span><span class="s2">"verificationId"</span><span class="p">:</span><span class="w"> </span><span class="s2">"111111111111111111111111"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">Verification</span><span class="w"> </span><span class="err">ID</span><span class="w"> </span><span class="err">that</span><span class="w"> </span><span class="err">should</span><span class="w"> </span><span class="err">be</span><span class="w"> </span><span class="err">used</span><span class="w"> </span><span class="err">for</span><span class="w"> </span><span class="err">all</span><span class="w"> </span><span class="err">future</span><span class="w"> </span><span class="err">calls</span><span class="w">
    </span><span class="s2">"currentStep"</span><span class="p">:</span><span class="w"> </span><span class="s2">"success"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">step</span><span class="w"> </span><span class="err">in</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">verification</span><span class="w"> </span><span class="err">flow</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">current</span><span class="w"> </span><span class="err">verification</span><span class="w"> </span><span class="err">is</span><span class="w"> </span><span class="err">on</span><span class="w">
    </span><span class="s2">"rewardCode"</span><span class="p">:</span><span class="w"> </span><span class="s2">"REWARD"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">reward</span><span class="w"> </span><span class="err">code</span><span class="w"> </span><span class="err">that</span><span class="w"> </span><span class="err">was</span><span class="w"> </span><span class="err">configured</span><span class="w"> </span><span class="err">in</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">self</span><span class="w"> </span><span class="err">service</span><span class="w"> </span><span class="err">tool</span><span class="w">
    </span><span class="s2">"errorIds"</span><span class="p">:</span><span class="w"> </span><span class="p">[],</span><span class="w">
    </span><span class="s2">"segment"</span><span class="p">:</span><span class="w"> </span><span class="s2">"student"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">current</span><span class="w"> </span><span class="err">segment</span><span class="w"> </span><span class="err">we</span><span class="w"> </span><span class="err">are</span><span class="w"> </span><span class="err">verifying</span><span class="w">
    </span><span class="s2">"subSegment"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">current</span><span class="w"> </span><span class="err">subsegment</span><span class="w"> </span><span class="err">we</span><span class="w"> </span><span class="err">are</span><span class="w"> </span><span class="err">verifying</span><span class="w"> </span><span class="err">if</span><span class="w"> </span><span class="err">applicable</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>

<p>After providing the <code class="highlighter-rouge">rewardCode</code> to your user to be used in your system, you’re done!</p>

<h3 id="document-review">Document Review</h3>

<p>If the verification was unsuccessful, then you will need to collect document(s) that prove the user is part of the verification segment to be provided to SheerID
for review. The document review response will be returned after submitting the personal info of the user if the user could not be verified instantly, and will look
something like this:</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
    </span><span class="s2">"verificationId"</span><span class="p">:</span><span class="w"> </span><span class="s2">"111111111111111111111111"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">Verification</span><span class="w"> </span><span class="err">ID</span><span class="w"> </span><span class="err">that</span><span class="w"> </span><span class="err">should</span><span class="w"> </span><span class="err">be</span><span class="w"> </span><span class="err">used</span><span class="w"> </span><span class="err">for</span><span class="w"> </span><span class="err">all</span><span class="w"> </span><span class="err">future</span><span class="w"> </span><span class="err">calls</span><span class="w">
    </span><span class="s2">"currentStep"</span><span class="p">:</span><span class="w"> </span><span class="s2">"docUpload"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">step</span><span class="w"> </span><span class="err">in</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">verification</span><span class="w"> </span><span class="err">flow</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">current</span><span class="w"> </span><span class="err">verification</span><span class="w"> </span><span class="err">is</span><span class="w"> </span><span class="err">on</span><span class="w">
    </span><span class="s2">"submissionUrl"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://services.sheerid.com/rest/v2/verification/111111111111111111111111/step/docUpload/1234"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">URL</span><span class="w"> </span><span class="err">to</span><span class="w"> </span><span class="err">hit</span><span class="w"> </span><span class="err">for</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">current</span><span class="w"> </span><span class="err">step</span><span class="w">
    </span><span class="s2">"errorIds"</span><span class="p">:</span><span class="w"> </span><span class="p">[],</span><span class="w">
    </span><span class="s2">"segment"</span><span class="p">:</span><span class="w"> </span><span class="s2">"student"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">audience</span><span class="w"> </span><span class="err">segment</span><span class="w"> </span><span class="err">targeted</span><span class="w"> </span><span class="err">in</span><span class="w"> </span><span class="err">your</span><span class="w"> </span><span class="err">program</span><span class="w">
    </span><span class="s2">"subSegment"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">audience</span><span class="w"> </span><span class="err">subsegment</span><span class="p">,</span><span class="w"> </span><span class="err">if</span><span class="w"> </span><span class="err">applicable</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>

<p>After collecting the documents, they should be submitted to SheerID by making a <code class="highlighter-rouge">POST</code> request to the <code class="highlighter-rouge">submissionUrl</code> provided in the doc upload response. This
request must use the <code class="highlighter-rouge">multipart/form-data</code> <code class="highlighter-rouge">Content-Type</code> header, and should specify each file with a key beginning with <code class="highlighter-rouge">file</code> e.g.</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>file1=first file...
file2=second file...
file3=third file...
</code></pre></div></div>

<p>Once all files have been submitted, you will receive a <code class="highlighter-rouge">pending</code> response.</p>

<h3 id="pending">Pending</h3>

<p>If documents have been successfully uploaded to SheerID for review, then you will receive a response that looks like this:</p>

<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
    </span><span class="s2">"verificationId"</span><span class="p">:</span><span class="w"> </span><span class="s2">"111111111111111111111111"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">Verification</span><span class="w"> </span><span class="err">ID</span><span class="w"> </span><span class="err">that</span><span class="w"> </span><span class="err">should</span><span class="w"> </span><span class="err">be</span><span class="w"> </span><span class="err">used</span><span class="w"> </span><span class="err">for</span><span class="w"> </span><span class="err">all</span><span class="w"> </span><span class="err">future</span><span class="w"> </span><span class="err">calls</span><span class="w">
    </span><span class="s2">"currentStep"</span><span class="p">:</span><span class="w"> </span><span class="s2">"pending"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">step</span><span class="w"> </span><span class="err">in</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">verification</span><span class="w"> </span><span class="err">flow</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">current</span><span class="w"> </span><span class="err">verification</span><span class="w"> </span><span class="err">is</span><span class="w"> </span><span class="err">on</span><span class="w">
    </span><span class="s2">"statusUrl"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://services.sheerid.com/rest/v2/verification/111111111111111111111111"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">URL</span><span class="w"> </span><span class="err">to</span><span class="w"> </span><span class="err">poll</span><span class="w"> </span><span class="err">for</span><span class="w"> </span><span class="err">current</span><span class="w"> </span><span class="err">status</span><span class="w">
    </span><span class="s2">"errorIds"</span><span class="p">:</span><span class="w"> </span><span class="p">[],</span><span class="w">
    </span><span class="s2">"segment"</span><span class="p">:</span><span class="w"> </span><span class="s2">"student"</span><span class="p">,</span><span class="w">
    </span><span class="s2">"subSegment"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>

<p>The <code class="highlighter-rouge">statusUrl</code> is the URL used to retrieve the current status of the verification. This endpoint can be polled to watch for changes to the verification state. If
a document review is completed and marked successful (the document proved the user was associated with the segment), then you will receive the <code class="highlighter-rouge">success</code> response.
If the document review was marked rejected (the document did not prove the user was associated with the segment), the you will receive the <code class="highlighter-rouge">docUpload</code> response so
the user has a chance to upload different documentation. The user has a limited number of times they can perform this operation. If the document review is still in
progress, you will continue to get the <code class="highlighter-rouge">pending</code> response.</p>

<h3 id="getting-current-status">Getting Current Status</h3>

<p>The current status of a verification can be retrieved at any time by making a <code class="highlighter-rouge">GET</code> request to <code class="highlighter-rouge">https://services.sheerid.com/rest/v2/verification/{verificationId}</code>. The
response from this endpoint will match the responses you get a various points through the flow (<code class="highlighter-rouge">success</code>, <code class="highlighter-rouge">docUpload</code>, <code class="highlighter-rouge">pending</code>, <code class="highlighter-rouge">error</code>, etc.). This endpoint can be
used to continue a verificaiton that was halted at any point.</p>

<h3 id="program-theme">Program Theme</h3>

<p>The program theme object contains all theme and messaging information that was configured for a program in the self-service tool at <a href="https://my.sheerid.com" target="_blank">MySheerID</a>. The theme includes a full CSS stylesheet
that can be included when rendering the form (as long as CSS selectors match), and any messaging that should be used throughout the verification process, including
field labels, success messages, etc.</p>

<h3 id="internationalization-i18n">Internationalization (i18n)</h3>

<p>The program theme contains an <code class="highlighter-rouge">intl</code> property which is a structured JSON object containing translated messaging to use when rendering the forms to collect the data
necessary for the verification flow. This object will also include custom messaging that was configured in the self-service tool.</p>

<h3 id="errorid">ErrorId</h3>

<p>The <code class="highlighter-rouge">errorId</code> property under the <code class="highlighter-rouge">intl</code> property can be used to find error messaging to display to users when a given error is thrown. Any time a response has an
<code class="highlighter-rouge">errorIds</code> property, it means an error occurred and appropriate messaging should be looked up here in the program theme based on the error ID that was returned.</p>

<h3 id="custom-css">Custom CSS</h3>

<p>The <code class="highlighter-rouge">customCss</code> property on the program theme contains a CSS stylesheet as it was configured in the self-service tool. This is heavily reliant on certain selectors
existing on the page, so it may or may not be useful when not using the JavaScript library.</p>

<h2 id="errors">Errors</h2>

<p>Any response while interacting with the API could be an error response. There are two types of possible errors: recoverable and non-recoverable.</p>

<h3 id="recoverable-errors">Recoverable Errors</h3>

<p>A recoverable error will include the step the verification was on before the error occurred. So if you were attempting to submit a student subject for the <code class="highlighter-rouge">collectStudentPersonalInfo</code> step, you could receive this response:</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
    </span><span class="s2">"verificationId"</span><span class="p">:</span><span class="w"> </span><span class="s2">"111111111111111111111111"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">Verification</span><span class="w"> </span><span class="err">ID</span><span class="w"> </span><span class="err">that</span><span class="w"> </span><span class="err">should</span><span class="w"> </span><span class="err">be</span><span class="w"> </span><span class="err">used</span><span class="w"> </span><span class="err">for</span><span class="w"> </span><span class="err">all</span><span class="w"> </span><span class="err">future</span><span class="w"> </span><span class="err">calls</span><span class="w">
    </span><span class="s2">"currentStep"</span><span class="p">:</span><span class="w"> </span><span class="s2">"collectStudentPersonalInfo"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">step</span><span class="w"> </span><span class="err">in</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">verification</span><span class="w"> </span><span class="err">flow</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">current</span><span class="w"> </span><span class="err">verification</span><span class="w"> </span><span class="err">is</span><span class="w"> </span><span class="err">on</span><span class="w">
    </span><span class="s2">"errorIds"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
        </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">errors</span><span class="w"> </span><span class="err">that</span><span class="w"> </span><span class="err">occurred</span><span class="w"> </span><span class="err">when</span><span class="w"> </span><span class="err">attempting</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">step</span><span class="w">
    </span><span class="p">],</span><span class="w">
    </span><span class="s2">"segment"</span><span class="p">:</span><span class="w"> </span><span class="s2">"student"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">current</span><span class="w"> </span><span class="err">segment</span><span class="w"> </span><span class="err">you</span><span class="w"> </span><span class="err">are</span><span class="w"> </span><span class="err">verifying</span><span class="w">
    </span><span class="s2">"subSegment"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">current</span><span class="w"> </span><span class="err">subsegment</span><span class="w"> </span><span class="err">you</span><span class="w"> </span><span class="err">are</span><span class="w"> </span><span class="err">verifying</span><span class="w"> </span><span class="err">if</span><span class="w"> </span><span class="err">applicable</span><span class="w">
    </span><span class="s2">"submissionUrl"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://submission-url.com"</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">URL</span><span class="w"> </span><span class="err">to</span><span class="w"> </span><span class="err">submit</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">person</span><span class="w"> </span><span class="err">data</span><span class="w"> </span><span class="err">to</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
<p>The <code class="highlighter-rouge">errorIds</code> will indicate what went wrong, but since the <code class="highlighter-rouge">currentStep</code> is not <code class="highlighter-rouge">error</code> it means the issue could be corrected. These errors occur when bad data was
supplied, e.g. an invalid birth date, invalid email, invalid organization, etc.</p>

<h4 id="messages">Messages</h4>

<p>Recoverable errors can be caused by invalid entries from the user, so the messaging that should be shown can be found in the <a href="/api-quickstart#program-theme">program theme</a>.
of the response that was returned. The messaging found in the <code class="highlighter-rouge">errorId</code> section of the messages should be appropriate to show users.</p>

<h4 id="example">Example</h4>

<p>When submitting a student subject for the <code class="highlighter-rouge">collectStudentPersonalInfo</code> if you sent this request:</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
    </span><span class="s2">"firstName"</span><span class="p">:</span><span class="w"> </span><span class="s2">"First"</span><span class="p">,</span><span class="w">
    </span><span class="s2">"lastName"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Last"</span><span class="p">,</span><span class="w">
    </span><span class="s2">"birthDate"</span><span class="p">:</span><span class="w"> </span><span class="s2">"1-1-1"</span><span class="p">,</span><span class="w">
    </span><span class="s2">"email"</span><span class="p">:</span><span class="w"> </span><span class="s2">"notValidEmail,com"</span><span class="p">,</span><span class="w">
    </span><span class="s2">"organization"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
        </span><span class="s2">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w">
        </span><span class="s2">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Organization name"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>

<p>You would receive the following <code class="highlighter-rouge">errorId</code>s:</p>

<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
    </span><span class="s2">"verificationId"</span><span class="p">:</span><span class="w"> </span><span class="s2">"111111111111111111111111"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">Verification</span><span class="w"> </span><span class="err">ID</span><span class="w"> </span><span class="err">that</span><span class="w"> </span><span class="err">should</span><span class="w"> </span><span class="err">be</span><span class="w"> </span><span class="err">used</span><span class="w"> </span><span class="err">for</span><span class="w"> </span><span class="err">all</span><span class="w"> </span><span class="err">future</span><span class="w"> </span><span class="err">calls</span><span class="w">
    </span><span class="s2">"currentStep"</span><span class="p">:</span><span class="w"> </span><span class="s2">"collectStudentPersonalInfo"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">step</span><span class="w"> </span><span class="err">in</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">verification</span><span class="w"> </span><span class="err">flow</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">current</span><span class="w"> </span><span class="err">verification</span><span class="w"> </span><span class="err">is</span><span class="w"> </span><span class="err">on</span><span class="w">
    </span><span class="s2">"errorIds"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
        </span><span class="s2">"invalidBirthDate"</span><span class="p">,</span><span class="w">
        </span><span class="s2">"invalidEmail"</span><span class="w">
    </span><span class="p">],</span><span class="w">
    </span><span class="s2">"segment"</span><span class="p">:</span><span class="w"> </span><span class="s2">"student"</span><span class="p">,</span><span class="w">
    </span><span class="s2">"subSegment"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>

<p>This lets you know that you need to perform the <code class="highlighter-rouge">collectStudentPersonalInfo</code> step again, and you should find the <code class="highlighter-rouge">invalidBirthDate</code> and <code class="highlighter-rouge">invalidEmail</code> messages in the
<a href="/api-quickstart#program-theme">program theme</a> to find the message to display to the user.</p>

<h3 id="non-recoverable-errors">Non Recoverable Errors</h3>

<p>A non recoverable error will have <code class="highlighter-rouge">error</code> as the <code class="highlighter-rouge">currentStep</code> and will provide both a list of <code class="highlighter-rouge">errorIds</code> as well as a <code class="highlighter-rouge">systemErrorMessage</code> that can be used to determine
what caused the failure to assist with debugging. An example error response would look like this:</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
    </span><span class="s2">"verificationId"</span><span class="p">:</span><span class="w"> </span><span class="s2">"111111111111111111111111"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">Verification</span><span class="w"> </span><span class="err">ID</span><span class="w"> </span><span class="err">that</span><span class="w"> </span><span class="err">should</span><span class="w"> </span><span class="err">be</span><span class="w"> </span><span class="err">used</span><span class="w"> </span><span class="err">for</span><span class="w"> </span><span class="err">all</span><span class="w"> </span><span class="err">future</span><span class="w"> </span><span class="err">calls</span><span class="w">
    </span><span class="s2">"currentStep"</span><span class="p">:</span><span class="w"> </span><span class="s2">"error"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">step</span><span class="w"> </span><span class="err">in</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">verification</span><span class="w"> </span><span class="err">flow</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">current</span><span class="w"> </span><span class="err">verification</span><span class="w"> </span><span class="err">is</span><span class="w"> </span><span class="err">on</span><span class="w">
    </span><span class="s2">"errorIds"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
        </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">errors</span><span class="w"> </span><span class="err">that</span><span class="w"> </span><span class="err">occurred</span><span class="w"> </span><span class="err">when</span><span class="w"> </span><span class="err">attempting</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">step</span><span class="w">
    </span><span class="p">],</span><span class="w">
    </span><span class="s2">"systemErrorMessage"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Debugging message"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">A</span><span class="w"> </span><span class="err">description</span><span class="w"> </span><span class="err">of</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">cause</span><span class="w"> </span><span class="err">for</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">error</span><span class="w"> </span><span class="err">to</span><span class="w"> </span><span class="err">aid</span><span class="w"> </span><span class="err">with</span><span class="w"> </span><span class="err">debugging</span><span class="w">
    </span><span class="s2">"segment"</span><span class="p">:</span><span class="w"> </span><span class="s2">"student"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">current</span><span class="w"> </span><span class="err">segment</span><span class="w"> </span><span class="err">we</span><span class="w"> </span><span class="err">are</span><span class="w"> </span><span class="err">verifying</span><span class="w">
    </span><span class="s2">"subSegment"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">current</span><span class="w"> </span><span class="err">subsegment</span><span class="w"> </span><span class="err">we</span><span class="w"> </span><span class="err">are</span><span class="w"> </span><span class="err">verifying</span><span class="w"> </span><span class="err">if</span><span class="w"> </span><span class="err">applicable</span><span class="w">
    </span><span class="s2">"submissionUrl"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://submission-url.com"</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">URL</span><span class="w"> </span><span class="err">to</span><span class="w"> </span><span class="err">submit</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">person</span><span class="w"> </span><span class="err">data</span><span class="w"> </span><span class="err">to</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>

<p>These errors occur when programs or verifications are not found, when internal SheerID errors occur, or when a step can not be completed for a non-user related reason.</p>

<h4 id="messages-1">Messages</h4>

<p>The supplied <code class="highlighter-rouge">errorIds</code> can be used to look up the user facing messages in the <a href="/api-quickstart#program-theme">program theme</a> just like for recoverable errors, however
these can potentially be much more generic messages and difficult to understand. So to provide feedback for the integrator, the <code class="highlighter-rouge">systemErrorMessage</code> property can be used
to understand what went wrong. These messages are NOT intended to be displayed to users, they are only for the integrators benefit.</p>

<h4 id="example-1">Example</h4>

<p>When submitting a student subject for the <code class="highlighter-rouge">collectStudentPersonalInfo</code> step, if you sent this request:</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
    </span><span class="s2">"firstName"</span><span class="p">:</span><span class="w"> </span><span class="s2">"First"</span><span class="p">,</span><span class="w">
    </span><span class="s2">"lastName"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Last"</span><span class="p">,</span><span class="w">
    </span><span class="s2">"birthDate"</span><span class="p">:</span><span class="w"> </span><span class="s2">"1-1-1"</span><span class="p">,</span><span class="w">
    </span><span class="s2">"email"</span><span class="p">:</span><span class="w"> </span><span class="s2">"notValidEmail,com"</span><span class="p">,</span><span class="w">
    </span><span class="s2">"invalidKey"</span><span class="p">:</span><span class="w"> </span><span class="s2">"something"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>

<p>You would receive the following error response:</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
    </span><span class="s2">"verificationId"</span><span class="p">:</span><span class="w"> </span><span class="s2">"111111111111111111111111"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">Verification</span><span class="w"> </span><span class="err">ID</span><span class="w"> </span><span class="err">that</span><span class="w"> </span><span class="err">should</span><span class="w"> </span><span class="err">be</span><span class="w"> </span><span class="err">used</span><span class="w"> </span><span class="err">for</span><span class="w"> </span><span class="err">all</span><span class="w"> </span><span class="err">future</span><span class="w"> </span><span class="err">calls</span><span class="w">
    </span><span class="s2">"currentStep"</span><span class="p">:</span><span class="w"> </span><span class="s2">"error"</span><span class="p">,</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">The</span><span class="w"> </span><span class="err">step</span><span class="w"> </span><span class="err">in</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">verification</span><span class="w"> </span><span class="err">flow</span><span class="w"> </span><span class="err">the</span><span class="w"> </span><span class="err">current</span><span class="w"> </span><span class="err">verification</span><span class="w"> </span><span class="err">is</span><span class="w"> </span><span class="err">on</span><span class="w">
    </span><span class="s2">"errorIds"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
        </span><span class="s2">"invalidRequest"</span><span class="w">
    </span><span class="p">],</span><span class="w">
    </span><span class="s2">"systemErrorMessage"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Unexpected property 'invalidKey', expected one of: firstName, lastName, birthDate, email, universityId, metadata"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>

<p>This lets you know you need to change the structure of your student subject request. Look
up the <code class="highlighter-rouge">invalidRequest</code> error in the <a href="/api-quickstart#program-theme">program theme</a> to find the message to show to the user. The <code class="highlighter-rouge">systemErrorMessage</code> tells you that you need to remove the <code class="highlighter-rouge">invalidKey</code> property
and only use the provided allowed keys.</p>

<p>Make sure you have your program ID before starting.</p>

<p>You can find your <code class="highlighter-rouge">programId</code> on the <em>Program</em> tab of any program listed on <a href="https://my.sheerid.com" target="_blank">MySheerID</a>.</p>

<p><a href="/assets/images/program-id.png"><img src="/assets/images/program-id.png" alt="Program ID" title="click to preview" class="" /></a></p>


        <br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/>
        <br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/>
        <br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/>
      </div>
    </div>
  </div>
  
<footer class="landing-footer landing-footer-jtd">

<a class="main-menu-item footer-item" href="https://www.sheerid.com" target="_blank">© 2019 SheerID</a>

<a class="main-menu-item footer-item" href="https://www.sheerid.com/about-sheerid-platform/" target="_blank">About Our Platform</a>

<a class="main-menu-item footer-item" href="https://sheerid.docsend.com/view/69uwwvu" target="_blank">User Guide</a>

<a class="main-menu-item footer-item" href="https://www.sheerid.com/blog/" target="_blank">Blog</a>

<a class="main-menu-item footer-item" href="https://www.sheerid.com/contact-us/" target="_blank">Contact Us</a>

<a class="main-menu-item footer-item" href="https://www.sheerid.com/privacy-policy/" target="_blank">Privacy Policy</a>

<div class="left-items-footer">
    <div class="mobile-footer-items" >
    
    
      <div class="mobile-foot-item-wrapper">
        <a class="mobile-foot-item" href="https://www.sheerid.com/about-sheerid-platform/" target="_blank">About Our Platform</a>
      </div>
    
    
      <div class="mobile-foot-item-wrapper">
        <a class="mobile-foot-item" href="https://sheerid.docsend.com/view/69uwwvu" target="_blank">User Guide</a>
      </div>
    
    
      <div class="mobile-foot-item-wrapper">
        <a class="mobile-foot-item" href="https://www.sheerid.com/blog/" target="_blank">Blog</a>
      </div>
    
    
      <div class="mobile-foot-item-wrapper">
        <a class="mobile-foot-item" href="https://www.sheerid.com/contact-us/" target="_blank">Contact Us</a>
      </div>
    
    
      <div class="mobile-foot-item-wrapper">
        <a class="mobile-foot-item" href="https://www.sheerid.com/privacy-policy/" target="_blank">Privacy Policy</a>
      </div>
    
    
    </div>
    <a class="main-logo footer-logo" href="https://www.sheerid.com/" target="_blank"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="118" height="26" viewBox="0 0 118 26">
    <defs>
        <path id="a" d="M.029 0H82.24v25.806H.03z"/>
        <path id="c" d="M.088.062h2.819v2.686H.087z"/>
    </defs>
    <g fill="none" fill-rule="evenodd">
        <g>
            <mask id="b" fill="#fff">
                <use xlink:href="#a"/>
            </mask>
            <path fill="#FFF" d="M57.81 14.534c.174-2.75 2.752-5.501 6.236-5.501 3.483 0 6.061 2.75 6.235 5.5H57.81zm-19.4 0c.173-2.75 2.751-5.501 6.235-5.501 3.483 0 6.06 2.75 6.235 5.5H38.41zm35.472 11.149h3.623V14.84c0-2.683.975-4.11 2.124-4.72.871-.442 2.055-.68 2.612-.68V5.806c-.905.035-3.378.103-4.911 2.209h-.069v-1.7h-3.38v8.558c-.337-5.211-4.76-9.067-9.8-9.067-4.82 0-8.87 3.341-9.724 8.03-.816-4.676-4.978-8.03-9.678-8.03-5.08 0-9.306 3.71-9.836 8.799v-.615c-.035-2.105-.452-3.599-1.219-4.822-1.393-2.106-3.832-3.362-6.827-3.362-.767 0-3.658 0-5.4 2.513h-.07V0h-3.622v16.464c-.477-1.561-1.546-2.96-3.095-3.99-.396-.288-1.771-1.145-4.81-1.742l-.122-.02C7.18 10.253 5.73 9.35 5.73 9.35c-.843-.553-1.367-1.55-1.367-2.602 0-1.77 2.049-3.265 4.472-3.265 1.09 0 2.143.297 2.965.836.957.628 1.506 1.514 1.506 2.43h3.488c0-2.067-1.11-3.98-3.046-5.25C12.335.572 10.636.082 8.835.082c-4.388 0-7.96 2.99-7.96 6.665a6.458 6.458 0 0 0 2.914 5.427c.201.13 2.052 1.29 5.28 1.885l.1.015c2.38.47 3.31 1.094 3.314 1.094l.133.097c1.198.784 1.884 1.903 1.884 3.069 0 2.256-2.47 4.093-5.506 4.093-1.33 0-2.615-.364-3.623-1.024-1.197-.786-1.883-1.904-1.883-3.07H0c0 2.316 1.248 4.463 3.425 5.891l.973-1.41-.972 1.41c1.6 1.049 3.524 1.603 5.568 1.603 4.185 0 7.712-2.395 8.71-5.626v5.391h3.624V14.874c0-3.77 2.055-5.841 5.085-5.841 4.808 0 4.808 4.414 4.808 5.875v10.685h3.622v-8.862c.523 4.873 4.658 8.874 9.767 8.874 2.995 0 7.42-1.53 9.266-6.385h-3.624c-.87 1.63-2.821 3.158-5.503 3.158-2.439 0-5.434-1.494-6.34-5.128h15.906c.75 4.634 4.77 8.355 9.696 8.355 2.995 0 7.42-1.53 9.266-6.385h-3.623c-.87 1.63-2.821 3.158-5.504 3.158-2.438 0-5.434-1.494-6.34-5.128h16.063l.009 8.433z" mask="url(#b)"/>
        </g>
        <path fill="#E01E45" d="M84.449.158v25.436h6.216V.158zM104.174 19.673l-5.58-5.501V6.928l5.58 5.502 8.026-7.914C108.845.106 103.866.104 101.042.104h-4.479v.008h-4.087v25.571h9.055c9.815 0 13.307-5.876 13.307-12.859 0-1.13-.099-2.247-.33-3.339l-10.334 10.188zM113.566 23.566h-.543v-.603h1.786v.603h-.539v2.082h-.704z"/>
        <g transform="translate(115.006 22.9)">
            <mask id="d" fill="#fff">
                <use xlink:href="#c"/>
            </mask>
            <path fill="#E01E45" d="M.088.062h.904L1.54 1.83h.006l.54-1.768h.908v2.686h-.648L2.37.738 2.362.73l-.588 2.018h-.466L.72.73.713.738l.022 2.01H.088z" mask="url(#d)"/>
        </g>
    </g>
</svg>
</a>
    
    
    <div>
      <a class="mobile-only mobile-foot-item" href="https://www.sheerid.com" target="_blank">© 2019 SheerID</a>
    </div>
    
    
</div>
</footer>
  <style>
.lightbox {width: 100%; height: 100%; position: fixed; top: 0; left: 0; background: rgba(0,0,0,0.85); z-index: 9999999; line-height: 0; cursor: pointer;}
.lightbox .img {
	position: relative;
	top: 50%;
	left: 50%;
	-ms-transform: translateX(-50%) translateY(-50%);
	-webkit-transform: translate(-50%,-50%);
	transform: translate(-50%,-50%);
	max-width: 100%;
	max-height: 100%;
}
.lightbox .img img {opacity: 0; pointer-events: none; width: auto;}
@media screen and (min-width: 1200px) {
    .lightbox .img {
		max-width: 1200px;
    }
}
@media screen and (min-height: 1200px) {
    .lightbox img {
		max-height: 1200px;
	}
}
.lightbox span {display: block; position: fixed; bottom: 13px; height: 1.5em; line-height: 1.4em; width: 100%; text-align: center; color: white; text-shadow:
    -1px -1px 0 #000,
    1px -1px 0 #000,
    -1px 1px 0 #000,
    1px 1px 0 #000;
}


.lightbox .videoWrapperContainer {
	position: relative;
	top: 50%;
	left: 50%;
	-ms-transform: translateX(-50%) translateY(-50%);
	-webkit-transform: translate(-50%,-50%);
	transform: translate(-50%,-50%);
	max-width: 900px;
	max-height: 100%;
}
.lightbox .videoWrapperContainer .videoWrapper {
	height: 0;
	line-height: 0;
	margin: 0;
	padding: 0;
	position: relative;
	padding-bottom: 56.333%; /* custom */
	background: black;
}
.lightbox .videoWrapper iframe {
	position: absolute;
	top: 0;
	left: 0;
	width: 100%;
	height: 100%;
	border: 0;
	display: block;
}
.lightbox #prev, .lightbox #next {height: 50px; line-height: 36px; display: none; margin-top: -25px; position: fixed; top: 50%; padding: 0 15px; cursor: pointer; text-decoration: none; z-index: 99; color: white; font-size: 60px;}
.lightbox.gallery #prev, .lightbox.gallery #next {display: block;}
.lightbox #prev {left: 0;}
.lightbox #next {right: 0;}
.lightbox #close {height: 50px; width: 50px; position: fixed; cursor: pointer; text-decoration: none; z-index: 99; right: 0; top: 0;}
.lightbox #close:after, .lightbox #close:before {position: absolute; margin-top: 22px; margin-left: 14px; content: ""; height: 3px; background: white; width: 23px;
-webkit-transform-origin: 50% 50%;
-moz-transform-origin: 50% 50%;
-o-transform-origin: 50% 50%;
transform-origin: 50% 50%;
/* Safari */
-webkit-transform: rotate(-45deg);
/* Firefox */
-moz-transform: rotate(-45deg);
/* IE */
-ms-transform: rotate(-45deg);
/* Opera */
-o-transform: rotate(-45deg);
}
.lightbox #close:after {
/* Safari */
-webkit-transform: rotate(45deg);
/* Firefox */
-moz-transform: rotate(45deg);
/* IE */
-ms-transform: rotate(45deg);
/* Opera */
-o-transform: rotate(45deg);
}
.lightbox, .lightbox * {
    -webkit-user-select: none;
    -moz-user-select: none;
    -ms-user-select: none;
    user-select: none;
}
</style>

<script>
function is_youtubelink(url) {
  var p = /^(?:https?:\/\/)?(?:www\.)?(?:youtu\.be\/|youtube\.com\/(?:embed\/|v\/|watch\?v=|watch\?.+&v=))((\w|-){11})(?:\S+)?$/;
  return (url.match(p)) ? RegExp.$1 : false;
}
function is_imagelink(url) {
	var p = /([a-z\-_0-9\/\:\.]*\.(jpg|jpeg|png|gif))/i;
	return (url.match(p)) ? true : false;
}
function is_vimeolink(url,el) {
	var id = false;
	$.ajax({
	  url: 'https://vimeo.com/api/oembed.json?url='+url,
	  async: true,
	  success: function(response) {
		if(response.video_id) {
		  id = response.video_id;
		  $(el).addClass('lightbox-vimeo').attr('data-id',id);
		}
	  }
	});
}

$(document).ready(function() {
	//add classes to links to be able to initiate lightboxes
	$("a").each(function(){
		var url = $(this).attr('href');
		if(url) {
			if(url.indexOf('vimeo') !== -1 && !$(this).hasClass('no-lightbox')) is_vimeolink(url,$(this));
			if(is_youtubelink(url) && !$(this).hasClass('no-lightbox')) $(this).addClass('lightbox-youtube').attr('data-id',is_youtubelink(url));
			if(is_imagelink(url) && !$(this).hasClass('no-lightbox')) {
				$(this).addClass('lightbox-image');
				var href = $(this).attr('href');
				var filename = href.split('/').pop();
				var split = filename.split(".");
				var name = split[0];
				$(this).attr('title',name);
			}
		}
	});
	//remove the clicked lightbox
	$("body").on("click", ".lightbox", function(event){
		if($(this).hasClass('gallery')) {
			$(this).remove();
			if($(event.target).attr('id')=='next') {
				//next item
				if($("a.gallery.current").nextAll("a.gallery:first").length) $("a.gallery.current").nextAll("a.gallery:first").click();
				else $("a.gallery.current").parent().find("a.gallery").first().click();
			}
			else if ($(event.target).attr('id')=='prev') {
				//prev item
				if($("a.gallery.current").prevAll("a.gallery:first").length) $("a.gallery.current").prevAll("a.gallery:first").click();
				else $("a.gallery.current").parent().find("a.gallery").last().click();
			}
			else {
				$("a.gallery").removeClass('gallery');
			}
		}
		else $(this).remove();
	});
	//prevent image from being draggable (for swipe)
	$("body").on('dragstart', ".lightbox img", function(event) { event.preventDefault(); });
	//add the youtube lightbox on click
	$("a.lightbox-youtube").click(function(event){
		event.preventDefault();
		$('<div class="lightbox"><a id="close"></a><a id="next">&rsaquo;</a><a id="prev">&lsaquo;</a><div class="videoWrapperContainer"><div class="videoWrapper"><iframe src="https://www.youtube.com/embed/'+$(this).attr('data-id')+'?autoplay=1&showinfo=0&rel=0"></iframe></div></div></div>').appendTo('body');
	});
	//add the image lightbox on click
	$("a.lightbox-image").click(function(event){
		event.preventDefault();
		$('<div class="lightbox"><a id="close"></a><a id="next">&rsaquo;</a><a id="prev">&lsaquo;</a><div class="img" style="background: url('+$(this).attr('href')+') center center / contain no-repeat;" title="'+$(this).attr('title')+'" ><img src="'+$(this).attr('href')+'" alt="'+$(this).attr('title')+'" /></div><span>'+$(this).attr('title')+'</span></div>').appendTo('body');
	});
	//add the vimeo lightbox on click
	$("body").on("click", "a.lightbox-vimeo", function(event){
		event.preventDefault();
		$('<div class="lightbox"><a id="close"></a><a id="next">&rsaquo;</a><a id="prev">&lsaquo;</a><div class="videoWrapperContainer"><div class="videoWrapper"><iframe src="https://player.vimeo.com/video/'+$(this).attr('data-id')+'/?autoplay=1&byline=0&title=0&portrait=0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe></div></div></div>').appendTo('body');
	});

	$("body").on("click", "a[class*='lightbox-']", function(){
		var link_elements = $(this).parent().find("a[class*='lightbox-']");
		$(link_elements).removeClass('current');
		for (var i=0; i<link_elements.length; i++) {
			if($(this).attr('href') == $(link_elements[i]).attr('href')) {
				$(link_elements[i]).addClass('current');
			}
		}
		if(link_elements.length>1) {
			$('.lightbox').addClass('gallery');
			$(link_elements).addClass('gallery');
		}
	});
});

$(document).keydown(function(e) {
    switch(e.which) {
        case 37: // left
        $("#prev").click();
        break;
        case 39: // right
        $("#next").click();
        break;
	case 27: // esc
        $("#close").click();
        break;
        default: return; // exit this handler for other keys
    }
    e.preventDefault(); // prevent the default action (scroll / move caret)
});

</script>

  <script type="text/javascript" src="/assets/js/replace-jslib-version-snippet.js"></script>
  <script type="text/javascript" src="/assets/js/scrollSpy.js"></script>
  <script src="/assets/js/clipBoardForHeaders.js" ></script>
  <script> $("#nava").scrollspy({ replaceState: true, offset: -25  }); </script>
  <script src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script>
<script>
    jQuery(function($) {
        $.searchState=false;
        docsearch({
            appId: 'O5IRJ16G25',
            apiKey: 'a01e1186e2fbbb8d6a7e0805fcfacfcd',
            indexName: 'dev_sheerid',
            inputSelector: '#algoliaSearch',
            debug: false
        });
        docsearch({
            appId: 'O5IRJ16G25',
            apiKey: 'a01e1186e2fbbb8d6a7e0805fcfacfcd',
            indexName: 'dev_sheerid',
            inputSelector: '#algoliaSearchDesktop',
            debug: false
        });
        $('#searchIcon').click(function () {
            if(!$.searchState) {
                $('#algoliaSearchDesktop').removeClass("hide").focus();
                $.searchState=true;
            } else {
                $('#algoliaSearchDesktop').addClass("hide");
                $.searchState=false;
            }
        });
    });
</script>

</html>