Zum Inhalt springen
DebtFlow

Contacts

Customers and debtors (shared contact base).

List contacts

GET/api/v1/contacts

Customers, debtors and suppliers with key figures (number of debts, outstanding amount). Newest first.

Permission: contacts:read

Query parameters

  • qstring
    Search in name, company, email, phone, city, customer/supplier number
    max. 100 characters
  • role"customer" | "debtor" | "supplier"
  • archived"true" | "false" | "all"
    Include archived contacts
    Default: "false"
  • open"true" | "false"
    true = only with an outstanding amount, false = only without
  • sort"created_desc" | "name_asc" | "name_desc" | "open_desc" | "open_asc" | "updated_desc"
    Sort order: created_desc (default, newest first), name_asc, name_desc, open_desc, open_asc, updated_desc
    Default: "created_desc"
  • limitinteger
    Number of entries (1–100)
    1–100 · Default: 25
  • cursorstring
    `nextCursor` of the previous page
    max. 500 characters

Response 200

  • object"list"required
  • dataArray<Contact>required
    • idstringrequired
    • object"contact"required
    • kind"person" | "company"required
    • rolesArray<"customer" | "debtor" | "supplier">required
    • displayNamestringrequired
    • firstNamestringrequired
    • middleNamestringrequired
    • lastNamestringrequired
    • companystringrequired
    • genderstringrequired
    • birthDatestring (date) | nullrequired
      Date (YYYY-MM-DD)
    • birthPlacestringrequired
    • emailsArray<string>required
    • phonesArray<string>required
    • addressesArray<ContactAddress>required
      • typestringrequired
        home, work or other
        max. 20 characters · Default: "home"
      • streetstringrequired
        max. 160 characters · Default: ""
      • houseNumberstringrequired
        max. 20 characters · Default: ""
      • zipCodestringrequired
        max. 10 characters · Default: ""
      • citystringrequired
        max. 80 characters · Default: ""
      • countrystringrequired
        max. 60 characters · Default: "Deutschland"
    • socialsArray<SocialProfile>required
      • platformstringrequired
        max. 40 characters
      • usernamestringrequired
        max. 200 characters
    • notesstringrequired
    • language"de" | "en"required
      Correspondence language for dunning letters, letters, invoices and quotes (default de)
    • customerNumberstring | nullrequired
    • supplierNumberstring | nullrequired
    • vatIdstring | nullrequired
    • taxNumberstring | nullrequired
    • billingEmailstring | nullrequired
    • billingAddressPostalAddress | nullrequired
      • namestringrequired
        Company or name
        max. 160 characters
      • additionstring
        Address supplement, e.g. attn. / department
        max. 160 characters
      • streetstringrequired
        Street and house number
        max. 160 characters
      • zipCodestringrequired
        max. 10 characters
      • citystringrequired
        max. 80 characters
      • countrystringrequired
        Country code ISO 3166-1 alpha-2
        max. 2 characters · Default: "DE"
    • leitwegIdstring | nullrequired
    • paymentTermsDaysinteger | nullrequired
      -9007199254740991–9007199254740991
    • defaultTaxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable" | nullrequired
      Tax treatment of the receipt
    • priceMode"net" | "gross" | nullrequired
    • einvoicePreference"pdf" | "zugferd" | "xrechnung" | nullrequired
    • einvoiceRecipientType"business" | "public_authority" | nullrequired
      E-invoice recipient profile: business (B2B, no Leitweg-ID needed) or public_authority (B2G, Leitweg-ID required)
    • clientIdstring | nullrequired
      Client (collection agency/law firm)
    • archivedAtstring (date-time) | nullrequired
      Timestamp (ISO 8601)
    • statsContactStatsrequired
      • debtCountintegerrequired
        -9007199254740991–9007199254740991
      • openDebtCountintegerrequired
        -9007199254740991–9007199254740991
      • totalCentsintegerrequired
        Total principal
        -100000000000–100000000000
      • openCentsintegerrequired
        Outstanding including costs less payments
        -100000000000–100000000000
    • createdAtstring (date-time)required
      Timestamp (ISO 8601)
    • updatedAtstring (date-time)required
      Timestamp (ISO 8601)
  • hasMorebooleanrequired
  • nextCursorstring | nullrequired

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/contacts' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 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",
      "einvoiceRecipientType": "business",
      "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"
}

