Zum Inhalt springen
DebtFlow

Kontakte

Kunden und Schuldner (gemeinsame Kontaktbasis).

Kontakte auflisten

GET/api/v1/contacts

Kunden, Schuldner und Lieferanten mit Kennzahlen (Anzahl Forderungen, offener Betrag). Neueste zuerst.

Berechtigung: contacts:read

Query-Parameter

  • qstring
    Suche in Name, Firma, E-Mail, Telefon, Ort, Kunden-/Lieferantennummer
    max. 100 Zeichen
  • role"customer" | "debtor" | "supplier"
  • archived"true" | "false" | "all"
    Archivierte Kontakte einbeziehen
    Standard: "false"
  • open"true" | "false"
    true = nur mit offenem Betrag, false = nur ohne
  • sort"created_desc" | "name_asc" | "name_desc" | "open_desc" | "open_asc" | "updated_desc"
    Reihenfolge: created_desc (Standard, neueste zuerst), name_asc, name_desc, open_desc, open_asc, updated_desc
    Standard: "created_desc"
  • limitinteger
    Anzahl Einträge (1–100)
    1–100 · Standard: 25
  • cursorstring
    `nextCursor` der vorherigen Seite
    max. 500 Zeichen

Antwort 200

  • object"list"Pflicht
  • dataArray<Contact>Pflicht
    • idstringPflicht
    • object"contact"Pflicht
    • kind"person" | "company"Pflicht
    • rolesArray<"customer" | "debtor" | "supplier">Pflicht
    • displayNamestringPflicht
    • firstNamestringPflicht
    • middleNamestringPflicht
    • lastNamestringPflicht
    • companystringPflicht
    • genderstringPflicht
    • birthDatestring (date) | nullPflicht
      Datum (YYYY-MM-DD)
    • birthPlacestringPflicht
    • emailsArray<string>Pflicht
    • phonesArray<string>Pflicht
    • addressesArray<ContactAddress>Pflicht
      • typestringPflicht
        home, work oder other
        max. 20 Zeichen · Standard: "home"
      • streetstringPflicht
        max. 160 Zeichen · Standard: ""
      • houseNumberstringPflicht
        max. 20 Zeichen · Standard: ""
      • zipCodestringPflicht
        max. 10 Zeichen · Standard: ""
      • citystringPflicht
        max. 80 Zeichen · Standard: ""
      • countrystringPflicht
        max. 60 Zeichen · Standard: "Deutschland"
    • socialsArray<SocialProfile>Pflicht
      • platformstringPflicht
        max. 40 Zeichen
      • usernamestringPflicht
        max. 200 Zeichen
    • notesstringPflicht
    • language"de" | "en"Pflicht
      Korrespondenzsprache für Mahnungen, Briefe, Rechnungen und Angebote (Standard de)
    • customerNumberstring | nullPflicht
    • supplierNumberstring | nullPflicht
    • vatIdstring | nullPflicht
    • taxNumberstring | nullPflicht
    • billingEmailstring | nullPflicht
    • billingAddressPostalAddress | nullPflicht
      • namestringPflicht
        Firma oder Name
        max. 160 Zeichen
      • additionstring
        Zusatz, z. B. z. Hd. / Abteilung
        max. 160 Zeichen
      • streetstringPflicht
        Straße und Hausnummer
        max. 160 Zeichen
      • zipCodestringPflicht
        max. 10 Zeichen
      • citystringPflicht
        max. 80 Zeichen
      • countrystringPflicht
        Ländercode ISO 3166-1 alpha-2
        max. 2 Zeichen · Standard: "DE"
    • leitwegIdstring | nullPflicht
    • paymentTermsDaysinteger | nullPflicht
      -9007199254740991–9007199254740991
    • defaultTaxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable" | nullPflicht
      Steuerbehandlung des Belegs
    • priceMode"net" | "gross" | nullPflicht
    • einvoicePreference"pdf" | "zugferd" | "xrechnung" | nullPflicht
    • clientIdstring | nullPflicht
      Mandant (Inkasso/Kanzlei)
    • archivedAtstring (date-time) | nullPflicht
      Zeitpunkt (ISO 8601)
    • statsContactStatsPflicht
      • debtCountintegerPflicht
        -9007199254740991–9007199254740991
      • openDebtCountintegerPflicht
        -9007199254740991–9007199254740991
      • totalCentsintegerPflicht
        Summe der Hauptforderungen
        -100000000000–100000000000
      • openCentsintegerPflicht
        Offen inkl. Kosten abzüglich Zahlungen
        -100000000000–100000000000
    • createdAtstring (date-time)Pflicht
      Zeitpunkt (ISO 8601)
    • updatedAtstring (date-time)Pflicht
      Zeitpunkt (ISO 8601)
  • hasMorebooleanPflicht
  • nextCursorstring | nullPflicht

