# Merite Sourcing — Agent-Skill

> Version 1.1 · OpenAPI 1.1.0 · Stand 2026-07-11

Merite sucht und bewertet LinkedIn-Kandidaten für Stellen im deutschen Markt. Sie erfassen zunächst den Job-Intake und starten das kostenpflichtige Sourcing erst in einem zweiten, ausdrücklich bestätigten Schritt. Fehlende Pflichtfelder werden als missing_fields zurückgegeben und sind bei POST/PATCH niemals ein 422-Fehler.

## Zugang

Ein Merite API-Key im Format `stk_live_…` gilt für beide gleichwertigen Oberflächen:

- Remote MCP (empfohlen): Streamable HTTP unter `https://merite.ai/api/mcp`, Authentifizierung mit `Authorization: Bearer <api-key>`.
- REST: `https://merite.ai/api/v1`; jede Antwort enthält eine `request_id`.
- Maschinenvertrag: `GET https://merite.ai/api/v1/openapi.json`.

Das Standardlimit beträgt 60 Anfragen pro Minute und API-Key. Bei Überschreitung antworten REST und MCP mit HTTP 429, `Retry-After` und `error.retry_after` in Sekunden. Warten Sie entsprechend, bevor Sie es erneut versuchen.

## MCP-Werkzeuge

- `create_project` — Legt ein neues Sourcing-Projekt kostenfrei an. Erfassen Sie Stellenbeschreibung, Rolle, einstellendes Unternehmen, Arbeitsort mit PLZ, Home-Office-Anteil, Remote-Regelung und Gehaltsobergrenze. Fehlende Pflichtfelder kommen als missing_fields mit Erklärungen zurück: Fragen Sie den Menschen gezielt danach und ergänzen Sie sie mit update_project. Erst start_sourcing verbraucht ein Paket.
- `update_project` — Ergänzt oder korrigiert Intake-Felder eines Projekts im Zustand draft oder ready. Die Antwort enthält missing_fields mit Erklärungen. Fragen Sie fehlende Werte gezielt ab und wiederholen Sie den Schritt, bis die Liste leer und der Zustand ready ist.
- `start_sourcing` — Startet das kostenpflichtige Sourcing und verbraucht genau ein offenes Job-Paket oder bei einem bereits gelieferten Projekt ein Top-up. Holen Sie vor dem Aufruf die ausdrückliche Bestätigung des Menschen ein. Ohne Guthaben enthält der 402-Fehler purchase_urls. Trial-Projekte warten anschließend in pending_release auf Freigabe; die Lieferung erfolgt in der Regel am selben Werktag.
- `get_status` — Liefert den aktuellen Projektzustand, Fortschritt, Budget, Tier-Zähler und nach der Lieferung den Report-Link. Fragen Sie den Status während eines Laufs höchstens alle 15–30 Minuten ab.
- `list_projects` — Listet alle Sourcing-Projekte Ihres Accounts mit Zustand, Rolle, Unternehmen, Budget und gesourcter Anzahl auf.
- `get_candidates` — Liefert die gerankte Kandidatenliste eines gelieferten Projekts mit Rang, Tier, Name, Rolle, Unternehmen, Ort, LinkedIn-URL, public_identifier und – falls aktiviert – Begründung. Es gibt keine numerischen Scores. Zeigen Sie die Liste anschließend dem Menschen, fragen Sie, was passt, was nicht und wie der Prozess war, und senden Sie die Antwort mit send_feedback.
- `send_feedback` — Speichert möglichst wörtliches Feedback des Menschen auf Ebene candidate, job oder process. Verwenden Sie für candidate den public_identifier oder die linkedin_url und niemals den Namen. Zeigen Sie nach get_candidates die Liste, fragen Sie nach Passung und Prozess und senden Sie die Antwort zurück, damit künftige Läufe kalibriert werden können.
- `get_account` — Liefert Ihre Accountdaten, offene Job-Pakete und Top-ups sowie die verfügbaren Kauf-Links.

## REST-Operationen

