Changes in the status of the ordered report can be communicated to the client in one of two ways. The first is for the gateway to post a small XML document with status information to the x:postback_url. The credentials submitted in the x:postback_password and x:postback_userId elements, if any, will be included. A status response is posted back each time there is a change or update to the order status. The second method is for the client to send to the gateway a status inquiry XML, to which the gateway will respond with the status information.
When posting information back to the provided postback URL, the information will be sent as URL Encoded text within the Form value. The following header values will be used on each postback:
| Headers | |
|---|---|
| connection | close |
| x-forwarded-for | 54.149.149.7 |
| accept-encoding | gzip,deflate |
| user-agent | Apache-HttpClient/4.5.6 (Java/1.8.0_161) |
| host | YOUR WEBHOOK URL HOST |
| content-type | application/x-www-form-urlencoded; charset=ISO-8859-1 |
| content-length | 1077 (value will vary) |
Note that of these values, x:ready indicates the report is completed and ready for delivery. The remaining indicate that incomplete work remains on the report.
The flag attribute on the OrderStatus tag indicates if one or more searches contain a flag.
= There was a flag set on one or more searches.
= There were no flags set on any searches.
| OrderStatus Value | Description |
|---|---|
| x:applicant-pending x:app_pending | QuickApp started waiting on the applicant. x:app_pending is returned on initial response, x:applicant_pending is returned on status checks. |
| x:applicant-ready | QuickApp started, applicant has filled out their part, it is waiting to created into an order. |
| x:draft | Order started but not completed, or order is in XML Ready queue. |
| x:canceled | The report has been canceled. |
| x:client-message | The report has a client message on it that the client need to review by logging into the system. (this status is uncommon) |
| x:error | There is an error on the report. |
| x:partial | Used with a post back message when a search is completed. |
| x:pending | The report is not complete yet. |
| x:ready | The report is completed and ready for delivery. |
| x:archived | The report is in archive status. |
Following is an example of the response XML that would be sent in the postback mode of notification when an individual search is completed. The status of the search is complete, but the overall status of the report remains incomplete. Note that the status is x:partial, the type of the completed search is passed in the type attribute of the Screening element, and that the URL returned in the InternetWebAddress element can be used to view the partially completed report.
<?xml version="1.0"?>
<BackgroundReports userId="XML_User_Name" password="*********">
<BackgroundReportPackage>
<ReferenceId>some_id_value</ReferenceId>
<OrderId>12358</OrderId>
<ScreeningStatus>
<OrderStatus flag="TRUE|FALSE">x:partial</OrderStatus>
<OrderDecision></OrderDecision>
</ScreeningStatus>
<Screenings>
<Screening type="criminal" qualifier="federal">
<ScreeningResults type="result" mediaType="html" resultType="report">
<InternetWebAddress>https://demo.instascreen.net/s...</InternetWebAddress>
</ScreeningResults>
</Screening>
</Screenings>
</BackgroundReportPackage>
</BackgroundReports>
Following is an example of the response XML that would be sent in the postback mode of notification when the overall status of the screening report changes to complete. Note that the status is x:ready, there are no attributes on the Screening element and that the URL returned in the InternetWebAddress element can be used to view the completed report.
<?xml version="1.0"?>
<BackgroundReports userId="XML_User_Name" password="*********">
<BackgroundReportPackage>
<ReferenceId>some_id_value</ReferenceId>
<OrderId>12358</OrderId>
<ScreeningStatus>
<OrderStatus flag="TRUE">x:ready</OrderStatus>
<OrderDecision>Fail</OrderDecision>
</ScreeningStatus>
<Screenings>
<Screening>
<ScreeningResults type="result" mediaType="html" resultType="report">
<InternetWebAddress>https://demo.instascreen.net/s...</InternetWebAddress>
</ScreeningResults>
</Screening>
</Screenings>
</BackgroundReportPackage>
</BackgroundReports>
Following is an example of the status inquiry XML the client submits to check the overall status of a background screening report. Note that OrderId is the same identifier that was returned in response to the initial submission.
<?xml version="1.0"?>
<BackgroundCheck userId="XML_User_Name" password="*********">
<BackgroundSearchPackage action="status">
<OrderId>12345</OrderId>
</BackgroundSearchPackage>
</BackgroundCheck>
Following is an example of the XML issued in response to a status inquiry. The values for OrderStatus are x:applicant-pending, x:applicant-ready, x:canceled, x:client-message, x:error, x:pending, and x:ready. Of those, x:ready indicates the report is completed and ready for delivery. The remaining indicate that incomplete work remains on the report.
<?xml version="1.0"?>
<BackgroundReports>
<BackgroundReportPackage>
<ReferenceId>some_id_value</ReferenceId>
<OrderId>12345</OrderId>
<ScreeningStatus>
<OrderStatus flag="TRUE|FALSE">x:ready</OrderStatus>
</ScreeningStatus>
<ReportURL>https://demo.instascreen.net/s...</ReportURL>
</BackgroundReportPackage>
</BackgroundReports>
Following is an example of the status inquiry XML the client submits to request the status of the overall order and receive a self-authenticating link to view the report. Note that OrderId is the same identifier that was returned in response to the initial submission. The value submitted for ReportLinkMinutesActive needs to be between 1 and 20. If the ReportLinkMinutesActive tag is omitted, it will default to 20 minutes.
<?xml version="1.0"?>
<BackgroundCheck userId="XML_User_Name" password="*********">
<BackgroundSearchPackage action="url">
<OrderId>123456</OrderId>
<ReportLinkMinutesActive>20</ReportLinkMinutesActive>
</BackgroundSearchPackage>
</BackgroundCheck>
Following is an example of the XML issued in response to an expiring URL inquiry. The values for OrderStatus are x:applicant-pending, x:applicant-ready, x:canceled, x:client-message, x:error, x:pending, and x:ready. Of those, x:ready indicates the report is completed and ready for delivery. The remaining indicate that incomplete work remains on the report. The link provided is self-authenticating and will not require a login to view the report. The link will expire and access will not be granted to view the report after the time specified in the request (Maximum 20 minutes).
<?xml version="1.0"?>
<BackgroundReports>
<BackgroundReportPackage>
<ReferenceId><![CDATA[]]></ReferenceId>
<OrderId>123456</OrderId>
<ScreeningStatus>
<OrderStatus flag="FALSE">x:ready</OrderStatus>
</ScreeningStatus>
<ReportURL><![CDATA[https://demo.instascreen.net/send/interchangeview/?a=48je1iuv0jt4dq2ke995cqult526evomp7mp4JCzSkPn4likHitsOAxo9DJqAXEzICXkeWIzx8ywa9tKB&b=540&c=rptview&file=123456]]></ReportURL>
</BackgroundReportPackage>
</BackgroundReports>
Following is an example of the XML the client submits to check the overall status for a given background screening report, and will return XML results of the specified search if it was requested on the original order. Note that OrderId is the same identifier that was returned in response to the initial submission.
<?xml version="1.0"?>
<BackgroundCheck userId="XML_User_Name" password="*********">
<BackgroundSearchPackage action="searchstatus">
<OrderId>12345</OrderId>
<Screenings>
<Screening type="criminal" qualifier="singlestate">
</Screening>
</Screenings>
</BackgroundSearchPackage>
</BackgroundCheck>
Following is an example of the XML issued in response to a searchstatus inquiry. The values for OrderStatus are x:applicant-pending, x:applicant-ready, x:canceled, x:client-message, x:error, x:pending, and x:ready. Of those, x:ready indicates the report is completed and ready for delivery. The remaining indicate that incomplete work remains on the report.
<?xml version="1.0"?>
<BackgroundReports>
<BackgroundReportPackage>
<ReferenceId/>
<OrderId>12345</OrderId>
<ScreeningStatus>
<OrderStatus flag="FALSE">x:pending</OrderStatus>
</ScreeningStatus>
<ReportURL>
<![CDATA[ https://localhost/editor/viewReport.taz?file=12345 ]]>
</ReportURL>
<Screenings>
<Screening type="criminal" qualifier="singlestate">
<GatewayXml>
<ResponseData>
<JurisdictionsSearched>AZ-Maricopa Superior Archive, AZ-Maricopa Felony, AZ-Maricopa Misdemeanor, AZ-AOC, AZ-Pima, AZ-Maricopa Superior, AZ-Mohave, AZ-DOC, AZ-Proprietary Offender Data, AZ-Manually Collected Data, AZ-Maricopa Superior, AK-Sex Offender, AL-Sex Offender, AR-Sex Offender, AZ-Sex Offender</JurisdictionsSearched>
<Records count="1">
<Record>
<Offender>
<FullName>MESS, HANK</FullName>
<SSN />
<DOB>1971-04-27</DOB>
<OtherPersonalIdentifiers>
<Gender>MALE</Gender>
<Race />
<Height>000</Height>
<Weight>000</Weight>
<HairColor />
<EyeColor>UNKNOWN</EyeColor>
<StateURL />
<ImageURL />
</OtherPersonalIdentifiers>
<Address>
<AddressLine>,Tonopah AZ 85354</AddressLine>
</Address>
</Offender>
<CaseNumber>M-0000-3583999</CaseNumber>
<Jurisdiction>AZ AOC</Jurisdiction>
<Comments>Case#: M-0000-3583999 Court: Phoenix Municipal</Comments>
<Offenses count="1">
<Offense>
<CaseNumber>M-0000-3583999</CaseNumber>
<Jurisdiction>AZ-Phoenix Munici</Jurisdiction>
<Description>SELLING ALCOHOL TO MINOR; MINOR IN POSSE</Description>
<OffenseType>MISDEMEANOR</OffenseType>
<DispositionDate>2007-01-16</DispositionDate>
<Disposition>
<Info>
<Label>Disposition</Label>
<Data>PLEA GUILTY/RESP SENT IMPOSED</Data>
</Info>
</Disposition>
<OffenseDate />
<StatuteNumber />
<ArrestDate />
<SentenceDate />
<SentenceLength>
<Years />
<Months />
<Days />
</SentenceLength>
<SentenceType />
<FileDate>2007-01-10</FileDate>
<CustodialAgency />
<Comments>MISDEMEANOR</Comments>
</Offense>
<Probation>
<SentenceLength>
<Years />
<Months />
<Days />
</SentenceLength>
</Probation>
</Record>
</Records>
</ResponseData>
</GatewayXml>
</Screening>
</Screenings>
</BackgroundReportPackage>
</BackgroundReports>