TED API

Introduction

The Publications Office (OP) has developed a range of applications for the submission, validation, processing, visualisation, and dissemination of eForms notices. These went into production on 14 November 2022 and are collectively known as TED Apps.

The OP has also developed TED API, a set of programmatic tools that allows third-party developers to integrate their applications with the TED ecosystem and the TED Apps. By using TED API, organisations can automate and streamline processes related to public procurement, enabling efficient interaction with TED services across Europe. This makes it an essential resource for governments, businesses, and developers (e.g. eSenders or reusers of TED Data) who need to work with public procurement notices.

Using the TED API, developers can create applications that:

Retrieve published procurement notices from the TED website for analysis or reuse.
Submit and Manage notices for publication programmatically, eliminating manual steps.
Validate notices to ensure compliance with procurement regulations.
Visualise notices in readable formats such as PDFs or HTML.

TED API allows anonymous access to all services manipulating published notices (i.e., searching for or retrieving notices already published on TED). All TED API endpoints that manipulate notices which are not yet published require the caller to be authenticated with an API key.

How TED API links to TED Apps

Each TED API operation aligns with specific TED applications, enabling the seamless processing, validation, and publication of eForms notices. The diagram below illustrates how these connections are structured:

eNotices2

The single entry point for submitting and managing eForms notices.

Interacts with the Publication API for programmatic submissions, queries, and publication management.
Designed with front-end users in mind, while developers interface directly with the Publication API.
Works with the TED Central Validation Service to validate notices before and upon submission.

TED Central Validation Service (TED CVS)

An API-only service ensuring compliance standards for notices.

The Validation API checks notices for errors and warnings when they are submitted to the Publication API.
Can be used independently to detect errors and warnings at any time before publication.
Notices that successfully pass CVS validation can be considered technically valid for publication on TED.

TED Viewer

Renders notices into readable formats like HTML and PDF.

The Visualisation API enables this functionality.
Works with eNotices2 to preview notices in PDF or HTML.
Can be called directly by external parties to preview XML notices.

TED Website

The public-facing platform for published notices.

The Search API allows access to these notices for reuse or analysis.
Expert queries built on the TED Website can also be used via the API.

TED XML Data Converter (TEDXDC)

An API-only service designed to convert legacy TED XML schema notices into drafts in eForms.

Utilised by eNotices2 when importing a TED XML notice to continue procedures in eForms.
Available as a stand-alone API for developers.

This interconnected structure ensures developers can automate the entire notice processing lifecycle—submission to publication and visualisation—while adhering to EU standards.

Other systems, like TED Monitor, are internal to the Publications Office and support the preparation of procurement notices for publication. Additionally, auxiliary developer operations provide essential tools for both developers and OP systems.

Getting started

Obtain an API key
- Visit the TED Developer Portal.
- Log in with your EU Login credentials.
- Generate your API Key via the Manage API Keys section.

Copy and save your API key upon creation; it cannot be retrieved later.

Authenticate Your Application
- Use your API Key in the header of requests to access TED services.

The Search API does not require a key.

Test in the eForms Preview Environment
- Do not test in the Production environment, as it is reserved for notices that will be published on TED.
- For more information, see section Testing your apps.

eSenders and developers can create multiple accounts in the Preview environment for testing. In the Production environment, only one account and one API key per EU Login are allowed. We strongly recommend using a shared or functional email address for setting up Production accounts instead of a personal email.

More information on API key management can be found here

New in TED API v3

The new TED API v3 introduces several enhancements designed to simplify access, consolidate services, and improve user experience for developers and organisations. Key improvements include:

Unified Gateway

All APIs are now accessible through a single domain: api.ted.europa.eu

Rationalised and Standardised API Endpoints

The structure of API URLs has been harmonised for consistency: https://api.ted.europa.eu/{api-version}/{resource}/{action}

Consolidated Swagger Interface

Explore all endpoints in one place for easier navigation and integration: https://api.ted.europa.eu/swagger

Streamlined API Transitions

One unified version number for all APIs

Backwards Compatibility

TED API v2 remains active, allowing for a smooth transition to v3

Transitioning from TED API v2

TED API v2 will remain supported until version 4 becomes available. Any plans for v4 will be communicated well in advance to ensure a smooth transition to the latest version.

Developers are encouraged to migrate to the latest version as soon as possible to benefit from its enhanced features and unified interface.

