Submitting an XML Request

The top-level elements of the XML request contain a userId and password attribute for authenticating to the gateway. The type attribute contains the name of the screening product to order. The user credentials and the product name are all configured, per client, by the background screening agency through the web-based interface.

The ReferenceId element is provided for the client to transmit any sort of file identifier, reference data, or other information of its choosing. The reference id is echoed back, unmodified, in subsequent XML communications.

The PersonalData element contains identifying information about the applicant who is the subject of the background screening report, including name, aliases, social security number, date of birth, and address.

The Screenings element contains Screening elements which indicate which of the available searches should be ordered. Each element contains a type attribute indicating which search is to be ordered, as well as other search specific information, such as driver’s license number, reference contact information, or criminal search jurisdictions.

The Screenings element also contains AdditionalItems elements which are used primarily to set flags that control various modes of operation of the gateway. However, the x:monthly_rent and x:monthly_income items are used to pass in additional information about the applicant. As well, the x:ordernotes items may be used as a catch-all to pass in any additional information pertaining to the applicant or the order.

The x:interface item controls into which workflow the order is placed. If a value of “Instant” is passed in, the order will be immediately submitted for processing. If a value of “Applicant” is passed in, only the applicant’s name and email address need be submitted. The system will then send an email to the applicant inviting him or her to login to the web-based interface to complete the data entry process. If omitted, the default value is ‘Instant’.

The gateway will post XML status notification messages to the client’s URL endpoint, if any, provided in x:postback_url. The XML message will be the value of a POST parameter named “Status”. The URL endpoint is simply a web page or web service hosted in the client’s environment that can accept and process the XML message according to the client’s business rules (e.g. updating a status column in the ATS, sending an alert, etc.). XML messages are sent when individual searches are completed on a report and when the overall report is completed. If credentials are provided in x:postback_username, x:postback_password, and/or x:postback_databaseset, those will be included in the XML message. If the client does not wish to receive XML messages, no value should be provided in x:postback_url.

The x:embed_credentials item controls whether the URLs returned for report access are encoded with embedded credentials to allow one-click viewing of the report, or if following the link will first require user authentication. Setting the value to “TRUE” will return URLs with the embedded credentials, setting the value to “FALSE” will return the link requiring authentication. If user access to the link will be provided outside of an authenticated system, such as email, the latter is recommended.

***Starting Q2 of 2020 links with embedded credentials will only be active for 20 minutes. If a new link is needed, you will need to request this via the API Gateway. See “Example XML – Requesting Expiring URL Inquiry” on the “Determining Order Status” page for more details.***

Test Cases

There are two test cases that can be used. The test cases only are identified by the SSN number. When using these test cases no charges are incurred. Other SSN numbers or no SSN number will incur charges.
SSN First Name Last Name Comments
111-22-3333 Joe Clean Clear / Good results
333-22-1111 Hank Mess Records / Bad results

Gateway URL

The client sends an XML request to the gateway via HTTP POST to /send/interchange using a single HTTP request form parameter named “request“. All XML communications are processed through a publicly available HTTPS protocol URL. Please note that we require TLS 1.2 or newer.

Gateway Request XML

Top-Level, BackgroundCheck Element

BackgroundCheck Required Description
@userId Yes The user id used for authenticating to the gateway. Configured, per client, by the background screening agency. String (50 char)
@password Yes The password used for authenticating to the gateway. Configured, per client, by the background screening agency. String (50 char)
BackgroundSearchPackage Yes (See the BackgroundSearchPackage Element section for more information.)
UserArea No Optional credit card to be charged according to client configuration. (See the BackgroundSearchPackage/UserArea Element section for more information.)

BackgroundSearchPackage Element

BackgroundCheck/BackgroundSearchPackage Required Description
@action Yes

Possible values include:

submit|status|searchstatus|add|addcharge|url

@type Yes Contains the name of the screening product to order. Configured, per client, by the background screening agency.
LinkedApplicants No

For tenant background checks, to link applicants use

<LinkedApplicants>
   <OrderId>123</OrderId>
</LinkedApplicants>
Organization No (See the Organization Element section for more information.)
PersonalData Yes Name, Address, and other personal information about the applicant. (See the PersonalData Element section for more information.)
ReferenceId No

String (64 char)

Provides for the client to transmit any sort of file identifier, reference data, or other information of its choosing. The reference id is echoed back, unmodified, in subsequent XML communications. If Reference is not used, ReferenceId is copied into Reference.
Accepted characters: A-Z 0-9 ! @ # $ % ^ * ( ) _ - + = . ,

Reference No

String (64 char)

The Reference can be used for human visible type data like location or client name. The Reference will show up in the InstaScreen user interface.
Accepted characters: A-Z 0-9 ! @ # $ % ^ * ( ) _ - + = . ,

