Content-Type for URL-Encoded Form Data
Set the Content-Type header for application/x-www-form-urlencoded form submissions. Covers encoding rules and when to use this vs multipart.
Form Submissions
Detailed Explanation
URL-Encoded Form Data
application/x-www-form-urlencoded is the default Content-Type for HTML form submissions. Data is sent as key-value pairs with special characters percent-encoded.
The Header Value
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Encoding Rules
The body is a single string of key=value pairs joined by &:
username=john%40example.com&password=p%40ssw0rd&remember=true
Special characters are percent-encoded:
- Space becomes
+or%20 @becomes%40&becomes%26=becomes%3D
When to Use
Use URL-encoded form data when:
- Submitting simple HTML forms without file uploads
- Sending data to OAuth token endpoints (required by RFC 6749)
- Posting to legacy APIs that expect form data
- The payload consists only of text key-value pairs
When NOT to Use
Switch to multipart/form-data when:
- The form includes file uploads (
<input type="file">) - The payload contains binary data
- Individual values are very large (URL encoding adds ~3x overhead for non-ASCII characters)
curl Example
curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code&code=abc123&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback" \
https://auth.example.com/token
Use Case
Use this for standard HTML form submissions, OAuth 2.0 token requests, and any API that expects form-encoded data. This is the format used by browsers when submitting forms without the enctype attribute.