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.
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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.
Military
Verify active military, veterans and retirees in the US from our database of over 28 million.
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.
First Responder
Verify First Responders from our database of over 1.5 million police, EMTs, and firefighters in the US.
Teacher
Verify users from our database of over 3 million teachers and 1 million faculty members at institutions of higher learning.
Medical Professional
Verify Medical Professionals from our database of over 4 million registered nurses and over 1 million doctors in the US.
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.
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.
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