The Angebote API v1/v2 and Vorgaenge API v1/v2 have reached end of life and will be shut down on End of November 2026. Please migrate to the only actively supported version v3 before that date.

This guide focuses on endpoint-level migration. Review your client implementation for:

• /v1/ or /v2/ URLs
• generated clients based on old OpenAPI specifications
• code that expects v2 302 responses and follows the Location header
• code that stores only an ermittlungsId, because v3 result-list endpoints also require the vorgangsnummer
• code that reads gemerkteAngebote from the Vorgaenge API, because this moved to the Angebote API v3

OpenAPI specifications

Use the current v3 OpenAPI specifications to regenerate clients or validate your implementation:

• Angebote API OpenAPI specification
• Vorgaenge API OpenAPI specification

Existing Authorization flows can be reused.

Angebote API migration

Main changes

In v1 and parts of v2 the Angebote API could calculate offers directly from ErfassteDaten. v3 calculates offer result lists only for an existing Vorgang. This means that clients must first create or update the Vorgang and then call the Angebote API v3 with the vorgangsnummer.

Alternative use Vorschlaege API for calculations without an existing Vorgang.

v3 also changes the calculation flow:

• The calculation endpoint is now POST /v3/vorgaenge/{vorgangsnummer}/ergebnisliste.
• Calculation options such as alternativen, produktAnbieter, exkludierteProduktAnbieter and provisionsAusgabe are sent in the JSON request body, not as query parameters.
• A successful calculation returns 200 with a result list or 204 if no result list is available. v2 clients must no longer expect a 302 response with a Location header.
• Follow-up reads use both vorgangsnummer and ergebnislisteId.

Example v3 calculation request:

POST /v3/vorgaenge/ABC123/ergebnisliste
Authorization: Bearer <access-token>
Content-Type: application/json
X-TraceId: <trace-id>

{
  "ermitteln": true,
  "aktualisieren": false,
  "alternativen": true,
  "produktAnbieter": ["PRODUKTANBIETER_ID"],
  "exkludierteProduktAnbieter": [],
  "provisionsAusgabe": true
}

Angebote API v1 to v3

Angebote API v2 to v3

Vorgaenge API migration

Vorgaenge API v1 to v3

Most v1 endpoints have a direct v3 endpoint with the version segment changed from /v1/ to /v3/.

Vorgaenge API v2 to v3

Most v2 endpoints also have a direct v3 endpoint with the version segment changed from /v2/ to /v3/. The exception is gemerkteAngebote: those endpoints are not part of the Vorgaenge API v3. Use the Angebote API v3 endpoints for saved offers.

Migration checklist

1. Inventory all calls to Angebote API and Vorgaenge API that still use /v1/ or /v2/.
2. Decide whether each Angebote API calculation uses an existing Vorgang. If not, migrate to Vorschlaege API or create/update a Vorgang before calculating.
3. Regenerate API clients from the v3 OpenAPI specifications.
4. Replace v2 Angebote API polling or redirect handling with v3 200/204 response handling.
5. Persist the vorgangsnummer together with the v3 ergebnislisteId for all follow-up reads.
6. Move gemerkteAngebote reads from Vorgaenge API v2 to Angebote API v3.