Mögliche Fehler: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/contacts' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Antwort 200
{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "contact",
      "kind": "person",
      "roles": [
        "customer"
      ],
      "displayName": "string",
      "firstName": "string",
      "middleName": "string",
      "lastName": "string",
      "company": "string",
      "gender": "string",
      "birthDate": "2026-11-01",
      "birthPlace": "string",
      "emails": [
        "string"
      ],
      "phones": [
        "string"
      ],
      "addresses": [
        {
          "type": null,
          "street": null,
          "houseNumber": null,
          "zipCode": null,
          "city": null,
          "country": null
        }
      ],
      "socials": [
        {
          "platform": null,
          "username": null
        }
      ],
      "notes": "string",
      "language": "de",
      "customerNumber": "string",
      "supplierNumber": "string",
      "vatId": "string",
      "taxNumber": "string",
      "billingEmail": "string",
      "billingAddress": {
        "name": null,
        "addition": null,
        "street": null,
        "zipCode": null,
        "city": null,
        "country": null
      },
      "leitwegId": "string",
      "paymentTermsDays": 0,
      "defaultTaxTreatment": "regular",
      "priceMode": "net",
      "einvoicePreference": "pdf",
      "clientId": "string",
      "archivedAt": "2026-11-01T09:30:00.000Z",
      "stats": {
        "debtCount": 0,
        "openDebtCount": 0,
        "totalCents": 0,
        "openCents": 0
      },
      "createdAt": "2026-11-01T09:30:00.000Z",
      "updatedAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Kontakt anlegen

POST/api/v1/contacts

Die Anzahl der Kontakte ist durch das Abo begrenzt (Fehler plan_limit_reached).

Berechtigung: contacts:write

Header

  • Idempotency-Keystring
    Eindeutiger Schlüssel (8–255 Zeichen). Wiederholte Anfragen mit gleichem Schlüssel liefern 24 h lang dieselbe Antwort.
    max. 255 Zeichen

Body (JSON) · ContactCreate

  • kind"person" | "company"
  • rolesArray<"customer" | "debtor" | "supplier">
  • firstNamestring
    max. 80 Zeichen
  • middleNamestring
    max. 80 Zeichen
  • lastNamestring
    max. 80 Zeichen
  • companystring
    max. 160 Zeichen
  • genderstring
    max. 20 Zeichen
  • birthDatestring (date) | null
    Datum (YYYY-MM-DD)
  • birthPlacestring
    max. 80 Zeichen
  • emailsArray<string (email)>
    max. 254 Zeichen
  • phonesArray<string>
    max. 40 Zeichen
  • addressesArray<ContactAddress>
    • typestringPflicht
      home, work oder other
      max. 20 Zeichen · Standard: "home"
    • streetstringPflicht
      max. 160 Zeichen · Standard: ""
    • houseNumberstringPflicht
      max. 20 Zeichen · Standard: ""
    • zipCodestringPflicht
      max. 10 Zeichen · Standard: ""
    • citystringPflicht
      max. 80 Zeichen · Standard: ""
    • countrystringPflicht
      max. 60 Zeichen · Standard: "Deutschland"
  • socialsArray<SocialProfile>
    • platformstringPflicht
      max. 40 Zeichen
    • usernamestringPflicht
      max. 200 Zeichen
  • notesstring
    max. 10000 Zeichen
  • language"de" | "en"
    Korrespondenzsprache (de oder en), Standard de
  • customerNumberstring | null
    max. 40 Zeichen
  • supplierNumberstring | null
    max. 40 Zeichen
  • vatIdstring | null
  • taxNumberstring | null
    max. 40 Zeichen
  • billingEmailstring (email) | null
    max. 254 Zeichen
  • billingAddressPostalAddress | null
    • namestringPflicht
      Firma oder Name
      max. 160 Zeichen
    • additionstring
      Zusatz, z. B. z. Hd. / Abteilung
      max. 160 Zeichen
    • streetstringPflicht
      Straße und Hausnummer
      max. 160 Zeichen
    • zipCodestringPflicht
      max. 10 Zeichen
    • citystringPflicht
      max. 80 Zeichen
    • countrystringPflicht
      Ländercode ISO 3166-1 alpha-2
      max. 2 Zeichen · Standard: "DE"
  • leitwegIdstring | null
    max. 46 Zeichen
  • paymentTermsDaysinteger | null
    0–365
  • defaultTaxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable" | null
    Steuerbehandlung des Belegs
  • priceMode"net" | "gross" | null
  • einvoicePreference"pdf" | "zugferd" | "xrechnung" | null
  • clientIdstring | null
    max. 128 Zeichen

Antwort 201 · Contact

  • idstringPflicht
  • object"contact"Pflicht
  • kind"person" | "company"Pflicht
  • rolesArray<"customer" | "debtor" | "supplier">Pflicht
  • displayNamestringPflicht
  • firstNamestringPflicht
  • middleNamestringPflicht
  • lastNamestringPflicht
  • companystringPflicht
  • genderstringPflicht
  • birthDatestring (date) | nullPflicht
    Datum (YYYY-MM-DD)
  • birthPlacestringPflicht
  • emailsArray<string>Pflicht
  • phonesArray<string>Pflicht
  • addressesArray<ContactAddress>Pflicht
    • typestringPflicht
      home, work oder other
      max. 20 Zeichen · Standard: "home"
    • streetstringPflicht
      max. 160 Zeichen · Standard: ""
    • houseNumberstringPflicht
      max. 20 Zeichen · Standard: ""
    • zipCodestringPflicht
      max. 10 Zeichen · Standard: ""
    • citystringPflicht
      max. 80 Zeichen · Standard: ""
    • countrystringPflicht
      max. 60 Zeichen · Standard: "Deutschland"
  • socialsArray<SocialProfile>Pflicht
    • platformstringPflicht
      max. 40 Zeichen
    • usernamestringPflicht
      max. 200 Zeichen
  • notesstringPflicht
  • language"de" | "en"Pflicht
    Korrespondenzsprache für Mahnungen, Briefe, Rechnungen und Angebote (Standard de)
  • customerNumberstring | nullPflicht
  • supplierNumberstring | nullPflicht
  • vatIdstring | nullPflicht
  • taxNumberstring | nullPflicht
  • billingEmailstring | nullPflicht
  • billingAddressPostalAddress | nullPflicht
    • namestringPflicht
      Firma oder Name
      max. 160 Zeichen
    • additionstring
      Zusatz, z. B. z. Hd. / Abteilung
      max. 160 Zeichen
    • streetstringPflicht
      Straße und Hausnummer
      max. 160 Zeichen
    • zipCodestringPflicht
      max. 10 Zeichen
    • citystringPflicht
      max. 80 Zeichen
    • countrystringPflicht
      Ländercode ISO 3166-1 alpha-2
      max. 2 Zeichen · Standard: "DE"
  • leitwegIdstring | nullPflicht
  • paymentTermsDaysinteger | nullPflicht
    -9007199254740991–9007199254740991
  • defaultTaxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable" | nullPflicht
    Steuerbehandlung des Belegs
  • priceMode"net" | "gross" | nullPflicht
  • einvoicePreference"pdf" | "zugferd" | "xrechnung" | nullPflicht
  • clientIdstring | nullPflicht
    Mandant (Inkasso/Kanzlei)
  • archivedAtstring (date-time) | nullPflicht
    Zeitpunkt (ISO 8601)
  • statsContactStatsPflicht
    • debtCountintegerPflicht
      -9007199254740991–9007199254740991
    • openDebtCountintegerPflicht
      -9007199254740991–9007199254740991
    • totalCentsintegerPflicht
      Summe der Hauptforderungen
      -100000000000–100000000000
    • openCentsintegerPflicht
      Offen inkl. Kosten abzüglich Zahlungen
      -100000000000–100000000000
  • createdAtstring (date-time)Pflicht
    Zeitpunkt (ISO 8601)
  • updatedAtstring (date-time)Pflicht
    Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/contacts' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "kind": "person",
  "roles": [
    "customer"
  ],
  "firstName": "string",
  "middleName": "string",
  "lastName": "string",
  "company": "string",
  "gender": "string",
  "birthDate": "2026-11-01",
  "birthPlace": "string",
  "emails": [
    "[email protected]"
  ],
  "phones": [
    "string"
  ],
  "addresses": [
    {
      "type": "home",
      "street": "",
      "houseNumber": "",
      "zipCode": "",
      "city": "",
      "country": "Deutschland"
    }
  ],
  "socials": [
    {
      "platform": "string",
      "username": "string"
    }
  ],
  "notes": "string",
  "language": "de",
  "customerNumber": "string",
  "supplierNumber": "string",
  "vatId": "string",
  "taxNumber": "string",
  "billingEmail": "[email protected]",
  "billingAddress": {
    "name": "string",
    "addition": "string",
    "street": "string",
    "zipCode": "string",
    "city": "string",
    "country": "DE"
  },
  "leitwegId": "string",
  "paymentTermsDays": 0,
  "defaultTaxTreatment": "regular",
  "priceMode": "net",
  "einvoicePreference": "pdf",
  "clientId": "string"
}'
Antwort 201
{
  "id": "string",
  "object": "contact",
  "kind": "person",
  "roles": [
    "customer"
  ],
  "displayName": "string",
  "firstName": "string",
  "middleName": "string",
  "lastName": "string",
  "company": "string",
  "gender": "string",
  "birthDate": "2026-11-01",
  "birthPlace": "string",
  "emails": [
    "string"
  ],
  "phones": [
    "string"
  ],
  "addresses": [
    {
      "type": "home",
      "street": "",
      "houseNumber": "",
      "zipCode": "",
      "city": "",
      "country": "Deutschland"
    }
  ],
  "socials": [
    {
      "platform": "string",
      "username": "string"
    }
  ],
  "notes": "string",
  "language": "de",
  "customerNumber": "string",
  "supplierNumber": "string",
  "vatId": "string",
  "taxNumber": "string",
  "billingEmail": "string",
  "billingAddress": {
    "name": "string",
    "addition": "string",
    "street": "string",
    "zipCode": "string",
    "city": "string",
    "country": "DE"
  },
  "leitwegId": "string",
  "paymentTermsDays": 0,
  "defaultTaxTreatment": "regular",
  "priceMode": "net",
  "einvoicePreference": "pdf",
  "clientId": "string",
  "archivedAt": "2026-11-01T09:30:00.000Z",
  "stats": {
    "debtCount": 0,
    "openDebtCount": 0,
    "totalCents": 0,
    "openCents": 0
  },
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Kontakt abrufen

GET/api/v1/contacts/{id}

Berechtigung: contacts:read

Pfadparameter

  • idstringPflicht
    ID der Ressource
    max. 128 Zeichen

Antwort 200 · Contact

  • idstringPflicht
  • object"contact"Pflicht
  • kind"person" | "company"Pflicht
  • rolesArray<"customer" | "debtor" | "supplier">Pflicht
  • displayNamestringPflicht
  • firstNamestringPflicht
  • middleNamestringPflicht
  • lastNamestringPflicht
  • companystringPflicht
  • genderstringPflicht
  • birthDatestring (date) | nullPflicht
    Datum (YYYY-MM-DD)
  • birthPlacestringPflicht
  • emailsArray<string>Pflicht
  • phonesArray<string>Pflicht
  • addressesArray<ContactAddress>Pflicht
    • typestringPflicht
      home, work oder other
      max. 20 Zeichen · Standard: "home"
    • streetstringPflicht
      max. 160 Zeichen · Standard: ""
    • houseNumberstringPflicht
      max. 20 Zeichen · Standard: ""
    • zipCodestringPflicht
      max. 10 Zeichen · Standard: ""
    • citystringPflicht
      max. 80 Zeichen · Standard: ""
    • countrystringPflicht
      max. 60 Zeichen · Standard: "Deutschland"
  • socialsArray<SocialProfile>Pflicht
    • platformstringPflicht
      max. 40 Zeichen
    • usernamestringPflicht
      max. 200 Zeichen
  • notesstringPflicht
  • language"de" | "en"Pflicht
    Korrespondenzsprache für Mahnungen, Briefe, Rechnungen und Angebote (Standard de)
  • customerNumberstring | nullPflicht
  • supplierNumberstring | nullPflicht
  • vatIdstring | nullPflicht
  • taxNumberstring | nullPflicht
  • billingEmailstring | nullPflicht
  • billingAddressPostalAddress | nullPflicht
    • namestringPflicht
      Firma oder Name
      max. 160 Zeichen
    • additionstring
      Zusatz, z. B. z. Hd. / Abteilung
      max. 160 Zeichen
    • streetstringPflicht
      Straße und Hausnummer
      max. 160 Zeichen
    • zipCodestringPflicht
      max. 10 Zeichen
    • citystringPflicht
      max. 80 Zeichen
    • countrystringPflicht
      Ländercode ISO 3166-1 alpha-2
      max. 2 Zeichen · Standard: "DE"
  • leitwegIdstring | nullPflicht
  • paymentTermsDaysinteger | nullPflicht
    -9007199254740991–9007199254740991
  • defaultTaxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable" | nullPflicht
    Steuerbehandlung des Belegs
  • priceMode"net" | "gross" | nullPflicht
  • einvoicePreference"pdf" | "zugferd" | "xrechnung" | nullPflicht
  • clientIdstring | nullPflicht
    Mandant (Inkasso/Kanzlei)
  • archivedAtstring (date-time) | nullPflicht
    Zeitpunkt (ISO 8601)
  • statsContactStatsPflicht
    • debtCountintegerPflicht
      -9007199254740991–9007199254740991
    • openDebtCountintegerPflicht
      -9007199254740991–9007199254740991
    • totalCentsintegerPflicht
      Summe der Hauptforderungen
      -100000000000–100000000000
    • openCentsintegerPflicht
      Offen inkl. Kosten abzüglich Zahlungen
      -100000000000–100000000000
  • createdAtstring (date-time)Pflicht
    Zeitpunkt (ISO 8601)
  • updatedAtstring (date-time)Pflicht
    Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/contacts/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Antwort 200
{
  "id": "string",
  "object": "contact",
  "kind": "person",
  "roles": [
    "customer"
  ],
  "displayName": "string",
  "firstName": "string",
  "middleName": "string",
  "lastName": "string",
  "company": "string",
  "gender": "string",
  "birthDate": "2026-11-01",
  "birthPlace": "string",
  "emails": [
    "string"
  ],
  "phones": [
    "string"
  ],
  "addresses": [
    {
      "type": "home",
      "street": "",
      "houseNumber": "",
      "zipCode": "",
      "city": "",
      "country": "Deutschland"
    }
  ],
  "socials": [
    {
      "platform": "string",
      "username": "string"
    }
  ],
  "notes": "string",
  "language": "de",
  "customerNumber": "string",
  "supplierNumber": "string",
  "vatId": "string",
  "taxNumber": "string",
  "billingEmail": "string",
  "billingAddress": {
    "name": "string",
    "addition": "string",
    "street": "string",
    "zipCode": "string",
    "city": "string",
    "country": "DE"
  },
  "leitwegId": "string",
  "paymentTermsDays": 0,
  "defaultTaxTreatment": "regular",
  "priceMode": "net",
  "einvoicePreference": "pdf",
  "clientId": "string",
  "archivedAt": "2026-11-01T09:30:00.000Z",
  "stats": {
    "debtCount": 0,
    "openDebtCount": 0,
    "totalCents": 0,
    "openCents": 0
  },
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Kontakt ändern

PATCH/api/v1/contacts/{id}

Nur übermittelte Felder werden geändert; null leert ein optionales Feld. archived: true archiviert den Kontakt.

Berechtigung: contacts:write

Pfadparameter

  • idstringPflicht
    ID der Ressource
    max. 128 Zeichen

Body (JSON) · ContactUpdate

  • kind"person" | "company"
  • rolesArray<"customer" | "debtor" | "supplier">
  • firstNamestring
    max. 80 Zeichen
  • middleNamestring
    max. 80 Zeichen
  • lastNamestring
    max. 80 Zeichen
  • companystring
    max. 160 Zeichen
  • genderstring
    max. 20 Zeichen
  • birthDatestring (date) | null
    Datum (YYYY-MM-DD)
  • birthPlacestring
    max. 80 Zeichen
  • emailsArray<string (email)>
    max. 254 Zeichen
  • phonesArray<string>
    max. 40 Zeichen
  • addressesArray<ContactAddress>
    • typestringPflicht
      home, work oder other
      max. 20 Zeichen · Standard: "home"
    • streetstringPflicht
      max. 160 Zeichen · Standard: ""
    • houseNumberstringPflicht
      max. 20 Zeichen · Standard: ""
    • zipCodestringPflicht
      max. 10 Zeichen · Standard: ""
    • citystringPflicht
      max. 80 Zeichen · Standard: ""
    • countrystringPflicht
      max. 60 Zeichen · Standard: "Deutschland"
  • socialsArray<SocialProfile>
    • platformstringPflicht
      max. 40 Zeichen
    • usernamestringPflicht
      max. 200 Zeichen
  • notesstring
    max. 10000 Zeichen
  • language"de" | "en"
    Korrespondenzsprache (de oder en), Standard de
  • customerNumberstring | null
    max. 40 Zeichen
  • supplierNumberstring | null
    max. 40 Zeichen
  • vatIdstring | null
  • taxNumberstring | null
    max. 40 Zeichen
  • billingEmailstring (email) | null
    max. 254 Zeichen
  • billingAddressPostalAddress | null
    • namestringPflicht
      Firma oder Name
      max. 160 Zeichen
    • additionstring
      Zusatz, z. B. z. Hd. / Abteilung
      max. 160 Zeichen
    • streetstringPflicht
      Straße und Hausnummer
      max. 160 Zeichen
    • zipCodestringPflicht
      max. 10 Zeichen
    • citystringPflicht
      max. 80 Zeichen
    • countrystringPflicht
      Ländercode ISO 3166-1 alpha-2
      max. 2 Zeichen · Standard: "DE"
  • leitwegIdstring | null
    max. 46 Zeichen
  • paymentTermsDaysinteger | null
    0–365
  • defaultTaxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable" | null
    Steuerbehandlung des Belegs
  • priceMode"net" | "gross" | null
  • einvoicePreference"pdf" | "zugferd" | "xrechnung" | null
  • clientIdstring | null
    max. 128 Zeichen
  • archivedboolean
    true archiviert, false holt zurück

Antwort 200 · Contact

  • idstringPflicht
  • object"contact"Pflicht
  • kind"person" | "company"Pflicht
  • rolesArray<"customer" | "debtor" | "supplier">Pflicht
  • displayNamestringPflicht
  • firstNamestringPflicht
  • middleNamestringPflicht
  • lastNamestringPflicht
  • companystringPflicht
  • genderstringPflicht
  • birthDatestring (date) | nullPflicht
    Datum (YYYY-MM-DD)
  • birthPlacestringPflicht
  • emailsArray<string>Pflicht
  • phonesArray<string>Pflicht
  • addressesArray<ContactAddress>Pflicht
    • typestringPflicht
      home, work oder other
      max. 20 Zeichen · Standard: "home"
    • streetstringPflicht
      max. 160 Zeichen · Standard: ""
    • houseNumberstringPflicht
      max. 20 Zeichen · Standard: ""
    • zipCodestringPflicht
      max. 10 Zeichen · Standard: ""
    • citystringPflicht
      max. 80 Zeichen · Standard: ""
    • countrystringPflicht
      max. 60 Zeichen · Standard: "Deutschland"
  • socialsArray<SocialProfile>Pflicht
    • platformstringPflicht
      max. 40 Zeichen
    • usernamestringPflicht
      max. 200 Zeichen
  • notesstringPflicht
  • language"de" | "en"Pflicht
    Korrespondenzsprache für Mahnungen, Briefe, Rechnungen und Angebote (Standard de)
  • customerNumberstring | nullPflicht
  • supplierNumberstring | nullPflicht
  • vatIdstring | nullPflicht
  • taxNumberstring | nullPflicht
  • billingEmailstring | nullPflicht
  • billingAddressPostalAddress | nullPflicht
    • namestringPflicht
      Firma oder Name
      max. 160 Zeichen
    • additionstring
      Zusatz, z. B. z. Hd. / Abteilung
      max. 160 Zeichen
    • streetstringPflicht
      Straße und Hausnummer
      max. 160 Zeichen
    • zipCodestringPflicht
      max. 10 Zeichen
    • citystringPflicht
      max. 80 Zeichen
    • countrystringPflicht
      Ländercode ISO 3166-1 alpha-2
      max. 2 Zeichen · Standard: "DE"
  • leitwegIdstring | nullPflicht
  • paymentTermsDaysinteger | nullPflicht
    -9007199254740991–9007199254740991
  • defaultTaxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable" | nullPflicht
    Steuerbehandlung des Belegs
  • priceMode"net" | "gross" | nullPflicht
  • einvoicePreference"pdf" | "zugferd" | "xrechnung" | nullPflicht
  • clientIdstring | nullPflicht
    Mandant (Inkasso/Kanzlei)
  • archivedAtstring (date-time) | nullPflicht
    Zeitpunkt (ISO 8601)
  • statsContactStatsPflicht
    • debtCountintegerPflicht
      -9007199254740991–9007199254740991
    • openDebtCountintegerPflicht
      -9007199254740991–9007199254740991
    • totalCentsintegerPflicht
      Summe der Hauptforderungen
      -100000000000–100000000000
    • openCentsintegerPflicht
      Offen inkl. Kosten abzüglich Zahlungen
      -100000000000–100000000000
  • createdAtstring (date-time)Pflicht
    Zeitpunkt (ISO 8601)
  • updatedAtstring (date-time)Pflicht
    Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl -X PATCH 'https://www.debt-flow.io/api/v1/contacts/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "kind": "person",
  "roles": [
    "customer"
  ],
  "firstName": "string",
  "middleName": "string",
  "lastName": "string",
  "company": "string",
  "gender": "string",
  "birthDate": "2026-11-01",
  "birthPlace": "string",
  "emails": [
    "[email protected]"
  ],
  "phones": [
    "string"
  ],
  "addresses": [
    {
      "type": "home",
      "street": "",
      "houseNumber": "",
      "zipCode": "",
      "city": "",
      "country": "Deutschland"
    }
  ],
  "socials": [
    {
      "platform": "string",
      "username": "string"
    }
  ],
  "notes": "string",
  "language": "de",
  "customerNumber": "string",
  "supplierNumber": "string",
  "vatId": "string",
  "taxNumber": "string",
  "billingEmail": "[email protected]",
  "billingAddress": {
    "name": "string",
    "addition": "string",
    "street": "string",
    "zipCode": "string",
    "city": "string",
    "country": "DE"
  },
  "leitwegId": "string",
  "paymentTermsDays": 0,
  "defaultTaxTreatment": "regular",
  "priceMode": "net",
  "einvoicePreference": "pdf",
  "clientId": "string",
  "archived": false
}'
Antwort 200
{
  "id": "string",
  "object": "contact",
  "kind": "person",
  "roles": [
    "customer"
  ],
  "displayName": "string",
  "firstName": "string",
  "middleName": "string",
  "lastName": "string",
  "company": "string",
  "gender": "string",
  "birthDate": "2026-11-01",
  "birthPlace": "string",
  "emails": [
    "string"
  ],
  "phones": [
    "string"
  ],
  "addresses": [
    {
      "type": "home",
      "street": "",
      "houseNumber": "",
      "zipCode": "",
      "city": "",
      "country": "Deutschland"
    }
  ],
  "socials": [
    {
      "platform": "string",
      "username": "string"
    }
  ],
  "notes": "string",
  "language": "de",
  "customerNumber": "string",
  "supplierNumber": "string",
  "vatId": "string",
  "taxNumber": "string",
  "billingEmail": "string",
  "billingAddress": {
    "name": "string",
    "addition": "string",
    "street": "string",
    "zipCode": "string",
    "city": "string",
    "country": "DE"
  },
  "leitwegId": "string",
  "paymentTermsDays": 0,
  "defaultTaxTreatment": "regular",
  "priceMode": "net",
  "einvoicePreference": "pdf",
  "clientId": "string",
  "archivedAt": "2026-11-01T09:30:00.000Z",
  "stats": {
    "debtCount": 0,
    "openDebtCount": 0,
    "totalCents": 0,
    "openCents": 0
  },
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Kontakt löschen

DELETE/api/v1/contacts/{id}

Löscht den Kontakt und alle zugehörigen Forderungen (wie im Dashboard). Zum Ausblenden stattdessen archivieren.

Berechtigung: contacts:write

Pfadparameter

  • idstringPflicht
    ID der Ressource
    max. 128 Zeichen

Antwort 204

Erfolg, keine Antwort

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl -X DELETE 'https://www.debt-flow.io/api/v1/contacts/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Kommunikation eines Kontakts

GET/api/v1/contacts/{id}/communications

Protokollierte Kommunikation (Telefonate, E-Mails, Briefe, Termine), neueste zuerst.

Berechtigung: contacts:read

Pfadparameter

  • idstringPflicht
    ID der Ressource
    max. 128 Zeichen

Query-Parameter

  • limitinteger
    Anzahl Einträge (1–100)
    1–100 · Standard: 25
  • cursorstring
    `nextCursor` der vorherigen Seite
    max. 500 Zeichen

Antwort 200

  • object"list"Pflicht
  • dataArray<Communication>Pflicht
    • idstringPflicht
    • object"communication"Pflicht
    • contactIdstringPflicht
    • typestringPflicht
      z. B. email, phone, letter, meeting, other
    • direction"incoming" | "outgoing" | nullPflicht
    • subjectstringPflicht
    • contentstringPflicht
    • datestring (date-time)Pflicht
      Zeitpunkt (ISO 8601)
    • createdAtstring (date-time)Pflicht
      Zeitpunkt (ISO 8601)
  • hasMorebooleanPflicht
  • nextCursorstring | nullPflicht

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/contacts/ID/communications' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Antwort 200
{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "communication",
      "contactId": "string",
      "type": "string",
      "direction": "incoming",
      "subject": "string",
      "content": "string",
      "date": "2026-11-01T09:30:00.000Z",
      "createdAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Kommunikation protokollieren

POST/api/v1/contacts/{id}/communications

Legt einen Eintrag im Kommunikationsprotokoll an (es wird nichts versendet). Ereignis communication.created.

Berechtigung: contacts:write

Pfadparameter

  • idstringPflicht
    ID der Ressource
    max. 128 Zeichen

Header

  • Idempotency-Keystring
    Eindeutiger Schlüssel (8–255 Zeichen). Wiederholte Anfragen mit gleichem Schlüssel liefern 24 h lang dieselbe Antwort.
    max. 255 Zeichen

Body (JSON) · CommunicationCreate

  • typestringPflicht
    max. 40 Zeichen
  • subjectstringPflicht
    max. 300 Zeichen
  • contentstring
    max. 10000 Zeichen
  • direction"incoming" | "outgoing"
  • datestring (date-time)
    Zeitpunkt der Kommunikation (Standard: jetzt)

Antwort 201 · Communication

  • idstringPflicht
  • object"communication"Pflicht
  • contactIdstringPflicht
  • typestringPflicht
    z. B. email, phone, letter, meeting, other
  • direction"incoming" | "outgoing" | nullPflicht
  • subjectstringPflicht
  • contentstringPflicht
  • datestring (date-time)Pflicht
    Zeitpunkt (ISO 8601)
  • createdAtstring (date-time)Pflicht
    Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/contacts/ID/communications' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "string",
  "subject": "string",
  "content": "string",
  "direction": "incoming",
  "date": "2026-11-01T09:30:00.000Z"
}'
Antwort 201
{
  "id": "string",
  "object": "communication",
  "contactId": "string",
  "type": "string",
  "direction": "incoming",
  "subject": "string",
  "content": "string",
  "date": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z"
}