API

Tenstreet provides a robust api, which allows the client to send and receive data to Tenstreet. The Tenstreet API supports both a standard HTTP ‘POST’ and a Simple Object Access Protocol (SOAP) when receiving data from the client.

When sending data to the client, Tenstreet sends the data over a SSL HTTP ‘POST’ to the clients requested URL. All data is transmitted in XML format. For more in-depth information, check out the links below.

Introduction

Our advanced API includes some premium features, including sending documents with your application data, and using custom questions for routing, and tagging. Setting these features up will take custom development and coordination between Tenstreet and you. For use of these features, Tenstreet charges an integration fee. Please reach out to your account manager, or [email protected] for more details.

In order to send data to Tenstreet programmatically, Tenstreet provides an XML POST listener and a Web Service (WSDL) you may consume (pick one).

When HTTP POSTing, you POST with a Content-Type of text/xml and a charset of UTF-8 in the header and does not come over as a url-encoded field. We take whatever information is sent over and put it into our system. If you do not have information for a field that we have listed in our specification, leave the field out entirely.


Agreements and Acknowledgements

Understanding the API

You are responsible for understanding the basics of XML and HTTP posting andunderstanding the information contained within this document.

Debugging

You are responsible for parsing the Tenstreet response for debugging purposes. Failure to do so will result in data not being accepted into the system. If the posting type requires you to send a response back to our system, you are also responsible for sending that response, otherwise our system will not consider operations complete.

Logging

We expect you to keep both post and response logs of data that has been sent and received. We expect this to be kept for at least 1 calendar year. Tenstreet keeps the same data for 1 calendar year. This ensures the ability to audit all transactions from both sides.

Data Accuracy

If you have access to send data to multiple accounts (usually in the case of a job board), you also acknowledge that you will be responsible for posting the correct information to the correct account. Tenstreet will only validate that the passed Company ID is a valid Enterprise Company, but will not attempt to validate that the information being sent belongs to the Company ID provided.

Support Requests

We want you to receive and send data to our system as your business use requires. We have a dedicated support group that handles requests about integrating your data with us at [email protected]

If you need to contact us for support, please note that we are working toward getting you a response in the order it was received in the support queue, and that can take several elapsed working days. Sending more requests will just put your need further behind in the queue as we will have to handle them all separately. So please send one really well-formed request at a time.

This service is very popular, technical, and therefore, requires us to free up resources to answer your questions. But we will get to them.

When sending support requests, please include:


  1. The Tenstreet XML response you are receiving if you are receiving one at all
  2. your outbound or inbound IP Addresses (as relevant)
  3. The URL you are posting to, as it is quite often that clients post to the development URL for their production data and get a response that says the company id is invalid, so make sure you are posting to the right environment.
  4. The XML you are sending or receiving (as relevant), This speaks volumes to us, and will ultimately expedite your request. Do not send us PII data in an email (PII is defined as the last name with any of the following: SSN, DOB, or license number). Just replace that with xxx-xx-1234 in the file before you send it. Or delete it completely, as these pieces of info are not usually relevant to a support case.
  5. A phone number, time zone, and time frame in which we can reach you. Often these issues are less overhead to resolve with a single phone call rather than multiple emails.
Other Items

In building this integration, you agree to not attempt to reverse engineer any portions of our application process, including our side of the interface or any portion of the IntelliApp process. The purpose of the API is to enable you to send basic application data and lead form data to Tenstreet. It is not meant to enable you to create a more complete application (as you’d find on Tenstreet’s IntelliApp) and then send all of the data to us. The API does not support this and it is not our intent for its use.


Authentication to the Tenstreet API

To authenticate your request, you must supply an authentication node in your xml. Please review the following table for a description of the node.

TenstreetData\Authentication
Node Data Type Required Description
ClientId Integer Required Provided by Tenstreet. The ClientId identifies the sender uniquely and is completely unrelated to the CompanyId(s) you are sending your information to.
Password String Required Provided by Tenstreet. This is a password generated specifically for authenticating to the Tenstreet API. It will be used for all API services, but nowhere else in the system.
Service String Required The service you are requesting.Tenstreet will provide the appropriate value for this field. For sending application data to Tenstreet, this value is: subject_upload
Example

The xml you need to use for this node looks like the follow and must be at the top of your file:

<Authentication>
	<ClientId>2</ClientId>
	<Password>987u34hng87asdh</Password>
	<Service>Service</Service>
</Authentication>
Considerations

PLEASE NOTE:This above is sample data. To receive your credentials, please contact [email protected]


Sending Application/Lead Data from Client to Tenstreet (subject_upload service)

Please review the following table for a listing of all the nodes that can be passed in this request, if they are required or not, and a description of what type of data can be passed in.

When developing at the start, you will POST to our development environment using CompanyId 15 (our test company in development set aside for this purpose). When your POSTs are successful (Status of Accepted), we will return HTML in an element called DisplayHTML. This is how you know your XML is being built and formatted correctly, as this is exactly how the customer will see your information. It is your responsibility to view the DisplayHTML response XML element and ensure that the information you send to us is formatted the way you want it to be, including accuracy and completeness.

TenstreetData

This is standard information that is sent with the request:

Node Data Type Required Description
Mode String Required DEV or PROD. Informational only, confirms the system that the data came from.
Source String Required Provided by Tenstreet. Indicates the source of the application, which is used in many places in Dashboard and is how the customer will see you. If you are a job board, you will have a unique Source that identifies you. In some rare cases, you may have more than one Source (a company who has more than one business or job board, for example, might have a Source for each unique job board).
CompanyId Integer Required

Provided by Tenstreet. Your internal Company ID, used to route your info to the correct Tenstreet customer

Example: 15

Company String Optional

Name of the Company the data came from. Informational Only and helpful for troubleshooting, especially when the CompanyId provided is incorrect.

