CSO WDSL SOAP API v1. Beta

Om de vacatures op deze website met open data te ontsluiten, is een API ontwikkeld.
Wil je als deelnemer gebruik maken van ons vacature-aanbod via de API? Neem dan contact op via:
Telefoon: +31 6 50768327
E-mailadres: helpdesk@werkenvoornederland.nl

This document describes the CSO SOAP API. It provides a description, use-cases, coding examples and a full reference documentation to every operation, object and property. This documentation is intended for developers and third-parties who need to communicate with the CSO Platform.

Table of Contents

1. 1 The CSO Platform
2. 2 Getting Started
   1. 2.1 Use soapUI to get a good insight
3. 3 Using the Api
   1. 3.1 Web Service: API Service
   2. 3.2 Port JobAPI.cfc
   3. 3.3 Sandbox
   4. 3.4 Security
4. 4 Reference documentation
5. 5 Example documentation
   1. 5.1 getApiKey - Get an ApiKey
   2. 5.2 isValidApi - Determining the validity of your API key
   3. 5.3 getJob - Get a single job
   4. 5.4 getJobs - get an Array of jobs
   5. 5.5 getJobCount - Count the number of jobs for the given filtercriteria
   6. 5.6 getJobEnumerations - Get all available enumerated data for jobs
   7. 5.7 getOrganisations - Get all available organisations available on the CSO Platform
   8. 5.8 getOrganisationsWithFilter - Get organisations based on a given filter
   9. 5.9 getJobCountForEnumeration - Get the number of jobs per enumeration type for the given filter.
   10. 5.10 saveJob - Save a job
   11. 5.11 removeJob - Delete a job
   12. 5.12 RemoteJobFilter - Define a filter for specific selections of jobs
   13. 5.13 RemoteJobFieldSelection - Define a fieldselection to define the level of detail for a job
   14. 5.14 RemoteOrganisationFilter - Define a filter to retrieve categories of organisations
   15. 5.15 RemoteJobEnumerationCount
6. 6 Frequently asked questions
7. 7 Deprecation documentation
8. 8 Future enhancements
9. 9 Support
10. 10 Known problems

1 The CSO Platform

The CSO platform (Carrière Sites Overheid) is a platform for recruitment communication for the Dutch Government. The platform contains several websites. These websites provide a means of communication between the Government and the visitors of the websites. Supply and demand of job openings are presented transparently to visitors ensuring them a better orientation towards working for the Dutch Government.

Approximately 2000 organizations are present at the platform, providing solutions in recruitment and mobility issues. The websites are publications of Expertisecentrum Organisatie en Personeel (EC-O&P).

2 Getting Started with the API

The CSO-API provides third-party access to the infrastructure of the CSO (Carriere Sites Overheid) Platform making it easy to create applications that integrate seamlessly with the platform.

The API provides a means communication between web, mobile, mashups and other applications, intranets or widgets with the CSO-platform. By using the CSO-API organisations have the flexibility to determine what information they will provide their visitors and in what way the publicly available information on the CSO platform is presented elsewhere. By using the API human resource systems can exchange information with the CSO-platform.

The API introduces a standardized specification on which other providers can base products and information flow. As such, the CSO-platform will be an open system, stimulating information distribution and limiting dependencies from supplier to supplier.

The API provides a webservice using Simple Object Access Protocol (SOAP) and Web Service Description Language (WSDL). Every API call requires a valid API key. All API calls are made over the HTTPS protocol for security reasons.

2.1 Use soapUI to get a good insight

A good starting point to get comfortable is soapUI which lets you experiment with the API.

• Download soapUI and when the program is installed create a new project.
• A dialog appears asking for a project name and initial WSDL/WADL.
• Enter the wsdl for CSO: http://api.cso20.net/v1/JobAPI.cfc?wsdl in the box for initial WSDL.
• The wsdl is interpreted and all methods will become available in the project window as SOAP requests with their parameters.
• To retrieve an apiKey for example, unfold the box to the left of the getApiKey method and right-click "Request 1".
• Select "Show request editor" to open the request in an editor.
• Type in your username and password in the appropriate fields and press the green "play" button on the upperleft of the editor.
• The request is made and an apiKey will be available in the response window.

