Research – API reference

Address research results

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

Addresses found for a contact, newest first.

Permission: research: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<AddressResearchResult>required
- idstringrequired
- object"address_research"required
- contactIdstringrequired
- streetstringrequired
- zipCodestringrequired
- citystringrequired
- countrystringrequired
- sourcestring | nullrequired
- 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/address-research' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 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"
}

Residents’ registration office requests for a contact

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

Permission: research: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<ResidenceRegistryInquiry>required
- idstringrequired
- object"residence_registry_inquiry"required
- contactIdstringrequired
- debtIdstring | nullrequired
- status"pending" | "processing" | "completed" | "failed"required
- referenceNumberstringrequired
- costCentsintegerrequired
  Net price (plus VAT)
  -100000000000–100000000000
- currency"EUR"required
- isPaidbooleanrequired
- notesstringrequired
- lastKnownAddressobject | nullrequired
  - streetstringrequired
  - houseNumberstringrequired
  - zipCodestringrequired
  - citystringrequired
  - countrystringrequired
  - sourcestringrequired
- resultstring | nullrequired
  Information from the residents’ register (once completed)
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
- completedAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
- paidAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
hasMorebooleanrequired
nextCursorstring | nullrequired

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

Response 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"
}

Order residents’ registration office request (paid)

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

Orders information from the residents’ registration office (Melderegisteranfrage beim Einwohnermeldeamt): €19.99 plus VAT per request, takes about 4–5 working days. Requires a date of birth and a known address on the contact (otherwise 422 missing_contact_data). Only one open request per contact (otherwise 409 inquiry_in_progress). Without lastKnownAddress, the latest research result or the first address is used. Protect against duplicate orders with an Idempotency-Key. Event residence_registry_inquiry.created. Blocked in the demo account.

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

debtIdstring
Debt for which the request is made
max. 128 characters
notesstring
max. 2000 characters
lastKnownAddressInquiryAddress
Default: latest research result, otherwise the contact’s first address
- streetstringrequired
  max. 160 characters
- houseNumberstring
  max. 20 characters · Default: ""
- zipCodestringrequired
  max. 10 characters
- citystringrequired
  max. 80 characters
- countrystring
  max. 60 characters · Default: "Deutschland"
- sourcestring
  Source, e.g. direct or address-research
  max. 40 characters · Default: "direct"

Response 201 · ResidenceRegistryInquiry

idstringrequired
object"residence_registry_inquiry"required
contactIdstringrequired
debtIdstring | nullrequired
status"pending" | "processing" | "completed" | "failed"required
referenceNumberstringrequired
costCentsintegerrequired
Net price (plus VAT)
-100000000000–100000000000
currency"EUR"required
isPaidbooleanrequired
notesstringrequired
lastKnownAddressobject | nullrequired
- streetstringrequired
- houseNumberstringrequired
- zipCodestringrequired
- citystringrequired
- countrystringrequired
- sourcestringrequired
resultstring | nullrequired
Information from the residents’ register (once completed)
createdAtstring (date-time)required
Timestamp (ISO 8601)
completedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
paidAtstring (date-time) | nullrequired
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/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"
  }
}'

Response 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"
}

Retrieve residents’ registration office request

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

Permission: research:read

Path parameters

idstringrequired
max. 128 characters
inquiryIdstringrequired
max. 128 characters

Response 200 · ResidenceRegistryInquiry

idstringrequired
object"residence_registry_inquiry"required
contactIdstringrequired
debtIdstring | nullrequired
status"pending" | "processing" | "completed" | "failed"required
referenceNumberstringrequired
costCentsintegerrequired
Net price (plus VAT)
-100000000000–100000000000
currency"EUR"required
isPaidbooleanrequired
notesstringrequired
lastKnownAddressobject | nullrequired
- streetstringrequired
- houseNumberstringrequired
- zipCodestringrequired
- citystringrequired
- countrystringrequired
- sourcestringrequired
resultstring | nullrequired
Information from the residents’ register (once completed)
createdAtstring (date-time)required
Timestamp (ISO 8601)
completedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
paidAtstring (date-time) | nullrequired
Timestamp (ISO 8601)

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

Response 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"
}

Delete residents’ registration office request

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

Removes the request from the overview. Requests that have already been ordered are not cancelled by this.

Permission: research:write

Path parameters

idstringrequired
max. 128 characters
inquiryIdstringrequired
max. 128 characters

Response 204

Success, no content

Possible errors: 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 profiles of a contact

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

Permission: research: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<SocialMediaProfile>required
- idstringrequired
- object"social_profile"required
- contactIdstringrequired
- platformstringrequired
- usernamestringrequired
- urlstringrequired
- activebooleanrequired
- notesstringrequired
- isPremiumbooleanrequired
  Premium monitoring (Instagram only)
- verifiedbooleanrequired
- lastCheckedstring (date-time) | nullrequired
  Timestamp (ISO 8601)
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
- updatedAtstring (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/social-profiles' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 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"
}

Add social media profile

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

isPremium (premium monitoring) only applies to Instagram. Event contact.updated.

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

platformstringrequired
max. 40 characters
usernamestringrequired
max. 200 characters
urlstringrequired
max. 500 characters
activeboolean
notesstring
max. 2000 characters
isPremiumboolean

Response 201 · SocialMediaProfile

idstringrequired
object"social_profile"required
contactIdstringrequired
platformstringrequired
usernamestringrequired
urlstringrequired
activebooleanrequired
notesstringrequired
isPremiumbooleanrequired
Premium monitoring (Instagram only)
verifiedbooleanrequired
lastCheckedstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (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/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
}'

Response 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"
}

Update social media profile

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

Permission: research:write

Path parameters

idstringrequired
max. 128 characters
profileIdstringrequired
max. 64 characters

Body (JSON) · SocialMediaProfileUpdate

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

Response 200 · SocialMediaProfile

idstringrequired
object"social_profile"required
contactIdstringrequired
platformstringrequired
usernamestringrequired
urlstringrequired
activebooleanrequired
notesstringrequired
isPremiumbooleanrequired
Premium monitoring (Instagram only)
verifiedbooleanrequired
lastCheckedstring (date-time) | nullrequired
Timestamp (ISO 8601)
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/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
}'

Response 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"
}

Remove social media profile

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

Permission: research:write

Path parameters

idstringrequired
max. 128 characters
profileIdstringrequired
max. 64 characters

Response 204

Success, no content

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