Receiving Application Data From Tenstreet API Guide (rev 10/2017)

Transcription

1 Receiving Applicatin Data Frm Tenstreet API Guide (rev 10/2017) Cntents Intrductin... 1 Agreements and Acknwledgements... 2 Understanding the API... 2 Debugging... 2 Lgging... 2 Data Accuracy... 2 Supprt Requests... 2 Overview... 4 POST Request... 4 POST Respnse... 4 Examples... 6 Client Respnse... 7 Example... 7

2 Intrductin We POST the XML as a UTF-8 string with a cntent-type text/xml. I've attached sme example XML strings we'd POST ver. Yur listener must be able t accept secure cnnectins (SSL). We nly use SSL t send data/dcuments t ensure the privacy f infrmatin cntained within ur systems while they are in transit t yu. When the listener has been set up, please ntify Tenstreet s that final cmpletin steps can be perfrmed. Mst f the fields in the exprt are straightfrward, but if yu have any questins, please let us knw. It's unlikely that all f these fields will appear in yur particular applicatin (the XML is a superset f all pssible fields). Custm fields appear in the CustmQuestins element (these are questins specific t the custmer n their applicatin) and CustmDataElements element (these are equivalent t what we call Tags, which are custm data fields in ur dashbard app, which is where yu may see many f the fields specific t yur cmpany). We d add additinal elements frm time t time as the scpe f ur applicatin and prcesses expand, but we wn't remve r change any existing elements (t maintain backwards cmpatibility). Receiving Applicatin Data frm Tenstreet 1 P a g e 10/4/2017

3 Agreements and Acknwledgements Understanding the API Yu are respnsible fr understanding the basics f xml and HTTP psting, and understanding the infrmatin cntained within this dcument. Debugging Yu are respnsible fr parsing the Tenstreet respnse fr debugging purpses. Failure t d s will result in data nt being accepted int the system. If the psting type requires yu t send a respnse back t ur system, yu are als respnsible fr sending that respnse, therwise ur system will nt cnsider peratins cmplete. Lgging We expect yu t keep bth pst and respnse lgs f data that has been sent and received. We expect this t be kept fr at least 1 calendar year. Tenstreet keeps the same data fr 1 calendar year. This ensures the ability t audit all transactins frm bth sides. Data Accuracy If yu have access t update multiple accunts (usually in the case f a jb bard), yu als acknwledge that yu will be respnsible fr psting the crrect infrmatin t the crrect accunt. Tenstreet will nly validate that the passed Cmpany ID and Passwrd match, but will nt attempt t validate that the infrmatin being sent belngs t the Cmpany ID prvided. Supprt Requests We want yu t receive and send data t ur system as yur business use requires. We have a dedicated supprt grup that handles requests abut integrating yur data with us at integratins@tenstreet.cm. If yu need t cntact us fr supprt, please nte that we are wrking tward getting yu a respnse in the rder it was received in the supprt queue, and that can take several elapsed wrking days. Sending mre requests will just put yur need further behind in the queue as we will have t handle them all separately. S please send ne really well-frmed request at a time. This service is very ppular, technical, and requires us t free up resurces t answer yur questins. But we will get t them. When sending supprt requests, please include: a) The Tenstreet XML respnse yu are receiving if yu are receiving ne at all b) yur utbund r inbund ips (as relevant) c) The URL yu are psting t, as it is quite ften that clients pst t the develpment URL fr their prductin data and get a respnse that says the cmpany id is invalid, s make sure yu are psting t the right envirnment. d) The XML yu are sending r receiving (as relevant), This speaks vlumes t us, and will ultimately expedite yur request. D nt send us PII data like an SSN. Just replace that with xxx-xx-1234 in the file Receiving Applicatin Data frm Tenstreet 2 P a g e 10/4/2017

4 befre yu send it. Or delete it cmpletely, it is nt usually relevant t a supprt case. e) A phne number, time zne, and time frame in which we can reach yu. Often these issues are less verhead t reslve with a single phne call rather than multiple s. Receiving Applicatin Data frm Tenstreet 3 P a g e 10/4/2017

5 Overview POST Request There is n POST request fr this service. The prcess will be triggered by an internal Tenstreet prcess, which can be set up via yur Tenstreet accunt manager. POST Respnse Please review the fllwing list fr infrmatin n the ndes that can be returned frm the Tenstreet system. Fr examples f what the XML may lk like, please see the fllwing files: Pst Bdy PersnalData: This sectin is cntains demgraphic inf n the candidate. ApplicatinData: This is data frm yur applicatin. Nt all f these fields will be filled in every time, and depending n yur applicatin setup, sme sectins may nt appear at all. License: If endrsements are present, they'll be listed here (Tanker, X Endrsement, HazMat, DublesTriples, Other). If yur app asks abut restrictins, these will be answered as yes/n. Accident: accident_nature will be things like Backing, Side-swiped, I was Rear- ended, hit parked vehicle/statinary, etc. UnemplymentPerids: Describes unemplyment alng with start and end dates. Emplyers: Describes all past emplyers prvided. Schls: Describes schls attended alng with start and end data as well as lcatin infrmatin. TruckingSchl: Curses can be Brder Crssing, FMCSR, Lg Bks and Hazardus Materials. Military: Describes Military infrmatin such as; startdate, enddate, branch, discharge type, discharge rank, and discharge descriptin MtrVechicleReprts: yes/n t the questin. If yes, the date f the incident and a descriptin are required. Suspensin: Has any license, permit r privilege ever been denied, suspended r revked fr any reasn? DuringSuspensin: Have yu ever been cnvicted f driving during license suspensin r revcatin, r driving withut a valid license r an expired license, r are any charges pending? CnvictedAlchlSubstance: Have yu ever been cnvicted fr any alchl r cntrlled substance related ffense while perating a mtr vehicle, r are Receiving Applicatin Data frm Tenstreet 4 P a g e 10/4/2017