Experimenting with the methods available will give insight in the (required) parameters and the types of information returned in the response. To get a full overview of the wsdl right-click on the "JobAPI.cfcSoapBinding" at the top of the project tree in the navigator window. Choose "Show interface viewer" and select the third tab "WSDL content" which gives a sorted overview of the WSDL.

3 Using the API

Currently the API provides the port JobAPI. See 'Future enhancements' for more information on functionality to come.

3.1 Web Service: API Service

Description:	CSO API.
Target Namespace:	http://v1

3.2 Port JobAPI.cfc

WSDL URL / location:	http://api.cso20.net/v1/JobAPI.cfc?wsdl
Protocol:	SOAP 1.1
Default style:	rpc
Transport protocol:	SOAP over HTTP
Definition:	JobAPI.cfc?wsdl
Last updated:	March 29, 2012
Operations:	getApiKey (Detail) isValidApiKey (Detail) getJob (Detail) getJobs (Detail) getJobCount (Detail) getJobEnumerations (Detail) getOrganisations (Detail) getOrganisationsWithFilter (Detail) getJobCountForEnumeration (Detail) saveJob (Detail) removeJob (Detail)
Encoding:	Every operations response is in UTF-8

The API service can be accessed by making SOAP calls to:

http://api.cso20.net/v1/JobAPI.cfc?wsdl

To access the API apply for access credentials by contacting the CSO help desk:

Telephone	+31 6 50768327
Email address	helpdesk@werkenvoornederland.nl

3.3 Sandbox

Applications developed on the CSO API can be tested using a sandbox environment. This environment is cleaned up on a regular schedule; data is deleted on a daily basis. The environment reflects the live situation of the platform: jobs available on the sandbox are always up to date. Calls to the API are only available on https protocol, see the list below for all sites in the CSO-Platform.

• https://sandbox.tasks.cso20.net
• https://sandbox.api.cso20.net/v1/JobAPI.cfc?wsdl
• https://sandbox.www.werkenvoornederland.nl
• https://sandbox.www.werkenbijdeoverheid.nl
• https://sandbox.mobi.rijkstalentencentrum.nl
• https://sandbox.www.persoonlijk-dossier.nl
• https://sandbox.xml.werkenbijdeoverheid.nl
• https://sandbox.www.ineu.nl
• https://sandbox.www.functiegebouwrijksoverheid.nl
• https://sandbox.www.rijkstalentencentrum.nl
• https://sandbox.m.werkenvoornederland.nl
• https://sandbox.rtc.rijkstalentencentrum.nl

3.4 Security

The CSO-API is secured to ensure that only authorized members have access. Three levels of security apply.

1. User name (user name field) and password (password field)
2. Request authentication using an API key included in all other method calls
3. Secure Sockets Layer (SSL) data transport

5 Example documentation

5.1 getApiKey - Get an ApiKey

Description

API key is required in each API call.

The API key is retrieved using the getApiKey function. A user name and password are required to use this function. Before retrieving your API key you need access credentials to the API. You can apply for API access at the helpdesk by phone (+31 6 50768327) or email (helpdesk@werkenvoornederland.nl).

The API key is retrieved by calling getApiKey with your credentials. To test if a given API key is still valid use the the function isValidApiKey with the given API key. All API calls are logged within the system. The apiKey returned is valid for 20 minutes.

Arguments

Input:	getApiKeyRequest (wsdlsoap:body, use = encoded) required username type string required password type string
Output:	getApiKeyResponse (wsdlsoap:body, use = encoded), getApiKeyReturn type string, A string representing the API key.
Fault:	CFCInvocationException (wsdlsoap:fault, use = encoded) fault type CFCInvocationException fly.cso.api.v1.exception.RemoteInvalidCredentialsException fly.cso.api.v1.exception.RemotePermissionDeniedException

An XML representation of the request:

<v1:getApiKey soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <username xsi:type="xsd:string"></username>
  <password xsi:type="xsd:string"></password>
</v1:getApiKey>

