API-Referenz

Leads

Kontakte anlegen, suchen, pflegen und ihren Verlauf lesen

Leads auflisten und filtern

GET/v1/leads

Scope read:leadsRecht: Leads einsehenliest

Neueste zuerst. Mehrere Filter werden mit UND verknüpft. q sucht in Vorname, Nachname, E-Mail und Firma.

Query-Parameter

limitintegerab 1bis 100
Einträge pro Seite (Standard 25, höchstens 100)
cursorstringmax. 200 Zeichen
Wert aus meta.next_cursor der vorigen Seite
qstringmax. 200 Zeichen
Freitextsuche (Name, E-Mail, Firma)
emailstring (email)max. 320 Zeichen
Exakte E-Mail (Groß/Klein egal)
linkedin_urlstringmax. 500 Zeichen
LinkedIn-Profil-URL: findet dieselbe Person in jeder Schreibweise (mit oder ohne www, Länder-Subdomain, Groß/Klein, Parameter, Unterseiten, %-Kodierung) und über die Member-ID, wie die Dublettenprüfung. Andere URLs (z. B. /pub/) exakt.
list_idstring (uuid)
Nur Leads dieser Liste (GET /v1/lists)
campaign_idstring (uuid)
Nur Leads, die dieser Kampagne zugeordnet sind (Feld campaign_id)
company_idstring (uuid)
Nur Leads, die mit dieser CRM-Firma verknüpft sind
statusListe aus string
Ein oder mehrere Status, kommagetrennt
open contacted not_reached interested qualified follow_up booked won lost disqualified opt_out archived
assigned_user_idstring (uuid)
Nur Leads dieses Team-Mitglieds (GET /v1/team)
show_in_crmboolean
true: nur Leads im CRM, false: nur Leads außerhalb
created_afterstring (date-time)
Nur Leads, die ab diesem Zeitpunkt angelegt wurden
updated_afterstring (date-time)
Nur Leads, die seitdem geändert wurden (für Abgleiche)
include_archivedboolean
Archivierte Leads mitliefern (Standard: nein)

Felder der Antwort

idstring (uuid)
ID des Leads
list_idstring (uuid), kann null sein
Liste, in der der Lead steht
campaign_idstring (uuid), kann null sein
Kampagne, der der Lead zugeordnet ist (Zuordnung über /v1/campaigns/{id}/leads)
company_idstring (uuid), kann null sein
Verknüpfte CRM-Firma
salutationstring, kann null sein
Anrede: Herr, Frau, Divers oder Unbekannt
Herr Frau Divers Unbekannt
academic_titlestring, kann null seinmax. 50 Zeichen
Akademischer Titel, z. B. Dr.
first_namestring, kann null seinmax. 200 Zeichen
Vorname, in Texten der Platzhalter {{first_name}}. Beim Anlegen ohne email und linkedin_url zusammen mit last_name Pflicht
last_namestring, kann null seinmax. 200 Zeichen
Nachname, in Texten der Platzhalter {{last_name}}. Beim Anlegen ohne email und linkedin_url zusammen mit first_name Pflicht
titlestring, kann null seinmax. 300 Zeichen
Position im Unternehmen
headlinestring, kann null seinmax. 500 Zeichen
LinkedIn-Headline
emailstring (email), kann null seinmax. 320 Zeichen
E-Mail-Adresse, wird klein geschrieben gespeichert. Nutzt ein anderer Lead im Konto dieselbe Adresse (Groß/Klein egal), ist es eine Dublette: einzeln 409, in der Sammel-Anlage status duplicate
email_statusstring, kann null sein
Ergebnis der E-Mail-Prüfung
phonestring, kann null seinmax. 50 Zeichen
Wird wie in der App ins internationale Format gebracht, z. B. +49 3012 3456
companystring, kann null seinmax. 300 Zeichen
Firmenname, in Texten der Platzhalter {{company}}
websitestring, kann null seinmax. 500 Zeichen
Website der Firma, z. B. https://beispiel.de. Videos mit scrollender Website (POST /v1/leads/{id}/video) zeigen diese Seite
employeesstring, kann null seinmax. 50 Zeichen
Unternehmensgröße, z. B. 11-50
streetstring, kann null seinmax. 300 Zeichen
Straße und Hausnummer
postal_codestring, kann null seinmax. 20 Zeichen
Postleitzahl
citystring, kann null seinmax. 200 Zeichen
Ort, in Texten der Platzhalter {{city}}
countrystring, kann null seinmax. 100 Zeichen
Land, wird zu ISO-Code normalisiert (DE, AT, CH …)
linkedin_urlstring (uri), kann null seinmax. 2048 Zeichen
LinkedIn-Profil-URL
linkedin_network_distancestring, kann null sein
Kontaktgrad zum verbundenen LinkedIn-Konto
statusstring
Vertriebsstatus
open contacted not_reached interested qualified follow_up booked won lost disqualified opt_out archived
stagestring, kann null sein
Temperatur aus dem Scoring: cold, warm, hot
outreach_statusstring
Outreach-Status: Ausstehend (Standard), Brief (ein Brief ist in Produktion), Abgemeldet (bei Status opt_out), daneben Email, Linkedin, Beendet, Warten. LinkedIn-Kampagnen ändern ihn nicht, ihren Stand je Lead liefert GET /v1/campaigns/{id}/leads
Ausstehend Brief Email Linkedin Beendet Warten Abgemeldet
scoreinteger, kann null sein
Lead-Score 0 bis 100
lead_sourcestring, kann null seinmax. 100 Zeichen
Herkunft. System: lead_scout, lead_finder, csv_import, api, manual, webhook; eigene Werte aus den Einstellungen
source_detailsstring, kann null seinmax. 1000 Zeichen
Freitext zur Herkunft, z. B. Messe Köln 2026
notesstring, kann null seinmax. 10000 Zeichen
Freitext-Notiz am Lead
assigned_user_idstring (uuid), kann null sein
Zuständiges Team-Mitglied (siehe /v1/team)
show_in_crmboolean, kann null sein
Im CRM anzeigen
crm_onlyboolean, kann null sein
Markierung aus dem CRM-Modul, Standard false. Über die API nicht änderbar
is_priorityboolean, kann null sein
Als Priorität markiert. Die App sortiert solche Leads bei Wiedervorlagen und unter „Nächster Lead“ nach vorn
do_not_contactboolean, kann null sein
Gesperrt für jede Ansprache
meeting_scheduled_atstring (date-time), kann null sein
Zeitpunkt des vereinbarten Termins. Eintragen wie in der App (Art, optional Status booked) über PUT /v1/leads/{id}/meeting
meeting_typestring, kann null sein
Art des Termins: setting, closing, demo oder other
setting closing demo other
next_actionstring, kann null sein
Nächster Schritt: call, email, meeting, proposal oder wait (Zeitpunkt in next_action_at)
call email meeting proposal wait
next_action_atstring (date-time), kann null sein
Zeitpunkt für den nächsten Schritt aus next_action
landing_page_urlstring, kann null sein
URL der personalisierten Landingpage des Leads, null solange keine erzeugt wurde
personalized_video_urlstring, kann null sein
URL des personalisierten Videos, null solange keins erzeugt wurde (POST /v1/leads/{id}/video)
personalized_video_thumbnailstring, kann null sein
URL des Vorschaubilds zum personalisierten Video, null ohne Video
landingpage_url_qrcodestring, kann null sein
URL eines QR-Code-Bilds, das auf landing_page_url zeigt (z. B. für Briefe), null solange keiner erzeugt wurde
utm_sourcestring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_source der Herkunft (Quelle, z. B. newsletter)
utm_mediumstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_medium der Herkunft (Medium, z. B. email)
utm_campaignstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_campaign der Herkunft (Name der Werbekampagne)
utm_contentstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_content der Herkunft (Anzeige oder Link)
utm_termstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_term der Herkunft (Suchbegriff)
last_activity_atstring (date-time), kann null sein
Zeitpunkt der letzten Aktivität am Lead (ISO 8601, UTC), null ohne Aktivität
archived_atstring (date-time), kann null sein
Zeitpunkt der Archivierung (ISO 8601, UTC), null bei aktiven Leads. GET /v1/leads zeigt archivierte nur mit include_archived
created_atstring (date-time)
Anlagezeitpunkt (ISO 8601, UTC)
updated_atstring (date-time), kann null sein
Zeitpunkt der letzten Änderung (ISO 8601, UTC)

Mögliche Fehler

400 VALIDATION_ERROR401 INVALID_API_KEY402 PLAN_REQUIRED403 SCOPE_MISSING429 RATE_LIMITED

curl -X GET "https://api.dealsky.io/functions/v1/api/v1/leads" \
  -H "X-API-Key: $DEALSKY_API_KEY"

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/leads", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.DEALSKY_API_KEY,
  },
});
const { ok, data, error } = await res.json();

import os, requests

res = requests.request(
    "GET",
    "https://api.dealsky.io/functions/v1/api/v1/leads",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
)
print(res.json())

Antwort 200

{
  "ok": true,
  "data": [
    {
      "id": "5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10",
      "list_id": "1f4e2d3c-7b6a-4c5d-9e8f-0a1b2c3d4e5f",
      "campaign_id": null,
      "company_id": null,
      "salutation": "Herr",
      "academic_title": "Dr.",
      "first_name": "Max",
      "last_name": "Mustermann",
      "title": "Geschäftsführer",
      "headline": "Geschäftsführer bei Beispiel GmbH | Digitalisierung im Mittelstand",
      "email": "max.mustermann@beispiel.de",
      "email_status": null,
      "phone": "+49 3012 3456",
      "company": "Beispiel GmbH",
      "website": "https://beispiel.de",
      "employees": "11-50",
      "street": "Musterstraße 1",
      "postal_code": "10115",
      "city": "Berlin",
      "country": "DE",
      "linkedin_url": "https://www.linkedin.com/in/max-mustermann",
      "linkedin_network_distance": "DISTANCE_2",
      "status": "open",
      "stage": "cold",
      "outreach_status": "Ausstehend",
      "score": 15,
      "lead_source": "api",
      "source_details": "Messe Köln 2026",
      "notes": null,
      "assigned_user_id": null,
      "show_in_crm": false,
      "crm_only": false,
      "is_priority": false,
      "do_not_contact": false,
      "meeting_scheduled_at": null,
      "meeting_type": null,
      "next_action": null,
      "next_action_at": null,
      "landing_page_url": null,
      "personalized_video_url": null,
      "personalized_video_thumbnail": null,
      "landingpage_url_qrcode": null,
      "utm_source": null,
      "utm_medium": null,
      "utm_campaign": null,
      "utm_content": null,
      "utm_term": null,
      "last_activity_at": "2026-10-18T09:12:00.000Z",
      "archived_at": null,
      "created_at": "2026-10-01T08:00:00.000Z",
      "updated_at": "2026-10-18T09:12:00.000Z"
    }
  ],
  "meta": {
    "request_id": "req_7f3a…",
    "next_cursor": null,
    "has_more": false
  }
}

Lead anlegen

POST/v1/leads

Scope write:leadsRecht: Leads anlegen/bearbeitenschreibt

Legt einen Lead in einer Liste an. Dubletten (gleiche E-Mail oder dieselbe LinkedIn-Person im Konto) werden mit 409 abgelehnt; error.details.existing_id nennt den ältesten vorhandenen Lead, der sich dann per PATCH ändern lässt. Telefonnummern bekommen die Ländervorwahl (+49 …), Länder werden zu ISO-Codes.

