How to integrate with the Taleo webservice (API) using

If you just want to try it out, download TaleoExport from here

The command line is

TaleoExport1.0 CompanyCode username password CustomFieldOnTaleoThatYouWantToUpdate SearchParameters OutPutDirectory

(Search Parameters are a key,value pair separated by a comma and if you have multiple pairs they are separated by a colon. Search parameters are additive for example if you want someone with the last name smith, who has status of NEW you would use lastName,Smith:status,NEW)

VERY IMPORTANT —PLEASE NOTE that the key is CASE SENSITIVE, but the value is not. Also note that if you give a bogus value(Or typo) you can cause BIG problems. For example if you sent LASTNAME,Smith:status,NEW it will export everyone with the status of NEW because LASTNAME is not a valid key!!! so make sure of your keys!

So here is an example that will get you those people with the last name smith, and the status of hired.

TaleoExport.exe ACOMPANY auser apassword Exported lastName,smith:status:hired c:\myExports

Ok, as I mentioned in this post I have been exploring how to use the Taleo API. Taleo is a great system, and extremely flexible. What I do think they are lacking is transparency in how to use their web service. Actually, I am surprised that they don’t offer sample code (anywhere on the open web, there is some on their customer forum but you can’t see it until you are a customer… little bit of a catch 22 don’t you think) or even better a generic dump to flat file program.

Well, speaking of the generic dump to flat file program. That is exactly what I will show you how to make. Gotta scratch my own itch ya’know

So how would you use this? On the Taleo side of things you need a premium service level to allow you to use the API. Then you need to create a custom field by going to Administration, Customize Taleo Business Edition Recruit, Candidate Fields, scroll down to Candidate Custome Fields, and then Click New Field. If you want to match the default for the program create a Check Box with the Label of Exported and the External Name of Exported. (Don’t set the default to checked)  (This checkbox will be set to true after we have exported the candidate data)

Ok, so download yourself a copy of express 2008.

Create yourself a new console app. So now we need to add two web services. They are listed here

But here they are for your reference

Dispatcher API: DispatcherAPI.wsdl
Web API: WebAPI.wsdl

Ok, so how do you add a web service in Right click your project (top right hand side) and choose add service reference. THEN, choose advanced because that is where they hide adding webservices. Click Add Web Reference on the bottom of that screen (easy to find huh) and then paste in the first web service (for the dispatcher URL). Then press Go.

If everything worked right you should have found the DispatcherAPI which has one method of getURL() this method gives you your URL that you will send all further requests to (and login) so click Add Reference.

Ok, so now we need to add the second webservice which is the actual workhorse. Follow the same procedure using the WebAPI.wsdl

Now, use some imports statements to make those webservices easier to deal with

Imports System.Xml
Imports System.IO

Ok, lets create some variables and instantiate our ‘IWebAPIService’

Dim myWebService As New IWebAPIService
Dim myAPIKey As String
Dim candidateArray As New ArrayList
Dim exportKeyValue As String = "Exported" 'this is a custom field created on Taleo

Dim companyCode As String = "yourcompany"
Dim userName As String = "youruser"
Dim userPassword As String = "yourpassword"

Ok, so as written in the documentation the first thing we need to do is get a url from the dispatcher. So lets instantiate the DispatcherAPIService and call getURL using your company code (assigned by Taleo)

Sub Main()

'get our URL using our companyCode
Dim myDispatcherAPIService As New DispatcherAPIService
Dim myurl As String = myDispatcherAPIService.getURL(companyCode)
 myWebService.Url = myurl

Ok, now we use the returned URL to login and get our APIKey (This APIKey is used for all our next queries)

'Now that we have our URL logon and get our APIKey
myAPIKey = myWebService.login(companyCode, userName, userPassword)

So, now that we are logged on lets do something useful. Let’s search on all of my candidates and bring back the ones that have a status of hired and have not been exported yet.

In order to search we have to create an array of mapItem’s that contain key and value pairs.

'create an array of mapItem's that are key and value pairs

Dim myArray(1) As mapItem
myArray(0) = New mapItem
myArray(0).key = "status"
myArray(0).value = "hired"

myArray(1) = New mapItem
myArray(1).key = exportKeyValue
myArray(1).value = "false"