An XML representation of the response:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <ns1:getApiKeyResponse soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:ns1="http://v1">
         <getApiKeyReturn xsi:type="xsd:string"></getApiKeyReturn>
      </ns1:getApiKeyResponse>
   </soapenv:Body>
</soapenv:Envelope>

Error handling

If an error occurs the response will contain error messages explaining the error:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <soapenv:Fault>
         <faultcode>soapenv:Server.userException</faultcode>
         <faultstring>coldfusion.xml.rpc.CFCInvocationException: [coldfusion.util.RuntimeWrapper : Could not find an API user with the given credentials][fly.cso.api.v1.exception.RemoteInvalidCredentialsException : Could not find an API user with the given credentials]</faultstring>
         <detail>
            <ns1:hostname xmlns:ns1="http://xml.apache.org/axis/"></ns1:hostname>
         </detail>
      </soapenv:Fault>
   </soapenv:Body>
</soapenv:Envelope>

5.2 isValidApi - Determining the validity of your API key

Description

Used to check if the returned API key is still valid.

Arguments

Input:	isValidApiKeyRequest (wsdlsoap:body, use = encoded) required API key type string
Output:	isValidApiKeyResponse: isValidApiKeyReturn type boolean, (wsdlsoap:body, use = encoded), true if the API key is still valid, false otherwise.
Fault:	CFCInvocationException (wsdlsoap:fault, use = encoded) fault type CFCInvocationException

An XML representation of the request:

<v1:isValidApiKey soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <apiKey xsi:type="xsd:string"></apiKey>
</v1:isValidApiKey>

An XML representation of the response:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <ns1:isValidApiKeyResponse soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:ns1="http://v1">
         <isValidApiKeyReturn xsi:type="xsd:boolean"></isValidApiKeyReturn>
      </ns1:isValidApiKeyResponse>
   </soapenv:Body>
</soapenv:Envelope>

5.3 getJob - Get a single job

Description

This function is used to retrieve a single job by its jobCode. The level of detail for the job returned is specified in jobFieldSelection.

A job on the CSO-platform is identified by jobCode (baanplein_ID used as URL parameter on the platform). To retrieve a single job make a call to the function 'getJob' providing your API key and the jobCode. To define the level of detail for the requested job, provide a jobFieldSelection (see the specification of jobFieldSelection for an overview of all available properties).

The field selection is required in the request even if it returns empty values. An empty field selection will return all fields available for the given job. Field selections are always of type Boolean and grouped by meaning.

For example, the settings for the job description are found in the property content. Detailed features on Branche, EducationLevel and Region are set in features.detail. Information on publication period, dates and status are found in publication.status and publication.data.

Arguments

Input:	getJobRequest, (wsdlsoap:body, use = encoded) required apiKey type string required jobCode type string required remoteJobFieldSelection type RemoteJobFieldSelection
Output:	getJobResponse (wsdlsoap:body, use = encoded), RemoteJob — a single job with the given id. getJobReturn type RemoteJob
Fault:	CFCInvocationException (wsdlsoap:fault, use = encoded) fault type CFCInvocationException fly.cso.api.v1.exception:RemotePermissionDeniedException fly.cso.api.v1.exception:RemoteInvalidApiKeyException fly.cso.api.v1.exception:RemoteJobNotFoundException

An XML representation of the request: (the remoteJobFieldSelection argument has more properties then actually used here)

<v1:getJob soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
 <apiKey xsi:type="xsd:string"></apiKey>
 <jobCode xsi:type="xsd:string"></jobCode>
 <remoteJobFieldSelection xsi:type="sel:RemoteJobFieldSelection" xmlns:sel="http://selection.v1.api.cso.fly">
    <jobContent xsi:type="sel:RemoteJobContentFieldSelection">
       <department xsi:type="xsd:boolean"></department>
       <employer xsi:type="xsd:boolean"></employer>
    </jobContent><jobPublication xsi:type="sel:RemoteJobPublicationDataFieldSelection">
       <publications xsi:type="xsd:boolean"></publications>
    </jobPublication>
    <organisation xsi:type="xsd:boolean"></organisation>
 </remoteJobFieldSelection>
