API-Referenz

Listen

Lead-Listen und Ordner verwalten

Listen auflisten

GET/v1/lists

Scope read:leadsRecht: Leads einsehenliest

Neueste zuerst. name sucht als Teilstring (Groß/Klein egal).

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
namestringmax. 200 Zeichen
Teil des Namens (Groß/Klein egal)
campaign_idstring (uuid)
Nur Listen, die an diese Kampagne gebunden sind

Felder der Antwort

idstring (uuid)
ID der Liste
namestringmind. 1 Zeichenmax. 200 Zeichen
Name der Liste, wie er in der App steht
descriptionstring, kann null seinmax. 2000 Zeichen
Freitext zur Liste, z. B. woher die Kontakte stammen. null leert sie
campaign_idstring (uuid), kann null sein
Kampagne, an die die Liste gebunden ist
folder_idstring (uuid), kann null sein
Ordner der Liste (siehe /v1/list-folders), null = oberste Ebene
leads_countinteger
Leads in der Liste ohne archivierte, von der Datenbank mitgezählt
personalized_landing_pages_countinteger
Leads der Liste (ohne archivierte) mit personalisierter Landingpage
personalized_videos_countinteger
Leads der Liste (ohne archivierte) mit personalisiertem Video
created_atstring (date-time)
Zeitpunkt der Anlage
updated_atstring (date-time)
Zeitpunkt der letzten Änderung, auch wenn sich die Lead-Zahlen geändert haben

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/lists" \
  -H "X-API-Key: $DEALSKY_API_KEY"

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/lists", {
  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/lists",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
)
print(res.json())

Antwort 200

{
  "ok": true,
  "data": [
    {
      "id": "1f4e2d3c-7b6a-4c5d-9e8f-0a1b2c3d4e5f",
      "name": "Messe Köln 2026",
      "description": "Kontakte vom Messestand",
      "campaign_id": null,
      "folder_id": null,
      "leads_count": 128,
      "personalized_landing_pages_count": 0,
      "personalized_videos_count": 0,
      "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
  }
}

Liste anlegen

POST/v1/lists

Scope write:leadsRecht: Leads anlegen/bearbeitenschreibt

Legt eine leere Liste an. Ohne folder_id steht sie auf der obersten Ebene. Mit folder_id (siehe GET /v1/list-folders) entsteht sie direkt in diesem Ordner, wie „Neue Liste“ in einem geöffneten Ordner der App; ein unbekannter oder fremder Ordner ergibt 400. Für folder_id braucht es einen API-Key, der einer Person zugeordnet ist; ohne Ordner legen auch ältere Keys ohne Person Listen an. Leads kommen danach mit list_id über POST /v1/leads oder POST /v1/leads/bulk hinein. Kostet keine Credits. Mit Test-Key wird geprüft, aber nichts angelegt (would_create).

Body

namestringPflichtmind. 1 Zeichenmax. 200 Zeichen
Name der Liste, wie er in der App steht
descriptionstring, kann null seinmax. 2000 Zeichen
Freitext zur Liste, z. B. woher die Kontakte stammen. null leert sie
folder_idstring (uuid), kann null sein
Ordner, in dem die Liste entsteht (siehe GET /v1/list-folders). Weglassen oder null = oberste Ebene

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/lists" \
  -H "X-API-Key: $DEALSKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Messe Köln 2026",
  "description": "Kontakte vom Messestand"
}'

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/lists", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.DEALSKY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Messe Köln 2026",
    "description": "Kontakte vom Messestand"
  }),
});
const { ok, data, error } = await res.json();

import os, requests

res = requests.request(
    "POST",
    "https://api.dealsky.io/functions/v1/api/v1/lists",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
    json={
        "name": "Messe Köln 2026",
        "description": "Kontakte vom Messestand"
    },
)
print(res.json())

Antwort 201