Example: My Company Name, LLC

DriverId Integer or String Optional An identifier in your system for a subject, such as a unique ID.
Personal Data

This section is contains demographic info on the candidate

TenstreetData\PersonalData\PersonName
Node Data Type Required Description
Prefix String Optional Subject’s Prefix (Mr., Mrs., etc)
GivenName String Required Subject’s given, or first, name
MiddleName String Optional Subject’s middle name or initial(s)
FamilyName String Required Subject’s family, or last, name
Affix String Optional Subject’s Affix (MD, II, III, Jr, etc)
TenstreetData\PersonalData\PostalAddress (Optional)
Node Data Type Optional Description
CountryCode String Optional Two letter code for subject’s country of residence. Use standard country codes from USPS. United States is US, Canada is CA.
Municipality String Optional Subject’s municipality of residence. Also called City or Town
Region String Optional Subject’s region of residence. Also called State or Province
PostalCode String or Integer Optional Subject’s postal code. Also called Zip Code or Post Code
Address1 String Optional Subject’s primary address. Usually a number followed by a street name. e.g., 123 Test Road
Address2 String Optional Subject’s secondary address. Usually an apartment number or division assignment number
ApplicationData

This is data from your application. Not all of these fields will be filled in every time and depending on your application setup, some sections may not appear at all. If you do not have information for a field or section, do not even include it in the XML. Do not provide empty fields or sections.

TenstreetData\ApplicationData
Node Data Type Optional Description
AppReferrer String Optional

Referrer string for where the application came from. The Source of the lead form answers the question “What form was completed?” while the Referrer answers the question “Where did the person who filled out that form come from?” You can enter almost any string into this field (up to 100 non-multibyte characters). The Referrer is visible on both reports and on the lead you provide.

Possible uses of the Referrer include: 1) indicating the specific lead page a candidate completed, 2) tracking the google campaign PPC that the candidate used to arrive at your Source form, 3) the web address that hosts the form if you have multiple sites for SEO purposes. Basically, you should use Referrer to send information that you’d want to report on, whatever that might be.

TenstreetData\ApplicationData\DisplayFields\DisplayField (Optional, Repeatable)

DisplayFields are custom fields that do not fit elsewhere in our API. Everyone has custom questions that they ask that are a little different than the way someone else asks the question (and more generally than you’d ask on a full application), so this is your opportunity to put the questions and answers here. These can be literally anything and we will record the question and answer (DisplayPrompt and DisplayValue respectively). These questions and answers are visible to the system users in the HTML we render for your lead, but are not actually stored in the database.

Node Data Type Optional Description
DisplayPrompt String Required The question you would like to record
DisplayValue String Optional The answer you would like to record
TenstreetData\ApplicationData\Licenses\License (Optional, Repeatable)

License information goes here if you have more detailed info. If you do not have a value for one of these fields, do not include the element. If you don’t have license info at all, don’t include the Licenses element at all. If you have more than one License, you should indicate which one is the CurrentLicense.

Node Data Type Optional Description
CurrentLicense String Optional Y or N. Is this the subject’s current license.
LicenseNumber String Required Number of the license
ExpirationDate DateTime Optional When the license expires. Format is YYYY-MM-DD.
Region String Required State or Province that issued the license.
CountryCode String Optional Two letter code for the country that issued the license.
CommercialDriversLicense String Optional Y or N. Is this license a Commerical Drivers License (CDL).
LicenseClass String Optional License Class. Valid values are “Class A”, “Class B”, “Class C”, “Class D”
TenstreetData\ApplicationData\Licenses\License\Endorsements (Optional)
Node Data Type Optional Description
Endorsement String Optional Name of the endorsement. These are the valid endorsements you may pass:
hazmat
xendorsement
tanker
doublestriples
other
Premium Features
TenstreetData\ApplicationData\CustomQuestions\CustomQuestion (Optional)

Custom question can be used for custom routing of applications (answer must correspond with list provided by Tenstreet).

Node Data Type Optional Description
QuestionId String Required Question ID/Name, provided by Tenstreet
Question String Required Wording of Question
Answer String Required Answer to the question. If used for custom routing, must use specific answers provided by Tenstreet.
Example

For an example XML file, please click here

Considerations

We identify the company in our system (Tenstreet’s Customer) using the CompanyId field. Each company in our system has a unique ID (732, 10281, etc.). The sender would need to store these values for each company when sending them over.

You can fill in however few or many of the fields as you want, so long as the required fields are met. Even with the pared down sample I’m sending over, there are more fields than will be used. If there are questions asked that don’t fit readily into our database, send them as DisplayFields. DisplayFields are fields that you want to be visible to the user looking at your lead but that are specific to your site and not ours, so we don’t have a way to insert them into our standard database tables. So in our attached example, you’d put “Are you at least 21 years old?” into the DisplayPrompt and put the answer into the DisplayValue.

The <source> of all of your leads would be something we work together on (but would reflect your job board name). The “referrer” (ApplicationData->AppReferrer) can be anything you want it to be for reporting purposes to indicate what position, link, campaign, etc. it came from, and is used for reporting later.

POST Response

You will always receive a POST response from Tenstreet, regardless if the attempted post was accepted or rejected, or if nothing occurred during the post. Please review the following table for a description of the XML and nodes that will be sent back.

You are responsible for monitoring all rejections (Status of REJECTED) we send back to you and determining the issue.

TenstreetResponse
Node Data Type Description
Status String ACCEPTED or REJECTED. The description node will contain more information regarding this message.
Description String Description of what happened. If REJECTED, this would indicate why we rejected your information.
Version Float Version of the Tenstreet API that is responding.
SourceIpAddress String The IP address the request came from.
CompanyPostedToId Integer Tenstreet Company ID that the data was posted to.
ApplicationId Integer Unique identifier associated with the application.
DateTime DateTime Date and Time the response was sent
Mode String DEV or PROD. The mode of the system the response was sent from.
DriverName String Name of the driver who’s information was accepted.
Example