</v1:getJob>

5.4 getJobs - get an Array of jobs

Description

This function returns an array of jobs based on a given jobFilter.

Otherwise identical to getJob function (fieldSelection is required but can by empty), the function getJobs requires an additional jobFilter. The filter defines the (search) criteria for the returned list.

For a detailed overview of all properties and the structure of remoteJobFilter and remoteJobFieldSelection see examples and reference documentation.

Arguments

Input:	getJobsRequest (wsdlsoap:body, use = encoded) required apiKey type string required remoteJobFilter type RemoteJobFilter required remoteJobFieldSelection type RemoteJobFieldSelection
Output:	getJobsResponse (wsdlsoap:body, use = encoded) getJobsReturn type ArrayOf_xsd_anyType - array of type anyType
Fault:	CFCInvocationException (wsdlsoap:fault, use = encoded) fault type CFCInvocationException fly.cso.api.v1.exception:RemotePermissionDeniedException fly.cso.api.v1.exception:RemoteInvalidApiKeyException fly.cso.api.v1.exception:RemoteInvalidFilterException

An XML representation of the request:

<v1:getJobs soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
 <apiKey xsi:type="xsd:string"></apiKey>
	<filter>
 </filter>
 <fieldSelection xsi:type="sel:RemoteJobFieldSelection" xmlns:sel="http://selection.v1.api.cso.fly">
    <jobContent xsi:type="sel:RemoteJobContentFieldSelection">
       <department xsi:type="xsd:boolean"></department>
       <employer xsi:type="xsd:boolean"></employer>
    </jobContent>
 </fieldSelection>
</v1:getJobs>

5.5 getJobCount - Count the number of jobs for the given filtercriteria

Description

The function getJobCount is used to retrieve the number of jobs for a specified jobFilter.

To count the number of jobs returned for a given set of filter criteria use the function getjobCount.

Arguments

Input:	getJobCountRequest (wsdlsoap:body, use = encoded) required apiKey type string required remoteJobFilter type RemoteJobFilter
Output:	getJobCountResponse (wsdlsoap:body, use = encoded) getJobCountReturn type string
Fault:	CFCInvocationException (wsdlsoap:fault, use = encoded) fault type CFCInvocationException fly.cso.api.v1.exception:RemotePermissionDeniedException fly.cso.api.v1.exception:RemoteInvalidApiKeyException

An XML representation of the request:

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://v1" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
   <soapenv:Header/>
   <soapenv:Body>
      <v1:getJobCount soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <apiKey xsi:type="xsd:string"></apiKey>
         <filter xsi:type="fil:RemoteJobFilter" xmlns:fil="http://filter.v1.api.cso.fly">
            <contentFilter xsi:type="fil:RemoteJobContentFilter">
               <name xsi:type="xsd:string">manager</name>
            </contentFilter>
         </filter>
      </v1:getJobCount>
   </soapenv:Body>
</soapenv:Envelope>

An XML representation of the response:

5.6 getJobEnumerations - Get all available enumerated data for jobs

Description

A job has many properties, some are freeform textual fields, others enumerated values such as publicationStatus, region, jobBranche, contractType or drivinglicense. These properties are enumerations with a label holding the description and a unique code. While making SOAP requests always use the property 'code' as input. The field 'description' is a read-only value used for display purposes.

The function getJobEnumerations returns a list of all available enumerated properties (labels and codes) and cannot be filtered while making an API call. Below is a mapping of the available types, their code and an excerpt of the descriptive labels.

Enumerations