{
  "ok": true,
  "data": {
    "id": "1f4e2d3c-7b6a-4c5d-9e8f-0a1b2c3d4e5f",
    "name": "Messe Köln 2026",
    "description": "Kontakte vom Messestand",
    "campaign_id": null,
    "folder_id": null,
    "leads_count": 128,
    "personalized_landing_pages_count": 0,
    "personalized_videos_count": 0,
    "created_at": "2026-10-01T08:00:00.000Z",
    "updated_at": "2026-10-18T09:12:00.000Z"
  },
  "meta": {
    "request_id": "req_7f3a…"
  }
}

Eine Liste abrufen

GET/v1/lists/{id}

Scope read:leadsRecht: Leads einsehenliest

Liefert eine Liste des eigenen Kontos mit Ordner (folder_id), gebundener Kampagne (campaign_id) und den Zählern der App für Leads, persönliche Landingpages und Videos. Die Leads selbst liefert GET /v1/leads?list_id=…. Eine unbekannte oder fremde ID ergibt 404.

Pfad-Parameter

idstring (uuid)Pflicht
ID der Liste

Felder der Antwort

idstring (uuid)
ID der Liste
namestringmind. 1 Zeichenmax. 200 Zeichen
Name der Liste, wie er in der App steht
descriptionstring, kann null seinmax. 2000 Zeichen
Freitext zur Liste, z. B. woher die Kontakte stammen. null leert sie
campaign_idstring (uuid), kann null sein
Kampagne, an die die Liste gebunden ist
folder_idstring (uuid), kann null sein
Ordner der Liste (siehe /v1/list-folders), null = oberste Ebene
leads_countinteger
Leads in der Liste ohne archivierte, von der Datenbank mitgezählt
personalized_landing_pages_countinteger
Leads der Liste (ohne archivierte) mit personalisierter Landingpage
personalized_videos_countinteger
Leads der Liste (ohne archivierte) mit personalisiertem Video
created_atstring (date-time)
Zeitpunkt der Anlage
updated_atstring (date-time)
Zeitpunkt der letzten Änderung, auch wenn sich die Lead-Zahlen geändert haben

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/lists/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10" \
  -H "X-API-Key: $DEALSKY_API_KEY"

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/lists/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/lists/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
)
print(res.json())

Antwort 200

{
  "ok": true,
  "data": {
    "id": "1f4e2d3c-7b6a-4c5d-9e8f-0a1b2c3d4e5f",
    "name": "Messe Köln 2026",
    "description": "Kontakte vom Messestand",
    "campaign_id": null,
    "folder_id": null,
    "leads_count": 128,
    "personalized_landing_pages_count": 0,
    "personalized_videos_count": 0,
    "created_at": "2026-10-01T08:00:00.000Z",
    "updated_at": "2026-10-18T09:12:00.000Z"
  },
  "meta": {
    "request_id": "req_7f3a…"
  }
}

Liste umbenennen, Beschreibung ändern oder in einen Ordner verschieben

PATCH/v1/lists/{id}

Scope write:leadsRecht: Leads anlegen/bearbeitenschreibt

Nur übergebene Felder werden geändert. folder_id verschiebt die Liste in einen Ordner (siehe GET /v1/list-folders), null holt sie auf die oberste Ebene, wie das Verschieben in der App. Leads, Kampagne und Landingpages der Liste bleiben unberührt. Zum Verschieben braucht es einen API-Key, der einer Person zugeordnet ist; Name und Beschreibung ändern auch ältere Keys ohne Person.

Pfad-Parameter

idstring (uuid)Pflicht
ID der Liste

Body

namestringmind. 1 Zeichenmax. 200 Zeichen
Name der Liste, wie er in der App steht
descriptionstring, kann null seinmax. 2000 Zeichen
Freitext zur Liste, z. B. woher die Kontakte stammen. null leert sie
folder_idstring (uuid), kann null sein
Ordner der Liste (siehe /v1/list-folders), null = oberste Ebene

Felder der Antwort

