Verification Report

In this guide, we’ll go through the necessary steps to generate and download a verification report using our REST API.

Overview

To programmatically consume verification reporting data for your internal systems, we provide 3 reporting endpoints:

POST /report/verification: Generate a verification report.
GET /report/{reportId}/status: Retrieve report generation status by report ID.
GET /report/{reportId}: Retrieve data for a previously-generated report.

Generating and retrieving reporting data is a 3-step process using these methods. Below we will walk you through the flow. For details, see our API reference.

Warning: Column order in our verification reports is not fixed and new columns may appear without notice, due to factors including but not limited to:

- New data points that SheerID exposes in reporting
- Metadata that you include in verification requests

If you are consuming SheerID reports programmatically, code defensively. Your integration should be tolerant of header changes.

Generate a Report

Generating a verification report is initiated by issuing a POST request to the /report/verification endpoint. Below is an example of the most basic request which will result in a report generated containing verifications that occurred between the startDate and endDate specified.

Example request:

POST /rest/v2/report/verification HTTP/1.1
Host: services.sheerid.com
Content-Type: application/json
Authorization: Bearer <YOUR_API_TOKEN>

{
	"format": "CSV", // 'format' is a required field. 'CSV' is the only acceptable format value at this time.
	"startDate": "2019-08-01", // Optional. Defaults to 30 days before the end date. 
	"endDate": "2019-08-17" // Optional. Defaults to the end of day of the request.
}

Note: REPORTER role is required.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json


{
    "id": "5d59a3dcf1d4ac6382441624",
    "status": "PENDING",
    "statusUrl": "https://services.sheerid.com/rest/v2/report/5d59a3dcf1d4ac6382441624/status",
    "retrievalUrl": null,
    "requester": "5c1c45b451cc4d30b7a132c2",
    "created": 1566155740700
}

See Check Report Status for instructions on retrieving the generated report once completed.

Report Contents

Filter Verifications

By default, generated reports contain all live mode verifications that occurred within the time span requested. You can optionally specify which verifications are included by adding any combination of the parameters shown below to the body of the request.

verificationModeInclusion - ( "ALL"|"LIVE"|"TEST") Which verification modes to include.
programIds - List of program ids. Only verifications associated with these programs will be included.
countryCodes- List of country codes. Only verifications from the countries requested with be included.
rewardEligibilities - ("ELIGIBLE", "INELIGIBLE") List of eligibility results. Only verifications that resulted in the states requested will be included.
communities - List of affiliation types. Only verification of the types requested will be included.

Example Request Body:

{
    "format": "CSV", 
    "startDate": "2019-08-01", 
    "endDate": "2019-08-17", 
    "verificationModeInclusion": "ALL", 
    "programIds": [ "63dc0d4b36e79e3a4a7e6551", "63ef50924a53c72e31006d09" ], 
    "countryCodes": [ "US", "UK" ], 
    "rewardEligibilities": [ "ELIGIBLE", "INELIGIBLE" ], 
    "communities": [ "Age", "Medical" ] 
}

Note: Values provided for verificationModeInclusion and rewardEligibilities are case sensitive.

Select Fields

By default, the report generated will include every field and metadata value that is available to your account and the programs requested. You also have the option to limit these by including the desired fields in the report request.

See Available Fields for instructions on retrieving the list of fields available to you.

standardFields - The list of standard fields to include. If empty or not present, all field will be included.
metadataFields - The list of account and program level metadata keys to include. All available fields are included when not present.

Example Request Body:

{
    "format": "CSV", 
    "startDate": "2019-08-01", 
    "endDate": "2019-08-17",
    "standardFields": ["REQUEST_ID", "ACCOUNT_ID"],
    "metadataFields: ["template_id", "my_custom_metadata_key"] 
}

Personal Identifiable Information

Person data for each verification is not included unless specifically requested. To include PII, add set the isPiiIncluded field to true in the request and include a short explanation describing the reason the data is needed.

isPiiIncluded - (true|false) Whether or not to include person fields in the report.
piiReason - Description of the reason for including PII data.
personFields - The list of person fields to include. When not present, all visible fields are included.

Example Request Body:

{
    "format": "CSV", 
    "startDate": "2019-08-01", 
    "endDate": "2019-08-17",
    "standardFields": ["REQUEST_ID", "ACCOUNT_ID"], 
    "metadataFields: ["template_id", "my_custom_metadata_key"],
    "isPiiIncluded": true,
    "piiReason": "Reason to request PII", 
    "personFields: ["FIRST_NAME", "LAST_NAME"] 
}

Note: Standard, person, and metadata field names are all case sensitive. If you do not have the PERSON_DATA role, or request a person field that isn’t visible to your account, an Unauthorized error will be returned

Available Fields

The list of fields available can be retrieved by making a GET request to the /report/fields endpoint. A list of program ids can be provided as an optional parameter to limit the metadata fields retrieved in the response.

Example request:

POST /rest/v2/report/fields?programIds=PROGRAM_1,PROGRAM_2 HTTP/1.1
Host: services.sheerid.com
Content-Type: application/json
Authorization: Bearer <YOUR_API_TOKEN>

The response object lists each field with three properties:

name - The identifier used to refer to a field. This is the value that is expected when including desired fields in report requests.
columnHeading - The name of the column as it will appear in reports.
description - A brief explanation of the field and its meaning.

Fields are grouped into three categories:

STANDARD - The set of fields available to all reports.
PII - The person fields that are visible to the requester’s account. These fields contain personally identifiable information associated with verifications.
METADATA - Metadata keys that are available to the account and its programs. Includes default metadata keys and customer provided keys.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  { 
    "scope": "STANDARD",
    "fields": [
      {
        "columnHeading": "Request ID",
        "description": "A unique identifier for the verification request",
        "name": "REQUEST_ID"
      }
    ]
  },
  {
    "scope": "PII",
    "fields": [ 
      { 
        "columnHeading": "BIRTH_DATE",
        "description": "The date of birth supplied by individual being verified",
        "name": "BIRTH_DATE"
			}
    ]
  },
  {
    "scope": "METADATA",
    "fields": [
      {
        "columnHeading": "templateId",
        "description": "A unique ID of the program which the individual attempted verification",
        "name": "templateId"
      }
    ]
  }
]

Check Report Status

With the statusUrl returned in the first step, you can check the report’s status.

Example request:

GET /rest/v2/report/5d59a3dcf1d4ac6382441624/status HTTP/1.1
Host: services.sheerid.com
Authorization: Bearer <YOUR_API_TOKEN>

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "5d59a3dcf1d4ac6382441624",
    "status": "COMPLETE",
    "statusUrl": "https://services.sheerid.com/rest/v2/report/5d59a3dcf1d4ac6382441624/status",
    "retrievalUrl": "https://services.sheerid.com/rest/v2/report/5d59a3dcf1d4ac6382441624",
    "requester": "5c1c45b451cc4d30b7a132c2",
    "created": 1566155740700
}

Download Report Data

Once the report status is COMPLETE, your report is ready for download using the retrievalUrl provided in the status step.

Example request:

GET /rest/v2/report/5d59a3dcf1d4ac6382441624 HTTP/1.1
Host: services.sheerid.com
Authorization: Bearer <YOUR_API_TOKEN>

Example response:

"Request ID","Request Timestamp","Account ID","User ID","Username","Result","Status","Errors","ErrorCodes","Person ID","Organization ID","Organization Name","Organization Phone","Organization Street","Organization City","Organization Zip","Organization State","Organization Country","Organization Type","Verification Types","Requested Affiliation Types","Confirmed Affiliation Types","Data Updated Date","Period Begin Date","Period End Date","Test Mode","PHONE_NUMBER","EMAIL","SSN_LAST4","COMPANY_NAME","MIDDLE_NAME","USERNAME","LAST_NAME","IP_ADDRESS","ADDRESS1","CITY","STATUS_START_DATE","JOB_TITLE","SSN","RELATIONSHIP","FULL_NAME","BIRTH_DATE","POSTAL_CODE","FIRST_NAME","STATE","ID_NUMBER","SUFFIX","EMAIL2","ADDRESS2","Program Name","amount","currency","trackingId","marketConsentValue","rewardCode","baz","foo","templateId","token","verifyUrl","transactionId"
"5d4a5b672988eb627bb6ffa6","2019-08-07 05:03:43","5c1c45b451cc4d30b7a132c2","5c1c45b451cc4d30b7a132c2","[email protected]","false","COMPLETE","Person is ineligible for verification because of age.","UNDERAGE_PERSON","5d4a5baf7b9ca962e0b6a8c5",,,,,,,,,"AGE_ID","AUTHORITATIVE","AGE","AGE","","","","true",,"[email protected]",,,,,"jackson","24.21.170.221",,,,,,,,"2000-1-30","97239","phil",,,,,,"Olive Garden Closing Sale",,,,"true",,,"bar","5d1314a34e15d06159132e03",,,
"5d4a5eea2988eb627bb70001","2019-08-07 05:27:46","5c1c45b451cc4d30b7a132c2","5c1c45b451cc4d30b7a132c2","[email protected]","true","COMPLETE",,,"5d4a61527b9ca962e0b6a96e","3679","UNIVERSITY OF SOUTHERN CALIFORNIA",,,"LOS ANGELES",,"CA","US","UNIVERSITY","AUTHORITATIVE","STUDENT_FULL_TIME, STUDENT_PART_TIME","STUDENT_FULL_TIME","","","","true",,"[email protected]",,,,,"johnson","24.21.170.221",,,,,,,,"1990-1-30",,"phil",,,,,,"metadata test",,,,"false","EXAMPLE-CODE",,"bar","5d4a5d2a7b9ca962e0b6a901",,,
"5d4a65ba2988eb627bb700b9","2019-08-07 05:47:31","5c1c45b451cc4d30b7a132c2","5c1c45b451cc4d30b7a132c2","[email protected]","true","COMPLETE",,,"5d4a65f37b9ca962e0b6a9f2","4343","YALE UNIVERSITY",,,"NEW HAVEN",,"CT","US","UNIVERSITY","AUTHORITATIVE","STUDENT_FULL_TIME, STUDENT_PART_TIME","STUDENT_FULL_TIME","","","","true",,"[email protected]",,,,,"Jetson","24.21.170.221",,,,,,,,"1990-10-1",,"Joe",,,,,,"metadata test",,,,"false","EXAMPLE-CODE","lurhmann","bar","5d4a5d2a7b9ca962e0b6a901",,,
"5d54a6a12de9ad624429424c","2019-08-15 00:28:27","5c1c45b451cc4d30b7a132c2","5c1c45b451cc4d30b7a132c2","[email protected]","true","COMPLETE",,,"5d54a72b088ba462375748b5","3499","UNIVERSITY OF CALIFORNIA LOS ANGELES (UCLA)",,,"LOS ANGELES",,"CA","US","UNIVERSITY","AUTHORITATIVE","STUDENT_FULL_TIME, STUDENT_PART_TIME","STUDENT_FULL_TIME","","","","true",,"[email protected]",,,,,"johnson","24.21.170.221",,,,,,,,"1998-1-31",,"john",,,,,,"metadata test",,,,"false","EXAMPLE-CODE",,,"5d4a5d2a7b9ca962e0b6a901",,,