Introduction

There are two different personas who connect with ShieldHub. The background check partner companies and then also the Oversight API subscribers.

With this in mind, this documentation is split into three sections to assist you in focusing on the documentation that is most relevant to you.

1. The aspects which are common across all end points

2. The end points relevant to our background check company partners

3. The end points relevant to our Oversight API subscribers.

The ShieldHub APIs are organized around REST and uses standard HTTP response codes.

The ShieldHub API doesn't support bulk requests. You can work on only one object per request.

Common Aspects

Authentication

Sample HTTP Request with Authorization Header:

POST /v1/submissions HTTP/1.1
Host: api.developer.shieldhub.com
Authorization: Basic QXNzaWduZWRVc2VybmFtZTpBc3NpZ25lZFBhc3N3b3Jk
Content-Length: ***
Content-Type: application/json

All requests to the ShieldHub API must use HTTP Basic Authentication. A username and password will be provided to you as part of the integration on-boarding process. The HTTP Basic Authentication scheme is defined in RFC 7617, which transmits credentials as username/password pairs, encoded using base64.

API Key Authentication

If you are authenticating using an API key you should include the API key as the password of HTTP Basic Authentication. You can use use any username value, it will be ignored.

Authorization delegation for platform providers

Sample HTTP Request with Assume Auth Header

POST /v2/oversight/details HTTP/1.1
Host: api.developer.shieldhub.com
Authorization: Basic QXNzaWduZWRVc2VybmFtZTpBc3NpZ25lZFBhc3N3b3Jk
Content-Length: ***
Content-Type: application/json
SH-Assume-Auth: 28a1e9fb-86e3-4d51-bff0-290ce9666884

ShieldHub Enterprise customers can delegate authorization to access the oversight api methods. For example, when a platform or technology provider needs to perform network subscription requests on behalf of other ShieldHub Enterprise customers. ShieldHub offers an additional API Key that allows you to perform the required authorization. A platform provider should still use their own HTTP Basic Authentication or API Key Authentication, but will also pass a custom header with the customer's API Key. The platform provider should use the SH-Assume-Auth header to pass the individual customer's API Key. You can also pass the header X-SH-Assume-Auth if your client only supports custom headers with an X- prefix. Please contact ShieldHub if this type of authentication is needed. We will issue API Keys for ShieldHub Enterprise customers using your platform.

Status Codes

ShieldHub uses conventional HTTP response codes, even in our file transfer mechanisms to indicate the success or failure of a request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted etc.). Codes in the 5xx range indicate an error with ShieldHub’s servers.

ABC Number is now called ShieldID^™

ShieldHub provides an anonymized ShieldID­ previously known as ABC # that can be used to access the ShieldHub scored vendor profile. Please note the API uses the parameter AbcNumber and/or AbcStatus in places for backwards compatibility.

Background Check Partner Companies

/v1/submissions

The /v1/submissions API is used by the background check companies (CRA) who partner with ShieldHub to facilitate the implementation of an Industry Standard background check and the issuing of an ShieldID and Expiration Date. In the event that a CRA adjudicated a screening report, then the /v1/submissions API should be called immediately.
This request would also be called in the event that there is a change to the candidates IC Status as a result of a dispute or a monitoring update.

/v1/submissions Request

Example: /v1/submissions Request

POST /v1/submissions HTTP/1.1
Host: api.developer.shieldhub.com
Authorization: Basic cXVpY2tzZWFyY2g6cGFzc3dvcmQ=
Content-Type: application/json

