FlowModels

Manage and delete end users via API: metadata, deletion and erasure receipt

Published on 11. November 2026

When a person closes their account in your application or requests the deletion of their data, you also need to remove their data from FlowModels. You can do this in the interface or automatically through the API. For each deletion, you get an erasure receipt that lets you prove later what was removed.

List and retrieve end users

Task Call
all end users GET /v1/end-users
create or fetch existing POST /v1/end-users
retrieve one end user GET /v1/end-users/{id}
change metadata or memories PATCH /v1/end-users/{id}
delete DELETE /v1/end-users/{id}

The list returns up to 100 entries per page. If has_more is true, fetch the next page with after and the UUID from last_id.

Each entry contains the id, your external_identifier and the metadata. For all calls with {id}, you need the id, not your own identifier. If you only know your identifier, POST /end-users with that identifier returns the existing end user including its id, without creating a second one.

Maintain metadata

With metadata, you store your own details about the end user, such as the plan from your system:

curl -X PATCH https://api.flowmodels.one/v1/end-users/018f1234-5678-7abc-9def-0123456789ab \
  -H "Authorization: Bearer at_your_key" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"plan": "business"}}'

New values are merged with the existing ones. Allowed are at most 50 entries, keys up to 64 characters and values as text up to 1,000 characters or null. In the same call, you can turn automatic memories on or off with memory_extraction_enabled. The external_identifier can't be changed.

Delete an end user

curl -X DELETE https://api.flowmodels.one/v1/end-users/018f1234-5678-7abc-9def-0123456789ab \
  -H "Authorization: Bearer at_your_key"

This removes this person's conversations, files and memories. It can't be undone. Billing and usage rows are kept for retention reasons, so your invoices stay correct.

The response "deleted": true confirms that the deletion has been started and the data is no longer used. We then remove stored files in the background. The erasure receipt shows you whether that has finished.

Retrieve the erasure receipt

curl https://api.flowmodels.one/v1/end_users/018f1234-5678-7abc-9def-0123456789ab/erasures \
  -H "Authorization: Bearer at_your_key"

Here too, note the underscore in end_users. The receipts remain available after the deletion, because that's exactly when you need the proof. You can fetch a single receipt with GET /end_users/{id}/erasures/{receipt}.

{
  "id": "018f9a2b-…",
  "object": "end_user.erasure",
  "status": "completed",
  "requested_at": "2026-11-05T08:15:00+00:00",
  "completed_at": "2026-11-05T08:15:04+00:00",
  "manifest_summary": {
    "resources": {
      "memories": {"before": 12, "after": 0},
      "end_user_files": {"before": 3, "after": 0}
    },
    "objects_remaining": 0
  }
}
  • status: pending (created), objects_pending (files are still being removed), completed (completed), objects_partial (partially completed) or failed (failed)
  • completed_at: time of completion, null while files are still being removed
  • manifest_summary.resources: the count before and after the deletion for each type of data
  • objects_remaining: how many stored objects are still open

The receipt contains only numbers, no text, no filenames and no identifiers. So you can safely keep it in your own deletion log.

In the interface

Under End users › Show details, you delete an end user by typing their identifier to confirm and clicking Delete end user. The Erasure runs section below the end-user list and in the details shows each run with Started, Status, Reason, Open objects and Finished. Details are in Manage the end users of your application.

A completed run removes the end user from the list, while the proof stays visible in the Erasure runs section, including for deletions through the API.

If something goes wrong

  • 404 end_user_not_found: The id doesn't exist or belongs to a different team. Check whether you're accidentally using your external_identifier instead of the id.
  • Status objects_partial or failed: Some of the files couldn't be removed yet. We retry temporary storage errors. If the status stays that way, contact support with the end user's id.

Was this article helpful?

Back to Webhooks, end users & MCP