idstring (uuid)
ID der Liste
namestringmind. 1 Zeichenmax. 200 Zeichen
Name der Liste, wie er in der App steht
descriptionstring, kann null seinmax. 2000 Zeichen
Freitext zur Liste, z. B. woher die Kontakte stammen. null leert sie
campaign_idstring (uuid), kann null sein
Kampagne, an die die Liste gebunden ist
folder_idstring (uuid), kann null sein
Ordner der Liste (siehe /v1/list-folders), null = oberste Ebene
leads_countinteger
Leads in der Liste ohne archivierte, von der Datenbank mitgezählt
personalized_landing_pages_countinteger
Leads der Liste (ohne archivierte) mit personalisierter Landingpage
personalized_videos_countinteger
Leads der Liste (ohne archivierte) mit personalisiertem Video
created_atstring (date-time)
Zeitpunkt der Anlage
updated_atstring (date-time)
Zeitpunkt der letzten Änderung, auch wenn sich die Lead-Zahlen geändert haben

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/lists/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10" \
  -H "X-API-Key: $DEALSKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Messe Köln 2026 (nachbearbeitet)"
}'

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/lists/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10", {
  method: "PATCH",
  headers: {
    "X-API-Key": process.env.DEALSKY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Messe Köln 2026 (nachbearbeitet)"
  }),
});
const { ok, data, error } = await res.json();

import os, requests

res = requests.request(
    "PATCH",
    "https://api.dealsky.io/functions/v1/api/v1/lists/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
    json={
        "name": "Messe Köln 2026 (nachbearbeitet)"
    },
)
print(res.json())

Antwort 200

{
  "ok": true,
  "data": {
    "id": "1f4e2d3c-7b6a-4c5d-9e8f-0a1b2c3d4e5f",
    "name": "Messe Köln 2026 (nachbearbeitet)",
    "description": "Kontakte vom Messestand",
    "campaign_id": null,
    "folder_id": null,
    "leads_count": 128,
    "personalized_landing_pages_count": 0,
    "personalized_videos_count": 0,
    "created_at": "2026-10-01T08:00:00.000Z",
    "updated_at": "2026-10-18T09:12:00.000Z"
  },
  "meta": {
    "request_id": "req_7f3a…"
  }
}

Ordner für Listen auflisten

GET/v1/list-folders

Scope read:leadsRecht: Leads einsehenliest

Alle Ordner des Kontos, nach Name sortiert wie in der App. Unterordner haben parent_folder_id. Welche Listen in einem Ordner liegen, steht in folder_id der Listen (GET /v1/lists).

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 des Ordners
namestringmind. 1 Zeichenmax. 200 Zeichen
Name des Ordners
parent_folder_idstring (uuid), kann null sein
Übergeordneter Ordner, null = oberste Ebene. Wie in der App höchstens zwei Ebenen: der übergeordnete Ordner muss selbst auf oberster Ebene liegen.
created_atstring (date-time)
Angelegt am
updated_atstring (date-time)
Zuletzt geändert am (auch beim Umbenennen oder Verschieben)

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/list-folders" \
  -H "X-API-Key: $DEALSKY_API_KEY"

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/list-folders", {
  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/list-folders",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
)
print(res.json())

Antwort 200

{
  "ok": true,
  "data": [
    {
      "id": "7e6d5c4b-3a2f-4e1d-8c9b-8a7f6e5d4c3b",
      "name": "Köln",
      "parent_folder_id": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a",
      "created_at": "2026-10-01T08:00:00.000Z",
      "updated_at": "2026-10-01T08:00:00.000Z"
    },
    {
      "id": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a",
      "name": "Messen 2026",
      "parent_folder_id": null,
      "created_at": "2026-10-01T08:00:00.000Z",
      "updated_at": "2026-10-01T08:00:00.000Z"
    }
  ],
  "meta": {
    "request_id": "req_7f3a…",
    "next_cursor": null,
    "has_more": false
  }
}

Ordner anlegen

POST/v1/list-folders

Scope write:leadsRecht: Leads anlegen/bearbeitenschreibt

Legt einen Ordner auf oberster Ebene oder, mit parent_folder_id, als Unterordner an. Wie in der App höchstens zwei Ebenen. Ein gleichnamiger Unterordner im selben Ordner ergibt 409. Listen kommen per PATCH /v1/lists/{id} mit folder_id hinein.

Body

