Taleo Web Services API
Taleo provides programming access to your organization's information using a simple, powerful, and secure application programming interface, the Taleo Web Services API (the API).
To use this document, you should have a basic familiarity with software development, Web services, and the Taleo user interface. Knowledge of the Taleo Connect Client is not required, but would greatly help to understand and visualize the Data Model made available through the API.
The API consists of a set of callable methods, and some API endpoints. The documentation is divided in two parts:
The first part (this document) describes the purposes of the API, its Standard Compliance, and how to use it using common Development Platforms. It further describes basics about Web Services Calls and Standard Taleo Data Types, and covers Error Handling, Security and Limits applying to any Web service of the API.
The second part consists of several documents, referred to as Taleo data dictionaries. Each data dictionary applies to one specific Taleo product and lists a set of callable methods specifically made available for that Product. A data dictionary further describes the Data Model applying to the associated Product, making reference to its Entities, Fields and Relations.
Integrate and Extend Taleo Solutions
Speed and agility are the keys to success in the highly competitive market for top talent. Integration between your talent management solution and your extended network of service providers is critical for streamlined processes and high quality hires.
The Taleo Web Services API allows you to integrate and extend Taleo Solutions using the language and platform of your choice:
Integrate Taleo with your organization: The API enables seamless transfer between Taleo Enterprise, data warehouses, backend human resources information system (HRIS), and financial systems such as Oracle, PeopleSoft, JD Edwards, SAP, Lawson, and others.
Extend Taleo Solutions: The API helps you to extend your talent management processes to external partners, eliminating manual steps in your process, costly process delays and errors, and the headaches of typical integration projects.
Standard Compliance
The API is implemented to comply with the following specifications:
| Standard Name | Website |
|---|---|
| Simple Object Access Protocol (SOAP) 1.1 | http://www.w3.org/TR/2000/NOTE-SOAP-20000508 |
| Web Service Description Language (WSDL) 1.1 | http://www.w3.org/TR/2001/NOTE-wsdl-20010315 |
| Hypertext Transfer Protocol (HTTP) 1.1 | http://www.w3.org/Protocols/rfc2616/rfc2616.html |
| WS-I Basic Profile 1.1 | http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html |
| Web Services Security 1.1 | http://www.oasis-open.org/committees/download.php/16790/wss-v1.1-spec-os-SOAPMessageSecurity.pdf |
There are many different styles of SOAP messages; the two most common today are rpc/encoded and document/literal. The API only supports the document/literal style, as rpc/encoded style is not endorsed by WS-I Basic Profile 1.1 and was removed in the SOAP 1.2 specifications. Technically, using the document/literal style means that a SOAP Body of a Web service request will be a complex message document that must conform to a specific XML schema (included in the WSDL of the Web service).
Development Platforms
The API has already been successfully tested against the following Development Platforms:
AXIS2 v1.3 using XmlBeans and ADB Data Binding
XFire 1.2.6 using XmlBeans Data Binding
If your Platform is not listed above, this means it has not yet been tested. Assuming this one is compliant with our supported Standard Compliance, you should be able to access and use the API successfully.
API Support Policy
Taleo recommends that your new client applications use the most recent version of the WSDL file to fully exploit the benefits of richer features and greater efficiency. When a new version is released, use the following steps in the Quick Start to update your WSDL:
Regenerate the WSDL file (see Step 3: Generate or Obtain the Web Services WSDL Files)
Import it into your environment (see Step 4: Import the WSDL File Into Your Development Platform)
Backward Compatibility
Taleo strives to make backward compatibility easy when using the API. Each Taleo product is associated to a data dictionary, defining its product specific API. Each data dictionary is bound to a specific mapping version. Backward compatibility support differs between minor versions (i.e. 7.5 SP1, 7.5 SP2) and major versions (7.0, 7.5, 10 and later).
We maintain support for each minor version of a product. We also maintain support for the last major version preceding the current version. The API is backward compatible in that an application created to work with a given data dictionary mapping version will work with that same mapping version in future minor versions and the next future major version of the product.
Taleo does not guarantee that an application written against one API version will work with future API versions. Changes in method signatures and data representations are often required as we continue to enhance the API. However, we strive to keep the API consistent from version to version with minimal, if any changes, required to port applications to newer API versions.
For example, an application written using the Taleo Recruiting 7.5 API shipped with the Taleo Enterprise Edition 7.5 release will continue to work with all future minor versions (i.e. Taleo Enterprise Edition 7.5 SP1), and with the next major version of the product (i.e. Taleo Enterprise 10 and later), using that same API. However, the same application may not work with later versions of the product (i.e. Taleo Enterprise 10) without modifications to the application, using the latest available product API (i.e. Taleo Enterprise 10 and later).
API End of Life
Taleo is committed to supporting each API version for a minimum of two (2) major versions from the version of first release. In order to mature and improve the quality and performance of the API, versions that were introduced more than one major version before the current version may cease to be supported.
For example, in the figure above, a major version is released, with a given version 1 of a service layer (Web Service API). A new major version is released, and the service layer also releases a new version. The former version is now supported, but deprecated. Then, a new major version is released, but no new service layer version is released. Support for version 1 of the service layer ends, and now only one version is supported. Then, a new major version is released, with a new service layer version. The version 2 is still supported, but deprecated.
Taleo Web Services Namespaces
Various namespaces are used inside a Taleo Web Service WSDL and SOAP document. These namespaces define specific parts of the document and are also used for versioning purposes. Taleo Web Services can be defined into two categories of services: import and export services.
Taleo 10 and Later Namespaces
| Namespace | Description |
|---|---|
| http://www.taleo.com/ws/integration/toolkit/[version] | The integration toolkit namespace. This namespace is used to define elements related to the integration toolkit framework. The integration toolkit framework is where the Taleo component web service infrastructure resides. It is used in the definition of elements such as the WebServiceFault. |
| http://www.taleo.com/ws/[productCode][nsVersion]/[service] | The service namespace. This namespace is used to define elements related to the web service itself. It is used in the definition of elements such as the operation parameters data types. It is the link between the service and the Taleo data model. Its name is composed of the product code (i.e. tee for Taleo Enterprise, so for SmartOrg, etc.) followed by the namespace version (i.e. 2009/01) and the service name (i.e. for the DepartmentService, it will be department). Example: WebService: DepartmentService Namespace: http://www.taleo.com/ws/tee800/2009/01/department |
| http://www.taleo.com/ws/[productCode][nsVersion]/import | The product import data model. This namespace is used to define elements related to the integration data model used to define all the entities that can be used in import services. It is used in the definition of elements such as the User, the Candidate, the Requisition and all the other Taleo entities. Its name is composed of the product code (i.e.: tee for Taleo Enterprise, so for SmartOrg, etc.) followed by the namespace version (i.e. 2009/01) and the import string. Example: Namespace: http://www.taleo.com/ws/tee800/2009/01/import |
| http://www.taleo.com/ws/[productCode][nsVersion] | The product export data model. This namespace is used to define elements related to the integration data model used to define all the entities that can be used in export services. It is used in the definition of elements such as the User, the Candidate, the Requisition and all the other Taleo entities. Its name is composed of the product code (i.e.: tee for Taleo Enterprise, so for SmartOrg, etc.) followed by the namespace version (i.e. 2009/01). For technical reasons, this namespace is not ended by the export string (as opposed to the import one). Example: Namespace: http://www.taleo.com/ws/tee800/2009/01 |
Version 7.5 Namespaces
| Namespace | Description |
|---|---|
| http://www.taleo.com/ws/integration/toolkit/[version] | The integration toolkit namespace. This namespace is used to define elements related to the integration toolkit framework. This is the Taleo component where the web service infrastructure resides. It is used in the definition of elements such as the WebServiceFault. |
| http://www.taleo.com/ws/[productCode][nsVersion] | The product import and export data model. This namespace is used to define elements related to the integration data model used to define all the entities that can be used in import and export services. It is used in the definition of elements such as the User, the Candidate, the Requisition and all the other Taleo entities. Its name is composed of the product code (i.e.: art for Active Recruiting Technology, so for SmartOrg, etc.) followed by the namespace version (i.e. 2006/12). Example: Namespace: http://www.taleo.com/ws/art750/2006/12 |
Namespace Limitations
The namespace strategy has evolved between Taleo 7.5 and Taleo 10 versions. The 7.5 version is missing some concepts to really make each piece of information independent of each other. This will be described in greater detailed in the Taleo 7.5 Namespaces section.
Using Web Services
For each specific Taleo product, a list of WSDL files is available. Any number of commercial or open source tools can then be used to create clients that access these services. The soapUI project (www.soapui.org) offers a free open source no-frills yet complete user interface to create and test web service calls. Other commercial solutions offer more advanced features: XML Spy (www.altova.com), Stylus Studio (www.stylusstudio.com) and oXygen (www.oxygenxml.com). In order to embed web service calls within an application, the Apache Web Service Axis2 project (ws.apache.org/axis2) offers a WSDL2Java tool that generates the proper source code for a Java based project. Microsoft .NET also offers a web service toolkit for its development framework. The Quick Start section provides a step by step procedure using these toolkits.
Multiple books and articles are available that describe in detail how to interact with the web services, SOAP, and WSDL standards. Some interesting starting points are:
http://www.w3.org/2002/ws (standards and links)
http://java.sun.com/webservices (Sun's Java web services portal)
http://msdn.microsoft.com/webservices (Microsoft's .NET web services portal)
Using SOAPUI with Taleo WSDL
There are constraints that SOAPUI users must be aware of when using Taleo WSDL to generate a test suite and/or a test request.
When creating a new WSDL project and adding a Taleo WSDL, DO NOT "Create default requests for all operations".
When creating a new test request, DO NOT "Create optional elements in schema."
Many Taleo operations use entity type parameters that are composed of base type entities. These base type entities can be specialized, and sometimes must be, to pass the correct data. To correctly support that characteristic, each base type in the WSDL is composed of a list of elements from all its specialized types. For detailed information about how to work with base types, refer to section Operations On Parameters With Base Type Elements.