Enumeration	Code (excerpt)	Label (excerpt)
contractTypes	CSD.nnn (numeric values)	For example: 'Vaste aanstelling (eventueel met een proeftijd)'
drivingLicences	A t/m E	Identical to the value in the code excerpt, lowercase
jobApplicationTypes	'electronic' or 'written'	'Elektronisch' or 'Schriftelijk'
onlineJobApplicationTypes	EST.nnn	For example: 'reactie URL'
jobBranches	CVG.nnn	For example: 'Administratief/Secretarieel, Agrarisch, Administratief/Secretarieel, '
jobCategories	CFT.nnn	For example: 'Bestuurlijk,Management / Leidinggevend, Onderwijsgevend'
jobPublicationStatuses	PUB.nnn	For example: 'Intern, Interdepartementaal, Extern'
jobPublicationPeriods	-1, -2, -5, -7, -30 negative numeric	For example: 'Gisteren, Laatste 3 dagen,Laatste 5 dagen, Laatste 7 dagen,Laatste maand'
payScales	uuid	For example 'Salarisniveau schaal 6,7 or 8'
educationLevels	CWD.nnn	For example: 'Master/doctoraal, Bachelor - HBO, MBO'
regions	BRG.nnn or NL, DZ, AO, BW	For example: 'Friesland or Nederland, Algerije, Angola, Botswana'
securityScreenings	VFN.01, 02 or 03	Functie is een vertrouwensfunctie op niveau 'A', 'B' or 'C'
tvDistinctions	'tutoyeren' or 'vousvoyeren'	'je' or 'u'

Arguments

Input:	getJobEnumerationsRequest (wsdlsoap:body, use = encoded) required apiKey type string
Output:	getJobEnumerationsResponse (wsdlsoap:body, use = encoded) getJobEnumerationsReturn type anyType
Fault:	CFCInvocationException (wsdlsoap:fault, use = encoded) fault type CFCInvocationException fly.cso.api.v1.exception:RemotePermissionDeniedException fly.cso.api.v1.exception:RemoteInvalidApiKeyException

An XML representation of the request:

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://v1">
   <soapenv:Header/>
   <soapenv:Body>
      <v1:getJobEnumerations soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <apiKey xsi:type="xsd:string"></apiKey>
      </v1:getJobEnumerations>
   </soapenv:Body>
</soapenv:Envelope>

An XML representation of the response:

5.7 getOrganisations - Get all available organisations available on the CSO Platform

Description

This function retrieves a list of all participating organisations on the CSO platform.

Arguments

Input:	getOrganisationsRequest (wsdlsoap:body, use = encoded) required apiKey type string
Output:	getJobEnumerationsResponse (wsdlsoap:body, use = encoded) getOrganisationsReturn type ArrayOf_xsd_anyType - array of type anyType
Fault:	CFCInvocationException (wsdlsoap:fault, use = encoded) fault type CFCInvocationException fly.cso.api.v1.exception:RemotePermissionDeniedException fly.cso.api.v1.exception:RemoteInvalidApiKeyException

An XML representation of the request:

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://v1" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
   <soapenv:Header/>
   <soapenv:Body>
      <v1:getOrganisations soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <apiKey xsi:type="xsd:string"></apiKey>
         <filter xsi:type="fil:RemoteOrganisationFilter" xmlns:fil="http://filter.v1.api.cso.fly">
            <sector xsi:type="job:RemoteSector" xmlns:job="http://job.data.v1.api.cso.fly">
               <code xsi:type="xsd:string"></code>
            </sector>
         </filter>
      </v1:getOrganisations>
   </soapenv:Body>
</soapenv:Envelope>

An XML representation of the response:

5.8 getOrganisationsWithFilter - Get organisations based on a given filter

Description

This function retrieves a specific list of organisations on the CSO platform; for example all organisations in a specific sector.

Arguments

Input:	getOrganisationsWithFilterRequest (wsdlsoap:body, use = encoded) required apiKey type string required remoteOrganisationFilter type RemoteOrganisationFilter
Output:	getJobEnumerationsResponse (wsdlsoap:body, use = encoded) getOrganisationsWithFilterReturn type ArrayOf_xsd_anyType - array of type anyType
Fault:	CFCInvocationException (wsdlsoap:fault, use = encoded) fault type CFCInvocationException fly.cso.api.v1.exception:RemotePermissionDeniedException fly.cso.api.v1.exception:RemoteInvalidApiKeyException fly.cso.api.v1.exception:RemoteInvalidFilterException