namestringPflichtmind. 1 Zeichenmax. 200 Zeichen
Name des Ordners
parent_folder_idstring (uuid), kann null sein
Übergeordneter Ordner, null = oberste Ebene. Wie in der App höchstens zwei Ebenen: der übergeordnete Ordner muss selbst auf oberster Ebene liegen.

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/list-folders" \
  -H "X-API-Key: $DEALSKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Messen 2026"
}'

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/list-folders", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.DEALSKY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Messen 2026"
  }),
});
const { ok, data, error } = await res.json();

import os, requests

res = requests.request(
    "POST",
    "https://api.dealsky.io/functions/v1/api/v1/list-folders",
    headers={"X-API-Key": os.environ["DEALSKY_API_KEY"]},
    json={
        "name": "Messen 2026"
    },
)
print(res.json())

Antwort 201

{
  "ok": true,
  "data": {
    "id": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a",
    "name": "Messen 2026",
    "parent_folder_id": null,
    "created_at": "2026-10-01T08:00:00.000Z",
    "updated_at": "2026-10-01T08:00:00.000Z"
  },
  "meta": {
    "request_id": "req_7f3a…"
  }
}

Ordner umbenennen

PATCH/v1/list-folders/{id}

Scope write:leadsRecht: Leads anlegen/bearbeitenschreibt

Ändert den Namen, wie „Umbenennen“ in der App. Verschieben von Ordnern bietet die App nicht an, die API darum auch nicht. Ein gleichnamiger Unterordner im selben Ordner ergibt 409.

Pfad-Parameter

idstring (uuid)Pflicht
ID des Ordners

Body

namestringPflichtmind. 1 Zeichenmax. 200 Zeichen
Name des Ordners

Felder der Antwort

idstring (uuid)
ID des Ordners
namestringmind. 1 Zeichenmax. 200 Zeichen
Name des Ordners
parent_folder_idstring (uuid), kann null sein
Übergeordneter Ordner, null = oberste Ebene. Wie in der App höchstens zwei Ebenen: der übergeordnete Ordner muss selbst auf oberster Ebene liegen.
created_atstring (date-time)
Angelegt am
updated_atstring (date-time)
Zuletzt geändert am (auch beim Umbenennen oder Verschieben)

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/list-folders/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10" \
  -H "X-API-Key: $DEALSKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Messen 2027"
}'

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/list-folders/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10", {
  method: "PATCH",
  headers: {
    "X-API-Key": process.env.DEALSKY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Messen 2027"
  }),
});
const { ok, data, error } = await res.json();

import os, requests

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

Antwort 200

{
  "ok": true,
  "data": {
    "id": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a",
    "name": "Messen 2027",
    "parent_folder_id": null,
    "created_at": "2026-10-01T08:00:00.000Z",
    "updated_at": "2026-10-18T09:12:00.000Z"
  },
  "meta": {
    "request_id": "req_7f3a…"
  }
}

Ordner löschen (Listen bleiben erhalten)

DEL/v1/list-folders/{id}

Scope write:leadsRecht: Leads anlegen/bearbeitenschreibt

Löscht nur den Ordner, wie in der App: Listen darin und Unterordner (samt ihren Listen) bleiben erhalten und rücken auf die oberste Ebene. Leads, Kampagnen und Landingpages sind nicht betroffen. Die Antwort nennt, wie viele Listen und Unterordner verschoben wurden. Listen selbst löschen geht hierüber nicht.

Pfad-Parameter

idstring (uuid)Pflicht
ID des Ordners

Felder der Antwort

deletedboolean
Immer true, wenn der Ordner gelöscht wurde
idstring (uuid)
ID des gelöschten Ordners
lists_moved_to_topinteger
Listen, die im Ordner lagen und jetzt auf oberster Ebene stehen
subfolders_moved_to_topinteger
Unterordner, die jetzt auf oberster Ebene stehen (ihre Listen bleiben darin)

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/list-folders/5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10" \
  -H "X-API-Key: $DEALSKY_API_KEY"

const res = await fetch("https://api.dealsky.io/functions/v1/api/v1/list-folders/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/list-folders/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": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a",
    "lists_moved_to_top": 3,
    "subfolders_moved_to_top": 1
  },
  "meta": {
    "request_id": "req_7f3a…"
  }
}