Overview

The Europass REST API is the latest addition to the public set of Europass Web Services. It tries to conform as much as possible to the Representational State Transfer (REST) design principles and architectural style. It is entirely HTTP-based and therefore can work with any system or application that is able to send HTTP requests.

If you are just starting out with Europass Interoperability, this is the web service to use. If you already use the legacy Europass SOAP API, you MUST migrate to the REST API the soonest possible since the SOAP API will cease functioning soon.

What Does It Do?

The Europass REST API mostly provides a set of conversion services which allow external systems to send a Europass XML or JSON document and get back a Europass document of a different file format such as PDF+XML. In addition, it provides two utility methods, one to extract the XML attachment from a Europass PDF+XML document and another one to upgrade an older Europass XML (i.e. XML versions <= 2.0) to the latest version.

For the time being, the file formats that can be used as input are Europass XML v3.0.x, PDF + Europass XML and Europass JSON v3.0.x. The returned file formats are (apart from those used as input) Microsoft Word 97-2003 (.doc) and OpenDocument ver 2 Text (.odt).

The conversion service methods support conversions for Europass CVs, Europass Language Passports and European Skills Passports, since all of these documents can be represented in Europass XML or Europass JSON. All services are available via simple HTTP POSTs.

Base URL and Versioning

All URLs mentioned in the REST API documentation start with the following base URL:

https://europass.cedefop.europa.eu/rest/v1

The Europass REST API uses a versioning scheme by including the API version in the request URL. Breaking changes will cause the version to change while non-breaking changes will leave it intact. In any case, even if the version changes, the previous version of the API will keep working for a sufficient amount of time, until all clients that depend on it have stopped using it.

Currently, there is only one version of the REST API, namely v1. If you want to get notified for future changes, you may subscribe to the Changelog Atom feed or join the Europass Interoperability Google Group.

Tip

You can also consult the Europass Compatibility Matrix for further details on versions and compatibility.

Security

The API does not require any kind of authentication, but given that the services involve personal data (e.g. in the Curriculum Vitae), all requests must be made over secure HTTP (HTTPS). Requests made on plain HTTP will be forbidden with an HTTP 403 Forbidden Status response.

Request Format

Requests to all REST API endpoints use a similar format which is described below.

Method

Currently, all REST API services/endpoints require a POST HTTP request.

Headers

Content-Type
Indicates the media type of the file to be sent to the server. Possible values:
  • application/xml
  • application/json
  • application/pdf
Accept-Language
An optional header to specify the preferred language of the document in the response. The accepted values are the two-letter codes corresponding to each one of the 26 languages currently supported by the Europass Online Editor. For example, an Accept-Language: fr header should be included in the request in order to translate an English document to French. See Localisation section below for details.

Request Body

The entire POST body consists of the file contents to be sent to the service. The media type of the file should match with the value of the Content-Type header described above.

Response Format

The response format for all requests includes an HTTP Status along with either the given file's contents in the requested file format in case of success, or an error object in case of failure.

Success Response

In case of a successful request, the response will include an 200 OK HTTP Status accompanied by the contents of a file in PDF+XML, DOC, ODT, XML or JSON format, depending on the REST service called.

Error Response

In case of an unsuccessful request, the response will include an 4xx or 5xx HTTP Status Code and optionally (depending on the HTTP Status) an XML or JSON error object with details about the error. Whether the error object is XML or JSON, depends on the Content-Type header of the request. If Content-Type: application/xml or Content-Type: application/json, the error object will be in XML or JSON format respectively. If the value of Content-Type is set to something different than XML or JSON (e.g. application/pdf) or if the Content-Type header is missing from the request, the error object defaults to XML format.

Regardless of XML or JSON, the error object consist of the following properties:

trace
A unique error id in the form of an 8-character alphanumeric string (e.g. ar37tMkr) used for troubleshooting purposes. This is the reference code to use in case you need to contact the Europass support team.
code
A short, codified representation of the error message such as unsupported.content.type, which can be used e.g. for testing purposes.
message
A human-friendly description of the error at hand.

A list of all possible 4xx and 5xx HTTP Statuses along with a short description for each one of them is given below. The exact error responses to expect for each service are described in detail in the REST API Reference.

Errors