Screenings Yes The screenings requested for the applicant. (See the Screenings Element section for more information.)
SupportingDocumentation No (See the Supporting Documentation Element section for more information.)
UserArea No Optional fields to include in an order. (See the BackgroundCheck/BackgroundSearchPackage/UserArea Element section for more information.)

Organization Element

BackgroundCheck/BackgroundSearchPackage/ Organization Required Description
@type Yes x:requesting | x:substitute
OrganizationName No

This is the client name. Only necessary if ordering for sub-accounts. Either OrganizationName and/or OrganizationCode can be used when needed.

Max length: 64

OrganizationCode No

This is the client code. Only necessary if ordering for sub-accounts. Either OrganizationName and/or OrganizationCode can be used when needed.

Max length: 64

OrganizationUser No

The client user’s name.

Names must be submitted in "Lname, Fname" format. If no Lname the format is ", Fname".

Fname: String (32 chars)
Lname: String (32 chars)

The total maximum String length including the comma and space between the Fname and Lname is 64 chars.

Example

<BackgroundCheck userId="XML_User_Name" password="*********">
  <BackgroundSearchPackage action="submit" type="test order">
    <Organization type="x:requesting">
      <!-- Only necessary if ordering for sub-accounts -->
      <OrganizationName>Armory Confidential Services</OrganizationName>
      <!-- Only necessary if ordering for sub-accounts -->
      <OrganizationCode>ACS</OrganizationCode>
      <!-- Names must be submitted in "Lname, Fname" format. If no Lname it would be ", Fname" -->
      <OrganizationUser>Cousteau, Jacques</OrganizationUser>
    </Organization>
    <ReferenceId>123456789</ReferenceId>
    <PersonalData>
...

Sample syntax for posting over the end-user-client name

<BackgroundCheck userId="XML_User_Name" password="*********">
  <BackgroundSearchPackage action="submit" type="test order">
    <Organization type="x:substitute">
      <OrganizationName>My Substitute End User</OrganizationName>
    </Organization>
    <ReferenceId>123456789</ReferenceId>
...

PersonalData Element

BackgroundCheck/BackgroundSearchPackage/ PersonalData Required Description
PersonName Yes The name of the applicant (See the PersonName Element section for more information.)
PostalAddress No An element containing the applicant’s postal address. A PersonalData element may contain more than one PostalAddress element. (See the PostalAddress Element section below.)
Telephone No String (24 char)
SendText No

Send QuickApp via text in addition to email. Default is No.

Yes | No

EmailAddress No String (256 char)
Gender No M|F
Race No String (32 char)
DemographicDetail No
DemographicDetail/GovernmentId No SSN number or driver’s license
DemographicDetail/GovernmentId/@issuing Authority No SSN or DMV
DemographicDetail/GovernmentId/@country Code No US
DemographicDetail/GovernmentId/@jurisdicti on No State abbreviation if issuingAuthority is DMV
DemographicDetail/DateOfBirth No yyyy-mm-dd
Aliases No
Aliases/PersonName No There may be zero or more PersonName elements in the Alias element. (See the PersonName Element section for more information.)

PostalAddress Element

PostalAddress Required Description
@type No

current|previous

If more than one address is submitted, the primary address must have a type attribute value of "current". All others must have a type attribute of "previous".

CountryCode No Country. The default value is "US" and is not required for domestic addresses. For international addresses, use the ISO 3166-1 alpha-2 code.
PostalCode No String (32 char)
Region No For domestic addresses, use the USPS 2-letter state abbreviations.
Municipality No String (32 char)
DeliveryAddress/AddressLine No String (63 char)

Example

<PersonalData>
  <PersonName>
    <GivenName>JOSE</GivenName>
    <FamilyName>ADACOMMON</FamilyName>
  </PersonName>
  <PostalAddress type="current">
    <PostalCode>82082</PostalCode>
    <Region>WY</Region>
    <Municipality>Pine Bluffs</Municipality>
    <DeliveryAddress>
      <AddressLine>123 Main</AddressLine>
    </DeliveryAddress>
  </PostalAddress>
  <PostalAddress type="previous">
    <PostalCode>87111</PostalCode>
    <Region>NM</Region>
    <Municipality>Albuquerque</Municipality>
    <DeliveryAddress>
      <AddressLine>3204 Lucerne</AddressLine>
    </DeliveryAddress>
  </PostalAddress>
  <PostalAddress type="previous">
    <CountryCode>CH</CountryCode>
    <PostalCode>1292</PostalCode>
    <Region>Geneve</Region>
    <Municipality>Geneve</Municipality>
    <DeliveryAddress>
      <AddressLine>8 Chemin William Barbey</AddressLine>
    </DeliveryAddress>
  </PostalAddress>
