How to Send a cURL POST Request

cURL is a command line tool that lets you send requests to a server. It comes pre-installed in most modern operating systems, so it’s a great starting point for many networking projects.

While there are applications that perform the same goal with a fancier UI (e.g., Postman ), cURL is more reliable and lower-level, making it a strong choice for automation and many other use cases.

Getting Started With cURL

cURL comes pre-installed in Windows 10 (and onwards) and most MacOS operating systems. Some Linux distributions may offer to install cURL, however, in many cases, you’ll have to do it yourself by running the installation command:

sudo apt-get install curl

For older Windows versions, you can download cURL from their official website. Once you’ve installed cURL, you can begin sending requests.

Finally, verify that everything is installed correctly by opening the terminal and inputting:

curl --help

On Windows, it’s better to use the Command Prompt instead of Powershell as the latter requires different formatting than displayed in the rest of this article.

Sending a cURL POST Request

All cURL usage follows the same structure—invoking cURL itself, setting the request options, the URL, followed by additional options such as headers.

curl [request options] [URL] [other options]

Some options, such as the aforementioned “–help”, allow you to perform actions without URLs, but they won’t be used to send a cURL POST request.

There are three requirements for a POST request:

1. -X and POST

The former indicates you intend to send a request and the latter the request method.

2. -d and some string

The former indicates that you intend to send some data and the string value is the content. Every cURL POST request has to have some data that’s being sent. cURL POST data can be any string, however, APIs usually have their formatting requirements, so you’ll have to read the documentation.

3. URL

Usually, the API you’re sending your POST requests to.

For testing purposes, we’ll be using the sample ReqBin API URL. To send the most basic POST cURL request, simply type in:

curl -X POST https://reqbin.com/echo/post/json -d "YOUR_STRING"

Many APIs will require you to send data in a JSON format, which you can do by formatting the data value as such:

curl -X POST https://reqbin.com/echo/post/json -d '{"KEY":"VALUE", "KEY":"VALUE"}'

Adjusting a cURL POST Request With Advanced Settings

Some APIs will give (or require) more options to fully utilize their capabilities. A common POST request method requirement is to add headers.

You can do that by adding an “-H” and supplying header information:

curl -X POST https://reqbin.com/echo/post/json -d "YOUR_STRING" -H "Content-Type: application/json"

You can also supply information such as user agents (e.g., ‘User Agent: Chrome’) and the accepted character set (e.g., ‘Accept-Charset: utf-8’). The “-H” option has to be included with each type of header:

curl -X POST https://reqbin.com/echo/post/json -d '{"KEY":"VALUE", "KEY":"VALUE"}' -H "Content-Type: application/json" -H "Accept-Charset: utf-8"

Additionally, many APIs will have some form of authentication before you submit any request method. Usernames and passwords are a common option, which can be included as such:

curl --user "USERNAME:PASSWORD" -X POST https://reqbin.com/echo/post/json -d '{"KEY":"VALUE", "KEY":"VALUE"}' -H "Content-Type: application/json"

Another common option used for authentication is to send a specific header with an API access token. It’ll usually look something like this:

curl -X POST https://reqbin.com/echo/post/json -d '{"KEY":"VALUE", "KEY":"VALUE"}' -H "Content-Type: application/json" -H "API-Access-Token: YOUR_TOKEN"

Finally, you can use cURL to POST data from a file. You can do so by adding either “-d” or “-F”. Usually, the “-F” option is used:

curl -F "data=@path/to/local/file" https://reqbin.com/echo/post/json

Error Handling

Whenever something goes wrong, cURL will automatically generate some form of response. You can view them in the terminal and look for error messages in the cURL POST body response.

For example, if you were to send a cURL POST request to Google’s domain without any data, you’d receive:

<title>Error 411 (Length Required)!!1</title>
[...]
<p>POST requests require a <code>Content-length</code> header.  <ins>That's all we know.</ins>

Similarly, a cURL POST request with some data will give you a different error, stating that you’re not allowed to do that:

<title>Error 405 (Method Not Allowed)!!1</title>
[...]
<p>The request method <code>--POST</code> is inappropriate for the URL <code>/</code>.  
<ins>That's all we know.</ins>

Some APIs may provide the generic HTTP errors while others will have custom-made responses informing you on how to change the request.

Wrapping Up

While we have overviewed many of the options, there’s even more available in cURL’s documentation . In practice, however, you’ll mostly modify the following cURL POST example:

curl --user "USERNAME:PASSWORD" 
-X POST https://reqbin.com/echo/post/json
-d '{"KEY":"VALUE", "KEY":"VALUE"}' 
-H "Content-Type: application/json"

Most APIs will ask you to include authentication, payload details (which are nested under “-d”), a header stating the content type and the URL of the endpoint. You can easily adjust the cURL POST request above as necessary to match the requirements of the API.

If you want to learn more about cURL, we recommend our cURL GET request blog post.