How to Send a POST Request With cURL?

What is a POST request in cURL?

A cURL POST request offers a method for communicating with web servers and APIs right from the Command line or within a script, enabling the transmission of data to either create or modify resources. This type of request is structured around several key components:

• URL. Specifies the endpoint to which the request is sent. This is the target resource or API where the data will be processed, provided directly after the cURL command and options.
• Headers. Included using the -H or --header flag followed by the header name and value. Headers in a cURL POST request can include content type (e.g., -H "Content-Type: application/json" for JSON payloads), authentication (e.g., -H "Authorization: Bearer TOKEN"), and any other necessary metadata required by the server or API.
• Body. The data payload of the POST request added using the -d or --data flag. This can be a string of key-value pairs for form data, a JSON string, or even a reference to a file containing the payload (using @filename syntax).

Building a cURL POST request with these components gives developers precise control over the data they send to servers, positioning cURL as an instrument for testing, automation, and engagement with web services.

cURL POST request: a step-by-step guide

cURL is a versatile command line tool widely used for interacting with servers, particularly for sending and receiving data across different protocols. Whether you're working with APIs, automating scripts, or troubleshooting network issues, understanding how to send POST requests with cURL is essential. This guide will take you through each step, from sending your first POST request to more advanced options. For those who need to work with proxies for added security or anonymity, be sure to check out our comprehensive cURL with proxies guide.

How to send a basic POST request?

To send a basic POST request with cURL, use the -X POST option followed by the URL you're targeting:

POST request options (arguments)

This table covers the fundamental arguments for constructing and sending POST requests with cURL, enabling a wide range of HTTP interactions from simple data submissions to complex file uploads and authentication handling:

#1 Table. cURL POST request options (arguments)

What is Request-Response cycle?

Here's a diagram illustrating the step-by-step process of sending a POST request with cURL and receiving a response from the server. This diagram includes decision points for handling different HTTP status codes, error handling, and retries.

#2 Diagram. cURL POST Request-Response cycle.

How to send data with a POST method?

To send data with your POST request, use the -d (or --data) option. This data is typically presented in the form of key-value pairs:

Remember, when adding data to your POST request, it's crucial to correctly specify the Content-Type header to match the type of data you're transmitting. If not, the server might struggle to process your request correctly. We'll dive into this in the sections below.

How to send JSON data?

When sending JSON data with cURL, it's important to set the Content-Type header to application/json to inform the server about the type of data being sent. This is done using the -H (or --header) option. The data itself is passed with the -d (or --data) option, formatted as a JSON string. Here's an example:

• -X POST specifies the request method.
• -H "Content-Type: application/json" sets the header to indicate the resource's media type.
• -d '{"key": "value", "number": 123, "boolean": true}' provides the JSON data to be sent to the server. This JSON string includes various data types commonly used in JSON, such as strings ("key": "value"), numbers ("number": 123), and booleans ("boolean": true).

How to post XML data?

When posting XML data with cURL, you should set the Content-Type header to application/xml or text/xml, depending on the requirements of the server you're interacting with. This header is set using the -H flag, and the XML data itself is included with the -d option. Here’s how you can send a POST request with XML data:

• -X POST specifies that the HTTP method is POST.
• -H "Content-Type: application/xml" sets the request header to inform the server that the data being sent is in XML format.
• -d '<person><name>John Smith</name><age>30</age></person>' is the XML data payload. This example represents a simple XML document with a person element containing name and age elements.

How to send form data?

Form data is a common method of data transmission in web interactions, especially in HTTP POST requests. It's the standard approach for submitting web forms, accommodating diverse fields like text entries, choices, and file uploads. When utilizing cURL to dispatch form data, shaping the request to replicate a web browser's form submission process is key.

How to set MIME types for form data?

When submitting form data, the MIME type (media type or content type) used is application/x-www-form-urlencoded for standard text inputs. For more complex forms, particularly those involving file uploads, the MIME type should be multipart/form-data. Note that cURL automatically uses multipart/form-data when the -F flag is used.

How to send standard form fields?

To send standard text fields (like username and password inputs), you can use the -F (or --form) flag with cURL, which automatically sets the content type to multipart/form-data. Here's an example of submitting simple form fields:

• -F "username=johndoe" and -F "password=123456" represent the form data being sent.
• Each -F adds another key-value pair to the request, mimicking the form fields in a web form.
• Checkboxes and selections. For a form with checkboxes or selection dropdowns, use the -F flag for each option. If a checkbox is checked, include it with its value; otherwise, omit it.

How to submit advanced forms?

Forms often contain more than simple text inputs; they may include selections, checkboxes, and file uploads. Here’s how to handle various form elements with cURL:

How to use encoding and special characters?

When sending form data, ensure that special characters are properly encoded, especially in URLs and form field values. cURL handles some of this encoding automatically when using the -F flag. However, when manually crafting data with the -d flag and using application/x-www-form-urlencoded, pay special attention to characters that may require percent-encoding.

How to debug form data requests?

Debugging form data submissions with cURL can be facilitated using the -v (verbose) flag to view the request headers and body. This can help ensure that your form data is being sent as expected. We’ll cover the verbose mode in detail in the dedicated section below.

Conclusion

Mastering cURL for sending POST requests is essential for anyone involved in web development or API integration. With the steps outlined in this guide, you should now be able to install cURL, send POST requests, and even use proxies for enhanced security. Whether you're testing APIs or automating tasks, cURL provides a powerful, flexible tool to do the job efficiently.

Looking for other relevant guides on cURL? We would recommend checking our other articles on this topic:

• How to send a cURL GET request (guide)

• cURL proxy: what is a cURL proxy and how it works (guide)

• Alternative Google SERP Scraping Techniques - Terminal and cURL [VIDEO]

To find answers to other questions you may have, check out the official documentation for cURL.