Menu

Matching-API

Endpoint: Matching-API

Die Matching-API nutzt KI, um passende Förderprogramme für Organisationen und Projekte zu finden. Jede Anfrage wird für die Abrechnung erfasst.

POST /api/v1/matching

Startet einen asynchronen Matching-Prozess und liefert eine matching_request_id zurück. Der Status und die Ergebnisse können anschließend über GET-Endpoints abgefragt werden.

Scope erforderlich: matching:use

Request Body

{
  "organization_id": "partner-org-123",
  "organization_profile": {
    "name": "Kulturverein München e.V.",
    "description": "Gemeinnütziger Verein zur Förderung von Kunst und Kultur...",
    "regions": ["bayern"],
    "grant_areas": ["kultur", "bildung"],
    "eligible_entities": ["eingetragener_verein"],
    "is_non_profit": true
  },
  "project": {
    "title": "Sommerfestival 2026",
    "description": "Open-Air Kulturfestival mit lokalen Künstler:innen..."
  }
}

Parameter

Parameter Typ Pflicht Beschreibung
organization_id String ✓ Eindeutige ID der Organisation in deinem System
organization_profile Object ✓ Profildaten der Organisation (siehe unten)
project Object Optionale Projektbeschreibung

organization_profile (Profildaten und Filter)

Die Filter-Felder (regions, grant_areas, eligible_entities) werden als UND-Filter kombiniert: Nur Förderprogramme, die alle angegebenen Kriterien erfüllen, werden berücksichtigt.

Jedes Filter-Feld akzeptiert Namen, Slugs oder UUIDs. UUIDs erhältst du über die Referenz-Endpoints (Regionen, Förderthemen, Rechtsformen).

Parameter Typ Pflicht Beschreibung
name String Name der Organisation
description String ✓ Ausführliche Beschreibung der Organisation und ihrer Tätigkeiten
regions Array Filter: Regionen (Namen, Slugs oder UUIDs)
grant_areas Array Filter: Förderthemen (Namen, Slugs oder UUIDs)
eligible_entities Array Filter: Rechtsformen (Namen, Slugs oder UUIDs)
is_non_profit Boolean Ist die Organisation gemeinnützig?
mission String Leitbild oder Mission
target_groups Array Zielgruppen (z.B. ["jugendliche", "senioren"])
keywords Array Schlüsselwörter zur Tätigkeit
annual_budget String Jahresbudget
number_of_employees String Anzahl Mitarbeitende
locale String Sprache für Match-Begründungen (de oder en, Standard: de)

Filter-Beispiele

// Mit Namen (einfach)
{
  "regions": ["bayern", "berlin"],
  "grant_areas": ["kultur"],
  "eligible_entities": ["eingetragener_verein", "stiftung"]
}

// Mit UUIDs (präzise)
{
  "regions": ["550e8400-e29b-41d4-a716-446655440111"],
  "grant_areas": ["550e8400-e29b-41d4-a716-446655440001"],
  "eligible_entities": ["550e8400-e29b-41d4-a716-446655440200"]
}

project (Projektdaten)

Parameter Typ Beschreibung
title String Projekttitel
description String Projektbeschreibung
budget String Projektbudget
duration String Projektlaufzeit

Rechtsformen (eligible_entities)

Die vollständige Liste der Rechtsformen erhältst du über GET /api/v1/eligible_entities. Hier die wichtigsten:

Name Beschreibung
Gemeinnützige Organisation Verein, Stiftung, gemeinnützige Unternehmen wie gGmbH, gUG, gAG
Bildungseinrichtung Universitäten, Fachhochschulen und Forschungseinrichtungen
Unternehmen KMU und Sozialunternehmen, Social Enterprises
Genossenschaft Eingetragene Genossenschaften (eG)
Stiftung Stiftungen und Förderfonds
Öffentliche Einrichtung Staatliche Akteure, Verwaltungen und kommunale Einrichtungen
Existenzgründer/in Start-ups und Gründer/innen
Privatperson Einzelpersonen

Tipp: Du kannst Namen, Slugs oder UUIDs verwenden. Die UUIDs erhältst du über den Eligible Entities Endpoint.

Regionen

Die vollständige Liste der Regionen erhältst du über GET /api/v1/regions. Hier die wichtigsten:

  • Bundesländer: Bayern, Berlin, Hamburg, Nordrhein-Westfalen, etc.
  • Deutschland (bundesweit) für deutschlandweite Programme
  • EU für EU-Programme

Förderthemen (grant_areas)

Die vollständige Liste der Förderthemen erhältst du über GET /api/v1/grant_areas. Beispiele:

  • Arbeit & Soziales, Aus- & Weiterbildung, Digitalisierung
  • Energieeffizienz & Klimaschutz, Forschung & Innovation
  • Kultur & Medien, Landwirtschaft & Ländliche Entwicklung

Beispiel-Request