Create contact

POST/api/v1/contacts

The number of contacts is limited by your subscription plan (error plan_limit_reached).

Permission: contacts:write

Headers

  • Idempotency-Keystring
    Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
    max. 255 characters

Body (JSON) · ContactCreate

  • kind"person" | "company"
  • rolesArray<"customer" | "debtor" | "supplier">
  • firstNamestring
    max. 80 characters
  • middleNamestring
    max. 80 characters
  • lastNamestring
    max. 80 characters
  • companystring
    max. 160 characters
  • genderstring
    max. 20 characters
  • birthDatestring (date) | null
    Date (YYYY-MM-DD)
  • birthPlacestring
    max. 80 characters
  • emailsArray<string (email)>
    max. 254 characters
  • phonesArray<string>
    max. 40 characters
  • addressesArray<ContactAddress>
    • typestringrequired
      home, work or other
      max. 20 characters · Default: "home"
    • streetstringrequired
      max. 160 characters · Default: ""
    • houseNumberstringrequired
      max. 20 characters · Default: ""
    • zipCodestringrequired
      max. 10 characters · Default: ""
    • citystringrequired
      max. 80 characters · Default: ""
    • countrystringrequired
      max. 60 characters · Default: "Deutschland"
  • socialsArray<SocialProfile>
    • platformstringrequired
      max. 40 characters
    • usernamestringrequired
      max. 200 characters
  • notesstring
    max. 10000 characters
  • language"de" | "en"
    Correspondence language (de or en), default de
  • customerNumberstring | null
    max. 40 characters
  • supplierNumberstring | null
    max. 40 characters
  • vatIdstring | null
  • taxNumberstring | null
    max. 40 characters
  • billingEmailstring (email) | null
    max. 254 characters
  • billingAddressPostalAddress | null
    • namestringrequired
      Company or name
      max. 160 characters
    • additionstring
      Address supplement, e.g. attn. / department
      max. 160 characters
    • streetstringrequired
      Street and house number
      max. 160 characters
    • zipCodestringrequired
      max. 10 characters
    • citystringrequired
      max. 80 characters
    • countrystringrequired
      Country code ISO 3166-1 alpha-2
      max. 2 characters · Default: "DE"
  • leitwegIdstring | null
    max. 46 characters
  • paymentTermsDaysinteger | null
    0–365
  • defaultTaxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable" | null
    Tax treatment of the receipt
  • priceMode"net" | "gross" | null
  • einvoicePreference"pdf" | "zugferd" | "xrechnung" | null
  • einvoiceRecipientType"business" | "public_authority" | null
  • clientIdstring | null
    max. 128 characters

