Recherche – API-Referenz

Ergebnisse der Adressrecherche

GET/api/v1/contacts/{id}/address-research

Gefundene Anschriften zu einem Kontakt, neueste zuerst.

Berechtigung: research: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<AddressResearchResult>Pflicht
- idstringPflicht
- object"address_research"Pflicht
- contactIdstringPflicht
- streetstringPflicht
- zipCodestringPflicht
- citystringPflicht
- countrystringPflicht
- sourcestring | nullPflicht
- 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/address-research' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "address_research",
      "contactId": "string",
      "street": "string",
      "zipCode": "string",
      "city": "string",
      "country": "string",
      "source": "string",
      "createdAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Melderegisteranfragen eines Kontakts

GET/api/v1/contacts/{id}/residence-registry-inquiries

Berechtigung: research: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<ResidenceRegistryInquiry>Pflicht
- idstringPflicht
- object"residence_registry_inquiry"Pflicht
- contactIdstringPflicht
- debtIdstring | nullPflicht
- status"pending" | "processing" | "completed" | "failed"Pflicht
- referenceNumberstringPflicht
- costCentsintegerPflicht
  Preis netto (zzgl. MwSt.)
  -100000000000–100000000000
- currency"EUR"Pflicht
- isPaidbooleanPflicht
- notesstringPflicht
- lastKnownAddressobject | nullPflicht
  - streetstringPflicht
  - houseNumberstringPflicht
  - zipCodestringPflicht
  - citystringPflicht
  - countrystringPflicht
  - sourcestringPflicht
- resultstring | nullPflicht
  Auskunft des Melderegisters (sobald abgeschlossen)
- createdAtstring (date-time)Pflicht
  Zeitpunkt (ISO 8601)
- completedAtstring (date-time) | nullPflicht
  Zeitpunkt (ISO 8601)
- paidAtstring (date-time) | nullPflicht
  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/residence-registry-inquiries' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "residence_registry_inquiry",
      "contactId": "string",
      "debtId": "string",
      "status": "pending",
      "referenceNumber": "string",
      "costCents": 0,
      "currency": "EUR",
      "isPaid": false,
      "notes": "string",
      "lastKnownAddress": {
        "street": "string",
        "houseNumber": "string",
        "zipCode": "string",
        "city": "string",
        "country": "string",
        "source": "string"
      },
      "result": "string",
      "createdAt": "2026-11-01T09:30:00.000Z",
      "completedAt": "2026-11-01T09:30:00.000Z",
      "paidAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Melderegisteranfrage beauftragen (kostenpflichtig)

POST/api/v1/contacts/{id}/residence-registry-inquiries

Beauftragt eine Auskunft beim Einwohnermeldeamt: 19,99 € zzgl. MwSt. je Anfrage, Dauer etwa 4–5 Werktage. Voraussetzung: Geburtsdatum und eine bekannte Anschrift am Kontakt (sonst 422 missing_contact_data). Je Kontakt nur eine offene Anfrage (sonst 409 inquiry_in_progress). Ohne lastKnownAddress wird das neueste Rechercheergebnis bzw. die erste Anschrift verwendet. Mit Idempotency-Key gegen doppelte Beauftragung absichern. Ereignis residence_registry_inquiry.created. Im Demo-Konto gesperrt.

Berechtigung: research: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) · ResidenceRegistryInquiryCreate

debtIdstring
Forderung, für die angefragt wird
max. 128 Zeichen
notesstring
max. 2000 Zeichen
lastKnownAddressInquiryAddress
Standard: neuestes Rechercheergebnis, sonst erste Anschrift des Kontakts
- streetstringPflicht
  max. 160 Zeichen
- houseNumberstring
  max. 20 Zeichen · Standard: ""
- zipCodestringPflicht
  max. 10 Zeichen
- citystringPflicht
  max. 80 Zeichen
- countrystring
  max. 60 Zeichen · Standard: "Deutschland"
- sourcestring
  Herkunft, z. B. direct oder address-research
  max. 40 Zeichen · Standard: "direct"