...

PersonName Element

PersonName Required Description
GivenName Yes String (32 char)
FamilyName Yes String (64 char)
MiddleName No String (32 char)
NoMiddleName No True | False
Affix No

Optional Generation

Valid values are JR, SR, I, II, III, and IV

Screenings Element

BackgroundCheck/BackgroundSearchPackage/Screenings Required Description
@useConfigurationDefaults No

Yes|No

The default value is No. Use this attribute set to Yes to order all searches set to DEFault or REQuired in the product. When using Yes, Screening (singular) tags are only required for searches that provide additional information like employment verifications, residence verifications, instant driving records, etc.

Screening No

The Screeningselement may contain one or more Screening.One Screenings element per order.

(See the Screening Element section for more information.)

AdditionalItems No

The Screenings element may contain zero or more Additional Items, which are used primarily to set flags that control various modes of operation of the gateway.

(See the AdditionalItems Element section for more information.)

Screening Element

BackgroundCheck/BackgroundSearchPackage/Screenings/Screening Required Description
@type Yes

A String value that indicates which search is to be ordered. Possible values include: >assumedname | bankruptcy | civil | credit | criminal | custom |drug | education | employment | eviction | executivesummary | license | lienjudgment | healthcare_compliance | personsearch | reference | resident | scorecard | sex_offender | ssn | workcomp

(See the Screening/@name section below for more information about custom types.)

@qualifier See Description

Further identifies the type of screening. The list of possible values differs depending on the value of Screening/@type

@type="civil"
possible values include:
county | federal

@type="criminal"
possible values include:
county | statewide | federal | international | singlestate | national | national_alias | security

@type="custom"
possible values include:
credentials | drug | identity | investigative | repository | summarization | verification

@type="eviction"
possible values include:
singlestate | national

@type="license"
possible values include:
professional | imvcommercial | imvPersonal

@type="reference"
possible values include:
personal | professional

@name See Description

Where the type attribute is custom and the qualifier attribute is one of identity, repository, investigative, verification, credentials, summarization, or drug the name comes from the custom search name in the Manage Custom Searches area.

If there is an ampersand in the name, it needs to be submitted as an entity

<Screening type="custom" qualifier="repository" name="REPOSITORY CUSTOM & TWO">
</Screening>
          

Credential Searches

Search Attributes
Education Verification type=education
<Screening type="education">
  <Region>UT</Region>
  <EducationHistory>
    <SchoolOrInstitution>
      <SchoolName>UNIVERSITY OF UTAH</SchoolName>
      <ContactCode>UofU</ContactCode>
      <PostalAddress>
        <Municipality>Draper</Municipality>
        <Region>UT</Region>
        <PostalCode>84020</PostalCode>
        <DeliveryAddress>
          <AddressLine>1192 Draper Parkway #401</AddressLine>
        </DeliveryAddress>
      </PostalAddress>
      <Degree degreeType="bachelors">
        <DegreeName>COMMUNICATIONS; Graduated: Yes</DegreeName>
      </Degree>
      <DatesOfAttendance>
        <StartDate>
          <StringDate>2002-09 TO 2006-01</StringDate>
        </StartDate>
      </DatesOfAttendance>
    </SchoolOrInstitution>
  </EducationHistory>
</Screening>              
          
Instant Driving Records type=license qualifier=imvpersonal
<Screening type="license" qualifier="imvPersonal">
  <Region>UT</Region>
  <Duration>7</Duration>
  <SearchLicense>
    <License>
      <LicenseNumber>123456789</LicenseNumber>
    </License>
  </SearchLicense>
</Screening>              
          

If no Duration is included, the default value is determined by the longest non-CDL option available for the specified state. Below are options for durations per state:
AR = 3, 5*
AZ= 3, 5
DC = 3, 10
FL = 3, 7, 99
GA = 3, 7
ME = 3, 10
MN = 0, 99
NC = 3, 7
NY = 3, 7*
SC = 3, 10
TX = 3, 5*
UT = 3, 5*
WY = 3, 10*
* = CDL

Healthcare Compliance Search type=healthcare_compliance
<Screening type="healthcare_compliance" />
Professional License type=license qualifier=professional
<Screening type="license" qualifier="professional" />

Drug Searches

Search Attributes
Substance Abuse Detection type=drug
<Screening type="drug">
  <Panel>Panel Name</Panel>
  <PermissiblePurpose>Pre- Employment</PermissiblePurpose>
  <SpecimenId></SpecimenId>
</Screening>

Possible values for PermissiblePurpose are: Pre-Employment, Random, Periodic, Post Incident, For Cause, Reasonable Suspicion, Return To Duty, Follow Up, Reconfirmation, Retest, Point of Collection Sampling, Student, or Other

