You send an API request and the docs say to put your data "in the payload." Meanwhile some values go in the URL and others in headers, and mixing them up produces 400 errors that say nothing useful. Here is what a request payload is and how to decide what goes where.
What is a request payload?
A request payload is the data a client sends in the body of an HTTP request, separate from the URL and the headers. It carries the actual content of the operation, most often as JSON: the fields of a record to create, the parameters of a job to run, the message to send.
In this request, everything between the braces is the payload:
POST /users with body {"name": "Ada", "email": "ada@example.com", "plan": "starter"}
The server reads the Content-Type header, here application/json, to know how to parse it. The response body coming back is likewise called the response payload; together they are the meaningful cargo of the exchange, which is why the general term is payload.
Payload vs headers vs URL parameters
The three places data can travel in a request split by role. The URL says which resource you mean, headers describe the request itself, and the payload carries the content. Keeping each kind of data in its place is what makes an API predictable to callers and easy to cache, log, and debug.
- URL path and query parameters: identity and filtering. /users/42?fields=name,email names the record and trims the response. Visible in logs and shareable, so never put secrets here unless the API is designed for it.
- Headers: metadata about the request: authentication tokens, Content-Type, accepted languages, client identifiers.
- Payload (body): the data being created, updated, or processed. Arbitrary size and structure, invisible to URL logging.
Which requests carry a payload?
POST, PUT, and PATCH requests carry payloads; that is their job. GET and DELETE requests conventionally do not: a GET describes what to fetch entirely through its URL. Most servers, proxies, and caches either ignore or reject a GET body, so if you feel the need for one, the operation probably wants to be a POST.
Payload formats
JSON dominates modern APIs because every language parses it and humans can read it. You will still meet application/x-www-form-urlencoded (classic HTML form posts), multipart/form-data (file uploads), XML in older enterprise systems, and compact binary formats like Protocol Buffers between internal services. Whatever the format, the Content-Type header must match the bytes you send, or the server answers with a 400 Bad Request or 415 Unsupported Media Type.
Keeping payloads sane
Three habits prevent most payload bugs. Validate on both sides: the client checks shape before sending, the server never trusts what arrives. Keep payloads small: send the fields the operation needs, not your whole object graph, and paginate anything list-shaped. And version deliberately: adding fields is safe, renaming or removing them breaks every existing caller.
Well-designed payloads are also flat where possible. A response like Abstract's email validation result, a single JSON object with named fields such as deliverability and is_disposable_email, is one request and one parse, with no nesting to unwind.
Frequently Asked Questions
What is the difference between a payload and a body?
In everyday API usage they are the same thing: the data section of the request or response. Strictly, "body" is the HTTP message part and "payload" is the meaningful data it carries, but the terms are used interchangeably.
Can a GET request have a payload?
Technically the spec does not forbid it, but the ecosystem does: many servers, proxies, and SDKs drop or reject GET bodies. Put inputs in query parameters, or use POST when the input is large or sensitive.
What format should a request payload use?
JSON, unless the API demands otherwise. Set Content-Type: application/json, encode as UTF-8, and match the exact field names in the API's documentation, including case.
Is there a size limit for request payloads?
HTTP itself sets none, but servers do: common defaults are 1 MB to 100 MB depending on the stack, and a 413 Content Too Large tells you that you hit one. For big files, use multipart uploads or a dedicated upload endpoint.
Why does my payload cause a 400 error?
The usual causes: invalid JSON (a trailing comma, unquoted key, or wrong quotes), a Content-Type header that does not match the body, or missing required fields. Validate the JSON first, then compare field names against the docs character by character.
Do payloads need to be encrypted?
Yes, in transit, which HTTPS handles for the whole request including the payload. Beyond transport, avoid putting data in a payload the receiving service does not need, especially credentials or personal data.