Dieselbe LinkedIn-Person erkennt die API wie die App beim CSV-Import: am Profil-Slug aus linkedin.com/in/<slug>, egal ob mit oder ohne www, mit Länder-Subdomain (de.linkedin.com), in Groß- oder Kleinschreibung, mit Parametern (?trk=…, ?miniProfileUrn=…), Unterseiten (/details/…), Schrägstrich am Ende oder %-kodierten Umlauten. Steht im Slug die LinkedIn-ID (/in/ACoAA… oder /in/ACwAA… aus Sales-Navigator-Exporten), trifft sie auch einen Lead, der diese ID als Member-ID führt. Andere URLs (z. B. /pub/…) werden exakt verglichen. Gespeichert wird die URL so, wie sie übergeben wurde.

Body

Mindestens eines von email, linkedin_url oder Vor- und Nachname ist nötig.

list_idstring (uuid), kann null seinPflicht
Liste, in der der Lead steht
salutationstring, kann null sein
Anrede: Herr, Frau, Divers oder Unbekannt
Herr Frau Divers Unbekannt
academic_titlestring, kann null seinmax. 50 Zeichen
Akademischer Titel, z. B. Dr.
first_namestring, kann null seinmax. 200 Zeichen
Vorname, in Texten der Platzhalter {{first_name}}. Beim Anlegen ohne email und linkedin_url zusammen mit last_name Pflicht
last_namestring, kann null seinmax. 200 Zeichen
Nachname, in Texten der Platzhalter {{last_name}}. Beim Anlegen ohne email und linkedin_url zusammen mit first_name Pflicht
titlestring, kann null seinmax. 300 Zeichen
Position im Unternehmen
headlinestring, kann null seinmax. 500 Zeichen
LinkedIn-Headline
emailstring (email), kann null seinmax. 320 Zeichen
E-Mail-Adresse, wird klein geschrieben gespeichert. Nutzt ein anderer Lead im Konto dieselbe Adresse (Groß/Klein egal), ist es eine Dublette: einzeln 409, in der Sammel-Anlage status duplicate
phonestring, kann null seinmax. 50 Zeichen
Wird wie in der App ins internationale Format gebracht, z. B. +49 3012 3456
companystring, kann null seinmax. 300 Zeichen
Firmenname, in Texten der Platzhalter {{company}}
websitestring, kann null seinmax. 500 Zeichen
Website der Firma, z. B. https://beispiel.de. Videos mit scrollender Website (POST /v1/leads/{id}/video) zeigen diese Seite
employeesstring, kann null seinmax. 50 Zeichen
Unternehmensgröße, z. B. 11-50
streetstring, kann null seinmax. 300 Zeichen
Straße und Hausnummer
postal_codestring, kann null seinmax. 20 Zeichen
Postleitzahl
citystring, kann null seinmax. 200 Zeichen
Ort, in Texten der Platzhalter {{city}}
countrystring, kann null seinmax. 100 Zeichen
Land, wird zu ISO-Code normalisiert (DE, AT, CH …)
linkedin_urlstring (uri), kann null seinmax. 2048 Zeichen
LinkedIn-Profil-URL
statusstring
Standard: open
open contacted not_reached interested qualified follow_up booked won lost disqualified opt_out archived
lead_sourcestring, kann null seinmax. 100 Zeichen
Herkunft. System: lead_scout, lead_finder, csv_import, api, manual, webhook; eigene Werte aus den Einstellungen
source_detailsstring, kann null seinmax. 1000 Zeichen
Freitext zur Herkunft, z. B. Messe Köln 2026
notesstring, kann null seinmax. 10000 Zeichen
Freitext-Notiz am Lead
assigned_user_idstring (uuid), kann null sein
Zuständiges Team-Mitglied (siehe /v1/team)
show_in_crmboolean, kann null sein
Im CRM anzeigen
is_priorityboolean, kann null sein
Als Priorität markiert. Die App sortiert solche Leads bei Wiedervorlagen und unter „Nächster Lead“ nach vorn
meeting_scheduled_atstring (date-time), kann null sein
Zeitpunkt des vereinbarten Termins. Eintragen wie in der App (Art, optional Status booked) über PUT /v1/leads/{id}/meeting
meeting_typestring, kann null sein
Art des Termins: setting, closing, demo oder other
setting closing demo other
next_actionstring, kann null sein
Nächster Schritt: call, email, meeting, proposal oder wait (Zeitpunkt in next_action_at)
call email meeting proposal wait
next_action_atstring (date-time), kann null sein
Zeitpunkt für den nächsten Schritt aus next_action
utm_sourcestring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_source der Herkunft (Quelle, z. B. newsletter)
utm_mediumstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_medium der Herkunft (Medium, z. B. email)
utm_campaignstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_campaign der Herkunft (Name der Werbekampagne)
utm_contentstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_content der Herkunft (Anzeige oder Link)
utm_termstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_term der Herkunft (Suchbegriff)

Mögliche Fehler

400 VALIDATION_ERROR401 INVALID_API_KEY402 PLAN_REQUIRED403 SCOPE_MISSING409 CONFLICT429 RATE_LIMITED

curl -X POST "https://api.dealsky.io/functions/v1/api/v1/leads" \
  -H "X-API-Key: $DEALSKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "list_id": "1f4e2d3c-7b6a-4c5d-9e8f-0a1b2c3d4e5f",
  "first_name": "Max",
  "last_name": "Mustermann",
  "email": "max.mustermann@beispiel.de",
  "company": "Beispiel GmbH",
  "phone": "030 123456",
  "country": "Deutschland",
  "linkedin_url": "https://www.linkedin.com/in/max-mustermann",
  "lead_source": "api"
}'

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/leads", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.DEALSKY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "list_id": "1f4e2d3c-7b6a-4c5d-9e8f-0a1b2c3d4e5f",
    "first_name": "Max",
    "last_name": "Mustermann",
    "email": "max.mustermann@beispiel.de",
    "company": "Beispiel GmbH",
    "phone": "030 123456",
    "country": "Deutschland",
    "linkedin_url": "https://www.linkedin.com/in/max-mustermann",
    "lead_source": "api"
  }),
});
const { ok, data, error } = await res.json();

import os, requests

res = requests.request(
    "POST",
    "https://api.dealsky.io/functions/v1/api/v1/leads",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
    json={
        "list_id": "1f4e2d3c-7b6a-4c5d-9e8f-0a1b2c3d4e5f",
        "first_name": "Max",
        "last_name": "Mustermann",
        "email": "max.mustermann@beispiel.de",
        "company": "Beispiel GmbH",
        "phone": "030 123456",
        "country": "Deutschland",
        "linkedin_url": "https://www.linkedin.com/in/max-mustermann",
        "lead_source": "api"
    },
)
print(res.json())

Antwort 201

{
  "ok": true,
  "data": {
    "id": "5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10",
    "list_id": "1f4e2d3c-7b6a-4c5d-9e8f-0a1b2c3d4e5f",
    "campaign_id": null,
    "company_id": null,
    "salutation": "Herr",
    "academic_title": "Dr.",
    "first_name": "Max",
    "last_name": "Mustermann",
    "title": "Geschäftsführer",
    "headline": "Geschäftsführer bei Beispiel GmbH | Digitalisierung im Mittelstand",
    "email": "max.mustermann@beispiel.de",
    "email_status": null,
    "phone": "+49 3012 3456",
    "company": "Beispiel GmbH",
    "website": "https://beispiel.de",
    "employees": "11-50",
    "street": "Musterstraße 1",
    "postal_code": "10115",
    "city": "Berlin",
    "country": "DE",
    "linkedin_url": "https://www.linkedin.com/in/max-mustermann",
    "linkedin_network_distance": "DISTANCE_2",
    "status": "open",
    "stage": "cold",
    "outreach_status": "Ausstehend",
    "score": 15,
    "lead_source": "api",
    "source_details": "Messe Köln 2026",
    "notes": null,
    "assigned_user_id": null,
    "show_in_crm": false,
    "crm_only": false,
    "is_priority": false,
    "do_not_contact": false,
    "meeting_scheduled_at": null,
    "meeting_type": null,
    "next_action": null,
    "next_action_at": null,
    "landing_page_url": null,
    "personalized_video_url": null,
    "personalized_video_thumbnail": null,
    "landingpage_url_qrcode": null,
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_content": null,
    "utm_term": null,
    "last_activity_at": "2026-10-18T09:12:00.000Z",
    "archived_at": null,
    "created_at": "2026-10-01T08:00:00.000Z",
    "updated_at": "2026-10-18T09:12:00.000Z"
  },
  "meta": {
    "request_id": "req_7f3a…"
  }
}

Einen Lead abrufen

GET/v1/leads/{id}

Scope read:leadsRecht: Leads einsehenliest

Liefert einen Lead des eigenen Kontos mit denselben Feldern wie GET /v1/leads, auch wenn er archiviert ist (archived_at gesetzt). Eine unbekannte oder fremde ID ergibt 404. Werte der eigenen Felder liefert GET /v1/leads/{id}/custom-fields, den Verlauf GET /v1/leads/{id}/activities.

Pfad-Parameter

idstring (uuid)Pflicht
ID des Leads

Felder der Antwort