For an example XML file, please click here

Considerations

When posting to our demo system, we will include a node called DisplayHTML, which includes the HTML and CSS of the posted app as you will see it in the dashboard. Please review this HTML to ensure the data is appearing as you want it to. You will not receive this node when posting to the production environment.


Sending Documents to Tenstreet (document_listener service)

Along with sending subject information, the Tenstreet API can also accept documents programmatically. This guide will instruct you on how to set up an XML poster to send data that the system can accept. This guide can also be used in conjunction with “Sending Application Data to Tenstreet” under the “Payload” node.

Please review the following table for a listing of all the nodes that can be passed in this request, if they are required or not, and a description of what type of data can be passed in.

TenstreetXML
Node Data Type Optional Description
Mode String Required Valid data “TEST” or “PROD”. Informational for sender. Not used on Tenstreet side.
Company String Recommended Informational for send and receive side. Example “My Company Name, LLC”.
CompanyId Integer Required Tenstreet will supply you with this number during integration.
SSN String or Integer Required Valid examples:
111-22-3333
111-222-333
111223333
DriverId String or Integer Optional Informational for send and receive side.
QuoteBack String or Integer Optional Informational for send and receive side.
TenstreetXML\Payload\Action\File (Repeatable)
Node Data Type Optional Description
FileId String or Integer Optional Informational for send and receive side.
FileCode String Optional, but strongly recommended

Document “Type” in dashboard. Examples: MVR, PSP, Certificate of Compliance, Driver’s Certificate of Violation.

Tenstreet can provide you with a list of avlid values. In the event you choose not to send a valid value, we will attempt to apply one

FileStorageType String Optional, but strongly recommended Informational for send and receive side.
DateCreated DateTime Optional Informational for send and receive side.
Format must be yyyy-mm-dd
Example: 2014-02-11
FileCategoryName String Optional

Informational for send and receive side.

Examples: General, Background

Filename String Required

The full name of the file you are sending.

Example: USIS_SSN_Check_Sample_Report.pdf

FileSize String Optional Informational for send and receive side. Should be the size of the file in bytes.
FileType String Optional

Informational, we will attempt to determine the real mime-type of a file, but it is helpful if you tell us what you are sending.

Example: If sending a pdf, the mime-type will be application/pdf

FileData Base64 Encoded String Required The contents of the file being sent.
FileExpiration DateTime Optional

The date that the file is no longer valid. Format must be yyyy-mm-dd

Example: 2014-02-11

Example

For an example XML file, please click here

Considerations

We identify the company in our system using the CompanyId field. Each company in our system has a unique ID (732, 10281, etc.). The sender would need to store these values for each company when they send them over.

You can fill in however few or many of the fields as you want, so long as the required fields are met.

POST Response

You will always receive a POST response from Tenstreet, regardless if the attempted post was accepted or rejected, or if nothing occurred during the post. Please review the following table for a description of the XML and nodes that will be sent back.

You are responsible for monitoring all rejections (Status of REJECTED) we send back to you and determining the issue.

TenstreetDocumentDataResponse
Node Data Type Description
Statuses String Node that contains information for each document posted.
Description String Description of what happened.
Version Float Version of the Tenstreet API that is responding.
DateTime DateTime Date and Time that the request was processed
Mode String TEST or PROD. Environment that the request was accepted to.
SSN String SSN of the subject that the document was posted to.
DriverID String Driver ID that the document was posted to.
QuoteBack String or Int Informational for send and receive side.
ReceiveId Int Reference ID. Used when there is an issue to report to Tenstreet for finding the post in our records.
TenstreetDocumentDataResponse\Statuses\Status (Repeatable)
Node Data Type Description
Filename String Name of the file that was posted in
Description String Description of what happened during the posting.
Response String ACCPETED or REJECTED. See description for details

Of these fields, the two that will always be sent are Status and Description. The rest may return blank or not be present:

  1. Status – ACCEPTED or REJECTED
  2. Description – This can say anything, and is visible in the user interface if the status is Rejected (so that a user can take action). Some of our customers have listeners that require certain fields to be set and have validation routines that run, echoing responses in the description upon failure. We show these to the user to remind them to populate certain fields.
Example

For an example XML file, please click here


Sending Data Updates from client to Tenstreet (subject_update service)

Tenstreet has the ability for customers to POST XML to us and update specific pieces of information on a subject/applicant already in our system. If the subject is not already in our system, we reject the POST update. The information that may be updated in Tenstreet today includes:

  • Subject Status (New, Hired, etc.)
  • Subject Worklist
  • Subject Tagging (setting a new tag, updating an existing tag, unsetting an existing tag)

At a high level, the Update process works by first attempting to match provided information to a subject (that is, finding the subject you want to update in our system), validating that we have what we need to do the update, then actually performing the update. After processing your POST, Tenstreet responds with ACCEPTED or REJECTED in XML (see section titled POST Response below for an example of what this XML looks like) and a description of what occurred.

Subject Match Process

Here’s how the subject match process works. We preferentially look for matches on the following information (in this order):

  1. DriverId: DriverId is Tenstreet’s unique subject identifier. If you provide a valid DriverId for your company, that is the subject we update. If the DriverId you provide is not in your company, we will reject your POST, even if the other data might have matched to a driver. So don’t provide a DriverId unless you know it’s valid.
  2. Social Security Number (SSN): If SSN is provided, we search on SSN. Note that all of the following matches (3 to 5 below) only take place if the SSN in the matched record is blank (else we’d have matched on it in this rule). For example, if the SSN is different, it doesn’t matter if we match on email, we assume it’s a different person.
  3. Email Address and Last Name: If the email address and last name match, we update the record.
  4. Primary Phone and Last Name
  5. Secondary Phone and Last Name