An XML representation of the request:

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://v1" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
   <soapenv:Header/>
   <soapenv:Body>
      <v1:getOrganisations soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <apiKey xsi:type="xsd:string"></apiKey>
         <filter xsi:type="fil:RemoteOrganisationFilter" xmlns:fil="http://filter.v1.api.cso.fly">
            <sector xsi:type="job:RemoteSector" xmlns:job="http://job.data.v1.api.cso.fly">
               <code xsi:type="xsd:string"></code>
            </sector>
         </filter>
      </v1:getOrganisations>
   </soapenv:Body>
</soapenv:Envelope>

An XML representation of the response:

5.9 getJobCountForEnumeration - Get the number of jobs per enumeration for the given enumeration type and filter

Description

This function returns the number of jobs ("14") per enumeration ("Utrecht") for the given enumeration type ("Region") and filter ("keyword:'internet'").

Arguments

Input:	getJobsRequest (wsdlsoap:body, use = encoded) required apiKey type string required enumerationType type string Must be one of these strings: "EducationLevel","JobBranch","JobCategory","ContractType","Region". required filter type RemoteJobFilter
Output:	getJobCountForEnumerationResponse (wsdlsoap:body, use = encoded) getJobCountForEnumerationReturn array of type RemoteJobEnumerationCount
Fault:	CFCInvocationException (wsdlsoap:fault, use = encoded) fault type CFCInvocationException fly.cso.api.v1.exception:RemotePermissionDeniedException fly.cso.api.v1.exception:RemoteInvalidApiKeyException fly.cso.api.v1.exception:RemoteInvalidFilterException

An XML representation of the request:

<soapenv:Envelope>
   <soapenv:Header/>
   <soapenv:Body>
      <v1:getJobCountForEnumeration soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <apiKey xsi:type="xsd:string">550e8400-e29b-41d4-a716-446655440000</apiKey>
         <enumerationType xsi:type="xsd:string">Region</enumerationType>
         <filter>
             <contentFilter xsi:type="def:fly.cso.api.v1.filter.remotejobcontentfilter">
               <name xsi:type="xsd:string">internet</name>
            </contentFilter>
         </filter>
      </v1:getJobCountForEnumeration>
   </soapenv:Body>
</soapenv:Envelope>

An XML representation of the response:

<soapenv:Envelope [...]>
   <soapenv:Body>
      <ns1:getJobCountForEnumerationResponse [...]>
         <getJobCountForEnumerationReturn 
          soapenc:arrayType="ns2:RemoteJobEnumerationCount[5]" 
          xsi:type="soapenc:Array" [...]>
            <getJobCountForEnumerationReturn xsi:type="ns2:RemoteJobEnumerationCount">
               <enumeration xsi:type="ns3:Region" xmlns:ns3="http://enumerations.domain.cso.fly">
                  <code xsi:type="xsd:string">BRG.0210</code>
                  <label xsi:type="xsd:string">Gelderland</label>
                  [...]
               </enumeration>
               <jobSearchCount xsi:type="xsd:double">2.0</jobSearchCount>
            </getJobCountForEnumerationReturn>
            <getJobCountForEnumerationReturn xsi:type="ns2:RemoteJobEnumerationCount">
               <enumeration xsi:type="ns4:Region" xmlns:ns4="http://enumerations.domain.cso.fly">
                  <code xsi:type="xsd:string">BRG.0214</code>
                  <label xsi:type="xsd:string">Utrecht</label>
                  [...]
               </enumeration>
               <jobSearchCount xsi:type="xsd:double">2.0</jobSearchCount>
            </getJobCountForEnumerationReturn>
           [... 3 more ...]
         </getJobCountForEnumerationReturn>
      </ns1:getJobCountForEnumerationResponse>
   </soapenv:Body>
</soapenv:Envelope>

5.10 saveJob - Save a job

Description

This function is used to save a job.

Jobs have many properties, a listing of the minimal required set of information is shown below. The fields locationData and publicationData require additional conditional logic to validate the job object. Publication data is the most comprehensive type of validation. See the table below for descriptions of publication data and publication periods.

Validation

General requirements

Saving a job requires a minimal set of required fields to be present in the SOAP request. Below is a list of all required fields with dutch names known to users of the CSO-platform.

