Reference

Development resources for the SheerID REST API and JavaScript library.

API Reference

For an introduction to the SheerID REST API, take a look at REST API.

For the complete reference, see:

Required Fields

We strive to keep the number of required fields to a minimum for each verification type.

Some fields may not be used as determinative factors in a verification, yet may still be required. For example, we don’t need a person’s email address to identify their student status, but we do need it to send them an offer code. Or a field may not be used in an instant verification, but we will need it if the verification requires a manual review.

This reference will help you determine the minimum number of fields you need to capture per targeted segment. If you are running multiple offers across different segments, you may wish to gather fields that are optional for one segment but required for another, to assist in your retargeting activities.

Student

Submit data for a student verification. (API Reference)
Field Required? Description
firstName Yes The first name of the person being verified.
lastName Yes The last name of the person being verified.
email Yes The email address of the person being verified.
birthDate Yes The date of birth of the person being verified (format YYYY-MM-DD). Date must be greater than 1900-01-01.
organization Yes An organization that can be used for instant verification of various segments (Student, Teacher, Military, etc.).
ipAddressExtended No The end-user's public IP address. This only needs to be provided in situations where the HTTP requests do not come directly from the end-user.
phoneNumber No The phone number used for SMS messages.
locale No The locale chosen by the user.
metadata No A collection of custom metadata to be stored with the verification. Learn more: Metadata Options

Active Military

The active military and branch of service data collected from the user to be verified (API Reference)
Field Required? Description
firstName Yes The first name of the person being verified.
lastName Yes The last name of the person being verified.
email Yes The email address of the person being verified.
birthDate Yes The date of birth of the person being verified (format YYYY-MM-DD). Date must be greater than 1900-01-01.
organization Yes An organization that can be used for instant verification of various segments (Student, Teacher, Military, etc.).
phoneNumber No The phone number used for SMS messages.
locale No The locale chosen by the user.
ipAddressExtended No The end-user's public IP address. This only needs to be provided in situations where the HTTP requests do not come directly from the end-user.
metadata No A collection of custom metadata to be stored with the verification. Learn more: Metadata Options

Inactive Military

The inactive duty and branch of service data collected from the user to be verified (API Reference)
Field Required? Description
firstName Yes The first name of the person being verified.
lastName Yes The last name of the person being verified.
email Yes The email address of the person being verified.
birthDate Yes The date of birth of the person being verified (format YYYY-MM-DD). Date must be greater than 1900-01-01.
organization Yes An organization that can be used for instant verification of various segments (Student, Teacher, Military, etc.)
dischargeDate Yes The date the person being verified was discharged from the military.
phoneNumber No The phone number used for SMS messages.
locale No The locale chosen by the user.
ipAddressExtended No The end-user's public IP address. This only needs to be provided in situations where the HTTP requests do not come directly from the end-user.
metadata No A collection of custom metadata to be stored with the verification. Learn more: Metadata Options

Age

The age data collected from the user to be verified. (API Reference)
Field Required? Description
firstName Yes The first name of the person being verified.
lastName Yes The last name of the person being verified.
email Yes The email address of the person being verified.
birthDate Yes The date of birth of the person being verified (format YYYY-MM-DD). Date must be greater than 1900-01-01.
postalCode No The postal code for the person being verified. Required if country == 'US'
phoneNumber No The phone number used for SMS messages. Required if country != 'US'
country No The country code of the person being verified. Defaults to 'US'
locale No The locale chosen by the user.
ipAddressExtended No The end-user's public IP address. This only needs to be provided in situations where the HTTP requests do not come directly from the end-user.
metadata No A collection of custom metadata to be stored with the verification. Learn more: Metadata Options

Teacher

A teacher to be verified. (API Reference)
Field Required? Description
firstName Yes The first name of the person being verified.
lastName Yes The last name of the person being verified.
email Yes The email address of the person being verified.
organization Yes An organization that can be used for instant verification of various segments (Student, Teacher, Military, etc.).
postalCode No The postal code for the person being verified. Provide when open org is submitted, i.e. organization id = 0
phoneNumber No The phone number used for SMS messages.
locale No The locale chosen by the user.
ipAddressExtended No The end-user's public IP address. This only needs to be provided in situations where the HTTP requests do not come directly from the end-user.
metadata No A collection of custom metadata to be stored with the verification. Learn more: Metadata Options