{
    "TransmissionGUID": "96f91f3f-7832-4234-9c44-e26112013a2d",
    "SubmissionGUID": "12345678-1234-1234-1234-000000000001",
    "CRAAccountID": "990",
    "Classification": "Direct Employee",
    "LegalFirstName": "John",
    "LegalMiddleName": "",
    "LegalLastName": "Smith",
    "SSN": "123456789",
    "DOB": "2001-02-02",
    "CurrentAddressZipcode": "43006",
    "Cell": "3333333336",
    "EmailAddress": "johnsmith@email.com",
    "CRAPackageID": "4426",
    "SubmissionStartDateTime": "2020-10-01 13:00",
    "SubmissionEndDateTime": "2020-10-01 13:00",
    "CurrentICStatus": "IC02",
    "ReleaseDecisionConsentTimeStamp": "2020-10-01 13:00",
    "image": "data:image/jpeg;base64,VGhpcyBpcyBhIGJhc2UgNjQgZXhhbXBsZQ=="  
}

The below table documents each of the request fields.

/v1/submissions Response

Example /v1/submissions Standard Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "SubmissionGUID":"12345678-1234-1234-1234-000000000001",
    "ABCNumber":"AB123456789",
    "ExpirationDateTime":"2023-10-01T13:00:00",
    "StatusCode":"200",
    "StatusComment":"IC Score/Candidate updated successfully."
}

The below table documents each of the response fields.

Release Decision

Oversight Subscribers

/v2/oversight/validateabcnumber

/v2/oversight/abcnumberdetails

/v2/oversight/details

Retrieve ShieldID Details

This would be used once you have established a business relationship with a person and confirmed that they have consented to have their compliance details made available in your system of record.

This is hugely beneficial going forward, as you can proactively ensure that the person you are assigning to a job will meet the compliance requirements of you and your customer.

Important Information

You can call this end point as often as you see fit, as long as you continue to have the consent of the individual. Doing so will ensure that your system of record is kept up to date with any changes in compliance for that person which can change periodically for a number of reasons. You can also setup a webhook to receive updates as they happen with the v2/oversight/webhook method

For example: If a person is convicted of a relevant charge several months after onboarding with your business, then by periodically calling this end point, your system of record will have the latest compliance details.

GET /v2/oversight/details?transmissionGuid=CC6E5730-5E5C-451C-B975-BEC06749EB74&ShieldId=OH990061115&legalLastName=SomeName&resourceID=1234567  HTTP/1.1
Host: api.developer.shieldhub.com
Authorization: Basic cXVpY2tzZWFyY2g6cGFzc3dvcmQ=

Request Parameters

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{ 
    "TransmissionGuid":" CC6E5730-5E5C-451C-B975-BEC06749EB74", 
    "ResourceId":"1234567", 
    "ShieldId":"OH990061115",
    "ShieldIdStatus":"Active",
    "LegalFirstName":"Name", 
    "LegalLastName":" SomeName ", 
    "ICScore":"IC01", 
    "Expiration":"2023-05-09T00:00:00", 
    "statusCode":"200",
    "StatusDate":"2025-12-31",
    "statusComment":null,
    "inviteStatus":null
} 

/v2/oversight/compliancerule

Retrieve ShieldID Compliance Result

The parameters for this request are in a JSON POST body, which differs from the other methods. This method is to retrieve the compliance result of a ShieldID and a ShieldScore, based on a effective date provided in the SignInDate parameter.

The compliance rules are a static validation of:

• ShieldID exists and matches LegalLastName
  • LegalLastName is matched case insensitive
  • If LegalLastName contains punctuation or special characters, the API will perform the match after stripping those characters
• SignInDate is not in the future
• ShieldScore was/is valid as of the SignInDate
  • A ShieldScore might be expired as of request time, but valid as of SignInDate
• ShieldScore is a valid score IC04,IC03,IC02,IC01,IC01+
• ShieldScore is at least a IC02 or better IC02,IC01,IC01+

POST /v2/oversight/compliancerule  HTTP/1.1
Host: api.developer.shieldhub.com
Authorization: Basic cXVpY2tzZWFyY2g6cGFzc3dvcmQ=

{
    "TransmissionGuid":"757cfcc0-9dbe-4d7c-9817-18fecab9fa78",
    "ShieldId":"OH990061115",
    "LegalLastName":"SomeName",
    "SignInDate":"2024-04-03",
    "ConsumerSource":"MOBILE APP",
    "OrderID":"A-78940",
    "NetworkOwner":"Nexora Network",
    "TaskId":"K 302810"
}

