How to Send a POST Request with cURL

cURL is a command-line tool for sending requests to a server. It comes pre-installed on most modern operating systems, making it an excellent starting point for networking projects.

Although applications like Postman offer similar functionality with a more sophisticated UI, cURL is more reliable and low-level, making it ideal for automation and various other use cases.

Introduction to cURL

cURL comes pre-installed on Windows 10 (and later) and most macOS operating systems. While some Linux distributions may offer cURL by default, in many cases, you'll need to install it yourself using the following command: 

sudo apt-get install curl

For older versions of Windows, you can download cURL from the official website. After installing cURL, you can start sending requests.

To verify that everything is installed correctly, open the terminal and enter:

curl --help 

Sending a cURL POST Request

All cURL commands follow the same structure: invoke cURL, set the request options, specify the URL, and include any additional options such as headers.

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

Some options, like the aforementioned --help, let you perform actions without specifying URLs, but they aren’t used for sending a cURL POST request.

There are three essentials for a POST request:

1. -X and POST

-X specifies the type of request you intend to send, and POST indicates the request method.

2. -d and some string

-d signifies that you intend to send data, with the string value being the content. Every cURL POST request must include data. The data can be any string, but APIs typically have specific formatting requirements, so you'll need to consult their documentation.

3. URL

Typically, this is the API endpoint to which you are sending your POST requests. For testing purposes, we'll use the sample ReqBin API URL. To send the most basic POST cURL request, simply enter:

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

Many APIs require you to send data in JSON format. You can do this by formatting the data value as follows:

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

Customizing a cURL POST Request

Some APIs may provide (or require) additional options to fully utilize their capabilities. A common requirement for a POST request is to include headers.

You can achieve this by including "-H" followed by the header information:

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

You can also provide details such as user agents (e.g., 'User Agent: Chrome') and specify the accepted character set (e.g., 'Accept-Charset: utf-8'). Each type of header must be included using the "-H" option.

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

Furthermore, many APIs typically require authentication before submitting any request. Usernames and passwords are commonly used for this purpose, and they can be included as follows:

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

Another commonly used authentication method involves sending a specific header containing an API access token. It typically appears as follows:

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"

Lastly, you can utilize cURL to POST data from a file. This can be accomplished by using either "-d" or "-F". Typically, the "-F" option is preferred for this purpose:

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

Handling Errors

When issues arise, cURL automatically generates a response, which you can view in the terminal. Look for error messages within the cURL POST body response.

For instance, if you attempt to send a cURL POST request to Google's domain without any data, you will 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>

Likewise, if you send a cURL POST request with data, you may encounter a different error indicating that such action is not permitted:

<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 might present standard HTTP errors, while others may offer custom responses advising on how to adjust the request.