Optional Collection Info Specification

<Screening type="drug">
  <Panel>Panel Name</Panel>
  <PermissiblePurpose>Pre- Employment</PermissiblePurpose>
  <SpecimenId></SpecimenId>
  <CollectionInfo>
    <SiteCode>UT076</SiteCode>
    <Observed>Yes</Observed>
    <SplitSpecimen>Yes</SplitSpecimen>
    <ExpirationDate>2017-10-01</ExpirationDate>
    <ExpirationTime>23:59:59</ExpirationTime>
    <ExpirationTimeZone>America/Los_Angeles</ExpirationTimeZone>
    <TestScheduler>Applicant</TestScheduler>
  </CollectionInfo>
</Screening>

CollectionInfo element is optional
SiteCode only applies to applicable products/configurations Observed only applies to DOT Urine panels and is Yes or No SplitSpecimen only applies to Non-DOT Urine panels and is Yes or No
ExpirationDate format is YYYY-MM-DD
ExpirationTime format is HH:mm:ss (defaults to 23:59:59 if not specified)
Possible values for ExpirationTimeZone are: America/Denver, America/Phoenix, America/Los_Angeles, America/Chicago, America/New_York, America/Juneau, Pacific/Honolulu (defaults to America/Denver or SiteCode time if not specified)
Possible values for TestScheduler are: applicant or processor

Identity Development Searches

Search Attributes
Person Search type=personsearch
<Screening type="personsearch" />
Social Security type=ssn
<Screening type="ssn" />

Investigative Searches

Search Attributes
Assumed Name Records type=assumedname
<Screening type="assumedname" />
Bankruptcy Filings bankruptcy
<Screening type="bankruptcy" />
County Civil Records type=civil qualifier=county

A screening element for County Civil records can contain a child called "Region" and a child element called "County". If you do not include a "Region" and "County", InstaScreen will select the "Region" and "County" from the first address provided.

<Screening type="civil" qualifier="county" />

or

<Screening type="civil" qualifier="county" >
  <Region>NM</Region>
  <County>Sandoval</County>
</Screening>
County Criminal Records type=criminal qualifier=county

A element for County Criminal records can contain a child called "Region" and a child element called "County". If you do not include a "Region" and "County", InstaScreen will select the "Region" and "County" from the first address provided.

<Screening type="criminal" qualifier="county" />

or

<Screening type="criminal" qualifier="county" >
  <Region>NM</Region>
  <County>Sandoval</County>
</Screening>
Federal Civil Records type=civil qualifier=federal

A screening element for Federal Civil records can contain a child called "District" and a child element called "Region". If you do not include a "Region" and "District", InstaScreen will select the "Region" and "District" from the first address provided.

<Screening type="civil" qualifier="federal" >
  <Region>NM</Region>
  <District>New Mexico</District>
</Screening>
Federal Criminal Records type=criminal qualifier=federal

A screening element for Federal Criminal records can contain a child called "District" and a child element called "Region".

<Screening type="criminal" qualifier="federal" >
  <Region>New Mexico</Region>
  <District>New Mexico</District>
</Screening>
Global Security Watch List type=criminal qualifier=security
<Screening type="criminal" qualifier="security" />
International Criminal Records type=criminal qualifier=international
<Screening type="criminal" qualifier="international" />
Lien and Judgment Filings type=lienjudgement

A screening element for Lien and Judgment Filings can contain a child called "County" and a child element called "Region". If you do not include a "Region" and "County", InstaScreen will select the "Region" and "County" from the first address provided.

<Screening type="lienjudgment">
  <Region>NM</Region>
  <County>Sandoval</County>
</Screening>
National Criminal Database Alias Search type=criminal qualifier=national_alias
<Screening type="criminal" qualifier="national_alias" />
National Criminal Database Search type=criminal qualifier=national
<Screening type="criminal" qualifier="national" />
National Rental Records Database Search type=eviction qualifier=national
<Screening type="eviction" qualifier="national" />
Sex Offender Records type=sex_offender

A screening element for Sex Offender Records can contain a child called "Region". If you do not include a "Region", InstaScreen will select the "Region" from the first address provided.

<Screening type="sex_offender">
  <Region>CO</Region>
</Screening>
State Criminal Court Search type=criminal qualifier=statewide

A screening element for State Criminal Court Search can contain a child called "Region". If you do not include a "Region", InstaScreen will select the "Region" from the first address provided.

<Screening type="criminal" qualifier="statewide">
  <Region>CO</Region>
</Screening>
State Criminal Database Search type=criminal qualifier=singlestate

A screening element for State Criminal Database Search can contain a child called "Region". If you do not include a "Region", InstaScreen will select the "Region" from the first address provided.