idstring (uuid)
ID des Leads
list_idstring (uuid), kann null sein
Liste, in der der Lead steht
campaign_idstring (uuid), kann null sein
Kampagne, der der Lead zugeordnet ist (Zuordnung über /v1/campaigns/{id}/leads)
company_idstring (uuid), kann null sein
Verknüpfte CRM-Firma
salutationstring, kann null sein
Anrede: Herr, Frau, Divers oder Unbekannt
Herr Frau Divers Unbekannt
academic_titlestring, kann null seinmax. 50 Zeichen
Akademischer Titel, z. B. Dr.
first_namestring, kann null seinmax. 200 Zeichen
Vorname, in Texten der Platzhalter {{first_name}}. Beim Anlegen ohne email und linkedin_url zusammen mit last_name Pflicht
last_namestring, kann null seinmax. 200 Zeichen
Nachname, in Texten der Platzhalter {{last_name}}. Beim Anlegen ohne email und linkedin_url zusammen mit first_name Pflicht
titlestring, kann null seinmax. 300 Zeichen
Position im Unternehmen
headlinestring, kann null seinmax. 500 Zeichen
LinkedIn-Headline
emailstring (email), kann null seinmax. 320 Zeichen
E-Mail-Adresse, wird klein geschrieben gespeichert. Nutzt ein anderer Lead im Konto dieselbe Adresse (Groß/Klein egal), ist es eine Dublette: einzeln 409, in der Sammel-Anlage status duplicate
email_statusstring, kann null sein
Ergebnis der E-Mail-Prüfung
phonestring, kann null seinmax. 50 Zeichen
Wird wie in der App ins internationale Format gebracht, z. B. +49 3012 3456
companystring, kann null seinmax. 300 Zeichen
Firmenname, in Texten der Platzhalter {{company}}
websitestring, kann null seinmax. 500 Zeichen
Website der Firma, z. B. https://beispiel.de. Videos mit scrollender Website (POST /v1/leads/{id}/video) zeigen diese Seite
employeesstring, kann null seinmax. 50 Zeichen
Unternehmensgröße, z. B. 11-50
streetstring, kann null seinmax. 300 Zeichen
Straße und Hausnummer
postal_codestring, kann null seinmax. 20 Zeichen
Postleitzahl
citystring, kann null seinmax. 200 Zeichen
Ort, in Texten der Platzhalter {{city}}
countrystring, kann null seinmax. 100 Zeichen
Land, wird zu ISO-Code normalisiert (DE, AT, CH …)
linkedin_urlstring (uri), kann null seinmax. 2048 Zeichen
LinkedIn-Profil-URL
linkedin_network_distancestring, kann null sein
Kontaktgrad zum verbundenen LinkedIn-Konto
statusstring
Vertriebsstatus
open contacted not_reached interested qualified follow_up booked won lost disqualified opt_out archived
stagestring, kann null sein
Temperatur aus dem Scoring: cold, warm, hot
outreach_statusstring
Outreach-Status: Ausstehend (Standard), Brief (ein Brief ist in Produktion), Abgemeldet (bei Status opt_out), daneben Email, Linkedin, Beendet, Warten. LinkedIn-Kampagnen ändern ihn nicht, ihren Stand je Lead liefert GET /v1/campaigns/{id}/leads
Ausstehend Brief Email Linkedin Beendet Warten Abgemeldet
scoreinteger, kann null sein
Lead-Score 0 bis 100
lead_sourcestring, kann null seinmax. 100 Zeichen
Herkunft. System: lead_scout, lead_finder, csv_import, api, manual, webhook; eigene Werte aus den Einstellungen
source_detailsstring, kann null seinmax. 1000 Zeichen
Freitext zur Herkunft, z. B. Messe Köln 2026
notesstring, kann null seinmax. 10000 Zeichen
Freitext-Notiz am Lead
assigned_user_idstring (uuid), kann null sein
Zuständiges Team-Mitglied (siehe /v1/team)
show_in_crmboolean, kann null sein
Im CRM anzeigen
crm_onlyboolean, kann null sein
Markierung aus dem CRM-Modul, Standard false. Über die API nicht änderbar
is_priorityboolean, kann null sein
Als Priorität markiert. Die App sortiert solche Leads bei Wiedervorlagen und unter „Nächster Lead“ nach vorn
do_not_contactboolean, kann null sein
Gesperrt für jede Ansprache
meeting_scheduled_atstring (date-time), kann null sein
Zeitpunkt des vereinbarten Termins. Eintragen wie in der App (Art, optional Status booked) über PUT /v1/leads/{id}/meeting
meeting_typestring, kann null sein
Art des Termins: setting, closing, demo oder other
setting closing demo other
next_actionstring, kann null sein
Nächster Schritt: call, email, meeting, proposal oder wait (Zeitpunkt in next_action_at)
call email meeting proposal wait
next_action_atstring (date-time), kann null sein
Zeitpunkt für den nächsten Schritt aus next_action
landing_page_urlstring, kann null sein
URL der personalisierten Landingpage des Leads, null solange keine erzeugt wurde
personalized_video_urlstring, kann null sein
URL des personalisierten Videos, null solange keins erzeugt wurde (POST /v1/leads/{id}/video)
personalized_video_thumbnailstring, kann null sein
URL des Vorschaubilds zum personalisierten Video, null ohne Video
landingpage_url_qrcodestring, kann null sein
URL eines QR-Code-Bilds, das auf landing_page_url zeigt (z. B. für Briefe), null solange keiner erzeugt wurde
utm_sourcestring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_source der Herkunft (Quelle, z. B. newsletter)
utm_mediumstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_medium der Herkunft (Medium, z. B. email)
utm_campaignstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_campaign der Herkunft (Name der Werbekampagne)
utm_contentstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_content der Herkunft (Anzeige oder Link)
utm_termstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_term der Herkunft (Suchbegriff)
last_activity_atstring (date-time), kann null sein
Zeitpunkt der letzten Aktivität am Lead (ISO 8601, UTC), null ohne Aktivität
archived_atstring (date-time), kann null sein
Zeitpunkt der Archivierung (ISO 8601, UTC), null bei aktiven Leads. GET /v1/leads zeigt archivierte nur mit include_archived
created_atstring (date-time)
Anlagezeitpunkt (ISO 8601, UTC)
updated_atstring (date-time), kann null sein
Zeitpunkt der letzten Änderung (ISO 8601, UTC)

Mögliche Fehler

400 VALIDATION_ERROR401 INVALID_API_KEY402 PLAN_REQUIRED403 SCOPE_MISSING404 NOT_FOUND429 RATE_LIMITED

curl -X GET "https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10" \
  -H "X-API-Key: $DEALSKY_API_KEY"

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.DEALSKY_API_KEY,
  },
});
const { ok, data, error } = await res.json();

import os, requests

res = requests.request(
    "GET",
    "https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
)
print(res.json())

Antwort 200

{
  "ok": true,
  "data": {
    "id": "5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10",
    "list_id": "1f4e2d3c-7b6a-4c5d-9e8f-0a1b2c3d4e5f",
    "campaign_id": null,
    "company_id": null,
    "salutation": "Herr",
    "academic_title": "Dr.",
    "first_name": "Max",
    "last_name": "Mustermann",
    "title": "Geschäftsführer",
    "headline": "Geschäftsführer bei Beispiel GmbH | Digitalisierung im Mittelstand",
    "email": "max.mustermann@beispiel.de",
    "email_status": null,
    "phone": "+49 3012 3456",
    "company": "Beispiel GmbH",
    "website": "https://beispiel.de",
    "employees": "11-50",
    "street": "Musterstraße 1",
    "postal_code": "10115",
    "city": "Berlin",
    "country": "DE",
    "linkedin_url": "https://www.linkedin.com/in/max-mustermann",
    "linkedin_network_distance": "DISTANCE_2",
    "status": "open",
    "stage": "cold",
    "outreach_status": "Ausstehend",
    "score": 15,
    "lead_source": "api",
    "source_details": "Messe Köln 2026",
    "notes": null,
    "assigned_user_id": null,
    "show_in_crm": false,
    "crm_only": false,
    "is_priority": false,
    "do_not_contact": false,
    "meeting_scheduled_at": null,
    "meeting_type": null,
    "next_action": null,
    "next_action_at": null,
    "landing_page_url": null,
    "personalized_video_url": null,
    "personalized_video_thumbnail": null,
    "landingpage_url_qrcode": null,
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_content": null,
    "utm_term": null,
    "last_activity_at": "2026-10-18T09:12:00.000Z",
    "archived_at": null,
    "created_at": "2026-10-01T08:00:00.000Z",
    "updated_at": "2026-10-18T09:12:00.000Z"
  },
  "meta": {
    "request_id": "req_7f3a…"
  }
}

Lead ändern

PATCH/v1/leads/{id}

Scope write:leadsRecht: Leads anlegen/bearbeitenschreibt

Nur übergebene Felder werden geändert. null leert ein Feld. Gesperrte Felder (score, stage, do_not_contact …) sind nur lesbar. Eine neue E-Mail oder LinkedIn-URL, die schon ein anderer Lead nutzt, ergibt 409 mit existing_id; bei LinkedIn zählt dieselbe Person in jeder Schreibweise wie bei POST /v1/leads. Eine andere Schreibweise des eigenen Profils ist kein Konflikt.

Pfad-Parameter

idstring (uuid)Pflicht
ID des Leads

Body

list_idstring (uuid), kann null sein
Liste, in der der Lead steht
salutationstring, kann null sein
Anrede: Herr, Frau, Divers oder Unbekannt
Herr Frau Divers Unbekannt
academic_titlestring, kann null seinmax. 50 Zeichen
Akademischer Titel, z. B. Dr.
first_namestring, kann null seinmax. 200 Zeichen
Vorname, in Texten der Platzhalter {{first_name}}. Beim Anlegen ohne email und linkedin_url zusammen mit last_name Pflicht
last_namestring, kann null seinmax. 200 Zeichen
Nachname, in Texten der Platzhalter {{last_name}}. Beim Anlegen ohne email und linkedin_url zusammen mit first_name Pflicht
titlestring, kann null seinmax. 300 Zeichen
Position im Unternehmen
headlinestring, kann null seinmax. 500 Zeichen
LinkedIn-Headline
emailstring (email), kann null seinmax. 320 Zeichen
E-Mail-Adresse, wird klein geschrieben gespeichert. Nutzt ein anderer Lead im Konto dieselbe Adresse (Groß/Klein egal), ist es eine Dublette: einzeln 409, in der Sammel-Anlage status duplicate
phonestring, kann null seinmax. 50 Zeichen
Wird wie in der App ins internationale Format gebracht, z. B. +49 3012 3456
companystring, kann null seinmax. 300 Zeichen
Firmenname, in Texten der Platzhalter {{company}}
websitestring, kann null seinmax. 500 Zeichen
Website der Firma, z. B. https://beispiel.de. Videos mit scrollender Website (POST /v1/leads/{id}/video) zeigen diese Seite
employeesstring, kann null seinmax. 50 Zeichen
Unternehmensgröße, z. B. 11-50
streetstring, kann null seinmax. 300 Zeichen
Straße und Hausnummer
postal_codestring, kann null seinmax. 20 Zeichen
Postleitzahl
citystring, kann null seinmax. 200 Zeichen
Ort, in Texten der Platzhalter {{city}}
countrystring, kann null seinmax. 100 Zeichen
Land, wird zu ISO-Code normalisiert (DE, AT, CH …)
linkedin_urlstring (uri), kann null seinmax. 2048 Zeichen
LinkedIn-Profil-URL
statusstring
Vertriebsstatus
open contacted not_reached interested qualified follow_up booked won lost disqualified opt_out archived
lead_sourcestring, kann null seinmax. 100 Zeichen
Herkunft. System: lead_scout, lead_finder, csv_import, api, manual, webhook; eigene Werte aus den Einstellungen
source_detailsstring, kann null seinmax. 1000 Zeichen
Freitext zur Herkunft, z. B. Messe Köln 2026
notesstring, kann null seinmax. 10000 Zeichen
Freitext-Notiz am Lead
assigned_user_idstring (uuid), kann null sein
Zuständiges Team-Mitglied (siehe /v1/team)
show_in_crmboolean, kann null sein
Im CRM anzeigen
is_priorityboolean, kann null sein
Als Priorität markiert. Die App sortiert solche Leads bei Wiedervorlagen und unter „Nächster Lead“ nach vorn
meeting_scheduled_atstring (date-time), kann null sein
Zeitpunkt des vereinbarten Termins. Eintragen wie in der App (Art, optional Status booked) über PUT /v1/leads/{id}/meeting
meeting_typestring, kann null sein
Art des Termins: setting, closing, demo oder other
setting closing demo other
next_actionstring, kann null sein
Nächster Schritt: call, email, meeting, proposal oder wait (Zeitpunkt in next_action_at)
call email meeting proposal wait
next_action_atstring (date-time), kann null sein
Zeitpunkt für den nächsten Schritt aus next_action
utm_sourcestring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_source der Herkunft (Quelle, z. B. newsletter)
utm_mediumstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_medium der Herkunft (Medium, z. B. email)
utm_campaignstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_campaign der Herkunft (Name der Werbekampagne)
utm_contentstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_content der Herkunft (Anzeige oder Link)
utm_termstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_term der Herkunft (Suchbegriff)

Felder der Antwort