If we do not have a match at this point, we reject the POST.

Validation

For several of the fields, we make sure that the data are valid. For example, if Status or Worklist are updated, we ensure the values provided are valid for your company. We also make sure that we have all of the fields we need for all updates. That is, we make an attempt to do all validation ahead of time so that you don’t end up in a situation where one field is updated from the XML POST but another field fails. Said another way, either all updates should work or no updates will be processed.

Updating

We compare the value of the field you provide to the value of the field already in the table. Even if the values are the same (meaning, nothing was really updated since the values were already set to the data you provide), as long as validation succeeds, we will return an ACCEPTED response.

Application Data Updates

The following is an example of the various parts of data we allow a user to update. For application data, it must be inside the ApplicationData node:

<ApplicationData>
	<Status>New</Status>
	<Worklist>Queue 1</Worklist>
	<Address1>PO Box 149</Address1>
	<Address2>Appt 5b</Address2>
	<City>Tulsa</City>
	<State>OK</State>
	<Zip>74053</Zip>
	<PrimaryPhone>9181234562</PrimaryPhone>
	<SecondaryPhone>9181234569</SecondaryPhone>
	<InternetEmailAddress>[email protected]</InternetEmailAddress>
	<WorklistHidden>yes</WorklistHidden>
</ApplicationData>
Tagging Updates

Tags are customer-specific data elements/fields that we store on a subject. Tagging is more complex than updating the Status or Worklist. This is because Tenstreet customer tags are customized for each customer. We not only have to match the data to a subject, we also have to match the tagging information you provide to a customer-specific tag. In the XML, the tagging section is referred to as CustomDataElements:

<UpdatedData>
	<CustomDataElements> 
		<CustomDataElement>
			<CustomDataPrompt>Termination Date</CustomDataPrompt>
			<CustomDataValue>2012-01-01</CustomDataValue>
			<CustomDataId>TerminationDate</CustomDataId>
		</CustomDataElement>
		<CustomDataElement>
			<CustomDataPrompt>Location</CustomDataPrompt>
			<CustomDataValue>Tulsa</CustomDataValue>
			<CustomDataId>Location</CustomDataId> 
			<CustomDataCustomerCode>Ttown</CustomDataCustomerCode>
			<CustomDataTableId>3474</CustomDataTableId>
		</CustomDataElement>
	</CustomDataElements>
</UpdatedData>
Example of tagging update XML

We have three different ways to determine which tag you’re attempting to update. We do three different searches.

  1. CustomDataTableId – The most specific way to specify the tag. This is an integer ID that corresponds to a single tag (what we call the Tag ID).
  2. CustomDataId – This is a cross-reference field that we use to look up the Tag ID. Generally, it will be a programming-friendly version of how the field appears in the system. For example, a date tag called “Hire Date” might have a CustomDataId set to hire_date or HireDate. The customer can choose the CustomDataIds for each field and we’ll store them for later lookup (we can set these to whatever you want).
  3. CustomDataPrompt – This is exactly what the user sees in the user interface when they’re looking at a tag. If the tag is “Hire Date” then we would expect the value to be “Hire Date”.

Once we find a matching tag, we stop searching and move to updating. This means that you could conceivably provide a CustomDataTableId that is in conflict with CustomDataId or CustomDataPrompt. We update on the first matching tag. Also, we must find a match on all tag elements provided (CustomDataElement XML elements) in order to update any data provided to us. This is part of validation and prevents us from updating some elements and not others. If we’re unable to find a tag, we reject the entire POST and explain what went wrong.

Once we know which Tag ID we’re working with, we look at the provided data to determine whether we’re updating or unsetting the tag’s value. Most of the time, you will provide the tag value directly in the CustomDataValue field. If the tag is a list in Tenstreet, you have the option of providing a cross- referenced value instead of the value as it appears in Tenstreet. The ability to update based on a cross- referenced value is unique to tags with dropdowns/lists and is optional.

In the example above, the Location tag provided a cross-referenced value (CustomDataCustomerCode) of “Ttown.” If you have previously worked with us to set up the cross-referenced list values, we will insert a value of “Tulsa” into the tag value, even if you don’t provide a CustomDataValue to us (our example above has both, but including both is optional). This is especially useful if you can only provide codes in your data, but need to have a human-readable value set in Tenstreet. Note that if you do not provide a CustomDataValue to us and we’re unable to find a cross- referenced value, we will reject the POST. We will not set the value to the CustomDataCustomerCode. Further, if you were to provide both and the CustomDataCustomerCode derives to a different value than the provided CustomDataValue, the derived value wins and overwrites the CustomDataValue provided. Therefore, only use CustomDataCustomerCodes when you know there will be a match. Otherwise, just provide CustomDataValue.

If the tag is a date field in Tenstreet, we will validate the CustomDataValue. Dates must be in either MM/DD/YYYY or YYYY-MM-DD format. If you provide a value for a date tag that is not a valid date (and not blank, which would happen if you’re unsetting the tag), we will reject the entire POST.

We identify the company in our system using the CompanyId field. Each company in our system has a unique ID (732, 10281, etc.). The sender would need to store these values for each company when they send them over.

You can fill in however few or many of the fields as you want, so long as the required fields are met.

Example

For an example of xml that can be sent, please click here

POST Response

You will always receive a POST response from Tenstreet, regardless if the attempted post was accepted or rejected, or if nothing occurred during the post. Please review the following table for a description of the XML and nodes that will be sent back.

You are responsible for monitoring all rejections (Status of REJECTED) we send back to you and determining the issue.

