Fixed: Enum Returned as a Number in a Minimal API's JSON

The response said "type": 0. The database row said Receipt, because I'd configured EF Core to store enums as strings. Nobody reading the API would know that 0 means a receipt, and adding a value in the middle of the enum would quietly change what every number means.

What I Was Doing

My .NET C# Web API on ASP.NET Core 10 returns stock movements, each with a Type enum. I recorded a delivery:

Request

POST http://localhost:5190/api/v1/products/9/stock/receipts
Content-Type: application/json

{"quantity":10,"reason":"First delivery","reference":"PO-1001"}

What I Expected

"type": "Receipt".

What I Got

Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: /api/v1/products/9/stock/movements

{
  "movement": {
    "id": 1,
    "productId": 9,
    "type": 0,
    "quantityChange": 10,
    "reason": "First delivery",
    "reference": "PO-1001",
    "orderId": null,
    "occurredAtUtc": "2026-11-05T05:11:52.204666Z"
  },
  "quantityOnHand": 10
}

What I Checked

The database. The column held the word Receipt, so this has nothing to do with EF Core's conversion.

The docs. JsonStringEnumConverter is the type that converts enumeration values to and from strings. System.Text.Json doesn't use it unless you ask.

Why It Happens

System.Text.Json writes an enum as its underlying number by default, and minimal APIs use its default settings unless told otherwise. What's in the database doesn't matter to it.

The Fix

Add the converter to the JSON options that minimal APIs use, in Program.cs:

src/Dewiride.Inventory.Api/Program.cs (excerpt)

// Enums travel as their names, such as "Receipt", not as numbers.
builder.Services.ConfigureHttpJsonOptions(options =>
    options.SerializerOptions.Converters.Add(new JsonStringEnumConverter()));

That covers every endpoint, in both directions. How to Return Enums as Strings in Minimal API JSON has what it accepts on the way in.

After the Fix

Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: /api/v1/products/9/stock/movements

{
  "movement": {
    "id": 2,
    "productId": 9,
    "type": "Receipt",
    "quantityChange": 5,
    "reason": "Second delivery",
    "reference": "PO-1003",
    "orderId": null,
    "occurredAtUtc": "2026-11-05T05:12:38.543732Z"
  },
  "quantityOnHand": 15
}

Common Mistakes

Mistake	What happens	Do this instead
Using [JsonConverter] on every enum	Easy to miss one	Register it once
Setting it on AddControllers in a minimal API	Minimal APIs don't read those options	Use ConfigureHttpJsonOptions
Assuming the EF Core conversion affects JSON	They're separate	Set both

Troubleshooting

Symptom	Likely cause	Fix
Numbers are still accepted in requests	The default converter allows them	new JsonStringEnumConverter(allowIntegerValues: false)
The query string behaves differently	JSON options don't apply there	The case-sensitivity fix
An undefined number in the query string is accepted	Enum parsing allows it	The fix

Conclusion

System.Text.Json writes enums as numbers unless told otherwise. Add JsonStringEnumConverter in ConfigureHttpJsonOptions, and every endpoint returns the names.

Additional Resources

• JsonStringEnumConverter — the converter.
• Configure JSON in minimal APIs — ConfigureHttpJsonOptions.

Related

• How to Return Enums as Strings in Minimal API JSON
• How to Store an Enum as a String with EF Core and MySQL
• Fixed: "Failed to bind parameter" for an Enum in a Minimal API Query String