Response 201 · Contact

  • idstringrequired
  • object"contact"required
  • kind"person" | "company"required
  • rolesArray<"customer" | "debtor" | "supplier">required
  • displayNamestringrequired
  • firstNamestringrequired
  • middleNamestringrequired
  • lastNamestringrequired
  • companystringrequired
  • genderstringrequired
  • birthDatestring (date) | nullrequired
    Date (YYYY-MM-DD)
  • birthPlacestringrequired
  • emailsArray<string>required
  • phonesArray<string>required
  • addressesArray<ContactAddress>required
    • typestringrequired
      home, work or other
      max. 20 characters · Default: "home"
    • streetstringrequired
      max. 160 characters · Default: ""
    • houseNumberstringrequired
      max. 20 characters · Default: ""
    • zipCodestringrequired
      max. 10 characters · Default: ""
    • citystringrequired
      max. 80 characters · Default: ""
    • countrystringrequired
      max. 60 characters · Default: "Deutschland"
  • socialsArray<SocialProfile>required
    • platformstringrequired
      max. 40 characters
    • usernamestringrequired
      max. 200 characters
  • notesstringrequired
  • language"de" | "en"required
    Correspondence language for dunning letters, letters, invoices and quotes (default de)
  • customerNumberstring | nullrequired
  • supplierNumberstring | nullrequired
  • vatIdstring | nullrequired
  • taxNumberstring | nullrequired
  • billingEmailstring | nullrequired
  • billingAddressPostalAddress | nullrequired
    • namestringrequired
      Company or name
      max. 160 characters
    • additionstring
      Address supplement, e.g. attn. / department
      max. 160 characters
    • streetstringrequired
      Street and house number
      max. 160 characters
    • zipCodestringrequired
      max. 10 characters
    • citystringrequired
      max. 80 characters
    • countrystringrequired
      Country code ISO 3166-1 alpha-2
      max. 2 characters · Default: "DE"
  • leitwegIdstring | nullrequired
  • paymentTermsDaysinteger | nullrequired
    -9007199254740991–9007199254740991
  • defaultTaxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable" | nullrequired
    Tax treatment of the receipt
  • priceMode"net" | "gross" | nullrequired
  • einvoicePreference"pdf" | "zugferd" | "xrechnung" | nullrequired
  • einvoiceRecipientType"business" | "public_authority" | nullrequired
    E-invoice recipient profile: business (B2B, no Leitweg-ID needed) or public_authority (B2G, Leitweg-ID required)
  • clientIdstring | nullrequired
    Client (collection agency/law firm)
  • archivedAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • statsContactStatsrequired
    • debtCountintegerrequired
      -9007199254740991–9007199254740991
    • openDebtCountintegerrequired
      -9007199254740991–9007199254740991
    • totalCentsintegerrequired
      Total principal
      -100000000000–100000000000
    • openCentsintegerrequired
      Outstanding including costs less payments
      -100000000000–100000000000
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)
  • updatedAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 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",
  "einvoiceRecipientType": "business",
  "clientId": "string"
}'
Response 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",
  "einvoiceRecipientType": "business",
  "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"
}

Retrieve contact

GET/api/v1/contacts/{id}

Permission: contacts:read

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 200 · Contact

  • idstringrequired
  • object"contact"required
  • kind"person" | "company"required
  • rolesArray<"customer" | "debtor" | "supplier">required
  • displayNamestringrequired
  • firstNamestringrequired
  • middleNamestringrequired
  • lastNamestringrequired
  • companystringrequired
  • genderstringrequired
  • birthDatestring (date) | nullrequired
    Date (YYYY-MM-DD)
  • birthPlacestringrequired
  • emailsArray<string>required
  • phonesArray<string>required
  • addressesArray<ContactAddress>required
    • typestringrequired
      home, work or other
      max. 20 characters · Default: "home"
    • streetstringrequired
      max. 160 characters · Default: ""
    • houseNumberstringrequired
      max. 20 characters · Default: ""
    • zipCodestringrequired
      max. 10 characters · Default: ""
    • citystringrequired
      max. 80 characters · Default: ""
    • countrystringrequired
      max. 60 characters · Default: "Deutschland"
  • socialsArray<SocialProfile>required
    • platformstringrequired
      max. 40 characters
    • usernamestringrequired
      max. 200 characters
  • notesstringrequired
  • language"de" | "en"required
    Correspondence language for dunning letters, letters, invoices and quotes (default de)
  • customerNumberstring | nullrequired
  • supplierNumberstring | nullrequired
  • vatIdstring | nullrequired
  • taxNumberstring | nullrequired
  • billingEmailstring | nullrequired
  • billingAddressPostalAddress | nullrequired
    • namestringrequired
      Company or name
      max. 160 characters
    • additionstring
      Address supplement, e.g. attn. / department
      max. 160 characters
    • streetstringrequired
      Street and house number
      max. 160 characters
    • zipCodestringrequired
      max. 10 characters
    • citystringrequired
      max. 80 characters
    • countrystringrequired
      Country code ISO 3166-1 alpha-2
      max. 2 characters · Default: "DE"
  • leitwegIdstring | nullrequired
  • paymentTermsDaysinteger | nullrequired
    -9007199254740991–9007199254740991
  • defaultTaxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable" | nullrequired
    Tax treatment of the receipt
  • priceMode"net" | "gross" | nullrequired
  • einvoicePreference"pdf" | "zugferd" | "xrechnung" | nullrequired
  • einvoiceRecipientType"business" | "public_authority" | nullrequired
    E-invoice recipient profile: business (B2B, no Leitweg-ID needed) or public_authority (B2G, Leitweg-ID required)
  • clientIdstring | nullrequired
    Client (collection agency/law firm)
  • archivedAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • statsContactStatsrequired
    • debtCountintegerrequired
      -9007199254740991–9007199254740991
    • openDebtCountintegerrequired
      -9007199254740991–9007199254740991
    • totalCentsintegerrequired
      Total principal
      -100000000000–100000000000
    • openCentsintegerrequired
      Outstanding including costs less payments
      -100000000000–100000000000
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)
  • updatedAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/contacts/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 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",
  "einvoiceRecipientType": "business",
  "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"
}