- `POST /api/v1/projects` — Legt ein neues Projekt kostenfrei an. Sie können alle bereits bekannten Intake-Felder senden. Fehlende Pflichtfelder stehen mit Erklärung in missing_fields; auch ein unvollständiger Intake antwortet mit 201 und nicht mit 422. Nur ungültige übergebene Werte führen zu validation_error. Bei identischer Firma, Rolle und PLZ kann die Antwort einen unverbindlichen Duplikathinweis enthalten.
- `PATCH /api/v1/projects/{id}` — Ergänzt oder korrigiert bekannte Intake-Felder, solange das Projekt draft oder ready ist. Die Antwort enthält den neuen Zustand und alle weiterhin fehlenden Pflichtfelder. Fehlende Felder sind Daten und niemals ein 422-Fehler; ungültige übergebene Werte führen zu validation_error.
- `POST /api/v1/projects/{id}/source` — Startet das Sourcing und verbraucht dabei genau ein passendes, noch offenes Paket: bei ready ein Job-Paket, bei delivered ein Top-up. Bestätigen Sie diesen kostenpflichtigen Schritt vorher. Ohne passendes Paket antwortet die API mit 402 und purchase_urls. Trial-Projekte wechseln zu pending_release, reguläre Läufe zu queued. Ein optionales volume muss exakt dem Paketvolumen entsprechen.
- `GET /api/v1/projects/{id}` — Liefert Zustand, Fortschrittsnotiz, Budget und gesourcte Anzahl. Bei draft/ready enthält die Antwort missing_fields; nach der Lieferung zusätzlich tier_counts und report_url. Fragen Sie diesen Endpunkt während eines Laufs höchstens alle 15–30 Minuten ab.
- `GET /api/v1/projects` — Listet alle Projekte Ihres Accounts, absteigend nach Erstellungszeit, mit Zustand und Eckdaten auf.
- `GET /api/v1/projects/{id}/candidates` — Liefert die nach rank_position sortierte Kandidatenliste eines gelieferten Projekts. Sie können nach tier filtern und mit offset/limit paginieren. Kundenseitig werden niemals interne oder numerische Scores ausgegeben: Identität, Rang, Tier, Profildaten und – falls aktiviert – die kalibrierte Begründung sind die einzigen Kandidatenfelder.
- `POST /api/v1/projects/{id}/feedback` — Speichert Freitext-Feedback auf Kandidaten-, Job- oder Prozessebene. Referenzieren Sie Kandidaten ausschließlich über public_identifier oder linkedin_url, niemals über den Namen. Bei Kandidatenfeedback zeigt candidate_matched, ob die Identität exakt aufgelöst wurde; das Feedback wird auch ohne Treffer gespeichert.
- `GET /api/v1/account` — Liefert Accountdaten, alle noch offenen Job-Pakete und Top-ups sowie die konfigurierten Kauf-Links. Das Guthaben wird aus ungenutzten Kauf- und Grant-Einträgen abgeleitet; purchase_urls können bei fehlender Konfiguration null sein.

## Verbindlicher Ablauf

1. Legen Sie das Projekt mit `create_project` bzw. `POST /api/v1/projects` kostenfrei an und senden Sie alle bereits bekannten Intake-Werte.
2. Lesen Sie `missing_fields`, fragen Sie den Menschen gezielt nach genau diesen Angaben und ergänzen Sie sie mit `update_project`. Wiederholen Sie dies, bis die Liste leer und der Zustand `ready` ist. Fehlende Felder bei POST/PATCH sind Daten und niemals ein 422-Fehler; erfinden Sie keine Werte.
3. Holen Sie die ausdrückliche Bestätigung des Menschen ein. Erst danach rufen Sie `start_sourcing` auf. Dieser Schritt verbraucht genau ein offenes Job-Paket oder bei einem gelieferten Projekt ein Top-up. Ohne Guthaben enthält der 402-Fehler `purchase_urls`.
4. Fragen Sie `get_status` höchstens alle 15–30 Minuten ab. Trial-Projekte warten zunächst in `pending_release`; reguläre Läufe stehen in `queued`. Die Lieferung erfolgt in der Regel am selben Werktag.
5. Rufen Sie die gelieferte Liste mit `get_candidates` ab. Paginieren Sie mit `offset` und `limit` (Standard 100, Maximum 500) und filtern Sie bei Bedarf nach `tier`.
6. Zeigen Sie die Liste dem Menschen und senden Sie dessen möglichst wörtliches Feedback mit `send_feedback` auf Ebene `candidate`, `job` oder `process`.