6 any charges pending? CnvictedDrugs: Have yu ever been cnvicted fr pssessin, sale r transfer f a drug, marijuana, amphetamines, r derivatives theref, r are any charges ending? CnvictedReckless: Have yu ever been cnvicted f reckless driving, careless driving r careless peratin f a mtr vehicle, r are any charges pending? PsitiveTest: Have yu ever tested psitive, r refused t test, n any preemplyment drug r alchl test administered by an emplyer t which yu applied fr, but did nt btain, safety-sensitive transprtatin wrk cvered by DOT agency drug and alchl testing rules during the past three years? CriminalRecrd: just like MVR, yes/n t questin. If yes, prvide date f incident and a descriptin. CnvictedCrime: Have yu ever been cnvicted f a crime? DeferredPrsecutins: D yu have any Deferred Prsecutins? ChargesPending: Or any criminal charges pending? Felny: Have yu ever pled "guilty" t, been cnvicted f, r pled "n cntest" t a felny? CanadianMinistersPermit: If yu have any felny cnvictins, d yu currently hld a ministers permit t enter r exit Canada? Misdemeanrs: The questin may vary if yu chse t edit it, but the default is: Have yu, within the last five years, pled "guilty" t, been cnvicted f, had prsecutin deferred in cnnectin with, r pled "n cntest" t a misdemeanr? Vilatins: Describes vilatins incurred by driver. CustmQuestins and CustmDataElements: Describes infrmatin distinct t yur cmpany. PrviderVerifiedData: This is data frm Xchange. Mst interfaces ignre this data, since any changes peple find while verifying emplyers and such are updated in ApplicatinData. Still, it's here shuld yu need it and if yu're backing up data, yu'd prbably want t stre the XML. FrmsData: If yu decide t use any custm frms frm the FrmsEngine, their data wuld be here. exprt_sample2 has a cuple f representative examples f hw this data appears, but since the frms are built entirely fr yu, the fields will be cmpletely different. DriverChangeLg: Changes in status, wrklist, recruiter (Primary User), prcessr (Secndary User), etc. are lgged here. As stated abve, CustmDataElements are Tags in the dashbard. If yu chse t exprt them, they will appear in yur XML as the fllwing: Receiving Applicatin Data frm Tenstreet 5 P a g e 10/4/2017

7 <CustmDataElement> <CustmDataPrmpt>Flatbed Skills</CustmDataPrmpt> <CustmDataValue>Yes</CustmDataValue> <CustmDataId>flatbed_skills</CustmDataId> <CustmDataCustmerCde>y</CustmDataCustmerCde> </CustmDataElement> CustmDataPrmpt: Exactly as the Tag appears t the user in ur UI CustmDataValue: the value f the Tag CustmDataId: if yu wuld like t crss reference the Tag name t smething specific in yur system, we can put it here (s a prmpt f Hire Date might be HireDate r hire_date here) CustmDataCustmerCde: If the Tag is a drpdwn in Tenstreet, we can crss reference the drpdwn value t a value meaningful in yur system ("Yes" might becme "y" r "1", fr example) Fr custm questins n yur applicatin, they appear as fllws, in a manner similar t CustmDataElements: <CustmQuestins> <CustmDataElements> <CustmDataElement> <CustmDataPrmpt>Driver Number</CustmDataPrmpt> <CustmDataValue> </CustmDataValue> <CustmDataId>LegacyEmplyeeNumber</CustmDataId> </CustmDataElement> <CustmDataElement> <CustmDataPrmpt>Orientatin Lcatin</CustmDataPrmpt> <CustmDataValue>LA, Brussard</CustmDataValue> <CustmDataId>OrientatinLcatin</CustmDataId> </CustmDataElement> <CustmDataElement> <CustmDataPrmpt>Hire Date</CustmDataPrmpt> <CustmDataValue>04/01/2011</CustmDataValue> <CustmDataId>HireDate</CustmDataId> </CustmDataElement> <CustmDataElement> <CustmDataPrmpt>Terminatin Date</CustmDataPrmpt> <CustmDataValue>04/15/2011</CustmDataValue> <CustmDataId>TerminatinDate</CustmDataId> </CustmDataElement> </CustmDataElements> </CustmQuestins> Examples Sample XML Request 1 - Please click here Sample XML Request 2 - Please click here Sample XML Request 3 - Please click here Receiving Applicatin Data frm Tenstreet 6 P a g e 10/4/2017

8 Client Respnse In rder fr ur pster t verify that the transfer prcess has wrked prperly, yu must respnd that the infrmatin has been either accepted r rejected frm yur system befre yur listener script finishes. This will help us t better trublesht a bad psting, shuld ne ccur. The ndes fr psting back t let Tenstreet knw the status f the receive are as fllws. TenstreetRespnse Nde Data Type Descriptin Status String ACCEPTED r REJECTED. The descriptin nde will cntain mre infrmatin regarding this message Descriptin String Descriptin f what happened Of these fields, the tw that are abslutely required are Status and Descriptin. The rest are ptinal. 1. Status - ACCEPTED r REJECTED 2. Descriptin - This can say anything, and is visible in the user interface if the status is Rejected (s that a user can take actin). Sme f ur custmers have listeners that require certain fields t be set and have validatin rutines that run, eching respnses in the descriptin upn failure. We shw these t the user t remind them t ppulate certain fields. Example Fr an example XML file, please click here Receiving Applicatin Data frm Tenstreet 7 P a g e 10/4/2017