Please be aware that in TED API v3, the mandatory property "noticeAuthorLocale" in the metadata has been replaced by "noticeAuthorLang." Both properties will be accepted during the transition period to v3, but we recommend making the change as soon as possible.

Testing your apps

The eForms Preview Environment was made available to allow and encourage developers to test their applications before or after deployment. Here is how to get started:

How to start testing

1. Obtain an API key

Create an EU Login account in the EU-Login Acceptance Environment.
Generate an API key on the TED Developer Portal of the Preview Environment via the Manage API Keys section.

Copy and save your API key upon creation; it cannot be retrieved later.

Accounts and API keys in "Production" and "Preview" environments are not interchangeable.

2. Authenticate Your Application

Use your API Key in the header of requests to access TED services.

If you are using the Publication API, you also need to create an account in eNotices2 in the Preview environment by logging in with the same EU Login account and perform at least one valid API request for the system to recognise you as an "eSender".

The Search API and the TED Website are not available in the Preview environment; notices submitted in the Preview environment do not get published.

Tips for eSenders

These recommendations help eSenders avoid common integration and workflow issues when using the TED API.

Do not mix eNotices2 UI and API workflows
- If you submit notices via the Publication API, manage the same notice lifecycle exclusively via the API.
- Avoid using the eNotices2 UI to continue procedures or create Change notices for notices originally submitted via the API.
Validate before you submit
- The status VALIDATION_FAILED applies only to eSenders using the Publication API.
- Use the Validation API (TED CVS) to check notices for errors and warnings before submitting them for publication.
- This helps avoid validation failures and reduces the risk of notice rejection following manual OP checks (due to CVS warnings).
- See Validation API.
Respect the notice lifecycle and references between notices
- Submitting a Change notice that refers to a parent notice which has not been published, or providing incorrect references to previous notices, may result in workflow errors (and potentially status NOT_PUBLISHED).
- See Notice lifecycle.
Manage the Business ID correctly
- The Business ID (businessID) is defined by the notice ID and version ID and is assigned by the eSender system.
- Whether a notice ID can be reused depends on the final status reached by the notice.
- See Business ID reuse rules.
Understand Preview vs Production notice timing
- Notice status behaviour and timing differ between the Preview and Production environments.
- These differences are operational and do not change the formal notice lifecycle.
- See Notice lifecycle for status definitions.
- Preview environment
  - Notices submitted in Preview are not published on TED.
  - There is no TED website environment connected to Preview applications.
  - Mock publication statuses are assigned to mimic Production behaviour:
    
    PUBLISHING is assigned at approximately 15:00 CET.
    
    PUBLISHED is assigned at approximately 16:00 CET, on the previous working day before the (preferred) publication date.
- Production environment
  - Notices enter export (PUBLISHING status) at approximately 15:00 CET on the (preferred) publication date.
  - Notices are published on TED no later than 09:00 CET on the publication date of the next OJ S.
  - Once a notice enters status PUBLISHING, publication can no longer be stopped.
- Indicative status timing
  - Preview
    
    PUBLISHING: 15:00–16:00 CET
    
    PUBLISHED: 16:00 CET on the mock export day
  - Production
    
    PUBLISHING: between afternoon export and next-morning publication on TED (working days)
- Important operational note
  - The Preview environment is currently unmonitored.
  - Notices with workflow errors or warnings in Preview may remain in status SUBMITTED without review.
  - To avoid this:
    
    respect the expected notice lifecycle
    
    use the Validation API (CVS) to pre-check notices before submission
  - Periodically, OP may clean Preview records by transferring them to status NOT_PUBLISHED.

Resources and Support

Unified Swagger Interface

Easily navigate and integrate with all API endpoints: https://api.ted.europa.eu/swagger

Developer Portal

Get your API key and manage your developer profile: https://developer.ted.europa.eu

Developers' Corner

Explore various tools and resources for reusing TED data: https://ted.europa.eu/en/simap/developers-corner-for-reusers

eForms Preview Environment

Understand the eForms Preview Environment before you test your eSender integration: https://docs.ted.europa.eu/eforms-common/preview

Technical Issues - eForms SDK

Discuss technical issues on GitHub related to the eForms SDK: https://github.com/OP-TED/eForms-SDK/discussions

Business Issues

TED eSender Workshops

Explore our events page: https://op.europa.eu/en/web/ted-eforms