Request Parameters

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{ 
    "TransmissionGuid":"757cfcc0-9dbe-4d7c-9817-18fecab9fa78",
    "ShieldId":"OH990061115",
    "LegalFirstName":"John",
    "LegalLastName":"SomeName",
    "ComplianceResult":"true",
    "ComplianceCode":"",
    "OrderID":"A-78940",
    "NetworkOwner":"Nexora Network",
    "TaskID":"K 302810",
    "StatusCode":"200", 
    "StatusComment":""
}

/v2/oversight/webhook

Set webhook details

The parameters for this request are in a JSON POST body, which differs from the other methods. This method is used to set your webhook information to recieve events to your system. The webhook payload is standardized and should include all of the information needed.

Note When you send this request the API will attempt to send a test payload to your provided webhook. If the response is not a HTTP 200, saving the webhook details will fail.

POST /v2/oversight/webhook  HTTP/1.1
Host: api.developer.shieldhub.com
Authorization: Basic cXVpY2tzZWFyY2g6cGFzc3dvcmQ=

{
    "transmissionGuid":"757cfcc0-9dbe-4d7c-9817-18fecab9fa78",
    "webhookurl":"https://webhookurl",
    "http_basic_auth":{
        "username":"authusername",
        "password":"authpassword"
    },
    "additional_headers":{
        "X-APIKEY":"123456789"
    }
}

Request Parameters

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{ 
    "transmissionGuid":"757cfcc0-9dbe-4d7c-9817-18fecab9fa78",
    "statusCode":"200", 
    "statusComment":"OK : Webhook Enabled"
} 

/v2/oversight/subscribe

If a user with a ShieldID has accepted your network invitation, you can subscribe to events of that ShieldID.

GET /v2/oversight/subscribe?transmissionGuid=CC6E5730-5E5C-451C-B975-BEC06749EB74&ShieldId=OH990061115&resourceID=1234567  HTTP/1.1
Host: api.developer.shieldhub.com
Authorization: Basic cXVpY2tzZWFyY2g6cGFzc3dvcmQ=

Request Parameters

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{ 
    "transmissionGuid":"CC6E5730-5E5C-451C-B975-BEC06749EB74",
    "ShieldId":"OH990061115",
    "statusCode":"200", 
    "statusComment":"OK : Subscription Created",
    "resourceID":null
} 

/v2/oversight/unsubscribe

If you would like to stop receiving webhook payload requests for a specific ShieldID, you can unsubscribe from the events of that ShieldID.

GET /v2/oversight/unsubscribe?transmissionGuid=1c1ba44c-d421-42a1-9d59-98ec2b48c936&ShieldId=OH990061115&resourceID=1234567  HTTP/1.1
Host: api.developer.shieldhub.com
Authorization: Basic cXVpY2tzZWFyY2g6cGFzc3dvcmQ=

Request Parameters

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{ 
    "transmissionGuid":"1c1ba44c-d421-42a1-9d59-98ec2b48c936",
    "ShieldId":"OH990061115",
    "statusCode":"200", 
    "statusComment":"OK : Subscription Removed",
    "resourceID":null
} 

Receiving Webhook Events

After setting the webhook details with the /v2/oversight/webhook method you can subscribe to events of specific ShieldID's. After you subscribe to a ShieldID your endpoint should start receiving POST requests. Webhook POST requests are sent asynchronously within a few minutes of receiving the updated information.

Payload example

POST / HTTP/1.1
Host: yourwebhook.com

{
    "ShieldID" : "NV891091000",
    "LegalFirstName" : "Frank",
    "LegalLastName" : "Sinatra",
    "StatusDate" :  "2024-11-10",
    "ShieldScore" : "IC01+",
    "Expiration" : "1998-05-14",
    "ShieldIDEvent" : "leftnetwork"
}

ShieldID Events

Understanding the ShieldIdStatus values

Active

This ShieldIdStatus means that the ShieldID provided is all of the following;