HTTP Status Description
400 Bad Request Something is wrong with the input document (it is missing/empty or e.g. invalid XML/JSON) or with the Accept-Language header (the requested locale is not supported by Europass).
403 Forbidden The request was made over plain, non-secure HTTP while HTTPS is required.
404 Not Found The requested resource could not be found, possibly due to a typo (e.g. /to/pdf instead of /document/to/pdf).
405 Method Not Allowed The requested resource does not allow the HTTP Method used (e.g. DELETE instead of POST).
406 Not Acceptable An invalid Accept header was set in the request (e.g. Accept: application/msword instead of Accept: application/pdf when generating a PDF). Note though that normally you should not include at all an Accept header in the request.
415 Unsupported Media Type This error can appear in the following cases:
  • The value of the Content-Type header is missing from the request or it is invalid (e.g. Content-Type: application/xml for a service that consumes JSON only such as /document/to/xml).
  • The input document is missing/empty or its format is not supported by the requested service (e.g. a PDF file was sent to /document/to/pdf).
500 Internal Server Error Something went wrong on the server-side (i.e. most probably it is not your fault). If the problem persists, contact the Europass support team.
503 Service Unavailable The requested service is unavailable most probably due to maintenance reasons. If the problem persists, contact the Europass support team.

Localisation

Encoding

The Europass REST API expects all data to be encoded in UTF-8.

Translations

Similarly to the Europass Online Editor, the REST API can also be used to translate a Europass document to anyone of the 26 supported languages. Only headings, taxonomies (occupational fields, countries, nationalities, etc.), addresss formats and date formats are translated though, not user-entered content.

In order to localise/translate a document, a suitable Accept-Language header should be set in the request sent to the REST API. More specifically, the following rules apply:

  • If the Accept-Language header is omitted from the request or if it is set in the request but the requested language of translation is the same with that in the locale element of the submitted XML or JSON, no translation takes place.
  • If the Accept-Language header is set in the request with a value that corresponds to the two-letter code of one of the 26 languages supported by Europass, the document is traslated according to this language.
  • If the Accept-Language header is set in the request with a value that does not match with the two-letter code of one of the 26 languages supported by Europass, the request will fail with an 400 Bad Request HTTP Status along with a suitable error object, like the one below:
{
   "Error": {
	"trace": "8CKvqOc6",
	"code": "unsupported.locale",
	"message": "Locale foo is not supported by Europass"
    }
}

Supported Languages

The following 26 languages are currently supported:

# Code Language
1 bg български
2 es español
3 cs čeština
4 da dansk
5 de Deutsch
6 et eesti keel
7 el ελληνικά
8 en english
9 fr français
10 hr hrvatski
11 is íslenska
12 it Italiano
13 lv latviešu valoda
14 lt lietuvių kalba
15 hu Magyar
16 mt Malti
17 nl Nederlands
18 no Norsk
19 pl polski
20 pt português
21 ro română
22 sk slovenčina
23 sl slovenščina
24 fi suomi
25 sv svenska
26 tr türkçe

Services Summary

Below you can find a summary of all the services currently provided by the Europass REST API v1. Extensive details and examples on how to call each one of the services can be found in the REST API Reference section or by following the links below.

Service Description
XML to PDF CV Converts a Europass CV or CV+ESP in XML format to a Europass CV in PDF format
XML to PDF ESP Converts a Europass ESP or CV+ESP in XML format to a Europass ESP in PDF format
XML to PDF CV+ESP Converts a Europass CV+ESP in XML format to a Europass CV+ESP in PDF format
XML to Word Converts a Europass CV or CV+ESP in XML format to a Europass CV in Microsoft Word 2003 format
XML to ODT Converts a Europass CV or CV+ESP in XML format to a Europass CV in OpenDocument format
XML to JSON Converts a Europass CV or ESP or CV+ESP in XML format to a Europass CV or ESP or CV+ESP in JSON format
XML Upgrade Converts a Europass CV (or LP) in XML format v2.0 or older to a Europass CV in XML format v3.0 or later
XML Extraction Extracts the XML attachment from a Europass PDF+XML (v3.0 or older)
JSON to PDF CV Converts a Europass CV or CV+ESP in JSON format to a Europass CV in PDF format
JSON to PDF ESP Converts a Europass ESP or CV+ESP in JSON format to a Europass ESP in PDF format
JSON to PDF CV+ESP Converts a Europass CV+ESP in JSON format to a Europass CV+ESP in PDF format
JSON to Word Converts a Europass CV or CV+ESP in JSON format to a Europass CV in Microsoft Word 2003 format
JSON to ODT Converts a Europass CV or CV+ESP in JSON format to a Europass CV in OpenDocument Text format
JSON to XML CV Converts a Europass CV or CV+ESP in JSON format to a Europass CV in XML format
JSON to XML ESP Converts a Europass ESP or CV+ESP in JSON format to a Europass ESP in XML format
JSON to XML CV+ESP Converts a Europass CV+ESP in JSON format to a Europass CV+ESP in XML format