idstring (uuid)
ID des Leads
list_idstring (uuid), kann null sein
Liste, in der der Lead steht
campaign_idstring (uuid), kann null sein
Kampagne, der der Lead zugeordnet ist (Zuordnung über /v1/campaigns/{id}/leads)
company_idstring (uuid), kann null sein
Verknüpfte CRM-Firma
salutationstring, kann null sein
Anrede: Herr, Frau, Divers oder Unbekannt
Herr Frau Divers Unbekannt
academic_titlestring, kann null seinmax. 50 Zeichen
Akademischer Titel, z. B. Dr.
first_namestring, kann null seinmax. 200 Zeichen
Vorname, in Texten der Platzhalter {{first_name}}. Beim Anlegen ohne email und linkedin_url zusammen mit last_name Pflicht
last_namestring, kann null seinmax. 200 Zeichen
Nachname, in Texten der Platzhalter {{last_name}}. Beim Anlegen ohne email und linkedin_url zusammen mit first_name Pflicht
titlestring, kann null seinmax. 300 Zeichen
Position im Unternehmen
headlinestring, kann null seinmax. 500 Zeichen
LinkedIn-Headline
emailstring (email), kann null seinmax. 320 Zeichen
E-Mail-Adresse, wird klein geschrieben gespeichert. Nutzt ein anderer Lead im Konto dieselbe Adresse (Groß/Klein egal), ist es eine Dublette: einzeln 409, in der Sammel-Anlage status duplicate
email_statusstring, kann null sein
Ergebnis der E-Mail-Prüfung
phonestring, kann null seinmax. 50 Zeichen
Wird wie in der App ins internationale Format gebracht, z. B. +49 3012 3456
companystring, kann null seinmax. 300 Zeichen
Firmenname, in Texten der Platzhalter {{company}}
websitestring, kann null seinmax. 500 Zeichen
Website der Firma, z. B. https://beispiel.de. Videos mit scrollender Website (POST /v1/leads/{id}/video) zeigen diese Seite
employeesstring, kann null seinmax. 50 Zeichen
Unternehmensgröße, z. B. 11-50
streetstring, kann null seinmax. 300 Zeichen
Straße und Hausnummer
postal_codestring, kann null seinmax. 20 Zeichen
Postleitzahl
citystring, kann null seinmax. 200 Zeichen
Ort, in Texten der Platzhalter {{city}}
countrystring, kann null seinmax. 100 Zeichen
Land, wird zu ISO-Code normalisiert (DE, AT, CH …)
linkedin_urlstring (uri), kann null seinmax. 2048 Zeichen
LinkedIn-Profil-URL
linkedin_network_distancestring, kann null sein
Kontaktgrad zum verbundenen LinkedIn-Konto
statusstring
Vertriebsstatus
open contacted not_reached interested qualified follow_up booked won lost disqualified opt_out archived
stagestring, kann null sein
Temperatur aus dem Scoring: cold, warm, hot
outreach_statusstring
Outreach-Status: Ausstehend (Standard), Brief (ein Brief ist in Produktion), Abgemeldet (bei Status opt_out), daneben Email, Linkedin, Beendet, Warten. LinkedIn-Kampagnen ändern ihn nicht, ihren Stand je Lead liefert GET /v1/campaigns/{id}/leads
Ausstehend Brief Email Linkedin Beendet Warten Abgemeldet
scoreinteger, kann null sein
Lead-Score 0 bis 100
lead_sourcestring, kann null seinmax. 100 Zeichen
Herkunft. System: lead_scout, lead_finder, csv_import, api, manual, webhook; eigene Werte aus den Einstellungen
source_detailsstring, kann null seinmax. 1000 Zeichen
Freitext zur Herkunft, z. B. Messe Köln 2026
notesstring, kann null seinmax. 10000 Zeichen
Freitext-Notiz am Lead
assigned_user_idstring (uuid), kann null sein
Zuständiges Team-Mitglied (siehe /v1/team)
show_in_crmboolean, kann null sein
Im CRM anzeigen
crm_onlyboolean, kann null sein
Markierung aus dem CRM-Modul, Standard false. Über die API nicht änderbar
is_priorityboolean, kann null sein
Als Priorität markiert. Die App sortiert solche Leads bei Wiedervorlagen und unter „Nächster Lead“ nach vorn
do_not_contactboolean, kann null sein
Gesperrt für jede Ansprache
meeting_scheduled_atstring (date-time), kann null sein
Zeitpunkt des vereinbarten Termins. Eintragen wie in der App (Art, optional Status booked) über PUT /v1/leads/{id}/meeting
meeting_typestring, kann null sein
Art des Termins: setting, closing, demo oder other
setting closing demo other
next_actionstring, kann null sein
Nächster Schritt: call, email, meeting, proposal oder wait (Zeitpunkt in next_action_at)
call email meeting proposal wait
next_action_atstring (date-time), kann null sein
Zeitpunkt für den nächsten Schritt aus next_action
landing_page_urlstring, kann null sein
URL der personalisierten Landingpage des Leads, null solange keine erzeugt wurde
personalized_video_urlstring, kann null sein
URL des personalisierten Videos, null solange keins erzeugt wurde (POST /v1/leads/{id}/video)
personalized_video_thumbnailstring, kann null sein
URL des Vorschaubilds zum personalisierten Video, null ohne Video
landingpage_url_qrcodestring, kann null sein
URL eines QR-Code-Bilds, das auf landing_page_url zeigt (z. B. für Briefe), null solange keiner erzeugt wurde
utm_sourcestring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_source der Herkunft (Quelle, z. B. newsletter)
utm_mediumstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_medium der Herkunft (Medium, z. B. email)
utm_campaignstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_campaign der Herkunft (Name der Werbekampagne)
utm_contentstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_content der Herkunft (Anzeige oder Link)
utm_termstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_term der Herkunft (Suchbegriff)
last_activity_atstring (date-time), kann null sein
Zeitpunkt der letzten Aktivität am Lead (ISO 8601, UTC), null ohne Aktivität
archived_atstring (date-time), kann null sein
Zeitpunkt der Archivierung (ISO 8601, UTC), null bei aktiven Leads. GET /v1/leads zeigt archivierte nur mit include_archived
created_atstring (date-time)
Anlagezeitpunkt (ISO 8601, UTC)
updated_atstring (date-time), kann null sein
Zeitpunkt der letzten Änderung (ISO 8601, UTC)

Mögliche Fehler

400 VALIDATION_ERROR401 INVALID_API_KEY402 PLAN_REQUIRED403 SCOPE_MISSING404 NOT_FOUND409 CONFLICT429 RATE_LIMITED

curl -X PATCH "https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10" \
  -H "X-API-Key: $DEALSKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "interested",
  "next_action": "proposal",
  "next_action_at": "2026-10-21T09:00:00+02:00"
}'

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10", {
  method: "PATCH",
  headers: {
    "X-API-Key": process.env.DEALSKY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "status": "interested",
    "next_action": "proposal",
    "next_action_at": "2026-10-21T09:00:00+02:00"
  }),
});
const { ok, data, error } = await res.json();

import os, requests

res = requests.request(
    "PATCH",
    "https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
    json={
        "status": "interested",
        "next_action": "proposal",
        "next_action_at": "2026-10-21T09:00:00+02:00"
    },
)
print(res.json())

Antwort 200

{
  "ok": true,
  "data": {
    "id": "5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10",
    "list_id": "1f4e2d3c-7b6a-4c5d-9e8f-0a1b2c3d4e5f",
    "campaign_id": null,
    "company_id": null,
    "salutation": "Herr",
    "academic_title": "Dr.",
    "first_name": "Max",
    "last_name": "Mustermann",
    "title": "Geschäftsführer",
    "headline": "Geschäftsführer bei Beispiel GmbH | Digitalisierung im Mittelstand",
    "email": "max.mustermann@beispiel.de",
    "email_status": null,
    "phone": "+49 3012 3456",
    "company": "Beispiel GmbH",
    "website": "https://beispiel.de",
    "employees": "11-50",
    "street": "Musterstraße 1",
    "postal_code": "10115",
    "city": "Berlin",
    "country": "DE",
    "linkedin_url": "https://www.linkedin.com/in/max-mustermann",
    "linkedin_network_distance": "DISTANCE_2",
    "status": "interested",
    "stage": "cold",
    "outreach_status": "Ausstehend",
    "score": 15,
    "lead_source": "api",
    "source_details": "Messe Köln 2026",
    "notes": null,
    "assigned_user_id": null,
    "show_in_crm": false,
    "crm_only": false,
    "is_priority": false,
    "do_not_contact": false,
    "meeting_scheduled_at": null,
    "meeting_type": null,
    "next_action": "proposal",
    "next_action_at": "2026-10-21T07:00:00.000Z",
    "landing_page_url": null,
    "personalized_video_url": null,
    "personalized_video_thumbnail": null,
    "landingpage_url_qrcode": null,
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_content": null,
    "utm_term": null,
    "last_activity_at": "2026-10-18T09:12:00.000Z",
    "archived_at": null,
    "created_at": "2026-10-01T08:00:00.000Z",
    "updated_at": "2026-10-18T09:12:00.000Z"
  },
  "meta": {
    "request_id": "req_7f3a…"
  }
}

Lead endgültig löschen

DEL/v1/leads/{id}

Scope delete:leadsRecht: Leads löschenlöscht

Löscht den Lead mit allen Daten (Aktivitäten, Landingpage, Video, CRM-Verknüpfungen), wie das Löschen in der App. Nicht umkehrbar. Braucht den Scope delete:leads.

Wirkung: Löscht endgültig. Nicht umkehrbar.

Pfad-Parameter

idstring (uuid)Pflicht
ID des Leads

Felder der Antwort

deletedboolean
Immer true, wenn der Lead gelöscht wurde
idstring (uuid)
ID des gelöschten Leads

Mögliche Fehler

400 VALIDATION_ERROR401 INVALID_API_KEY402 PLAN_REQUIRED403 SCOPE_MISSING404 NOT_FOUND429 RATE_LIMITED

curl -X DELETE "https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10" \
  -H "X-API-Key: $DEALSKY_API_KEY"

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10", {
  method: "DELETE",
  headers: {
    "X-API-Key": process.env.DEALSKY_API_KEY,
  },
});
const { ok, data, error } = await res.json();

import os, requests

res = requests.request(
    "DELETE",
    "https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
)
print(res.json())

Antwort 200

{
  "ok": true,
  "data": {
    "deleted": true,
    "id": "5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10"
  },
  "meta": {
    "request_id": "req_7f3a…"
  }
}

Bis zu 100 Leads auf einmal anlegen

POST/v1/leads/bulk

Scope write:leadsRecht: Leads anlegen/bearbeitenschreibt

Legt bis zu 100 Leads in einem Aufruf an, mit denselben Feldern und derselben Prüfung wie POST /v1/leads (Pflichtangaben, Telefon mit Ländervorwahl, Land als ISO-Code, Herkunft, Liste und Team-Mitglied des eigenen Kontos). Eine fehlerhafte Zeile hält die anderen nicht auf: results nennt für jede Zeile in Eingabe-Reihenfolge created, duplicate, invalid (mit errors) oder bei on_duplicate: "update" auch updated. Alle neuen Leads werden in einem Schritt geschrieben.

list_id oben gilt für jede Zeile ohne eigenes list_id; die Liste muss zum eigenen Konto gehören, sonst 400 und es wird nichts geschrieben.

Dubletten wie bei POST /v1/leads: gleiche E-Mail (Groß/Klein egal) oder dieselbe LinkedIn-Person im Konto (jede Schreibweise der Profil-URL, siehe dort), dazu dieselbe Angabe weiter oben in derselben Anfrage, auch in anderer Schreibweise (duplicate_of_index, die erste Zeile gewinnt). existing_id ist der älteste passende Lead.

on_duplicate: skip (Standard) überspringt vorhandene Personen, wie der CSV-Import der App, der bekannte Personen nie überschreibt. update füllt beim vorhandenen Lead nur Felder, die dort leer sind, wie das Zusammenführen von Dubletten in der App. Nichts wird überschrieben, Liste und Status bleiben. Wer gezielt überschreiben will, nutzt PATCH /v1/leads/{id} mit existing_id.

Nicht enthalten, wie bei POST /v1/leads: Der CSV-Import der App sortiert zusätzlich Kontakte auf der Ausschlussliste aus, startet danach die Anreden-Erkennung und legt bei CRM-Leads die Firma im CRM an.

Body höchstens 1 MB (für 100 Leads reicht das reichlich). Mit Test-Key kommt dieselbe Auswertung je Zeile, geschrieben wird nichts und neue Zeilen haben keine id.

Body

list_idstring (uuid)
Liste für alle Zeilen ohne eigenes list_id
on_duplicatestring
skip (Standard): vorhandene Leads bleiben unverändert. update: nur leere Felder des vorhandenen Leads füllen
skip update
leadsListe aus objectPflichtmax. 100 Einträge
1 bis 100 Leads
Felder anzeigen
- list_idstring (uuid), kann null sein
  Liste, in der der Lead steht
- salutationstring, kann null sein
  Anrede: Herr, Frau, Divers oder Unbekannt
  Herr Frau Divers Unbekannt
- academic_titlestring, kann null seinmax. 50 Zeichen
  Akademischer Titel, z. B. Dr.