Update contact

PATCH/api/v1/contacts/{id}

Only the fields you send are changed; null clears an optional field. archived: true archives the contact.

Permission: contacts:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Body (JSON) · ContactUpdate

  • kind"person" | "company"
  • rolesArray<"customer" | "debtor" | "supplier">
  • firstNamestring
    max. 80 characters
  • middleNamestring
    max. 80 characters
  • lastNamestring
    max. 80 characters
  • companystring
    max. 160 characters
  • genderstring
    max. 20 characters
  • birthDatestring (date) | null
    Date (YYYY-MM-DD)
  • birthPlacestring
    max. 80 characters
  • emailsArray<string (email)>
    max. 254 characters
  • phonesArray<string>
    max. 40 characters
  • addressesArray<ContactAddress>
    • typestringrequired
      home, work or other
      max. 20 characters · Default: "home"
    • streetstringrequired
      max. 160 characters · Default: ""
    • houseNumberstringrequired
      max. 20 characters · Default: ""
    • zipCodestringrequired
      max. 10 characters · Default: ""
    • citystringrequired
      max. 80 characters · Default: ""
    • countrystringrequired
      max. 60 characters · Default: "Deutschland"
  • socialsArray<SocialProfile>
    • platformstringrequired
      max. 40 characters
    • usernamestringrequired
      max. 200 characters
  • notesstring
    max. 10000 characters
  • language"de" | "en"
    Correspondence language (de or en), default de
  • customerNumberstring | null
    max. 40 characters
  • supplierNumberstring | null
    max. 40 characters
  • vatIdstring | null
  • taxNumberstring | null
    max. 40 characters
  • billingEmailstring (email) | null
    max. 254 characters
  • billingAddressPostalAddress | null
    • namestringrequired
      Company or name
      max. 160 characters
    • additionstring
      Address supplement, e.g. attn. / department
      max. 160 characters
    • streetstringrequired
      Street and house number
      max. 160 characters
    • zipCodestringrequired
      max. 10 characters
    • citystringrequired
      max. 80 characters
    • countrystringrequired
      Country code ISO 3166-1 alpha-2
      max. 2 characters · Default: "DE"
  • leitwegIdstring | null
    max. 46 characters
  • paymentTermsDaysinteger | null
    0–365
  • defaultTaxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable" | null
    Tax treatment of the receipt
  • priceMode"net" | "gross" | null
  • einvoicePreference"pdf" | "zugferd" | "xrechnung" | null
  • einvoiceRecipientType"business" | "public_authority" | null
  • clientIdstring | null
    max. 128 characters
  • archivedboolean
    true archives, false restores