TenstreetResponse
Node Data Type Description
Status String ACCEPTED or REJECTED. The description node will contain more information regarding this message.
Description String Description of what happened.
Version Float Version of the Tenstreet API that is responding.
SourceIpAddress String The IP address the original request came from.
CompanyPostedToId Integer Tenstreet company id that the data was posted to.
CompanyPostedToName String Name in Tenstreet of company that data was posted to.
DateTime DateTime Date and Time the response was sent
Mode String DEV or PROD. The mode of the system the response was sent from.
DriverName String Name of the driver who’s information was accepted.

Of these fields, the two that are absolutely required are Status and Description. The rest are optional.

  1. Status – ACCEPTED or REJECTED
  2. Description – This can say anything, and is visible in the user interface if the status is Rejected (so that a user can take action). Some of our customers have listeners that require certain fields to be set and have validation routines that run, echoing responses in the description upon failure. We show these to the user to remind them to populate certain fields.
Example

For an example of the xml response, please click here


Sending Xchange data to Tenstreet (xchange_stored_record service)

TenstreetData
Node Data Type Optional Description
Mode String Required TEST or PROD. Informational only, confirms the system that the data came from.
CompanyID Integer Required

Provided by Tenstreet. Your internal Company ID, used to help in matching up your request to the correct company.

Example: 15

ProviderId Integer Required

Provided by Tenstreet. Internal ID used in the Xchange system.

Example: 15

DriverID Integer Optional An identifier in your system for a subject, such as a unique ID. Will be populated in the Tenstreet POST Response, which can then be used in your system for validation of the request.
SendSubjectToXpress String Optional y or n. Also send subject information to Xpress (for enterprise clients)
PersonalData

This section contains demographic info on the candidate

TenstreetData\PersonalData
Node Data Type Optional Description
GovernmentId String Optional Subject’s Government ID. Has attributes of the following:
countryCode
issuingAuthority
documentType
Example: <GovernmentID countryCode=”US” issuingAuthority=”SSA” documentType=”SSN”>111223333</GovernmentID>
DateOfBirth String Optional

Subject’s Date of Birth.

Example: 1969-01-01

TenstreetData\PersonalData\PersonName
Node Data Type Optional Description
Prefix String Optional Subject’s Prefix (Mr., Mrs., etc)
GivenName String Required Subject’s given, or first, name
MiddleName String Optional Subject’s middle name or initial(s)
FamilyName String Required Subject’s family, or last, name
Affix String Optional Subject’s Affix (MD, II, III, Jr, etc)
TenstreetData\PersonalData\PostalAddress
Node Data Type Optional Description
CountryCode String Optional Two letter code for subject’s country of residence. Use standard country codes from USPS. United States is US, Canada is CA.
Municipality String Optional Subject’s municipality of residence. Also called City or Town
Region String Optional Subject’s region of residence. Also called State or Province
PostalCode String or Integer Optional Subject’s postal code. Also called Zip Code or Post Code
Address1 String Optional Subject’s primary address. Usually a number followed by a street name. e.g., 123 Test Road
Address2 String Optional Subject’s secondary address. Usually an apartment number or division assignment number
TenstreetData\PersonalData\ContactData(Optional Node)

This node has an optional attribute of PreferredMethod, which can be set to the node name of any of the below

Node Data Type Optional Description
InternetEmailAddress String Optional Subject’s email address.
PrimaryPhone String Optional Subject’s Primary Phone Number.
SecondaryPhone String Optional Subject’s Secondary Phone Number, such as mobile phone.
ProviderData

This section contains information about the period of service for the subject.

TenstreetData\ProviderData\PeriodOfService
Node Data Type Optional Description
StartDate DateTime Optional Start of Subject’s employment period.
EndDate DateTime Optional End of Subject’s employment period.
PositionHeld String Optional Subject’s title
ReasonForLeaving String Optional Describes why the subject left, if not terminal
DriverClass String Optional One of the following: <blank>, Company, Lease/Purchase, Owner/Operator, Driver for Owner/Operator
DriverType String Optional One of the following: <blank>, Solo, Student, Team
EligibleForRehire String Optional One of the following: <blank>, Yes, No, Review, Other
Terminated String Optional Y or N. Was the subject terminated
TerminatedReason String Optional Explanation of why the subject was terminated
PositionSubjectToFmcsr String Optional Y or n. Was the subject’s position subject to the FMCSR
PositionDotSafetySensitive String Optional Y or n. Was the subject’s position a DOT safety sensitive position?
FullTimePartTime String Optional Describe the subject’s working hours
HoursPerWeek String Optional How many hours the subject drove per week
AreasDriven String Optional Where subject would drive for this position
NumberOfStatesDriven String Optional Number of states subject would drive through for this position
MilesPerWeek String Optional Number of miles subject would drive per week
TruckType String Optional Type of truck driven. Please see examples for a list of acceptable values.
TrailerType String Optional Type of trailer pulled. Please see examples for a list of acceptable values.
TrailerLength String Optional Length of trailer driven
LoadsHauled String Optional Description of loads hauled
TenstreetData\ProviderData\PeriodOfService\DrugAlcoholDetail(Optional Node)
Node Data Type Optional Description
AlcoholTestHigherThan04 String Optional Y or N. Did the subject test higher than a .04 BAC?
VerifiedPositiveDrugTests String Optional Y or N. Did the subject test positive on drug test?
TestRefusals String Optional Y or N. Did the subject refuse a drug test?
OtherDrugAlcoholTestingRegulations String Optional Y or N
PreviousEmployerReportViolation String Optional Y or N
IfYesReturnToDuty String Optional Y or N
TenstreetData\ProviderData\PeriodOfService\Accidents (Optional Node)

If supplying accidents, must have an accident node with an attribute of have_accident=”y”