- first_namestring, kann null seinmax. 200 Zeichen
  Vorname, in Texten der Platzhalter {{first_name}}. Beim Anlegen ohne email und linkedin_url zusammen mit last_name Pflicht
- last_namestring, kann null seinmax. 200 Zeichen
  Nachname, in Texten der Platzhalter {{last_name}}. Beim Anlegen ohne email und linkedin_url zusammen mit first_name Pflicht
- titlestring, kann null seinmax. 300 Zeichen
  Position im Unternehmen
- headlinestring, kann null seinmax. 500 Zeichen
  LinkedIn-Headline
- emailstring (email), kann null seinmax. 320 Zeichen
  E-Mail-Adresse, wird klein geschrieben gespeichert. Nutzt ein anderer Lead im Konto dieselbe Adresse (Groß/Klein egal), ist es eine Dublette: einzeln 409, in der Sammel-Anlage status duplicate
- phonestring, kann null seinmax. 50 Zeichen
  Wird wie in der App ins internationale Format gebracht, z. B. +49 3012 3456
- companystring, kann null seinmax. 300 Zeichen
  Firmenname, in Texten der Platzhalter {{company}}
- websitestring, kann null seinmax. 500 Zeichen
  Website der Firma, z. B. https://beispiel.de. Videos mit scrollender Website (POST /v1/leads/{id}/video) zeigen diese Seite
- employeesstring, kann null seinmax. 50 Zeichen
  Unternehmensgröße, z. B. 11-50
- streetstring, kann null seinmax. 300 Zeichen
  Straße und Hausnummer
- postal_codestring, kann null seinmax. 20 Zeichen
  Postleitzahl
- citystring, kann null seinmax. 200 Zeichen
  Ort, in Texten der Platzhalter {{city}}
- countrystring, kann null seinmax. 100 Zeichen
  Land, wird zu ISO-Code normalisiert (DE, AT, CH …)
- linkedin_urlstring (uri), kann null seinmax. 2048 Zeichen
  LinkedIn-Profil-URL
- statusstring
  Standard: open
  open contacted not_reached interested qualified follow_up booked won lost disqualified opt_out archived
- lead_sourcestring, kann null seinmax. 100 Zeichen
  Herkunft. System: lead_scout, lead_finder, csv_import, api, manual, webhook; eigene Werte aus den Einstellungen
- source_detailsstring, kann null seinmax. 1000 Zeichen
  Freitext zur Herkunft, z. B. Messe Köln 2026
- notesstring, kann null seinmax. 10000 Zeichen
  Freitext-Notiz am Lead
- assigned_user_idstring (uuid), kann null sein
  Zuständiges Team-Mitglied (siehe /v1/team)
- show_in_crmboolean, kann null sein
  Im CRM anzeigen
- is_priorityboolean, kann null sein
  Als Priorität markiert. Die App sortiert solche Leads bei Wiedervorlagen und unter „Nächster Lead“ nach vorn
- meeting_scheduled_atstring (date-time), kann null sein
  Zeitpunkt des vereinbarten Termins. Eintragen wie in der App (Art, optional Status booked) über PUT /v1/leads/{id}/meeting
- meeting_typestring, kann null sein
  Art des Termins: setting, closing, demo oder other
  setting closing demo other
- next_actionstring, kann null sein
  Nächster Schritt: call, email, meeting, proposal oder wait (Zeitpunkt in next_action_at)
  call email meeting proposal wait
- next_action_atstring (date-time), kann null sein
  Zeitpunkt für den nächsten Schritt aus next_action
- utm_sourcestring, kann null seinmax. 200 Zeichen
  UTM-Parameter utm_source der Herkunft (Quelle, z. B. newsletter)
- utm_mediumstring, kann null seinmax. 200 Zeichen
  UTM-Parameter utm_medium der Herkunft (Medium, z. B. email)
- utm_campaignstring, kann null seinmax. 200 Zeichen
  UTM-Parameter utm_campaign der Herkunft (Name der Werbekampagne)
- utm_contentstring, kann null seinmax. 200 Zeichen
  UTM-Parameter utm_content der Herkunft (Anzeige oder Link)
- utm_termstring, kann null seinmax. 200 Zeichen
  UTM-Parameter utm_term der Herkunft (Suchbegriff)

Felder der Antwort

summaryobject
Zählung der Ergebnisse je status
Felder anzeigen
- totalinteger
  Zahl der Zeilen in leads
- createdinteger
  Zeilen mit status created
- updatedinteger
  Zeilen mit status updated
- duplicateinteger
  Zeilen mit status duplicate
- invalidinteger
  Zeilen mit status invalid
resultsListe aus object
Eine Zeile je Eingabe, in derselben Reihenfolge
Felder anzeigen
- indexinteger
  Position in leads, ab 0
- statusstring
  Ergebnis der Zeile: created (neu angelegt), updated (vorhandener Lead ergänzt, nur bei on_duplicate update), duplicate (Dublette, nicht angelegt), invalid (Prüfung fehlgeschlagen)
  created updated duplicate invalid
- idstring (uuid)
  Nur bei created: ID des neuen Leads (mit Test-Key nicht gesetzt)
- existing_idstring (uuid)
  duplicate oder updated: der vorhandene Lead im Konto
- duplicate_of_indexinteger
  duplicate innerhalb dieser Anfrage: Position der ersten Zeile mit derselben Angabe
- fieldstring
  Woran die Dublette erkannt wurde
  email linkedin_url
- updated_fieldsListe aus string
  Nur bei updated: die vorher leeren Felder, die gefüllt wurden
- errorsListe aus object
  Nur bei invalid: Feld und Grund
  Felder anzeigen
  - fieldstring
    Betroffenes Feld der Zeile, (zeile) wenn die ganze Zeile scheiterte
  - messagestring
    Grund auf Deutsch

Mögliche Fehler

400 VALIDATION_ERROR401 INVALID_API_KEY402 PLAN_REQUIRED403 SCOPE_MISSING409 CONFLICT429 RATE_LIMITED

curl -X POST "https://api.dealsky.io/functions/v1/api/v1/leads/bulk" \
  -H "X-API-Key: $DEALSKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "list_id": "1f4e2d3c-7b6a-4c5d-9e8f-0a1b2c3d4e5f",
  "on_duplicate": "skip",
  "leads": [
    {
      "first_name": "Erika",
      "last_name": "Beispiel",
      "email": "erika@beispiel.de",
      "company": "Beispiel GmbH",
      "phone": "030 987654"
    },
    {
      "first_name": "Max",
      "last_name": "Mustermann",
      "email": "max.mustermann@beispiel.de"
    },
    {
      "first_name": "Erika",
      "last_name": "Beispiel",
      "email": "ERIKA@beispiel.de"
    },
    {
      "first_name": "Jonas",
      "company": "Muster AG"
    }
  ]
}'

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/leads/bulk", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.DEALSKY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "list_id": "1f4e2d3c-7b6a-4c5d-9e8f-0a1b2c3d4e5f",
    "on_duplicate": "skip",
    "leads": [
      {
        "first_name": "Erika",
        "last_name": "Beispiel",
        "email": "erika@beispiel.de",
        "company": "Beispiel GmbH",
        "phone": "030 987654"
      },
      {
        "first_name": "Max",
        "last_name": "Mustermann",
        "email": "max.mustermann@beispiel.de"
      },
      {
        "first_name": "Erika",
        "last_name": "Beispiel",
        "email": "ERIKA@beispiel.de"
      },
      {
        "first_name": "Jonas",
        "company": "Muster AG"
      }
    ]
  }),
});
const { ok, data, error } = await res.json();

import os, requests

res = requests.request(
    "POST",
    "https://api.dealsky.io/functions/v1/api/v1/leads/bulk",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
    json={
        "list_id": "1f4e2d3c-7b6a-4c5d-9e8f-0a1b2c3d4e5f",
        "on_duplicate": "skip",
        "leads": [
            {
                "first_name": "Erika",
                "last_name": "Beispiel",
                "email": "erika@beispiel.de",
                "company": "Beispiel GmbH",
                "phone": "030 987654"
            },
            {
                "first_name": "Max",
                "last_name": "Mustermann",
                "email": "max.mustermann@beispiel.de"
            },
            {
                "first_name": "Erika",
                "last_name": "Beispiel",
                "email": "ERIKA@beispiel.de"
            },
            {
                "first_name": "Jonas",
                "company": "Muster AG"
            }
        ]
    },
)
print(res.json())

Antwort 200

{
  "ok": true,
  "data": {
    "summary": {
      "total": 4,
      "created": 1,
      "updated": 0,
      "duplicate": 2,
      "invalid": 1
    },
    "results": [
      {
        "index": 0,
        "status": "created",
        "id": "7d1e2f3a-4b5c-4d6e-8f70-81a2b3c4d5e6"
      },
      {
        "index": 1,
        "status": "duplicate",
        "field": "email",
        "existing_id": "5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10"
      },
      {
        "index": 2,
        "status": "duplicate",
        "field": "email",
        "duplicate_of_index": 0
      },
      {
        "index": 3,
        "status": "invalid",
        "errors": [
          {
            "field": "email",
            "message": "oder linkedin_url oder first_name + last_name"
          }
        ]
      }
    ]
  },
  "meta": {
    "request_id": "req_7f3a…"
  }
}

Verlauf eines Leads

GET/v1/leads/{id}/activities

Scope read:leadsRecht: Leads einsehenliest

Aktivitäten wie gesendete LinkedIn-Nachrichten, Antworten, Anrufe, Notizen und Statuswechsel, neueste zuerst.

Pfad-Parameter

idstring (uuid)Pflicht
ID des Leads

Query-Parameter

limitintegerab 1bis 100
Einträge pro Seite (Standard 25, höchstens 100)
cursorstringmax. 200 Zeichen
Wert aus meta.next_cursor der vorigen Seite
channelstring
Nur Aktivitäten dieses Kanals
email linkedin phone direct_mail web landingpage
typestringmax. 100 Zeichen
Nur Aktivitäten dieser Art, exakter Wert wie im Feld type, z. B. linkedin_message_sent

Felder der Antwort

idstring (uuid)
ID der Aktivität
typestring
Art der Aktivität, z. B. linkedin_message_sent, call, note
channelstring, kann null sein
Kanal: email, linkedin, phone, direct_mail, web oder landingpage, null wenn keiner zugeordnet ist
subjectstring, kann null sein
Betreff oder Kurztitel, null wenn die Aktivität keinen hat
contentstring, kann null sein
Inhalt, z. B. Nachrichtentext oder Notiz, null wenn leer
campaign_idstring (uuid), kann null sein
Kampagne, aus der die Aktivität stammt, null ohne Kampagne
metadataobject, kann null sein
Zusatzangaben je Art als freies JSON-Objekt, Schlüssel hängen von type ab
created_atstring (date-time)
Zeitpunkt der Aktivität (ISO 8601, UTC)

Mögliche Fehler

400 VALIDATION_ERROR401 INVALID_API_KEY402 PLAN_REQUIRED403 SCOPE_MISSING404 NOT_FOUND429 RATE_LIMITED

curl -X GET "https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10/activities" \
  -H "X-API-Key: $DEALSKY_API_KEY"

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10/activities", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.DEALSKY_API_KEY,
  },
});
const { ok, data, error } = await res.json();

import os, requests

res = requests.request(
    "GET",
    "https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10/activities",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
)
print(res.json())

Antwort 200

{
  "ok": true,
  "data": [
    {
      "id": "9c7a1b2d-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
      "type": "linkedin_message_sent",
      "channel": "linkedin",
      "subject": null,
      "content": "Hallo Herr Mustermann, …",
      "campaign_id": null,
      "metadata": {},
      "created_at": "2026-10-18T09:12:00.000Z"
    }
  ],
  "meta": {
    "request_id": "req_7f3a…",
    "next_cursor": null,
    "has_more": false
  }
}