<Screening type="criminal" qualifier="singlestate">
  <Region>UT</Region>
</Screening>
State Rental Records Database Search type=eviction qualifier=singlestate

A screening element for State Rental Records Database Search can contain a child called "Region". If you do not include a "Region", InstaScreen will select the "Region" from the first address provided.

<Screening type="eviction" qualifier="singlestate">
  <Region>UT</Region>
</Screening>

Verification Searches

Search Attributes
Residence Verification type=resident
<Screening type="resident" verify="yes">
  <StartDate>2005-06-01</StartDate>
  <EndDate>2008-06-01</EndDate>
  <ContactInfo>
    <PersonName>
      <FormattedName>Ramona Propietario</FormattedName>
    </PersonName>
    <ContactCode>Romona</ContactCode>
    <Telephone>505-299-5527</Telephone>
    <Fax>801-999-8555</Fax>
    <EmailAddress>res@res.com</EmailAddress>
    <PostalAddress>
      <PostalCode>87111</PostalCode>
      <Region>NM</Region>
      <Municipality>Albuquerque</Municipality>
      <DeliveryAddress>
        <AddressLine>3204 Lucerne NE</AddressLine>
      </DeliveryAddress>
    </PostalAddress>
  </ContactInfo>
  <Comments>These are some resident comments.</Comments>
</Screening>

When an applicant has requested that we do not contact the property, the verify attribute should be set to "no".

<Screening type="resident" verify="no">
...
Employment Verification type=employment
<Screening type="employment" verify="yes">
  <OrganizationName>Burger Shack</OrganizationName>
  <ContactCode>BurgerShack</ContactCode>
  <Title>Fry Cook</Title>
  <JobLevelInfo>Full-time</JobLevelInfo>
  <StartDate>2005-05-05</StartDate>
  <EndDate>2005-06-16</EndDate>
  <!--Valid Frequencies: Hourly, Weekly, Monthly, Yearly, Annually, Contract -->
  <Compensation>21.50 Hourly</Compensation>
  <ReasonForLeaving>Moved to Texas</ReasonForLeaving>
  <ContactInfo>
    <PersonName>
      <FormattedName>Susan Boss</FormattedName>
    </PersonName>
    <Telephone>801-123-4567</Telephone>
    <Fax>801-999-9999</Fax>
    <EmailAddress>emp@example.com</EmailAddress>
    <PostalAddress>
      <PostalCode>84020</PostalCode>
      <Region>UT</Region>
      <Municipality>Draper</Municipality>
      <DeliveryAddress>
        <AddressLine>1192 Main St</AddressLine>
      </DeliveryAddress>
    </PostalAddress>
  </ContactInfo>
</Screening>

When an applicant has requested that we do not contact the employer, the verify attribute should be set to "no".

<Screening type="employment" verify="no">
...
Personal Reference Verification type=reference qualifier=personal
<Screening type="reference" qualifier="personal">
  <Contact>
    <PersonName>
      <FormattedName>1 Yolanda Ortega</FormattedName>
    </PersonName>
    <ContactMethod>
      <Telephone>505-292-3969</Telephone>
      <Fax>801-FAX-PERS</Fax>
      <EmailAddress>personal@example.com</EmailAddress>
    </ContactMethod>
    <Relationship>Mother</Relationship>
  </Contact>
  <Comments>This is my list of random comments.</Comments>
</Screening>
Professional Reference Verification type=reference qualifier=professional
<Screening type="reference" qualifier="professional">
  <Contact>
    <PersonName>
      <FormattedName>1 Yuan Li Xian</FormattedName>
    </PersonName>
    <ContactMethod>
      <Telephone>801-444-5544</Telephone>
      <Fax>801-FAX</Fax>
      <EmailAddress>yuan@example.com</EmailAddress>
    </ContactMethod>
    <Relationship>Supervisor</Relationship>
  </Contact>
  <Comments>This is my list of random comments.</Comments>
</Screening>
Reference Verification type=reference
<Screening type="reference">
  <Contact>
    <PersonName>
      <FormattedName>Plain Old Reference</FormattedName>
    </PersonName>
    <ContactMethod>
      <Telephone>123-123-1234</Telephone>
      <Fax>801-FAX-PLAIN</Fax>
      <EmailAddress>plain@example.com</EmailAddress>
    </ContactMethod>
    <Relationship>Reference</Relationship>
  </Contact>
  <Comments>This is my list of random comments.</Comments>
</Screening>
Workers Compensation Report type=workcomp
<Screening type="workcomp" />

Other Searches

Search Attributes
Scorecard Pro type=scorecard
<Screening type="scorecard_pro" />
Tenant Scorecard type=scorecard
<Screening type="scorecard" />