internalReferenceCode	code this job is referenced by within the organisation (vacaturenummer).
organisation	code for the organisation this job belongs to (deelnemer).
jobContent.name	title for this job (functienaam).
jobContent.description	short text describing the job (functie-omschrijving).
jobContent.requirements	requirements for the job (functie-eisen).
jobContent.applicationTypes	how to apply for this job: written application, digital application or both.
jobContent.locationData.city	city in which is the job situated (standplaats).
jobFeatures.jobDetail.educationLevels	codes for the education level(s) required for this job (werk-denkniveau).
jobFeatures.jobDetail.jobCategories	codes categorizing the type(s) of this job, (functietype).
jobFeatures.jobDetail.jobBranches	codes to categorize the jobbranche(s) this job applies to (vakgebied).
jobFeatures.jobDetail.regions	code to categorize the region(s) or country the job is situated (regio of land).
jobFeatures.employmentConditionsData.hoursMax	maximum number of hours per week for this job.
jobFeatures.employmentConditionsData.contractType	type of contract for this job, for example 'permanent contract' or 'research Internship'.
publication.visible	value to flag the jobs visiblity on the platforms.

Conditional requirements

Some properties have conditional requirements. Below is a list of conditional fields and a description of the conditional logic.

1. Job application data:

   Different fields are required for electronic and written application types. Since applicationTypes is a required field, we can omit the validation when it is absent. See table Enumerations for an overview of applicationTypes.

2. Location data

   When multiple regions are specified, regions must be situated in The Netherlands which makes the fields Postalcode and City required fields. When a country outside the Netherlands is selected, those fields are not required.

3. Salary

   We distinguish two groups of organisations: those that have payScales and those that don't. The first group must either submit a payScale or payDescription and are not allowed to submit min/max salary values. The second group must either submit min/max salary values or payDescription and are not allowed to submit any payScales.

4. Publication data and phases

   the publication period of a job is composed of several publication phases. These phases mark the availability of the information to a specific audience. See the table below for general rules that apply for saving or retrieving a job. Sometimes, no job information is returned after a (valid) request because of these rules.

   Publication phase	Description
   HPK	If the organisation that provides the job has a required HPK period, the range between dateStart and dateEnd should at least be similar to the predefined range. The dateEnd could extend the predefined range. Overlap of the HPK period with another period is not allowed. DateStart and dateEnd are required fields (the API does not calculate ranges automatically).
   Intern	Publication dates for 'Intern' are required fields. Overlap with HPK period is not allowed. The jobs are published on mobiliteitsbank.nl.
   Interdepartementaal	This publication period only applies to RijksOrganisaties. Both dateStart and dateEnd are required fields. Overlap with HPK period is not allowed. An overlap in dates with 'Intern' is allowed. Jobs will be published on mobiliteitsbank.nl.
   Extern	During this publication period the job will be available on both mobiliteitsbank.nl, werkenbijdeoverheid.nl and werkenbijhetrijk.nl. Both dateStart and dateEnd are required fields and should never overlap with HPK period.

Arguments

Input:	saveJobRequest (wsdlsoap:body, use = encoded) required apiKey type string required job type RemoteJob
Output:	saveJobResponse (wsdlsoap:body, use = encoded) saveJobReturn type RemoteJob
Fault:	CFCInvocationException (wsdlsoap:fault, use = encoded) fault type CFCInvocationException fly.cso.api.v1.exception:RemotePermissionDeniedException fly.cso.api.v1.exception:RemoteInvalidApiKeyException fly.cso.api.v1.exception:RemoteInvalidJobDataException