• A valid, well formatted ShieldID
• The person has agreed to release their IC0# from the background check company, making it available to any Oversight Subscriber they consent to share it with.
  
• The expiration date is a date in the future & in the case of a /v2/oversight/details request, that the last name exactly matches the legal last name associated with the ShieldID

Inactive

This ShieldIdStatus can mean that the ShieldID provided is any one of the following;

• The person has not agreed to release their IC0# from the background check company, therefore it is not available to be consumed by any Oversight Subscriber. This person would need to discuss this with their background check company if they do want to release it for the purposes of being onboarded by your business
  
• The expiration date is a date in the past

No Match Found

This ShieldIdStatus can mean that the ShieldID provided is any one of the following;

• An invalid or poorly formatted ShieldID and in the case of a /v2/oversight/details request, the last name may not exactly match the legal last name associated with the ShieldID

ShieldID Verification Widget

Overview

The ShieldID Verification Widget is a free, embeddable tool that allows homeowners and businesses to verify a vendor's ShieldID and view their ShieldScore in real-time. This widget is designed to help customers confirm the identity and compliance status of service providers who present a ShieldID at their door or worksite.

The widget provides a seamless, secure verification experience without requiring authentication or API integration. It's perfect for companies who want to offer ShieldID verification to their customers or website visitors.

Key Features

• Free to use - No API credentials or subscription required
• reCAPTCHA v3 protection - Built-in bot protection with daily rate limiting (10 searches per day per visitor)
• Real-time verification - Instant validation of ShieldID and ShieldScore status
• Responsive design - Works seamlessly on desktop and mobile devices
• Privacy-focused - Only displays information for users who have enabled sharing
• Easy integration - Simple iframe or JavaScript embed

Use Cases

• Homeowners verifying door-to-door vendors
• Property managers checking contractor credentials
• Businesses validating service provider compliance
• Partner websites offering ShieldID verification to customers

How It Works

1. A visitor enters an 11-character ShieldID (e.g., CA123451234)
2. reCAPTCHA v3 validates the request (invisible to user)
3. The widget displays the vendor's name, ShieldScore, expiration date, and verification status
4. Only users who have enabled sharing will have their details displayed

Integration

Integrating the ShieldID Verification Widget is simple - just add one line of code before your closing </body> tag:

<script
  src="https://portal.shieldhub.com/widget/shieldhub-widget.min.js"
  async
></script>

Then add a button anywhere on your page with the class shieldhub-search:

<button class="shieldhub-search">
  Verify ShieldID
</button>

You can also use id="shieldhub-search" for a single button:

<button id="shieldhub-search">
  Verify ShieldID
</button>

The widget automatically attaches to any element with id="shieldhub-search" or class="shieldhub-search" and opens a modal when clicked.

Widget Behavior

Valid ShieldID with Sharing Enabled

When a valid ShieldID is entered and the user has enabled sharing, the widget displays:

• Profile photo (if available)
• Legal first and last name
• ShieldScore badge (IC01+, IC01, IC02, IC03, IC04, or N/A)
• Verification status checkmark
• ShieldID certification number
• Expiration date
• "What is a ShieldScore?" educational link

Valid ShieldID with Sharing Disabled

When a valid ShieldID exists but the user has not enabled sharing, the widget displays:

ShieldScore sharing not enabled for this user.

Invalid ShieldID

When a ShieldID is not found or incorrectly formatted, the widget displays:

Shield ID "XX123456789" not found

Expired ShieldScore

If a ShieldScore has expired, an "EXPIRED" badge is displayed prominently alongside the expiration date.

Rate Limiting

The widget limits searches to 10 per visitor per day to prevent abuse. Rate limiting is enforced using browser-based tracking combined with bot protection and resets 24 hours from the first search.

When the limit is reached, visitors will see:

Daily search limit reached. Please try again later.

Testing

A live demo and test page is available at:

https://www.shieldhublabs.com/widget-test.html

Test ShieldID (if configured in test environment): CA123451234

Revision History