AddtionalItems Element

BackgroundCheck/BackgroundSearchPackage /Screenings/AdditionalItems Required Description
@Type Yes (See the AdditionalItems/@Type Values section for possible values for this attribute.)
Text Yes (See the AdditionalItems/@Type Values section for possible values.)

AdditionalItems/@Type Values

@Type Value Description
x:california_credit_code

for submitting the California Credit Code override value. The validvalues for the override code are one of the following:

EXECUTIVE_EXEMPT | STATE_DEPT_JUST | LAW_ENFORCEMENT|REQUIRED_BY_LAW | ACCESS_TO_PII | ACCESS_TO_CASH | FINANCIAL_TXS | CONFIDENTIAL_INF

Example:

<Screenings>
  ...
  <AdditionalItems type="x:california_credit_code">
    <Text>EXECUTIVE_EXEMPT</Text>
  </AdditionalItems>
</Screenings>
x:decision_model

The valid values for this code are one of the following:

SCORECARD: request that the Scorecard Decision be returned in the completed XML.

SCORECARD_PRO: request that the Scorecard Pro Decision be returned in the completed XML.

REPORT: request that the Report Decision be returned in the completed XML. The default values returned for REPORT are: Approved (per client specifications), Pending (per client specifications), Negative (per client specifications), Review, Dispute, Pre- Adverse (per client specifications), Declined (per client specifications), and Opt Out (per client specifications).

x:desired_unit The desired apartment number can be passed over in an AdditionalItems element, similar to the monthly rent. String (16 char)
x:embed_credentials

Controls whether the URLs returned for report access are encoded with embedded credentials to allow one-click viewing of the report, or if following the link will first require user authentication. Setting the value to "TRUE" will return URLs with the embedded credentials, setting the value to "FALSE" will return the link requiring authentication. If user access to the link will be provided outside of an authenticated system, suchas email, the latter is recommended.

***Starting Q2 of 2020 links with embedded credentials will only be active for 20 minutes. If a new link is needed, you will need to request this via the API Gateway. See "Example XML – Requesting Expiring URL Inquiry" on the "Determining Order Status" page for more details.***

x:integration_type

This is required. It is used for identifying each integration type. Choose a string to identify your company/integration.

Example:

<Screenings>
  ...
  <AdditionalItems type="x:integration_type">
    <Text>CompanyABC</Text>
  </AdditionalItems>
</Screenings>
x:interface

Controls into which workflow the order is placed. If omitted, the default behavior is "INSTANT".

Value definitions:

"REVIEWED" = Order submission goes into the XML Ready queue for processing by CRA/client in InstaScreen.

INSTANT" = Order submission processes automatically according to InstaScreen configuration.

APPLICANT" = Order submission goes into Applicant Pending queue for data entry by the applicant. InstaScreenwill send email invitation to the applicant with a link and instructions for completing the data entry. The submission XML needs a minimum of the applicant’s name, email address, the requested Screening(s) and the QuickApp x:interface flag.

APPLICANT_NO_EMAIL" = Order submission goes into Applicant Pending queue for data entry by the applicant. InstaScreen will not send an email invitation to the applicant, so the third-party will need to communicate the link and instructions to the applicant.

Example:

<BackgroundCheck userId="XML_User_Name" password="*********">
  <BackgroundSearchPackage action="submit" type="DEMO">
    <Screenings>
      ...
      <AdditionalItems type="x:interface">
        <Text>REVIEWED</Text>
      </AdditionalItems>
    </Screenings>
  </BackgroundSearchPackage>
</BackgroundCheck>

Note that the QuickApp link comes back in the response XML for both the APPLICANT and APPLICANT_NO_EMAIL x:interface types.

x:monthly_income The amount of income the applicant makes per month. Numeric.
x:monthly_rent The amount the applicant pays in rent per month. Numeric.
x:ordernotes A catch-all to pass in any additional information pertaining to the applicant or the order.
x:postback_basicauth Post back with HTTP basic authentication
x:postback_databaseset Optional databaseset returned in a post back message.
x:postback_format

In order to flag a requesting the report to return in PDF format, add the AdditionalItems element to the Screenings section of the original request XML. With that flag, the report view link that is returned in the XML completed notification will be for the PDF view of the report.

Example:

...
   <Screenings>
      ...
      <AdditionalItems type="x:postback_format">
       <Text>PDF</Text>
      </AdditionalItems>
    </Screenings>
  </BackgroundSearchPackage>
</BackgroundCheck>
x:postback_password Optional password returned in a post back message.
x:postback_suppress_xpartial

When using x:postback_url, if you want to suppress the x:partial messages, include x:postback_suppress_xpartial

The valid values for this code are one of the following: true or false