To get our results back we need to create a SearchResultArr, then use our previously instantiated webservice send our APIkey, and our array of mapItems (key and value pairs)

'create a SearchResultArr to recive the results
'then submit to our webservice
Dim resultsArray As SearchResultArr
resultsArray = myWebService.searchCandidate(myAPIKey, myArray)

The resultsArray will contain a bunch of SearchResultBeans so instantiate a search result to use in our For Each statement. What we need from this search is the Candidate Id’s so we can use them to get the full details of the the candidate. Once we have the id use the getCandidateById method to return the full details and then add them to an arrayList for writing out to XML.

'take that list and get each candidates data using id 'add to arrayList Dim aBean As SearchResultBean For Each aBean In resultsArray.array

Dim myCandidateData As New CandidateBean
myCandidateData = myWebService.getCandidateById(myAPIKey,


Then we will call the WriteOutData function. At a high level this creates an xml doc, and for each candidate it lists through the methods and uses the CallByName function to output any of the values.

Public Sub WriteOutData()

Dim doc As New Xml.XmlDocument
'create nodes
Dim root As Xml.XmlElement = doc.CreateElement("TaleoExport")
Dim aCandidateBean As New CandidateBean
Dim aFlexValue As New FlexFieldBean

Dim pdc As System.ComponentModel.PropertyDescriptorCollection
Dim pdc2 As System.ComponentModel.PropertyDescriptorCollection

For Each aCandidateBean In candidateArray

Dim eCandidate As Xml.XmlElement = doc.CreateElement("Candidate")
Dim valueTxt As XmlText
Dim eValue As Xml.XmlElement

'iterate through every method in CandidateBean Object
'and save the value out to XML

pdc = System.ComponentModel.TypeDescriptor.GetProperties(aCandidateBean.GetType)
For Each pd As System.ComponentModel.PropertyDescriptor In pdc

eValue = doc.CreateElement(pd.Name)

'detect the flexValues
If pd.Name = "flexValues" Then

Dim eFlexValues As Xml.XmlElement = doc.CreateElement("FlexValues")

For Each aFlexValue In aCandidateBean.flexValues

pdc2 = System.ComponentModel.TypeDescriptor.GetProperties(aFlexValue.GetType)
For Each pd2 As System.ComponentModel.PropertyDescriptor In pdc2

eValue = doc.CreateElement(pd2.Name)

valueTxt = doc.CreateTextNode(CallByName(aFlexValue, pd2.Name, CallType.Get))

If Not valueTxt.Value = "" Then
End If





valueTxt = doc.CreateTextNode(CallByName(aCandidateBean, pd.Name, CallType.Get))

' don't write tags if they don't contain data
If Not valueTxt.Value = "" Then
End If

End If




'put them all together
'save it

Catch ex As Exception

End Try

End Sub

Ok, well that source line wraps awful but we only have one more thing to do, we need to update the status on Taleo that our Candidate has been exported.

Once again we will iterate through our candidates in our array, then we will look for the fieldName that matches our exportKeyValue (custom field\checkbox created on Taleo to mark the candidate as exported) and then we will set the boolean value to true. Then after we are done we will update the candidate using the updateCandidate method (you need to push back all of the data or else it will clear fields that don’t get re-filled in again, if that makes sense)

Dim aCandidateBean As New CandidateBean
Dim aFlexValue As New FlexFieldBean
For Each aCandidateBean In candidateArray

For Each aFlexValue In aCandidateBean.flexValues

If aFlexValue.fieldName = exportKeyValue Then

aFlexValue.valueBool = True

End If


myWebService.updateCandidate(myAPIKey, aCandidateBean)


To make this into a more generic Taleo Flat filer we can pull out the companyCode, userName, and userPassword, and the search array as parameters.

Notes: The Tale WebAPI guide has typos with what the datafield name should be. I think this was caused by auto capitalization. Things like Phone should really be phone, Status should be status etc…


I was extremely amused by this post about EDI and SaaS

As the guy who gets to read really long EDI specs I can emphasize with this post. Even more amusing was the fact that I had implemented the 48 page Target 850 purchase… and am in the middle of reading and implementing the Taleo API docs. It was like this blog post was written for me!