Antwort 201 · ResidenceRegistryInquiry

idstringPflicht
object"residence_registry_inquiry"Pflicht
contactIdstringPflicht
debtIdstring | nullPflicht
status"pending" | "processing" | "completed" | "failed"Pflicht
referenceNumberstringPflicht
costCentsintegerPflicht
Preis netto (zzgl. MwSt.)
-100000000000–100000000000
currency"EUR"Pflicht
isPaidbooleanPflicht
notesstringPflicht
lastKnownAddressobject | nullPflicht
- streetstringPflicht
- houseNumberstringPflicht
- zipCodestringPflicht
- citystringPflicht
- countrystringPflicht
- sourcestringPflicht
resultstring | nullPflicht
Auskunft des Melderegisters (sobald abgeschlossen)
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
completedAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
paidAtstring (date-time) | nullPflicht
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/residence-registry-inquiries' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "debtId": "string",
  "notes": "string",
  "lastKnownAddress": {
    "street": "string",
    "houseNumber": "",
    "zipCode": "string",
    "city": "string",
    "country": "Deutschland",
    "source": "direct"
  }
}'

Antwort 201

{
  "id": "string",
  "object": "residence_registry_inquiry",
  "contactId": "string",
  "debtId": "string",
  "status": "pending",
  "referenceNumber": "string",
  "costCents": 0,
  "currency": "EUR",
  "isPaid": false,
  "notes": "string",
  "lastKnownAddress": {
    "street": "string",
    "houseNumber": "string",
    "zipCode": "string",
    "city": "string",
    "country": "string",
    "source": "string"
  },
  "result": "string",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "completedAt": "2026-11-01T09:30:00.000Z",
  "paidAt": "2026-11-01T09:30:00.000Z"
}

Melderegisteranfrage abrufen

GET/api/v1/contacts/{id}/residence-registry-inquiries/{inquiryId}

Berechtigung: research:read

Pfadparameter

idstringPflicht
max. 128 Zeichen
inquiryIdstringPflicht
max. 128 Zeichen

Antwort 200 · ResidenceRegistryInquiry

idstringPflicht
object"residence_registry_inquiry"Pflicht
contactIdstringPflicht
debtIdstring | nullPflicht
status"pending" | "processing" | "completed" | "failed"Pflicht
referenceNumberstringPflicht
costCentsintegerPflicht
Preis netto (zzgl. MwSt.)
-100000000000–100000000000
currency"EUR"Pflicht
isPaidbooleanPflicht
notesstringPflicht
lastKnownAddressobject | nullPflicht
- streetstringPflicht
- houseNumberstringPflicht
- zipCodestringPflicht
- citystringPflicht
- countrystringPflicht
- sourcestringPflicht
resultstring | nullPflicht
Auskunft des Melderegisters (sobald abgeschlossen)
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
completedAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
paidAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)

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

curl 'https://www.debt-flow.io/api/v1/contacts/ID/residence-registry-inquiries/INQUIRYID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "id": "string",
  "object": "residence_registry_inquiry",
  "contactId": "string",
  "debtId": "string",
  "status": "pending",
  "referenceNumber": "string",
  "costCents": 0,
  "currency": "EUR",
  "isPaid": false,
  "notes": "string",
  "lastKnownAddress": {
    "street": "string",
    "houseNumber": "string",
    "zipCode": "string",
    "city": "string",
    "country": "string",
    "source": "string"
  },
  "result": "string",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "completedAt": "2026-11-01T09:30:00.000Z",
  "paidAt": "2026-11-01T09:30:00.000Z"
}

Melderegisteranfrage löschen

DELETE/api/v1/contacts/{id}/residence-registry-inquiries/{inquiryId}

Entfernt die Anfrage aus der Übersicht. Bereits beauftragte Anfragen werden dadurch nicht storniert.

Berechtigung: research:write

Pfadparameter

idstringPflicht
max. 128 Zeichen
inquiryIdstringPflicht
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/residence-registry-inquiries/INQUIRYID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Social-Media-Profile eines Kontakts