<AdditionalItems type="x:postback_suppress_xpartial">
  <Text>true</Text>
</AdditionalItems>
x:postback_url

The gateway will post XML status notification messages to the client’s URL endpoint, if any, provided in x:postback_url. The XML message will be the value of a POST parameter named "Status". The URL endpoint is simply a web page or web service hosted in the client’s environment that can accept and process the XML message according to the client’s business rules (e.g. updating a status column in the ATS, sending an alert, etc.). XML messages are sent when individual searches are completed on a report and when the overall report is completed. If credentials are provided in x:postback_username, x:postback_password, and/or x:postback_databaseset, those will be included in the XML message. If the client does not wish to receive XML messages, no value should be provided in x:postback_url.

TazWorks will not install any third-party security certificates in our testing, staging, or production environments. Integrators are required to use SSL Certificates signed by one of the Certificate Authorities included in the Sun Java SE 8.0_121 default trusted certificate keystore. This includes any intermediate or chained SSL certificate(s).

The post back url needs to use port 80 or 443.

x:postback_username Optional username returned in a post back message.
x:return_xml_results

Either yes or no.

The following searches are supported by x:return_xml_results: County

Criminal Records Search
Credit Report (Equifax, Experian, Transunion, and Acxiom)
Custom Searches Education Verification Employment Verification Instant Driving Records
National Criminal Database Alias Search National Criminal Database Search National Rental Records Database Search Person Search
Personal Reference Verification Professional Reference Verification PSP Crash And Inspection History Reference Verification
State Criminal Court Search State Criminal Database Search
State Rental Records Database Search Tenant Scorecard

x:queue_consumer_disclosure
<AdditionalItems type="x:queue_consumer_disclosure">
  <Text>true</Text>
</AdditionalItems>
x:postback_name

Either yes or no.

Applicant’s name returned in a post back message.

*Needs to be approved and enabled by CRA before use.

x:postback_address

Either yes or no.

Applicant’s address returned in a post back message.

*Needs to be approved and enabled by CRA before use.

x:postback_ssn

Either yes or no.

Applicant’s SSN returned in a post back message.

*Needs to be approved and enabled by CRA before use.

x:postback_dob

Either yes or no.

Applicant’s Date of Birth returned in a post back message.

*Needs to be approved and enabled by CRA before use.

x:postback_drivers_license

Either yes or no.

Applicant’s Drivers License number and state returned in a post back message.

*Needs to be approved and enabled by CRA before use.

SupportingDocumentation Element

BackgroundSearchPackage/SupportingDocumentation Required Description
@authorization No

Yes|No

The default value is No. Use this attribute set to Yes to identify the attachment as an authorization form.

@spouse No

Yes|No

The default value is No. Use this attribute set to Yes to if the attachment is for the spouse.

OriginalFileName Yes

String (64 char)

The file name, without path information.

Name Yes

String (255 char)

The display name for the file.

EncodedContent Yes Within the XML message binary files such as .PDF are submitted as base64 encoded content. You can submit multiple documents, each in their own SupportingDocumentation element.

Example

The following is an example of XML for passing over an attachment for the applicant’s file in InstaScreen. Possibly used for this include attaching an applicant release or disclosure form to the submission.

Note. Within the XML message, binary files such as PDF are submitted as base64 encoded content. You can submit multiple documents, each in their own SupportingDocumentation element.

...
    </Screenings>
    <SupportingDocumentation>
      <OriginalFileName>image.png</OriginalFileName>
      <Name>Network Hardware Specifications</Name>
      <EncodedContent>
        <!—base64 encoded file contents go here --> 
        iVBORw0KGgoAAAANSUhEUgAAAvsAAAKPCAIAAAB8UJLOAAAAAXNSR0Iars4c6QAAAARnQU1BAACx
       jwv8YQUAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAA/45JREFU
        eF7t/U3rREF31gt7voeg4NShZPDgxJEGJ4Kg0YngrQQlHBQ0OniCRASfR8RISJAbHQgixoFncPA1
        U41EHKlIhiGcYQbxG3iunJ/nuq+sqv3S3bu79+5ef5o/u3dXrVp1rZdaVbt2rf/tf/7P//m7+q8R
        ...
      </EncodedContent>
    </SupportingDocumentation>
  </BackgroundSearchPackage>
</BackgroundCheck>

BackgroundCheck/BackgroundSearchPackage/UserArea Element

BackgroundCheck/BackgroundSearchPackage/UserArea Required Description
PositionDetail No (See the PositionDetail Element section for more information.)

PositionDetail Element

This is XML for passing over the accounting to InstaScreen When the CRA has received payment for the background check outside of InstaScreen.