First Responder

A first responder to be verified. (API Reference)
Field Required? Description
firstName Yes The first name of the person being verified.
lastName Yes The last name of the person being verified.
email Yes The email address of the person being verified.
organization Yes An organization that can be used for instant verification of various segments (Student, Teacher, Military, etc.).
statuses Yes List of first responder statuses. Possible values: 'POLICE', 'EMT', 'FIREFIGHTER'.
birthDate No The date of birth of the person being verified (format YYYY-MM-DD). Date must be greater than 1900-01-01.
phoneNumber No The phone number used for SMS messages.
locale No The locale chosen by the user.
ipAddressExtended No The end-user's public IP address. This only needs to be provided in situations where the HTTP requests do not come directly from the end-user.
metadata No A collection of custom metadata to be stored with the verification. Learn more: Metadata Options
postalCode Yes The postal code for the person being verified. Provide when open org is submitted, i.e. organization id = 0

Medical Professional

A medical professional to be verified. (API Reference)
Field Required? Description
firstName Yes The first name of the person being verified.
lastName Yes The last name of the person being verified.
email Yes The email address of the person being verified.
birthDate Yes The date of birth of the person being verified (format YYYY-MM-DD). Date must be greater than 1900-01-01.
postalCode Yes The postal code for the person being verified.
organization Yes An organization that can be used for instant verification of various segments (Student, Teacher, Military, etc.).
statuses Yes List of medical professional statuses. A single value will be interpreted as a list with one entry. Possible values: 'NURSE', 'DOCTOR', 'OTHER_HEALTH_WORKER'
phoneNumber No The phone number used for SMS messages.
locale No The locale chosen by the user.
ipAddressExtended No The end-user's public IP address. This only needs to be provided in situations where the HTTP requests do not come directly from the end-user.
metadata No A collection of custom metadata to be stored with the verification. Learn more: Metadata Options

Employment

An employee to be verified. (API Reference)
Field Required? Description
firstName Yes The first name of the person being verified.
lastName Yes The last name of the person being verified.
email Yes The email address of the person being verified.
address1 Yes The street address for the person being verified.
city Yes The city for the person being verified.
state Yes The 2-digit state code for the person being verified.
postalCode Yes The postal code for the person being verified.
organization Yes An organization that can be used for instant verification of various segments (Student, Teacher, Military, etc.).
phoneNumber No The phone number used for SMS messages.
locale No The locale chosen by the user.
deviceFingerprintHash No The device fingerprint collected for the person being verified.
ipAddressExtended No The end-user's public IP address. This only needs to be provided in situations where the HTTP requests do not come directly from the end-user.
metadata No A collection of custom metadata to be stored with the verification. Learn more: Metadata Options

Membership

A member to be verified. (API Reference)
Field Required? Description
firstName Yes The first name of the person being verified.
lastName Yes The last name of the person being verified.
email Yes The email address of the person being verified.
organization Yes An organization that can be used for instant verification of various segments (Student, Teacher, Military, etc.).
deviceFingerprintHash No The device fingerprint collected for the person being verified.
birthDate No The date of birth of the person being verified (format YYYY-MM-DD). Date must be greater than 1900-01-01.
memberId No The unique member ID number for the person being verified.
address1 No The street address for the person being verified.
city No The city for the person being verified.
state No The 2-digit state code for the person being verified.
postalCode No The postal code for the person being verified.
phoneNumber No The phone number used for SMS messages.
locale No The locale chosen by the user.
ipAddressExtended No The end-user's public IP address. This only needs to be provided in situations where the HTTP requests do not come directly from the end-user.
metadata No A collection of custom metadata to be stored with the verification. Learn more: Metadata Options

Licensed Professional