GET/api/v1/contacts/{id}/social-profiles

Berechtigung: research: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<SocialMediaProfile>Pflicht
- idstringPflicht
- object"social_profile"Pflicht
- contactIdstringPflicht
- platformstringPflicht
- usernamestringPflicht
- urlstringPflicht
- activebooleanPflicht
- notesstringPflicht
- isPremiumbooleanPflicht
  Premium-Überwachung (nur Instagram)
- verifiedbooleanPflicht
- lastCheckedstring (date-time) | nullPflicht
  Zeitpunkt (ISO 8601)
- createdAtstring (date-time)Pflicht
  Zeitpunkt (ISO 8601)
- updatedAtstring (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/social-profiles' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "social_profile",
      "contactId": "string",
      "platform": "string",
      "username": "string",
      "url": "string",
      "active": false,
      "notes": "string",
      "isPremium": false,
      "verified": false,
      "lastChecked": "2026-11-01T09:30:00.000Z",
      "createdAt": "2026-11-01T09:30:00.000Z",
      "updatedAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Social-Media-Profil hinzufügen

POST/api/v1/contacts/{id}/social-profiles

isPremium (Premium-Überwachung) gilt nur für Instagram. Ereignis contact.updated.

Berechtigung: research: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) · SocialMediaProfileCreate

platformstringPflicht
max. 40 Zeichen
usernamestringPflicht
max. 200 Zeichen
urlstringPflicht
max. 500 Zeichen
activeboolean
notesstring
max. 2000 Zeichen
isPremiumboolean

Antwort 201 · SocialMediaProfile

idstringPflicht
object"social_profile"Pflicht
contactIdstringPflicht
platformstringPflicht
usernamestringPflicht
urlstringPflicht
activebooleanPflicht
notesstringPflicht
isPremiumbooleanPflicht
Premium-Überwachung (nur Instagram)
verifiedbooleanPflicht
lastCheckedstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
updatedAtstring (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/social-profiles' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "platform": "string",
  "username": "string",
  "url": "string",
  "active": false,
  "notes": "string",
  "isPremium": false
}'

Antwort 201

{
  "id": "string",
  "object": "social_profile",
  "contactId": "string",
  "platform": "string",
  "username": "string",
  "url": "string",
  "active": false,
  "notes": "string",
  "isPremium": false,
  "verified": false,
  "lastChecked": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Social-Media-Profil ändern

PATCH/api/v1/contacts/{id}/social-profiles/{profileId}

Berechtigung: research:write

Pfadparameter

idstringPflicht
max. 128 Zeichen
profileIdstringPflicht
max. 64 Zeichen

Body (JSON) · SocialMediaProfileUpdate

platformstring
max. 40 Zeichen
usernamestring
max. 200 Zeichen
urlstring
max. 500 Zeichen
activeboolean
notesstring
max. 2000 Zeichen
isPremiumboolean

Antwort 200 · SocialMediaProfile

idstringPflicht
object"social_profile"Pflicht
contactIdstringPflicht
platformstringPflicht
usernamestringPflicht
urlstringPflicht
activebooleanPflicht
notesstringPflicht
isPremiumbooleanPflicht
Premium-Überwachung (nur Instagram)
verifiedbooleanPflicht
lastCheckedstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
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/social-profiles/PROFILEID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "platform": "string",
  "username": "string",
  "url": "string",
  "active": false,
  "notes": "string",
  "isPremium": false
}'

Antwort 200

{
  "id": "string",
  "object": "social_profile",
  "contactId": "string",
  "platform": "string",
  "username": "string",
  "url": "string",
  "active": false,
  "notes": "string",
  "isPremium": false,
  "verified": false,
  "lastChecked": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Social-Media-Profil entfernen

DELETE/api/v1/contacts/{id}/social-profiles/{profileId}

Berechtigung: research:write

Pfadparameter

idstringPflicht
max. 128 Zeichen
profileIdstringPflicht
max. 64 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/social-profiles/PROFILEID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"