BackgroundCheck/BackgroundSearchPac kage/UserArea/PositionDetail Required Description
Billable No Billable – String (64 char)
CostCode No Cost Code – String (64 char)
DesiredUnit No Desired Unit – String (16 char)
EmploymentState No Employment State – String (64 char)
JobCode No Job Code – String (64 char)
JobLocation No Job Location – String (64 char)
OptionalField1 No Optional Field 1 – String (64 char)
OptionalField2 No Optional Field 2 – String (64 char)
OptionalField3 No Optional Field 3 – String (64 char)
OptionalField4 No Optional Field 4 – String (64 char)
OptionalField5 No Optional Field 5 – String (64 char)
OptionalField6 No Optional Field 6 – String (64 char)
OptionalField7 No Optional Field 7 – String (64 char)
OptionalField8 No Optional Field 8 – String (64 char)
OptionalField9 No Optional Field 9 – String (64 char)
OptionalField10 No Optional Field 10 – String (64 char)
ReferredBy No Referred By – String (64 char)
ProposedPosition No Proposed Position – String (64 char)
ProposedSalary No Proposed Salary – String (32 char)

Example

<BackgroundCheck userId="XML_User_Name" password="*********">
  <BackgroundSearchPackage action="submit" type="demo">
    ...
    <UserArea>
      <PositionDetail>
        <CostCode>XYZ</CostCode>
        <JobCode>123</JobCode>
        <JobLocation>Taipei, Taiwan</JobLocation>
      </PositionDetail>
    </UserArea>
  </BackgroundSearchPackage>
</BackgroundCheck>

BackgroundCheck/UserArea Element

BackgroundCheck/UserArea Required Description
CreditCard No (See the CreditCard Element section for more information.)
CreditCardPayment No (See the CreditCardPayment Element section for more information.)

CreditCard Element

BackgroundCheck/UserArea/CreditCard Required Description
CardType Yes visa | amex | discover | mastercard
CardNumber Yes Numeric (max 16 digits)
CardSecurity No Numeric (3-5 digits)
ExpireMonth Yes Numeric (2)
ExpireYear Yes Numeric (4)
FirstName Yes String (64 char)
LastName Yes String (64 char)
BillingStreetAddress Yes String (128 char)
BillingCity Yes String (128 char)
BillingState Yes String (16 char)
BillingZip Yes Numeric (5 or 5-4)

Example

<BackgroundCheck userId="XML_User_Name" password="*********">
  <BackgroundSearchPackage action="submit" type="demo">
            ...
  </BackgroundSearchPackage>
  <UserArea>
    <CreditCard>
      <CardType>visa</CardType>
      <CardNumber>4111111111111111</CardNumber>
      <CardSecurity>321</CardSecurity>
      <ExpireMonth>12</ExpireMonth>
      <ExpireYear>2013</ExpireYear>
      <FirstName>FRANK</FirstName>
      <LastName>CARDHOLDER</LastName>
      <BillingStreetAddress>1234 MAIN</BillingStreetAddress>
      <BillingCity>MESA</BillingCity>
      <BillingState>AZ</BillingState>
      <BillingZip>85201</BillingZip>
    </CreditCard>
  </UserArea>
</BackgroundCheck>

CreditCardPayment Element

This is XML for passing over the accounting to InstaScreen When the CRA has received payment for the background check outside of InstaScreen.

BackgroundCheck/UserArea/CreditCardP ayment Required Description
Amount No Numeric
SalesTax Yes Numeric
LastFour No String (4 char)
TransactionId No String (32 char)
AuthorizationCode No String (8 char)

Example

<BackgroundCheck userId="XML_User_Name" password="*********">
  <BackgroundSearchPackage action="submit" type="demo">
            ...
  </BackgroundSearchPackage>
  <UserArea>
    <CreditCardPayment>
      <!—Should be a negative amount -->
      <Amount>-34.00</Amount>
      <!—Sales Tax should be a positive amount -->
      <SalesTax>2.95</SalesTax>
      <LastFour>1006</LastFour>
      <TransactionId>120490771924</TransactionId>
      <AuthorizationCode>999999</AuthorizationCode>
    </CreditCardPayment>
  </UserArea>
</BackgroundCheck>

Add To Order

This option can be used to add additional searches to a report that was previously submitted. Before this can be used, the following client preference must be checked: “Allow client to add new search types after order is placed (add to order)”.

<?xml version='1.0'?>
    <BackgroundCheck userId='XML_User_Name' password='*********'>
        <BackgroundSearchPackage action='add'>
            <OrderId>123456</OrderId>
            <Screenings>
                <Screening type='personsearch'>
                    <Vendor>OMNI_ROUTING</Vendor>
                </Screening>
            </Screenings>
        </BackgroundSearchPackage>
    </BackgroundCheck>