application/x-www-form-urlencoded URL-Encoded Form Data Flagship

What it's for

application/x-www-form-urlencoded is the default encoding for HTML form submissions — it's what your browser sends automatically when you submit a plain <form> without specifying a different enctype. It encodes field data as key=value pairs joined by &, with special characters percent-encoded, essentially the same encoding used in URL query strings, just placed in the request body instead of the URL.

Because it's the HTML default, it's still extremely common for simple forms (login, search, basic data entry) even in an era where JSON is the dominant format for programmatic API calls — the two coexist because they serve different origins: this one comes from actual browser form submission behavior, JSON from deliberate API design.

Format & syntax

Content-Type: application/x-www-form-urlencoded

username=alice&password=hunter2&remember=true

• Field names and values are joined with =, pairs joined with &
• Special characters (spaces, &, =, non-ASCII characters) are percent-encoded — a space becomes %20 or sometimes + depending on encoding convention
• No native support for nested structures or arrays without a convention layered on top (like items[]=a&items[]=b, which different frameworks handle somewhat inconsistently)

How it's used in practice

• Plain HTML form submissions — any <form> without an explicit enctype="multipart/form-data" attribute submits using this encoding by default, making it the baseline for the simplest, no-JavaScript form handling.
• OAuth2 token requests — several OAuth2 grant type exchanges (particularly the authorization code and client credentials flows) specify application/x-www-form-urlencoded for the token request body, a detail that trips up developers used to defaulting everything to JSON in modern API work.
• Simple API endpoints that mirror form submission behavior — some APIs, particularly older ones or ones designed to be directly submittable from an HTML form, accept this format specifically so a browser form can POST to them without any JavaScript intermediary.
• Search and filter query construction — the same encoding scheme used here underlies URL query string construction generally, so understanding this format helps with both form submission and general URL parameter encoding.

Common mistakes & gotchas

• Assuming modern APIs default to this format — most JSON-first REST APIs explicitly expect application/json, not this. If you're building a modern API client and things aren't parsing correctly, double check you're not accidentally sending form-encoded data to an endpoint expecting JSON, or vice versa.
• Struggling with nested data structures — this format has no standardized way to represent nested objects or arrays; different server frameworks handle bracket notation (user[name]=alice) differently or not at all, making it a poor fit for anything beyond flat key-value data.
• Forgetting OAuth2 token endpoints specifically require this format — a common integration bug: sending JSON to an OAuth2 token endpoint that strictly expects application/x-www-form-urlencoded per the OAuth2 spec, resulting in a rejected or misparsed request.
• Percent-encoding mistakes — manually constructing this format without using a proper encoding library/function can lead to unescaped special characters breaking the parsing on the receiving end, particularly with &, =, and + characters that have specific meaning in this format.

Comparison & FAQ

When should I use application/x-www-form-urlencoded instead of JSON?

When submitting a plain HTML form without file uploads (it's the browser default), or when integrating with a specific API/protocol (like OAuth2 token endpoints) that explicitly requires this format per its spec.

Can I send file uploads with application/x-www-form-urlencoded?

No — this format can't represent binary file content. Any form with a file input needs multipart/form-data instead, which is why HTML requires you to explicitly opt into enctype="multipart/form-data" for such forms.

Why does my OAuth2 token request fail when I send JSON?

Several OAuth2 grant types specify application/x-www-form-urlencoded as the required content type for the token request body per the OAuth2 spec — sending JSON instead will typically be rejected or fail to parse correctly by a compliant authorization server.

How do I represent nested objects in this format?

There's no universal standard — different frameworks handle bracket notation (address[city]=NYC) with varying levels of support, or you may need to flatten your data structure entirely. For genuinely nested data, JSON is a much better fit than trying to force it into this format.