A licensed professional to be verified. (API Reference)
Field Required? Description
firstName Yes The first name of the person being verified.
lastName Yes The last name of the person being verified.
email Yes The email address of the person being verified.
birthDate Yes The date of birth of the person being verified (format YYYY-MM-DD). Date must be greater than 1900-01-01.
organization Yes An organization that can be used for instant verification of various segments (Student, Teacher, Military, etc.).
deviceFingerprintHash No The device fingerprint collected for the person being verified.
ipAddressExtended No The end-user's public IP address. This only needs to be provided in situations where the HTTP requests do not come directly from the end-user.
phoneNumber No The phone number used for SMS messages.
locale No The locale chosen by the user.
metadata No A collection of custom metadata to be stored with the verification. Learn more: Metadata Options

JavaScript Library Reference

For an introduction to the SheerID JavaScript library, take a look at our JavaScript Library getting started guide.

Flow Diagrams

Verification flows conform to the same basic principles, regardless of the segment. However, certain steps may vary slightly, as information requirements are different from segment to segment. The diagrams below show the specific flow diagrams for segments supported by the SheerID self-service app and corresponding 2.0 JavaScript and REST APIs.

US Student

Verify US college student status from our data sources including over 20 million students.

Student Flow

Military

Verify active military, veterans and retirees in the US from our database of over 28 million.

Military Flow

Age

Verify US and international seniors and young adults. Our data sources include:

  • 110M+ US seniors (50+)
  • 778M+ Non-US seniors
  • 55M+ US young adults (18-30)
  • 590M+ non-US young adults

Available for any age over 18.

Age Flow

First Responder

Verify First Responders from our database of over 1.5 million police, EMTs, and firefighters in the US.

First Responder Flow

Teacher

Verify users from our database of over 3 million teachers and 1 million faculty members at institutions of higher learning.

Teacher Flow

Medical Professional

Verify Medical Professionals from our database of over 4 million registered nurses and over 1 million doctors in the US.

Medical Professional Flow

TLS Certificates

Effective April 2, 2021, SheerID will no longer use SSL wildcard certificates for services.sheerid.com, my.sheerid.com, and offers.sheerid.com. Other sheerid.com sites will continue to use a wildcard certificate. All certificates will be signed by our new certificate authority provider, Amazon.

SheerID Certificate Authority

The following TLS certificates will be put in place on April 2, 2021:

Hostname Authority
services.sheerid.com Amazon
my.sheerid.com Amazon
offers.sheerid.com Amazon
*.sheerid.com (used by verify.sheerid.com and some legacy programs) Amazon

Before this change SheerID used a single *.sheerid.com TLS certificate generated by a different authority: DigiCert, Inc. Please make any necessary changes to support the new certificates and Authority listed above.

Note: In most instances, no work will be required on your part to accommodate this change. However, if you employ site-specific behaviors for TLS certificates, you may need to adjust your certificate stores.

Static IP Addressing

Many SheerID customers maintain firewalls, aka Access Control Lists (ACL) to govern traffic to and from SheerID.

Provided below are SheerID’s ACL entries for your outbound and inbound IP traffic.

Important: As of the release of the 2.0 version of the SheerID platform, we no longer maintain a separate sandbox environment for testing. All of your programs are hosted in the same environment with configuration flags for Test or Live mode. If you have questions about legacy production/sandbox environments, contact [email protected] or see our Migration Guides.

Outbound API Requests

The associated IP addresses should be added to the firewall/network ACL for outbound HTTPS traffic via port 443.

Outbound entries:

Hostname: services.sheerid.com
IP Addresses: 13.248.160.105 | 76.223.33.86

Inbound Notifications (HTTP Notifier)

HTTP Notifiers are optional callbacks that can be set up to notify your server of various SheerID verification activities. Accounts with provisioned HTTP notifiers will receive notifications initiating from the IP addresses shown below. These notifications will be submitted as HTTPS requests via port 443 to a webhook URL that you define (optional).

Inbound entries:

Hostname: notifications.sheerid.com
IP Addresses: 44.234.246.67 | 52.4.200.14 | 52.43.240.185 | 54.70.188.131 | 54.209.170.78 | 54.236.234.189