Response 200 · Contact

  • idstringrequired
  • object"contact"required
  • kind"person" | "company"required
  • rolesArray<"customer" | "debtor" | "supplier">required
  • displayNamestringrequired
  • firstNamestringrequired
  • middleNamestringrequired
  • lastNamestringrequired
  • companystringrequired
  • genderstringrequired
  • birthDatestring (date) | nullrequired
    Date (YYYY-MM-DD)
  • birthPlacestringrequired
  • emailsArray<string>required
  • phonesArray<string>required
  • addressesArray<ContactAddress>required
    • typestringrequired
      home, work or other
      max. 20 characters · Default: "home"
    • streetstringrequired
      max. 160 characters · Default: ""
    • houseNumberstringrequired
      max. 20 characters · Default: ""
    • zipCodestringrequired
      max. 10 characters · Default: ""
    • citystringrequired
      max. 80 characters · Default: ""
    • countrystringrequired
      max. 60 characters · Default: "Deutschland"
  • socialsArray<SocialProfile>required
    • platformstringrequired
      max. 40 characters
    • usernamestringrequired
      max. 200 characters
  • notesstringrequired
  • language"de" | "en"required
    Correspondence language for dunning letters, letters, invoices and quotes (default de)
  • customerNumberstring | nullrequired
  • supplierNumberstring | nullrequired
  • vatIdstring | nullrequired
  • taxNumberstring | nullrequired
  • billingEmailstring | nullrequired
  • billingAddressPostalAddress | nullrequired
    • namestringrequired
      Company or name
      max. 160 characters
    • additionstring
      Address supplement, e.g. attn. / department
      max. 160 characters
    • streetstringrequired
      Street and house number
      max. 160 characters
    • zipCodestringrequired
      max. 10 characters
    • citystringrequired
      max. 80 characters
    • countrystringrequired
      Country code ISO 3166-1 alpha-2
      max. 2 characters · Default: "DE"
  • leitwegIdstring | nullrequired
  • paymentTermsDaysinteger | nullrequired
    -9007199254740991–9007199254740991
  • defaultTaxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable" | nullrequired
    Tax treatment of the receipt
  • priceMode"net" | "gross" | nullrequired
  • einvoicePreference"pdf" | "zugferd" | "xrechnung" | nullrequired
  • einvoiceRecipientType"business" | "public_authority" | nullrequired
    E-invoice recipient profile: business (B2B, no Leitweg-ID needed) or public_authority (B2G, Leitweg-ID required)
  • clientIdstring | nullrequired
    Client (collection agency/law firm)
  • archivedAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • statsContactStatsrequired
    • debtCountintegerrequired
      -9007199254740991–9007199254740991
    • openDebtCountintegerrequired
      -9007199254740991–9007199254740991
    • totalCentsintegerrequired
      Total principal
      -100000000000–100000000000
    • openCentsintegerrequired
      Outstanding including costs less payments
      -100000000000–100000000000
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)
  • updatedAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 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",
  "einvoiceRecipientType": "business",
  "clientId": "string",
  "archived": false
}'
Response 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",
  "einvoiceRecipientType": "business",
  "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"
}

Delete contact

DELETE/api/v1/contacts/{id}

Deletes the contact and all associated debts (as in the dashboard). To hide it instead, archive it.

Permission: contacts:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 204

Success, no content

Possible errors: 400, 401, 403, 404, 409, 429, 500

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

Communications with a contact

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

Logged communications (phone calls, emails, letters, meetings), newest first.

Permission: contacts:read

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Query parameters

  • limitinteger
    Number of entries (1–100)
    1–100 · Default: 25
  • cursorstring
    `nextCursor` of the previous page
    max. 500 characters

Response 200

  • object"list"required
  • dataArray<Communication>required
    • idstringrequired
    • object"communication"required
    • contactIdstringrequired
    • typestringrequired
      e.g. email, phone, letter, meeting, other
    • direction"incoming" | "outgoing" | nullrequired
    • subjectstringrequired
    • contentstringrequired
    • datestring (date-time)required
      Timestamp (ISO 8601)
    • createdAtstring (date-time)required
      Timestamp (ISO 8601)
  • hasMorebooleanrequired
  • nextCursorstring | nullrequired

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/contacts/ID/communications' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 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"
}

Log communication

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

Creates an entry in the communication log (nothing is sent). Event communication.created.

Permission: contacts:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Headers

  • Idempotency-Keystring
    Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
    max. 255 characters

Body (JSON) · CommunicationCreate

  • typestringrequired
    max. 40 characters
  • subjectstringrequired
    max. 300 characters
  • contentstring
    max. 10000 characters
  • direction"incoming" | "outgoing"
  • datestring (date-time)
    Time of the communication (default: now)

Response 201 · Communication

  • idstringrequired
  • object"communication"required
  • contactIdstringrequired
  • typestringrequired
    e.g. email, phone, letter, meeting, other
  • direction"incoming" | "outgoing" | nullrequired
  • subjectstringrequired
  • contentstringrequired
  • datestring (date-time)required
    Timestamp (ISO 8601)
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 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"
}'
Response 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"
}