TenstreetData\ProviderData\PeriodOfService\Accidents\Accident (Optional Node, Repeatable)
Node Data Type Optional Description
AccidentDate DateTime Required Date of the Accident
DotRecordable String Optional Y or N. Was the accident reportable to the DOT?
AccidentPreventable String Optional Y or N. Was the accident preventable?
AccidentCity String Optional City the accident occurred in
AccidentState String Optional State the accident occurred in
NumberOfInjuries String Optional Number of injuries resulting from the accident
NumberOfFatalities String Optional Number of fatalities resulting from the accident
Hazmat String Optional Y or N. Did the accident involve hazardous material
AccidentVehicleType String Optional Type of vehicle the subject was driving. Please see the appendix for a list of truck types
AccidentDescription String Optional Description of the accident
Example

For an example XML file, please click here.

Considerations

Please note that you must send all accident data for a subject that you would like to have recorded each time you send a subject. If you send 4 accidents in the initial post of a subject, then follow up with two accidents, only two will be shown in Xchange.

We identify the company in our system using the CompanyId field. Each company in our system has a unique ID (732, 10281, etc.). The sender would need to store these values for each company when they send them over.

You can fill in however few or many of the fields as you want, so long as the required fields are met.

POST Response

You will always receive a POST response from Tenstreet, regardless if the attempted post was accepted or rejected, or if nothing occurred during the post. Please review the following table for a description of the XML and nodes that will be sent back.

TenstreetResponse
Node Data Type Description
Status String ACCEPTED or REJECTED. The description node will contain more information regarding this message.
Description String Description of what happened.
Version Float Version of the Tenstreet API that is responding.
SourceIpAddress String IP Address the original POST request came from.
CompanyPostedToId Integer Internal ID that the information was posted to.
CompanyPostedToName String Company name that the information was posted to.
DateTime DateTime Date and time the response was sent, in CST
Mode String Dev or Prod, based on the system that is responding.
DriverName String Name of the subject that information was posted about.

Of these fields, the two that are absolutely required are Status and Description. The rest are optional.

  1. Status – ACCEPTED or REJECTED
  2. Description – This can say anything, and is visible in the user interface if the status is Rejected (so that a user can take action). Some of our customers have listeners that require certain fields to be set and have validation routines that run, echoing responses in the description upon failure. We show these to the user to remind them to populate certain fields.
Example

For an example XML file, please click here.


Sending Job Requisition Data from client to Tenstreet (job_requisitions service)

POST Request

Please review the following table for a listing of all the nodes that can be passed in this request, if they are required or not, and a description of what type of data can be passed in.

JobRequisition

This section is contains information about the job

TenstreetData\JobRequsition
Node Data Type Optional Description
CompanyID Integer Required

Provided by Tenstreet. Your internal Company ID, used to route your info to the correct Tenstreet customer

Example: 15

JobCode String Required This will be the Job Code of the new Job Requisition being created.
JobTitle String Required This will be the Job Title of the new Job Requisition being created.
City String Required The city the new Job Requisition will be in. This must match a city they have access to in the City dropdown on the Manage Job Requisitions page.
State String Required The state the new Job Requisition will be in. Should be a US state or Canadian province.
Country String Required The country the new Job Requisition will be in.
Department String Optional The department for the new Job Requisition. This will show in the Division/Department text field.
Division String Optional The division for the new Job Requisition. This will show after the Department in the Division/Department text field.
Worklist String Optional The worklist for the new Job Requisition. This must exactly match one of the company’s Worklist values, or it will be ignored.
Category String Optional The category for the new Job Requisition. This must exactly match one of the categories they have in the Category dropdown on the Manage Job Requisition screen.
AppCompanyId String Optional If sending to an alias company, the company id of the alias should go here.
StartDate Date Required The date the new Job Requisition should start. To ensure it works correctly, please send dates in YYYY-MM-DD format.
EndDate Date Required The date the new Job Requisition should end. To ensure it works correctly, please send dates in YYYY-MM-DD format.
JobDescription String Required The Job Description of the new Job Requisition.
JobRequirements String Required The Job Requirements for the new Job Requisition.
Example

For an example XML file, please click here

POST Response

You will always receive a POST response from Tenstreet, regardless if the attempted post was accepted or rejected, or if nothing occurred during the post. Please review the following table for a description of the XML and nodes that will be sent back.

TenstreetResponse
Example
Node Data Type Description
Status String ACCEPTED or REJECTED. The description node will contain more information regarding this message.
Description String Description of what happened.
Version Float Version of the Tenstreet API that is responding.
SourceIpAddress String IP Address the original POST request came from.
CompanyPostedToId Integer Internal ID that the information was posted to.
DateTime DateTime Date and time the response was sent, in CST.
Mode String Dev or Prod, based on the system that is responding.
JobRequisitionId Integer The ID in Tenstreet of the new Job Requsition.
Example

For an example XML file, please click here


Receiving Application Data from Tenstreet

We POST the XML as a UTF-8 string with a content-type text/xml. I’ve attached some example XML strings
we’d POST over. Your listener must be able to accept secure connections (SSL). We only use SSL to send
data/documents to ensure the privacy of information contained within our systems while they are in
transit to you. When the listener has been set up, please notify Tenstreet so that final completion steps
can be performed.

Most of the fields in the export are straightforward, but if you have any questions, please let us know. It’s
unlikely that all of these fields will appear in your particular application (the XML is a superset of all
possible fields). Custom fields appear in the CustomQuestions element (these are questions specific to the
customer on their application) and CustomDataElements element (these are equivalent to what we call
Tags, which are custom data fields in our dashboard app, which is where you may see many of the fields
specific to your company). We do add additional elements from time to time as the scope of our
application and processes expand, but we won’t remove or change any existing elements (to maintain
backwards compatibility).

Post Request

There is no POST request for this service. The process will be triggered by an internal Tenstreet process, which can be set up via your Tenstreet account manager.