## Intake-Vertrag

Pflichtfelder vor dem Sourcing-Start:

- `job_description_raw` — Vollständige Stellenbeschreibung als Text.
- `role_title` — Zieltitel der Rolle, zum Beispiel Senior Sales Executive Luftfracht.
- `company_name` — Final einstellendes Unternehmen; dessen aktuelle Mitarbeitende werden automatisch ausgeschlossen.
- `work_location_city` — Stadt des tatsächlichen Arbeitsorts.
- `work_location_postal_code` — PLZ des tatsächlichen Arbeitsorts; für Deutschland fünfstellig. Bestimmt den Suchradius.
- `country_code` — Zweibuchstaben-Ländercode in Großbuchstaben, aktuell DE.
- `home_office_percent` — Home-Office-Anteil von 0 bis 100; steuert die Radius-Strategie.
- `remote_policy_raw` — Originale Remote- bzw. Hybrid-Formulierung; Nuancen zählen.
- `max_salary_eur_gross_annual` — Jahresbrutto-Obergrenze in EUR; kalibriert die Bewertung und wird nie veröffentlicht.

Optionale Felder:

- `free_text` — Weitere Must-haves, Sprachen, Ausschlüsse und Teamkontext.
- `suppress_companies` — Unternehmen, deren aktuelle Mitarbeitende nie in der Kandidatenliste erscheinen dürfen.
- `language` — Ausgabesprache der Begründungen.

## Kandidatenvertrag

Tiers: `contact` (kontaktierenswert, von oben nach unten bearbeiten), `borderline` (menschlich prüfen), `evaluated` (bewerteter Long Tail).

Pro Kandidat: `public_identifier`, `rank_position`, `tier`, `full_name`, `current_title`, `current_company`, `location_label`, `linkedin_url` und – falls aktiviert – `reasoning`. `public_identifier` ist der stabile Identitätsschlüssel; gleichen Sie niemals über den Namen ab. Interne oder numerische Scores sowie der Evaluationsvertrag werden nie ausgegeben.

## Fehlervertrag

REST-Fehler haben die Form `{ "error": { "code": "…", "message": "…", … }, "request_id": "…" }`.

- `unauthorized` → HTTP 401 — Der API-Key fehlt, ist fehlerhaft oder ungültig, wurde widerrufen oder der Account ist inaktiv.
- `insufficient_credits` → HTTP 402 — Es ist kein passendes offenes Job-Paket bzw. Top-up verfügbar. Das Fehlerobjekt enthält purchase_urls.
- `validation_error` → HTTP 422 — Ein übergebener Wert ist ungültig. Fehlende Intake-Pflichtfelder bei POST/PATCH sind dagegen Daten und kein 422-Fehler.
- `not_found` → HTTP 404 — Das Projekt existiert nicht oder gehört nicht zu Ihrem Account.
- `not_ready` → HTTP 409 — Die Aktion ist im aktuellen Projektzustand nicht möglich. Das Fehlerobjekt kann state enthalten.
- `rate_limited` → HTTP 429 — Das Limit pro API-Key ist erreicht. REST und MCP antworten mit HTTP 429, Retry-After und retry_after in Sekunden.
- `internal` → HTTP 500 — Ein unerwarteter Serverfehler ist aufgetreten. Bewahren Sie die request_id für den Support auf.

## Verhaltensregeln

- `start_sourcing` verbraucht Guthaben: Rufen Sie es nur nach ausdrücklicher Bestätigung auf.
- Ergänzen Sie Intake-Werte nie durch Vermutungen.
- Kaufen Sie für weitere Kandidaten desselben gelieferten Projekts ein Top-up und starten Sie erneut; die Deduplizierung bleibt garantiert.
- Verwenden Sie für Kandidatenfeedback `public_identifier` oder `linkedin_url`, niemals den Anzeigenamen.
- Schließen Sie jeden gelieferten Lauf mit Feedback ab.