curl -X POST "https://foerdermittelkompass.reflecta.org/api/v1/matching" \
  -H "Authorization: Bearer rfk_dein_token" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org-12345",
    "organization_profile": {
      "name": "Umweltinitiative Rhein-Main e.V.",
      "description": "Wir setzen uns für Umweltbildung und nachhaltige Stadtentwicklung im Rhein-Main-Gebiet ein. Unsere Projekte umfassen Urban Gardening, Workshops für Schulen und Baumpflanzaktionen.",
      "regions": ["Hessen"],
      "grant_areas": ["Energieeffizienz & Klimaschutz", "Aus- & Weiterbildung"],
      "eligible_entities": ["Gemeinnützige Organisation"],
      "is_non_profit": true
    },
    "project": {
      "title": "Grüne Klassenzimmer",
      "description": "Einrichtung von Schulgärten an 10 Frankfurter Schulen mit begleitendem Umweltbildungsprogramm für 500 Schüler:innen."
    }
  }'

Beispiel-Response

{
  "matching_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "organization_id": "org-12345",
  "results_count": 15,
  "results": [
    {
      "id": "c369cf66-264d-45a4-af01-e7906f404d89",
      "rank": 1,
      "grant_id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Hessische Umweltbildungsförderung",
      "relevance_score": 92,
      "match_category": "very_suitable",
      "match_reason": "Hohe Übereinstimmung: Umweltbildung, Schulprojekte, Region Hessen"
    },
    {
      "id": "8812987a-ceae-4a15-894c-b2dca14a3e29",
      "rank": 2,
      "grant_id": "661f9500-f30c-52e5-b827-557766551111",
      "title": "DBU Förderprogramm Umweltbildung",
      "relevance_score": 85,
      "match_category": "partially_suitable",
      "match_reason": "Passt zu Umweltbildung und gemeinnützigen Trägern"
    }
  ],
  "quota": {
    "matching_requests_used": 1523,
    "matching_requests_limit": 10000,
    "usage_percentage": 15.23
  }
}

Hinweis: Die Response enthält nur die wichtigsten Match-Informationen. Für vollständige Förderungsdetails (Fristen, Förderhöhe, Antragsweg etc.) nutze den GET /api/v1/grants/:id Endpoint.

Match-Objekt

Feld Typ Beschreibung
id UUID Eindeutige ID des Match-Ergebnisses
rank Integer Rang im Matching (1 = bester Match)
grant_id UUID ID des Förderprogramms
title String Programmtitel
relevance_score Integer Relevanz-Score (0-100)
match_category String Kategorie: very_suitable, partially_suitable, conditionally_suitable, not_suitable
match_reason String Kurze Begründung des Matchings

Relevance Score

Der relevance_score (0-100) zeigt die Übereinstimmung:

Score Bedeutung
90-100 Ausgezeichnete Übereinstimmung
70-89 Gute Übereinstimmung
50-69 Moderate Übereinstimmung
< 50 Geringe Übereinstimmung

Matches werden nach Score absteigend sortiert. Die API liefert maximal 25 Matches.

organization_id und Abrechnung

Die organization_id ist wichtig für:

  1. Tracking aktiver Organisationen: Jede eindeutige organization_id pro Quartal wird als "aktive Organisation" gezählt
  2. Kontingent-Berechnung: Dein Tier bestimmt, wie viele aktive Organisationen erlaubt sind
  3. Deduplizierung: Mehrere Matching-Anfragen derselben Organisation zählen nur als eine aktive Organisation

Wichtig: Verwende konsistente IDs für dieselbe Organisation über alle Anfragen hinweg.

Quota-Information

Jede Response enthält meta.quota mit dem aktuellen Kontingent-Status:

{
  "quota": {
    "matching_requests_used": 1523,
    "matching_requests_limit": 10000,
    "percentage": 15.23
  }
}

Bei 90% Auslastung erhältst du eine Warnung per E-Mail.

Fehler

Status Code Beschreibung
400 bad_request Pflichtfeld fehlt
401 unauthorized Authentifizierung fehlgeschlagen
403 insufficient_scope Token hat nicht matching:use Scope
429 rate_limit_exceeded Rate Limit überschritten
503 service_unavailable Matching-Service temporär nicht verfügbar

Fehler-Beispiel

{
  "error": {
    "code": "bad_request",
    "message": "organization_id is required"
  }
}

Best Practices

Qualität der Beschreibung

Je detaillierter die organization_profile.description, desto besser das Matching:

// ❌ Schlecht
{
  "description": "Verein für Kultur"
}

// ✅ Gut
{
  "description": "Gemeinnütziger Kulturverein in München mit Fokus auf zeitgenössische Kunst und Nachwuchsförderung. Wir organisieren jährlich 20 Ausstellungen und bieten Kunstworkshops für Jugendliche an. Schwerpunkte: Malerei, Skulptur, digitale Kunst."
}

Projekt-Kontext

Wenn ein konkretes Projekt gefördert werden soll, füge das project-Objekt hinzu. Dies verbessert das Matching erheblich:

{
  "project": {
    "title": "Digitale Kunstwerkstatt",
    "description": "Ausstattung eines Kreativraums mit digitalen Tools für Jugendliche. Ziel: 200 Teilnehmer:innen pro Jahr, Workshops zu Digital Art, VR-Kunst und 3D-Druck."
  }
}

Caching

Matching-Ergebnisse können clientseitig gecacht werden. Empfohlene Cache-Dauer: 24 Stunden (Förderprogramme ändern sich selten).

War diese Seite hilfreich?