Post Response

Please review the following list for information on the nodes that can be returned from the Tenstreet system. For examples of what the XML may look like, please see the following files:

Post Body
  • PersonalData: This section is contains demographic info on the candidate.
  • ApplicationData: This is data from your application. Not all of these fields will be filled in every time, and depending on your application setup, some sections may not appear at all.
    • License: If endorsements are present, they’ll be listed here (Tanker, X Endorsement, HazMat, DoublesTriples, Other). If your app asks about restrictions, these will be answered as yes/no.
    • Accident: accident_nature will be things like Backing, Side-swiped, I was Rear- ended, hit parked vehicle/stationary, etc.
    • UnemploymentPeriods: Describes unemployment along with start and end dates.
    • Employers: Describes all past employers provided.
    • Schools: Describes schools attended along with start and end data as well as location information.
    • TruckingSchool: Courses can be Border Crossing, FMCSR, Log Books and Hazardous Materials.
    • Military: Describes Military information such as; startdate, enddate, branch, discharge type, discharge rank, and discharge description
    • MotorVechicleReports: yes/no to the question. If yes, the date of the incident and a description are required.
      • Suspension: Has any license, permit or privilege ever been denied, suspended or revoked for any reason?
      • DuringSuspension: Have you ever been convicted of driving during license suspension or revocation, or driving without a valid license or an expired license, or are any charges pending?
      • ConvictedAlcoholSubstance: Have you ever been convicted for any alcohol or controlled substance related offense while operating a motor vehicle, or are any charges pending?
      • ConvictedDrugs: Have you ever been convicted for possession, sale or transfer of a drug, marijuana, amphetamines, or derivatives thereof, or are any charges ending?
      • ConvictedReckless: Have you ever been convicted of reckless driving, careless driving or careless operation of a motor vehicle, or are any charges pending?
      • PositiveTest: Have you ever tested positive, or refused to test, on any preemployment drug or alcohol test administered by an employer to which you applied for, but did not obtain, safety-sensitive transportation work covered by DOT agency drug and alcohol testing rules during the past three years?
    • CriminalRecord: just like MVR, yes/no to question. If yes, provide date of incident and a description.
      • ConvictedCrime: Have you ever been convicted of a crime?
      • DeferredProsecutions: Do you have any Deferred Prosecutions?
      • ChargesPending: Or any criminal charges pending?
      • Felony: Have you ever pled “guilty” to, been convicted of, or pled “no contest” to a felony?
      • CanadianMinistersPermit: If you have any felony convictions, do you currently hold a ministers permit to enter or exit Canada?
      • Misdemeanors: The question may vary if you choose to edit it, but the default is: Have you, within the last five years, pled “guilty” to, been convicted of, had prosecution deferred in connection with, or pled “no contest” to a misdemeanor?
    • Violations: Describes violations incurred by driver.
    • CustomQuestions and CustomDataElements: Describes information distinct to your company.
  • ProviderVerifiedData: This is data from Xchange. Most interfaces ignore this data, since any changes people find while verifying employers and such are updated in ApplicationData. Still, it’s here should you need it and if you’re backing up data, you’d probably want to store the XML.
  • FormsData: If you decide to use any custom forms from the FormsEngine, their data would be here. export_sample2 has a couple of representative examples of how this data appears, but since the forms are built entirely for you, the fields will be completely different.
  • DriverChangeLog: Changes in status, worklist, recruiter (Primary User), processor (Secondary User), etc. are logged here.

As stated above, CustomDataElements are Tags in the dashboard. If you choose to export them, they will appear in your XML as the following:

<CustomDataElement>
	<CustomDataPrompt>Flatbed Skills</CustomDataPrompt>
	<CustomDataValue>Yes</CustomDataValue>
	<CustomDataId>flatbed_skills</CustomDataId>
	<CustomDataCustomerCode>y</CustomDataCustomerCode>
</CustomDataElement>

CustomDataPrompt: Exactly as the Tag appears to the user in our UI CustomDataValue: the value of the Tag CustomDataId: if you would like to cross reference the Tag name to something specific in your system, we can put it here (so a prompt of Hire Date might be HireDate or hire_date here) CustomDataCustomerCode: If the Tag is a dropdown in Tenstreet, we can cross reference the dropdown value to a value meaningful in your system (“Yes” might become “y” or “1”, for example)

For custom questions on your application, they appear as follows, in a manner similar to CustomDataElements:

<CustomQuestions>
	<CustomDataElements>
		<CustomDataElement>
			<CustomDataPrompt>Driver Number</CustomDataPrompt>
			<CustomDataValue>1234567</CustomDataValue>
			<CustomDataId>LegacyEmployeeNumber</CustomDataId>
		</CustomDataElement>
		<CustomDataElement>
			<CustomDataPrompt>Orientation Location</CustomDataPrompt>
			<CustomDataValue>LA, Broussard</CustomDataValue>
			<CustomDataId>OrientationLocation</CustomDataId>
		</CustomDataElement>
		<CustomDataElement>
			<CustomDataPrompt>Hire Date</CustomDataPrompt>
			<CustomDataValue>04/01/2011</CustomDataValue>
			<CustomDataId>HireDate</CustomDataId>
		</CustomDataElement>
		<CustomDataElement>
			<CustomDataPrompt>Termination Date</CustomDataPrompt>
			<CustomDataValue>04/15/2011</CustomDataValue>
			<CustomDataId>TerminationDate</CustomDataId>
		</CustomDataElement>
	</CustomDataElements>
</CustomQuestions>
Examples

Sample XML Request 1 – Please click here
Sample XML Request 2 – Please click here
Sample XML Request 3 – Please click here

Client Response

In order for our poster to verify that the transfer process has worked properly, you must respond that the information has been either accepted or rejected from your system before your listener script finishes. This will help us to better troubleshoot a bad posting, should one occur. The nodes for posting back to let Tenstreet know the status of the receive are as follows.