Heiße Leads

GET/v1/leads/hot

Scope read:leadsRecht: Leads einsehenliest

Leads, deren Score die Schwelle „heiß“ des Kontos erreicht, wie der Schnellfilter „Hot“ in der Leads-Tabelle und die Kachel „Heiße Leads“ im Dashboard: Score mindestens die Hot-Schwelle aus den Einstellungen (Lead-Scoring, Standard 76), ohne archivierte Leads und ohne Demo-Leads.

Höchster Score zuerst, bei gleichem Score die jüngste Aktivität zuerst. Felder wie GET /v1/leads. Die Schwellen und die Wärme eines einzelnen Leads nennt GET /v1/leads/{id}/engagement.

Query-Parameter

limitintegerab 1bis 100
Einträge pro Seite (Standard 25, höchstens 100)
cursorstringmax. 200 Zeichen
Wert aus meta.next_cursor der vorigen Seite
list_idstring (uuid)
Nur Leads dieser Liste
campaign_idstring (uuid)
Nur Leads, die dieser Kampagne zugeordnet sind (wie bei GET /v1/leads)

Felder der Antwort

idstring (uuid)
ID des Leads
list_idstring (uuid), kann null sein
Liste, in der der Lead steht
campaign_idstring (uuid), kann null sein
Kampagne, der der Lead zugeordnet ist (Zuordnung über /v1/campaigns/{id}/leads)
company_idstring (uuid), kann null sein
Verknüpfte CRM-Firma
salutationstring, kann null sein
Anrede: Herr, Frau, Divers oder Unbekannt
Herr Frau Divers Unbekannt
academic_titlestring, kann null seinmax. 50 Zeichen
Akademischer Titel, z. B. Dr.
first_namestring, kann null seinmax. 200 Zeichen
Vorname, in Texten der Platzhalter {{first_name}}. Beim Anlegen ohne email und linkedin_url zusammen mit last_name Pflicht
last_namestring, kann null seinmax. 200 Zeichen
Nachname, in Texten der Platzhalter {{last_name}}. Beim Anlegen ohne email und linkedin_url zusammen mit first_name Pflicht
titlestring, kann null seinmax. 300 Zeichen
Position im Unternehmen
headlinestring, kann null seinmax. 500 Zeichen
LinkedIn-Headline
emailstring (email), kann null seinmax. 320 Zeichen
E-Mail-Adresse, wird klein geschrieben gespeichert. Nutzt ein anderer Lead im Konto dieselbe Adresse (Groß/Klein egal), ist es eine Dublette: einzeln 409, in der Sammel-Anlage status duplicate
email_statusstring, kann null sein
Ergebnis der E-Mail-Prüfung
phonestring, kann null seinmax. 50 Zeichen
Wird wie in der App ins internationale Format gebracht, z. B. +49 3012 3456
companystring, kann null seinmax. 300 Zeichen
Firmenname, in Texten der Platzhalter {{company}}
websitestring, kann null seinmax. 500 Zeichen
Website der Firma, z. B. https://beispiel.de. Videos mit scrollender Website (POST /v1/leads/{id}/video) zeigen diese Seite
employeesstring, kann null seinmax. 50 Zeichen
Unternehmensgröße, z. B. 11-50
streetstring, kann null seinmax. 300 Zeichen
Straße und Hausnummer
postal_codestring, kann null seinmax. 20 Zeichen
Postleitzahl
citystring, kann null seinmax. 200 Zeichen
Ort, in Texten der Platzhalter {{city}}
countrystring, kann null seinmax. 100 Zeichen
Land, wird zu ISO-Code normalisiert (DE, AT, CH …)
linkedin_urlstring (uri), kann null seinmax. 2048 Zeichen
LinkedIn-Profil-URL
linkedin_network_distancestring, kann null sein
Kontaktgrad zum verbundenen LinkedIn-Konto
statusstring
Vertriebsstatus
open contacted not_reached interested qualified follow_up booked won lost disqualified opt_out archived
stagestring, kann null sein
Temperatur aus dem Scoring: cold, warm, hot
outreach_statusstring
Outreach-Status: Ausstehend (Standard), Brief (ein Brief ist in Produktion), Abgemeldet (bei Status opt_out), daneben Email, Linkedin, Beendet, Warten. LinkedIn-Kampagnen ändern ihn nicht, ihren Stand je Lead liefert GET /v1/campaigns/{id}/leads
Ausstehend Brief Email Linkedin Beendet Warten Abgemeldet
scoreinteger, kann null sein
Lead-Score 0 bis 100
lead_sourcestring, kann null seinmax. 100 Zeichen
Herkunft. System: lead_scout, lead_finder, csv_import, api, manual, webhook; eigene Werte aus den Einstellungen
source_detailsstring, kann null seinmax. 1000 Zeichen
Freitext zur Herkunft, z. B. Messe Köln 2026
notesstring, kann null seinmax. 10000 Zeichen
Freitext-Notiz am Lead
assigned_user_idstring (uuid), kann null sein
Zuständiges Team-Mitglied (siehe /v1/team)
show_in_crmboolean, kann null sein
Im CRM anzeigen
crm_onlyboolean, kann null sein
Markierung aus dem CRM-Modul, Standard false. Über die API nicht änderbar
is_priorityboolean, kann null sein
Als Priorität markiert. Die App sortiert solche Leads bei Wiedervorlagen und unter „Nächster Lead“ nach vorn
do_not_contactboolean, kann null sein
Gesperrt für jede Ansprache
meeting_scheduled_atstring (date-time), kann null sein
Zeitpunkt des vereinbarten Termins. Eintragen wie in der App (Art, optional Status booked) über PUT /v1/leads/{id}/meeting
meeting_typestring, kann null sein
Art des Termins: setting, closing, demo oder other
setting closing demo other
next_actionstring, kann null sein
Nächster Schritt: call, email, meeting, proposal oder wait (Zeitpunkt in next_action_at)
call email meeting proposal wait
next_action_atstring (date-time), kann null sein
Zeitpunkt für den nächsten Schritt aus next_action
landing_page_urlstring, kann null sein
URL der personalisierten Landingpage des Leads, null solange keine erzeugt wurde
personalized_video_urlstring, kann null sein
URL des personalisierten Videos, null solange keins erzeugt wurde (POST /v1/leads/{id}/video)
personalized_video_thumbnailstring, kann null sein
URL des Vorschaubilds zum personalisierten Video, null ohne Video
landingpage_url_qrcodestring, kann null sein
URL eines QR-Code-Bilds, das auf landing_page_url zeigt (z. B. für Briefe), null solange keiner erzeugt wurde
utm_sourcestring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_source der Herkunft (Quelle, z. B. newsletter)
utm_mediumstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_medium der Herkunft (Medium, z. B. email)
utm_campaignstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_campaign der Herkunft (Name der Werbekampagne)
utm_contentstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_content der Herkunft (Anzeige oder Link)
utm_termstring, kann null seinmax. 200 Zeichen
UTM-Parameter utm_term der Herkunft (Suchbegriff)
last_activity_atstring (date-time), kann null sein
Zeitpunkt der letzten Aktivität am Lead (ISO 8601, UTC), null ohne Aktivität
archived_atstring (date-time), kann null sein
Zeitpunkt der Archivierung (ISO 8601, UTC), null bei aktiven Leads. GET /v1/leads zeigt archivierte nur mit include_archived
created_atstring (date-time)
Anlagezeitpunkt (ISO 8601, UTC)
updated_atstring (date-time), kann null sein
Zeitpunkt der letzten Änderung (ISO 8601, UTC)

Mögliche Fehler

400 VALIDATION_ERROR401 INVALID_API_KEY402 PLAN_REQUIRED403 SCOPE_MISSING429 RATE_LIMITED

curl -X GET "https://api.dealsky.io/functions/v1/api/v1/leads/hot" \
  -H "X-API-Key: $DEALSKY_API_KEY"

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/leads/hot", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.DEALSKY_API_KEY,
  },
});
const { ok, data, error } = await res.json();

import os, requests

res = requests.request(
    "GET",
    "https://api.dealsky.io/functions/v1/api/v1/leads/hot",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
)
print(res.json())

Antwort 200

{
  "ok": true,
  "data": [
    {
      "id": "5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10",
      "list_id": "1f4e2d3c-7b6a-4c5d-9e8f-0a1b2c3d4e5f",
      "campaign_id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "company_id": null,
      "salutation": "Herr",
      "academic_title": null,
      "first_name": "Max",
      "last_name": "Mustermann",
      "title": "Geschäftsführer",
      "headline": "Geschäftsführer bei Beispiel GmbH",
      "email": "max.mustermann@beispiel.de",
      "email_status": null,
      "phone": "+49 3012 3456",
      "company": "Beispiel GmbH",
      "website": "https://beispiel.de",
      "employees": "11-50",
      "street": null,
      "postal_code": "10115",
      "city": "Berlin",
      "country": "DE",
      "linkedin_url": "https://www.linkedin.com/in/max-mustermann",
      "linkedin_network_distance": "DISTANCE_1",
      "status": "interested",
      "stage": "hot",
      "outreach_status": "Ausstehend",
      "score": 82,
      "lead_source": "api",
      "source_details": null,
      "notes": null,
      "assigned_user_id": null,
      "show_in_crm": false,
      "crm_only": false,
      "is_priority": false,
      "do_not_contact": false,
      "meeting_scheduled_at": null,
      "meeting_type": null,
      "next_action": null,
      "next_action_at": null,
      "landing_page_url": "https://beispiel.dealsky.app/max-mustermann",
      "personalized_video_url": null,
      "personalized_video_thumbnail": null,
      "landingpage_url_qrcode": null,
      "utm_source": null,
      "utm_medium": null,
      "utm_campaign": null,
      "utm_content": null,
      "utm_term": null,
      "last_activity_at": "2026-10-17T19:06:10.000Z",
      "archived_at": null,
      "created_at": "2026-10-01T08:00:00.000Z",
      "updated_at": "2026-10-17T19:06:10.000Z"
    }
  ],
  "meta": {
    "request_id": "req_7f3a…",
    "next_cursor": null,
    "has_more": false
  }
}

Ereignisse eines Leads

GET/v1/leads/{id}/events

Scope read:leadsRecht: Leads einsehenliest

Was der Lead selbst getan hat oder was mit ihm passiert ist, neueste zuerst: Landingpage besucht (pageview), Video gestartet und angesehen, Buttons geklickt, Buchungsseite geöffnet, Termin bestätigt, Briefe übermittelt und versendet. Das sind die Ereignisse, die die App im Reiter „Journey“ neben dem Verlauf zeigt; den Verlauf (Nachrichten, Anrufe, Notizen) liefert GET /v1/leads/{id}/activities, beides gemischt GET /v1/leads/{id}/journey.

Seitenaufrufe erkannter Bots und Link-Vorschauen werden nicht gespeichert. Ist das Tracking in den Einstellungen aus, entstehen keine Landingpage-Ereignisse.

Filter: type und channel (je kommagetrennt), from (einschließlich) und to (ausschließlich) als Zeitpunkt.

Pfad-Parameter

idstring (uuid)Pflicht
ID des Leads

Query-Parameter

limitintegerab 1bis 100
Einträge pro Seite (Standard 25, höchstens 100)
cursorstringmax. 200 Zeichen
Wert aus meta.next_cursor der vorigen Seite
typeListe aus string
Eine oder mehrere Arten, kommagetrennt, z. B. pageview,booking_confirmed
pageview video_start video_progress video_25 video_50 video_75 video_90 video_100 cta_clicked middle_cta_clicked final_cta_clicked final_website_clicked booking_page_opened booking_confirmed explainer_start explainer_progress explainer_cta_clicked sent delivered opened clicked replied bounced unsubscribed connection_sent connection_accepted message_sent message_replied inmail_sent inmail_replied follow like profile_view linkedin_message_sent linkedin_reply_received linkedin_unknown campaign_completed tag_added tag_removed letter_planned letter_production letter_sent
channelListe aus string
Ein oder mehrere Kanäle, kommagetrennt
email linkedin phone letter video landingpage
fromstring (date-time)
Nur Ereignisse ab diesem Zeitpunkt
tostring (date-time)
Nur Ereignisse vor diesem Zeitpunkt