An example XML representation of the request to save a job:

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://v1" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
   <soapenv:Header/>
   <soapenv:Body>
      <v1:saveJob soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <apiKey xsi:type="xsd:string"></apiKey>
         <job xsi:type="job:RemoteJob" xmlns:job="http://job.data.v1.api.cso.fly">
            <content xsi:type="job:RemoteJobContent">
                  <description xsi:type="xsd:string"></description>
                  <name xsi:type="xsd:string"></name>
                  <requirements xsi:type="xsd:string"></requirements>
            </content>
            <features xsi:type="job:RemoteJobFeatures">
               <employmentConditions xsi:type="job:RemoteJobEmploymentConditions">
                  <contractType xsi:type="enum:ContractType" xmlns:enum="http://enumerations.domain.cso.fly">
                     <code xsi:type="xsd:string"></code>
                     <label xsi:type="xsd:string"></label>
                  </contractType>
                  <hoursMax xsi:type="xsd:double"></hoursMax>
               </employmentConditions>
               <featuresDetail xsi:type="job:RemoteJobFeaturesDetail">
                  <educationLevels xsi:type="v1:ArrayOf_tns6_EducationLevel" soapenc:arrayType="enum:EducationLevel[]" xmlns:enum="http://enumerations.domain.cso.fly"/>
                  <jobBranches xsi:type="v1:ArrayOf_tns6_JobBranch" soapenc:arrayType="enum:JobBranch[]" xmlns:enum="http://enumerations.domain.cso.fly"/>
                  <jobCategories xsi:type="v1:ArrayOf_tns6_JobCategory" soapenc:arrayType="enum:JobCategory[]" xmlns:enum="http://enumerations.domain.cso.fly"/>
               </featuresDetail>
               <location xsi:type="job:RemoteJobLocation">
                  <city xsi:type="xsd:string"></city>
               </location>
            </features>
            <internalReferenceCode xsi:type="xsd:string"></internalReferenceCode>
         </job>
      </v1:saveJob>
   </soapenv:Body>
</soapenv:Envelope>

5.11 removeJob - Delete a job

Description

This function deletes a job

Arguments

Input:	removeJobRequest (wsdlsoap:body, use = encoded) required apiKey type string required jobCode type string
Output:	removeJobResponse (wsdlsoap:body, use = encoded)
Fault:	CFCInvocationException (wsdlsoap:fault, use = encoded) fault type CFCInvocationException fly.cso.api.v1.exception:RemotePermissionDeniedException fly.cso.api.v1.exception:RemoteInvalidApiKeyException fly.cso.api.v1.exception:RemoteJobNotFoundException

An XML representation of the request:

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://v1">
   <soapenv:Header/>
   <soapenv:Body>
      <v1:removeJob soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <apiKey xsi:type="xsd:string"></apiKey>
         <jobCode xsi:type="xsd:string"></jobCode>
      </v1:removeJob>
   </soapenv:Body>
</soapenv:Envelope>

5.12 RemoteJobFilter - Define a filter for specific selections of jobs

Description

JobFilter defines selection criteria of jobs to return.

For example, to list all jobs currently available, all jobs for a specified organisation or sector, all jobs for a given publication period or jobs with specific employment conditions.

Filter criteria are of type Boolean, string or a code for an enumerated object (for example: region). For more information and a full mapping of available properties see the reference documentation.

Arguments

5.13 RemoteJobFieldSelection - Define a fieldselection to define the level of detail for a job

Description

This function defines the level of detail for a requested job provide a jobFieldSelection.

The specification for jobFieldSelection provides an overview of all properties available for a job. If no jobFieldSelection is provided all data available for a job will be returned. Field selections are always of type Boolean and grouped by meaning. For example, settings for textual content of a job are found in the property content. Detailed features like branche, education level or region are set in features.detail.

Arguments

5.14 RemoteOrganisationFilter - Define a filter to retrieve categories of organisations

Description

To find all organisations in a given sector provide a remoteOrganisationFilter.

Arguments

5.15 RemoteJobEnumerationCount

Description

This object represents the number of jobs found for each enumeration.

6 Frequently asked questions

Section not avaliable.

7 Deprecation documentation

Section not avaliable.

8 Future enhancements

Currently the CSO API v1. features the port JobAPI. Future enhancements will provide access to both a CandidateAPI and JobApplicationAPI.

9 Support

For API access requests, questions, suggestions and feedback, contact the help desk.

Telephone	+31 6 50768327
Email address	helpdesk@werkenvoornederland.nl

Known problems

Currently there are no known problems for API v1.