TenstreetResponse
Node Data Type Description
Status String ACCEPTED or REJECTED. The description node will contain more information regarding this message.
Description String Description of what happened.
Example

For an example XML file, please click here


Receiving Documents from Tenstreet

The Tenstreet API makes it possible to send documents from our dashboard to your system via an XML POST. A process is executed in the Tenstreet Dashboard, which will then post to an address that you have supplied to Tenstreet. We POST the XML as a UTF-8 string with a content-type text/xml. Your listener must be able to accept secure connections (SSL). We only use SSL to send data/documents to ensure the privacy of information contained within our systems while they are in transit to you. When the listener has been set up, please notify Tenstreet so that final completion steps can be performed.

Most of the fields in the export are straightforward, but if you have any questions, please let us know. We do add additional elements from time to time as the scope of our application and processes.

Post Request

There is no POST request for this service. The process will be triggered by an internal Tenstreet process, which can be set up via your Tenstreet account manager.

Post Response

The XML that is sent will consist of either your requested information, including the file being sent, or a rejection notice and a description of why the request was rejected. Please see the following table for a description of the nodes.

TenstreetXML
Node Data Type Description
Version String Version of the Tenstreet API. Informational Only
DateTime DateTime

Date and Time when the request was completed. Format will be YYYY-DD-MM HH:MM:SS (24 hour time format)

Example: 2014-11-06 15:00:00

Mode String DEV or PROD. Informational only, confirms the system that the data came from
Company String

Name of the Company the data came from. Informational Only.

Example “My Company Name, LLC”

CompanyId Integer

Tenstreet Company ID the data came from

Example: 15

SSN String

SSN of the subject that the documents are attached to.

Example: 111-22-3333

TenstreetXML\Payload\Action\File
Node Data Type Description
FileId String or Integer Informational for send and receive side
FileCode String Document “Type” in dashboard. Examples: MVR, PSP, Certificate of Compliance, Driver’s Certificate of Violation. Tenstreet can provide you with a list of avlid values. In the event you choose not to send a valid value, we will attempt to apply one
FileStorageType String Informational for send and receive side
DateCreated DateTime

Informational for send and receive side. Format must be yyyy-mm-dd

Example: 2014-02-11

FileCategoryName String

Informational for send and receive side.

Examples: General, Background

Filename String

The full name of the file you are sending.

Example: USIS_SSN_Check_Sample_Report.pdf

FileSize Integer Informational for send and receive side. Should be the size of the file in bytes
FileType String The mime-type of file as it exists in our system.
FileData Base64 Encoded String The contents of the file being sent
FileExpiration DateTime

The date that the file is no longer valid. Format will be yyyy-mm-dd

Example: 2014-02-11

Example

For an example XML file, please click here

Client Response

In order for our poster to verify that the transfer process has worked properly, you must respond that the information has been either accepted or rejected from your system before your listener script finishes. This will help us to better troubleshoot a bad posting, should one occur. The nodes for posting back to let Tenstreet know the status of the receive are as follows.

TenstreetResponse
Node Data Type Optional Description
Status String Required ACCEPTED or REJECTED. This field will let Tenstreet know if the data we sent was brought in to your system or not based on your processing rules and not a technical issue (timeout, connectivity, etc). This helps Tenstreet route any issue to the correct department.
Description String Required This can say anything, and is visible in the user interface if the status is Rejected (so that a user can take action). Some of our customers have listeners that require certain fields to be set and have validation routines that run, echoing responses in the description upon failure. We show these to the user to remind them to populate certain fields.
Example

For an example XML file, please click here


Transmitting Data

Standard HTTPS POST

We’ve made an attempt to make the POST/response process as straightforward as possible. There are two types of data transmitting we accept. These are 1) standard HTTP POST,and 2) SOAP (Web Service) call.

Dev URL: https://devapi.tenstreet.com/
Production URL: https://api.tenstreet.com/

We will provide the customer’s CompanyId to you, along with your ClientId and Passwordcredentials. POST the data as an XML string to us with text/xml headers (not urlencoded or with a POST variable). In procedural PHP, it would look something like this:

$post_address = 'https://api.tenstreet.com/';
$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $post_address);
curl_setopt($ch, CURLOPT_VERBOSE,1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1); // return into a variable
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: text/xml; charset=utf-8'));
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER,FALSE);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt ($ch, CURLOPT_POSTFIELDS, $xml_data); // add POST fields

$response_xml = curl_exec($ch);// run the whole process

curl_close($ch); // Always close the connection

echo $response_xml; // $response_xml now contains Tenstreet response
WSDL Consumption
  1. The WSDL for consumption is located here:
    1. Prod: https://api.tenstreet.com/clientPost.wsdl
    2. Dev: https://devapi.tenstreet.com/clientPost.wsdl
  2. We’ll look at an example using Visual Studio. Right-click on ‘References’
  3. Select ‘Add Service Reference’

Appendix

Truck Types
  • Tanker
  • Bus
  • Cabover Tractor
  • Class B Vehicle
  • Conventional Tractor
  • Tractor-Trailer
  • Intermodal
  • Day Cab
  • Day Cab Cabover
  • Day Cab Conventional
  • Dump Truck
  • LC Truck
  • Straight Truck
  • Yard Horse
  • Other
Trailer Types
  • Flatbed
  • Van
  • Container
  • Single Trailer
  • Doubles
  • Triples
  • Liftgate
  • Reefer Trailer
  • Tank Trailer
  • Auto Transporter
  • Other

Ready to use the API?

To request API access/credentials, please email [email protected] Please provide details on who you are (Tenstreet client or third party), and the integration you are looking to accomplish to help us find the solution to best fit your needs.