Felder der Antwort

idstring (uuid)
ID des Ereignisses
typestring
Art des Ereignisses, z. B. pageview (Landingpage besucht), video_progress, cta_clicked, booking_confirmed, letter_sent
pageview video_start video_progress video_25 video_50 video_75 video_90 video_100 cta_clicked middle_cta_clicked final_cta_clicked final_website_clicked booking_page_opened booking_confirmed explainer_start explainer_progress explainer_cta_clicked sent delivered opened clicked replied bounced unsubscribed connection_sent connection_accepted message_sent message_replied inmail_sent inmail_replied follow like profile_view linkedin_message_sent linkedin_reply_received linkedin_unknown campaign_completed tag_added tag_removed letter_planned letter_production letter_sent
channelstring, kann null sein
Kanal: landingpage, linkedin, letter, email, phone, video
email linkedin phone letter video landingpage
occurred_atstring (date-time)
Zeitpunkt des Ereignisses
campaign_idstring (uuid), kann null sein
Kampagne, falls bekannt
subjectstring, kann null sein
Kurztext zum Ereignis, falls vorhanden (in der App Spalte „Details“)
score_deltanumber, kann null sein
Punkte, die das Ereignis dem Lead-Score gegeben hat (in der Journey als +N)
video_progress_percentinteger, kann null sein
Nur bei video_progress und explainer_progress: wie weit das Video angesehen wurde (25, 50, 75 oder 100)
letter_pdf_urlstring, kann null sein
Nur bei Brief-Ereignissen: Link zum PDF des Briefs

Mögliche Fehler

400 VALIDATION_ERROR401 INVALID_API_KEY402 PLAN_REQUIRED403 SCOPE_MISSING404 NOT_FOUND429 RATE_LIMITED

curl -X GET "https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10/events" \
  -H "X-API-Key: $DEALSKY_API_KEY"

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10/events", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.DEALSKY_API_KEY,
  },
});
const { ok, data, error } = await res.json();

import os, requests

res = requests.request(
    "GET",
    "https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10/events",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
)
print(res.json())

Antwort 200

{
  "ok": true,
  "data": [
    {
      "id": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a4b",
      "type": "booking_confirmed",
      "channel": "landingpage",
      "occurred_at": "2026-10-17T19:06:10.000Z",
      "campaign_id": null,
      "subject": null,
      "score_delta": 50,
      "video_progress_percent": null,
      "letter_pdf_url": null
    },
    {
      "id": "1f2a3b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
      "type": "video_progress",
      "channel": "landingpage",
      "occurred_at": "2026-10-17T19:04:55.000Z",
      "campaign_id": null,
      "subject": null,
      "score_delta": 18,
      "video_progress_percent": 75,
      "letter_pdf_url": null
    },
    {
      "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
      "type": "pageview",
      "channel": "landingpage",
      "occurred_at": "2026-10-17T19:02:31.000Z",
      "campaign_id": null,
      "subject": null,
      "score_delta": 8,
      "video_progress_percent": null,
      "letter_pdf_url": null
    }
  ],
  "meta": {
    "request_id": "req_7f3a…",
    "next_cursor": null,
    "has_more": false
  }
}

Engagement eines Leads

GET/v1/leads/{id}/engagement

Scope read:leadsRecht: Leads einsehenliest

Zusammenfassung wie im Lead-Panel: Score und Wärme (heiß, warm, kalt nach den Schwellen des Kontos, wie in der Leads-Tabelle), letzte Aktivität, Landingpage-Besuche, Video, Klicks, Buchungen und der LinkedIn-Stand (laufende Kampagne, Vernetzung, Antwort).

Alle Zahlen sind exakt gezählt, auch bei mehr als 1000 Ereignissen. Gezählt werden alle Ereignisse des Leads, auch von früheren Landingpages.

Der LinkedIn-Stand berücksichtigt nur Kampagnen auf LinkedIn-Konten, die die Person hinter dem Key in der App sehen darf.

Pfad-Parameter

idstring (uuid)Pflicht
ID des Leads

Felder der Antwort

lead_idstring (uuid)
ID des Leads
scorenumber, kann null sein
Lead-Score 0 bis 100
warmthstring
Wärme wie in der Leads-Tabelle: hot ab thresholds.hot, warm ab thresholds.warm, sonst cold (ohne Score: cold)
hot warm cold
thresholdsobject
Score-Grenzen für warmth aus den Einstellungen des Kontos
Felder anzeigen
- hotnumber
  Ab diesem Score heiß (Einstellungen, Lead-Scoring; Standard 76)
- warmnumber
  Ab diesem Score warm (Standard 40)
last_activity_atstring (date-time), kann null sein
Letzte Aktivität laut Lead (Spalte „Letzte Aktivität“)
last_event_atstring (date-time), kann null sein
Jüngstes Ereignis (Landingpage, Video, Brief …)
landing_pageobject
Zählung der Landingpage-Ereignisse des Leads
Felder anzeigen
- visitsinteger
  Seitenaufrufe (in der App „Besucht (Nx)“)
- first_visit_atstring (date-time), kann null sein
  Erster Seitenaufruf (Ereignis pageview), null ohne Besuch
- last_visit_atstring (date-time), kann null sein
  Letzter Seitenaufruf (Ereignis pageview), null ohne Besuch
- cta_clicksinteger
  Klicks auf die Buttons der Seite (Kopf, Mitte, Ende, Erklärvideo)
- booking_page_opensinteger
  Buchungsseite geöffnet
- bookingsinteger
  Termine über die Seite bestätigt
videoobject
Stand des personalisierten Hauptvideos aus den Ereignissen video_start und video_progress
Felder anzeigen
- startsinteger
  Hauptvideo gestartet
- max_progress_percentinteger, kann null sein
  Höchster gemeldeter Fortschritt des Hauptvideos (25, 50, 75, 100), null ohne Meldung
- completedboolean
  Video bis zum Ende angesehen (Fortschritt 100)
meeting_scheduled_atstring (date-time), kann null sein
Gesetzter Termin am Lead
linkedinobject
Nur Sequenzen auf LinkedIn-Konten, die der Key-Ersteller sehen darf
Felder anzeigen
- active_campaignobject, kann null sein
  Kampagne, in der der Lead gerade läuft (im Lead-Panel „LinkedIn Kampagne“), sonst null
  Felder anzeigen
  - campaign_idstring (uuid), kann null sein
    ID der laufenden Kampagne
  - campaign_namestring, kann null sein
    null, wenn die Kampagne für den Key-Ersteller nicht sichtbar ist
  - sequence_statusstring
    pending, active, in_progress oder waiting_for_connection
- connection_statusstring, kann null sein
  Vernetzung laut jüngster Sequenz: unknown, not_connected, pending, connected, withdrawn
- connected_atstring (date-time), kann null sein
  Zeitpunkt der Vernetzung laut jüngster Sequenz, null wenn nicht vernetzt
- repliedboolean
  Hat in einer LinkedIn-Kampagne geantwortet
- replied_atstring (date-time), kann null sein
  Zeitpunkt der Antwort (bei mehreren Kampagnen die jüngste)

Mögliche Fehler

400 VALIDATION_ERROR401 INVALID_API_KEY402 PLAN_REQUIRED403 SCOPE_MISSING404 NOT_FOUND429 RATE_LIMITED

curl -X GET "https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10/engagement" \
  -H "X-API-Key: $DEALSKY_API_KEY"

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10/engagement", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.DEALSKY_API_KEY,
  },
});
const { ok, data, error } = await res.json();

import os, requests

res = requests.request(
    "GET",
    "https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10/engagement",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
)
print(res.json())

Antwort 200

{
  "ok": true,
  "data": {
    "lead_id": "5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10",
    "score": 82,
    "warmth": "hot",
    "thresholds": {
      "hot": 76,
      "warm": 40
    },
    "last_activity_at": "2026-10-17T19:06:10.000Z",
    "last_event_at": "2026-10-17T19:06:10.000Z",
    "landing_page": {
      "visits": 4,
      "first_visit_at": "2026-10-15T08:31:12.000Z",
      "last_visit_at": "2026-10-17T19:02:31.000Z",
      "cta_clicks": 1,
      "booking_page_opens": 1,
      "bookings": 1
    },
    "video": {
      "starts": 2,
      "max_progress_percent": 75,
      "completed": false
    },
    "meeting_scheduled_at": "2026-10-21T08:00:00.000Z",
    "linkedin": {
      "active_campaign": {
        "campaign_id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
        "campaign_name": "Geschäftsführer DACH Q4",
        "sequence_status": "active"
      },
      "connection_status": "connected",
      "connected_at": "2026-10-14T10:12:00.000Z",
      "replied": false,
      "replied_at": null
    }
  },
  "meta": {
    "request_id": "req_7f3a…"
  }
}

Zeitleiste eines Leads

GET/v1/leads/{id}/journey

Scope read:leadsRecht: Leads einsehenliest

Alles zu einem Lead in einer Liste, wie der Reiter „Journey“ im Lead-Panel: Verlauf (Nachrichten, Anrufe, Notizen, Kampagnen-Schritte, source: activity), Ereignisse (Landingpage, Video, Briefe, source: event) und als ältester Eintrag „Lead angelegt“ (source: lead).

Neueste zuerst. Bei gleichem Zeitpunkt in derselben Reihenfolge wie die App: Aufnahme in die Kampagne, Aufnahme in die Sequenz, Sequenz gestoppt (Antwort, Termin, manuell), dann alles andere; Verlauf vor Ereignissen.

Seitenweise über meta.next_cursor. Der Cursor merkt sich die Stelle des letzten Eintrags, darum gibt es beim Blättern keine Doppelten und keine Lücken.

Pfad-Parameter

idstring (uuid)Pflicht
ID des Leads

Query-Parameter

limitintegerab 1bis 100
Einträge pro Seite (Standard 25, höchstens 100)
cursorstringmax. 200 Zeichen
Wert aus meta.next_cursor der vorigen Seite

Felder der Antwort

idstring (uuid)
ID der Aktivität bzw. des Ereignisses; beim Eintrag lead_created die ID des Leads
sourcestring
activity (Verlauf, wie GET /v1/leads/{id}/activities), event (wie GET /v1/leads/{id}/events) oder lead (Lead angelegt)
activity event lead
typestring
Art, z. B. linkedin_message_sent, note, call_completed, pageview, booking_confirmed, lead_created
channelstring, kann null sein
Kanal, z. B. linkedin, email, phone, landingpage, letter, video; null wenn keiner zugeordnet ist (immer bei lead_created)
occurred_atstring (date-time)
Zeitpunkt des Eintrags (ISO 8601, UTC); bei Aktivitäten deren created_at, bei Ereignissen der Ereigniszeitpunkt
campaign_idstring (uuid), kann null sein
Kampagne, aus der der Eintrag stammt, null ohne Kampagne
subjectstring, kann null sein
Betreff der Aktivität bzw. Kurztext des Ereignisses, null wenn keiner vorhanden ist
contentstring, kann null sein
Nur bei Aktivitäten: Text, z. B. einer Notiz oder Nachricht
metadataobject, kann null sein
Nur bei Aktivitäten: Zusatzangaben wie bei GET /v1/leads/{id}/activities
score_deltanumber, kann null sein
Nur bei Ereignissen: Punkte für den Lead-Score
video_progress_percentinteger, kann null sein
Nur bei Video-Ereignissen mit Fortschritt
letter_pdf_urlstring, kann null sein
Nur bei Brief-Ereignissen: Link zum PDF

Mögliche Fehler

400 VALIDATION_ERROR401 INVALID_API_KEY402 PLAN_REQUIRED403 SCOPE_MISSING404 NOT_FOUND429 RATE_LIMITED

curl -X GET "https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10/journey" \
  -H "X-API-Key: $DEALSKY_API_KEY"

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10/journey", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.DEALSKY_API_KEY,
  },
});
const { ok, data, error } = await res.json();

import os, requests

res = requests.request(
    "GET",
    "https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10/journey",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
)
print(res.json())

Antwort 200

{
  "ok": true,
  "data": [
    {
      "id": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a4b",
      "source": "event",
      "type": "booking_confirmed",
      "channel": "landingpage",
      "occurred_at": "2026-10-17T19:06:10.000Z",
      "campaign_id": null,
      "subject": null,
      "content": null,
      "metadata": null,
      "score_delta": 50,
      "video_progress_percent": null,
      "letter_pdf_url": null
    },
    {
      "id": "9c7a1b2d-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
      "source": "activity",
      "type": "linkedin_message_sent",
      "channel": "linkedin",
      "occurred_at": "2026-10-16T09:12:00.000Z",
      "campaign_id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "subject": null,
      "content": "Hallo Herr Mustermann, danke fürs Vernetzen …",
      "metadata": {},
      "score_delta": null,
      "video_progress_percent": null,
      "letter_pdf_url": null
    },
    {
      "id": "8b6a0c1d-3e4f-4a5b-9c8d-7e6f5a4b3c2d",
      "source": "activity",
      "type": "campaign_enrolled",
      "channel": "linkedin",
      "occurred_at": "2026-10-14T08:00:00.000Z",
      "campaign_id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "subject": null,
      "content": "In Kampagne aufgenommen",
      "metadata": {},
      "score_delta": null,
      "video_progress_percent": null,
      "letter_pdf_url": null
    },
    {
      "id": "5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10",
      "source": "lead",
      "type": "lead_created",
      "channel": null,
      "occurred_at": "2026-10-01T08:00:00.000Z",
      "campaign_id": null,
      "subject": null,
      "content": null,
      "metadata": null,
      "score_delta": null,
      "video_progress_percent": null,
      "letter_pdf_url": null
    }
  ],
  "meta": {
    "request_id": "req_7f3a…",
    "next_cursor": null,
    "has_more": false
  }
}

Eigene Felder (Custom Fields) auflisten

GET/v1/custom-fields

Scope read:leadsRecht: Leads einsehenliest

Die Felder, die das Konto unter Einstellungen → Felder für Leads angelegt hat, in der Reihenfolge der App (Gruppe, dann Feld). Standardmäßig nur aktive Felder, wie die App sie im Lead-Panel zeigt; include_inactive=true liefert auch deaktivierte. Anlegen und Ändern von Feldern geht nur in der App (dort der Leitung vorbehalten).

Query-Parameter

limitintegerab 1bis 100
Einträge pro Seite (Standard 25, höchstens 100)
cursorstringmax. 200 Zeichen
Wert aus meta.next_cursor der vorigen Seite
include_inactiveboolean
Auch deaktivierte Felder liefern (Standard: nein)

Felder der Antwort

idstring (uuid)
ID der Felddefinition
field_keystring
Schlüssel des Felds, so wird es in /v1/leads/{id}/custom-fields angesprochen
field_namestring
Anzeigename in der App
field_typestring
Typ, bestimmt das erlaubte Format des Werts (siehe PUT /v1/leads/{id}/custom-fields)
text textarea number decimal currency date select multiselect checkbox user url email phone
field_optionsListe aus string
Erlaubte Werte bei select und multiselect, sonst leer
is_requiredboolean
In der App als Pflichtfeld markiert (Stern). Die App erzwingt es beim Speichern nicht, die API auch nicht.
category_namestring
Gruppe, unter der das Feld in der App steht
default_valuestring, kann null sein
Gespeicherter Standardwert der Definition. Die App legt Felder mit null an und setzt ihn nicht in Leads ein; meist null
is_activeboolean
Nur aktive Felder zeigt die App an, nur sie lassen sich setzen
display_statusesListe aus string
Die App zeigt das Feld im Lead-Panel nur bei Leads mit diesen Status; leer = immer. Lesen und Setzen per API gehen unabhängig davon.
created_atstring (date-time), kann null sein
Angelegt am
updated_atstring (date-time), kann null sein
Zuletzt geändert am

Mögliche Fehler

400 VALIDATION_ERROR401 INVALID_API_KEY402 PLAN_REQUIRED403 SCOPE_MISSING429 RATE_LIMITED

curl -X GET "https://api.dealsky.io/functions/v1/api/v1/custom-fields" \
  -H "X-API-Key: $DEALSKY_API_KEY"

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/custom-fields", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.DEALSKY_API_KEY,
  },
});
const { ok, data, error } = await res.json();

import os, requests

res = requests.request(
    "GET",
    "https://api.dealsky.io/functions/v1/api/v1/custom-fields",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
)
print(res.json())

Antwort 200

{
  "ok": true,
  "data": [
    {
      "id": "2b3c4d5e-6f70-4a81-9b2c-3d4e5f6a7b8c",
      "field_key": "budget",
      "field_name": "Budget",
      "field_type": "currency",
      "field_options": [],
      "is_required": false,
      "category_name": "Qualifizierung",
      "default_value": null,
      "is_active": true,
      "display_statuses": [],
      "created_at": "2026-09-01T08:00:00.000Z",
      "updated_at": "2026-09-01T08:00:00.000Z"
    },
    {
      "id": "3c4d5e6f-7081-4b92-8c3d-4e5f6a7b8c9d",
      "field_key": "interesse",
      "field_name": "Interesse an",
      "field_type": "multiselect",
      "field_options": [
        "Video",
        "Landingpage",
        "Brief"
      ],
      "is_required": false,
      "category_name": "Qualifizierung",
      "default_value": null,
      "is_active": true,
      "display_statuses": [],
      "created_at": "2026-09-01T08:00:00.000Z",
      "updated_at": "2026-09-01T08:00:00.000Z"
    }
  ],
  "meta": {
    "request_id": "req_7f3a…",
    "next_cursor": null,
    "has_more": false
  }
}

Werte der eigenen Felder eines Leads

GET/v1/leads/{id}/custom-fields

Scope read:leadsRecht: Leads einsehenliest

Ein Objekt mit dem Schlüssel jedes aktiven Felds und dem Wert beim Lead, null = kein Wert. Werte kommen als Text, so wie die App sie speichert, Mehrfachauswahl als Liste. Formate je Typ stehen bei PUT /v1/leads/{id}/custom-fields. Werte deaktivierter Felder zeigt die App nicht, die API auch nicht.

Pfad-Parameter

idstring (uuid)Pflicht
ID des Leads

Mögliche Fehler

400 VALIDATION_ERROR401 INVALID_API_KEY402 PLAN_REQUIRED403 SCOPE_MISSING404 NOT_FOUND429 RATE_LIMITED

curl -X GET "https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10/custom-fields" \
  -H "X-API-Key: $DEALSKY_API_KEY"

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10/custom-fields", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.DEALSKY_API_KEY,
  },
});
const { ok, data, error } = await res.json();

import os, requests

res = requests.request(
    "GET",
    "https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10/custom-fields",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
)
print(res.json())

Antwort 200

{
  "ok": true,
  "data": {
    "budget": "15000",
    "entscheider": "true",
    "interesse": [
      "Video",
      "Landingpage"
    ],
    "naechster_termin": "2026-11-03",
    "zustaendig": "8e7d6c5b-4a39-4281-9f0e-1d2c3b4a5f60",
    "bemerkung": null
  },
  "meta": {
    "request_id": "req_7f3a…"
  }
}

Werte der eigenen Felder eines Leads setzen

PUT/v1/leads/{id}/custom-fields

Scope write:leadsRecht: Leads anlegen/bearbeitenschreibt

Setzt die übergebenen Felder, alle anderen bleiben unverändert. null, leerer Text oder eine leere Liste leeren ein Feld. Schlüssel aus GET /v1/custom-fields; unbekannte oder deaktivierte Felder und Werte im falschen Format ergeben 400 mit allen Fehlern in error.details, dann wird nichts geschrieben. Die Antwort ist der Stand danach wie bei GET.

Gespeichert wird wie im Lead-Panel der App: ein Wert je Lead und Feld, als Text. Kein Eintrag im Verlauf, keine weitere Wirkung. Pflichtfelder erzwingt die App beim Speichern nicht, die API auch nicht. Ob die App ein Feld nur bei bestimmten Status zeigt (display_statuses), spielt fürs Setzen keine Rolle.

| Typ | Wert beim Setzen | gespeichert und gelesen als |
|---|---|---|
| text, textarea | Text, höchstens 10.000 Zeichen | Text |
| number | ganze Zahl, z. B. 42 oder "42" | "42" |
| decimal | Zahl, Punkt als Trenner, z. B. 12.5 | "12.5" |
| currency | Betrag in Euro, höchstens zwei Nachkommastellen, z. B. 1500.5 oder "1500.50" | "1500.5" bzw. "1500.50" |
| date | JJJJ-MM-TT, gültiges Kalenderdatum | "2026-11-03" |
| select | genau eine der field_options | Text |
| multiselect | Liste aus field_options, z. B. ["A", "B"] | Liste |
| checkbox | true, false oder "unclear" (wie Ja, Nein, Unklar in der Qualifizierung) | "true", "false", "unclear" |
| user | ID eines Team-Mitglieds (GET /v1/team) | ID |
| url | vollständige URL mit http:// oder https:// | Text |
| email | E-Mail-Adresse (wird klein geschrieben) | Text |
| phone | Telefonnummer aus Ziffern, Leerzeichen, + ( ) / . - | Text wie übergeben |

Höchstens 200 Felder je Aufruf. Mit Test-Key kommt dieselbe Prüfung und die Liste der Änderungen, geschrieben wird nichts.

Pfad-Parameter

idstring (uuid)Pflicht
ID des Leads

Body

Feld-Schlüssel → Wert. Format je Typ siehe Tabelle.

Mögliche Fehler

400 VALIDATION_ERROR401 INVALID_API_KEY402 PLAN_REQUIRED403 SCOPE_MISSING404 NOT_FOUND429 RATE_LIMITED

curl -X PUT "https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10/custom-fields" \
  -H "X-API-Key: $DEALSKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "budget": 15000,
  "entscheider": true,
  "interesse": [
    "Video",
    "Landingpage"
  ],
  "naechster_termin": "2026-11-03",
  "bemerkung": null
}'

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10/custom-fields", {
  method: "PUT",
  headers: {
    "X-API-Key": process.env.DEALSKY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "budget": 15000,
    "entscheider": true,
    "interesse": [
      "Video",
      "Landingpage"
    ],
    "naechster_termin": "2026-11-03",
    "bemerkung": null
  }),
});
const { ok, data, error } = await res.json();

import os, requests

res = requests.request(
    "PUT",
    "https://api.dealsky.io/functions/v1/api/v1/leads/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10/custom-fields",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
    json={
        "budget": 15000,
        "entscheider": True,
        "interesse": [
            "Video",
            "Landingpage"
        ],
        "naechster_termin": "2026-11-03",
        "bemerkung": None
    },
)
print(res.json())

Antwort 200

{
  "ok": true,
  "data": {
    "budget": "15000",
    "entscheider": "true",
    "interesse": [
      "Video",
      "Landingpage"
    ],
    "naechster_termin": "2026-11-03",
    "zustaendig": "8e7d6c5b-4a39-4281-9f0e-1d2c3b4a5f60",
    "bemerkung": null
  },
  "meta": {
    "request_id": "req_7f3a…"
  }
}