All the examples in the Zendesk REST API docs use cURL, a lightweight, command-line tool for making HTTP requests without a web browser. cURL lets you try out various API requests in a command-line interface such as the command prompt in Windows or Terminal in macOS. You don't need to build a working web application just to try out the APIs.
cURL makes HTTP requests just like a web browser. To request a web page from the command line, type curl
followed by the site's URL:
The web server's response is displayed directly in your command-line interface. If you requested an HTML page, you get the page source -- which is what a browser normally sees.
This article covers the following topics:
Related topic
Using cURL
You can use cURL to inspect and test different Zendesk API requests without having to build a functioning web application. For example, the following cURL statement makes an HTTP request to the List Groups endpoint in the Zendesk API:
curl https://mysubdomain.zendesk.com/api/v2/groups.json \
-v -u myemail@example.com:mypassword
The API returns a JSON object that lists the groups in your Zendesk Support instance:
Status: 200 OK
{
"groups": [
{
"name": "DJs",
"created_at": "2009-05-13T00:07:08Z",
"updated_at": "2011-07-22T00:11:12Z",
"id": 211
},
{
"name": "MCs",
"created_at": "2009-08-26T00:07:08Z",
"updated_at": "2010-05-13T00:07:08Z",
"id": 122
}
]
}
JSON (JavaScript Object Notation) is a lightweight data-interchange format. It's designed to be easy for humans to read and write, and for machines to parse and generate. To learn more, see Working with JSON.
Using cURL in Windows
You can use the Windows command prompt to run the cURL examples. To start the command prompt, open the Start menu, type cmd in the search box, and press Enter.
cURL isn't installed in Windows by default. See Installing cURL below to install it on your system.
The examples in the docs have to be modified slightly to work correctly in Windows. First, replace any line-ending backslash (\) character with the caret (^) character. Second, if an example contains JSON data, move the data to a file before running the example. The following sections give more details.
Replace line-ending backslashes
The cURL examples often have a backslash (\) at the end of lines to break up a long statement into easier-to-read lines. The backslash is a line continuation character in UNIX but not in Windows. In Windows, replace any backslash at the end of lines with the caret (^) character, which is an escape character in Windows. Don't leave any space after any ^ character or it won't work. The caret will escape the space instead of the new line.
Example:
curl https://mysubdomain.zendesk.com/api/v2/groups.json ^
-v -u myemail@example.com:mypassword
You can paste a multiline statement at the command prompt by clicking the icon in the upper-left corner and selecting Edit > Paste. If you prefer using the keyboard, press Alt+spacebar to open the menu, then press E and P.
Move JSON data to a file
The Windows command prompt doesn't support single quotes. It's a problem because cURL statements use single quotes to specify JSON data. Example:
curl https://{subdomain}.zendesk.com/api/v2/groups.json ^
-d '{"group": {"name": "My Group"}}' ^
-H "Content-Type: application/json" ^
-v -u {email_address}:{password} -X POST
The statement specifies JSON data for creating a group (the -d
flag stands for data). Because the JSON is enclosed in single quotes, the statement won't work on the command line.
To fix the problem, save the JSON in a separate file and import it into the cURL statement. To modify the example above, create a file named json.txt containing the following text:
{"group": {"name": "My Group"}}
Next, change the cURL statement to import the JSON data with the @filename syntax:
curl https://{subdomain}.zendesk.com/api/v2/groups.json ^
-d @json.txt ^
-H "Content-Type: application/json" ^
-v -u {email_address}:{password} -X POST
Before running the statement, use the cd command (for change directory) to navigate to the folder that contains the file. Example:
C:\> cd json_files
Then paste the cURL statement at the command prompt:
C:\json_files> curl https://{subdomain}.zendesk.com/api/v2/groups.json ^
-d @json.txt ^
-H "Content-Type: application/json" ^
-v -u {email_address}:{password} -X POST
An alternative to moving the JSON to a separate file is to use double quotes around the JSON data in the cURL statement and escape the inner ones with backslashes:
-d "{\"group\": {\"name\": \"My Group\"}}" \
...
It doesn't end there. The following special characters in strings must be escaped with the caret (^) character: &, \, <, >, ^, |
. If the JSON includes HTML, such as when you try to create or update an article in Help Center, you need to find and escape all the angle brackets in the HTML.
This is tedious and error prone. Best to stick with importing the JSON from a file.
Installing cURL
macOS
cURL is installed by default on macOS. To try it out, see Testing your cURL installation below.
Windows 10, version 1803 or later
If you have version 1803 or later of Windows 10, cURL is installed by default. To try it out, see Testing your cURL installation below.
Windows
If you have a version of Windows earlier than Windows 10, version 1803, you can download and install cURL as follows.
-
In Windows, create a new folder called curl in your C: drive.
C:\curl
-
Go to http://curl.haxx.se/download.html and download one of the following zip files:
- If you have a Windows 64 system, scroll to the Win64 - Generic section and look for the latest Win64 ia64 zip version with SSL support. It's normally second in the list. Click the version number to start the download.
- If you have a Windows 32 system, scroll to the Win32 - Generic section and look for the latest Win32 zip version with SSL support. It's normally second in the list. Click the version number to start the download.
-
Unzip the downloaded file and move the curl.exe file to your C:\curl folder.
-
Go to http://curl.haxx.se/docs/caextract.html and download the digital certificate file named cacert.pem.
The PEM file contains a bundle of valid digital certificates. The certificates are used to verify the authenticity of secure websites. They're distributed by certificate authority (CA) companies such as GlobalSign and VeriSign. The PEM file allows cURL to connect securely to the Zendesk API using the Secure Sockets Layer (SSL) protocol.
-
Move the cacert.pem file to your C:\curl folder and rename it curl-ca-bundle.crt.
-
Add the curl folder path to your Windows PATH environment variable so that the curl command is available from any location at the command prompt. Update the variable as follows:
-
In the Start menu, right-click This PC and select More > Properties.
Note: In Windows 7, right-click Computer and select Properties.
-
Click Advanced System Settings.
-
In the Advanced tab, click the Environment Variables button on the lower right side.
-
Select the "Path" variable in System Variables, and click Edit.
-
In the Edit environment variable dialog box, click New and add the path to the curl.exe file. Example: C:\curl.
Windows 7: In the Variable Value textbox, append a semicolon to the value, followed by the path to the curl.exe file. Example: ;C:\curl
-
Keep clicking OK to accept the change and close the dialog box.
-
Testing your cURL installation
You can test your cURL installation by making a request to the Zendesk API. The test retrieves your Zendesk Support user information.
To test cURL
-
Paste the following cURL statement into your favorite text editor:
curl https://{subdomain}.zendesk.com/api/v2/users/me.json \ -v -u {email_address}:{password}
For details on this endpoint, see Show the Currently Authenticated User in the Zendesk API docs.
Windows users: Replace the backslash (\) line continuation character with a caret (^) character. Make sure there's no space after the caret. See Using cURL in Windows above. -
Replace the placeholders in curly brackets with the information you use to sign in to Zendesk Support. Example:
curl https://obscura.zendesk.com/api/v2/users/me.json \ -v -u myemail@example.com:mypassword
-
Launch your command-line interface.
- In Windows, open the Start menu, type cmd in the search box, and press Enter.
- In macOS, double-click the Terminal application in your Applications/Utilities folder.
-
Copy the cURL statement from your text file and paste it at the command prompt.
Windows users: After copying it to the Clipboard, select Edit > Paste from the context menu in the upper left corner of the window:
-
Press Enter to run the cURL statement.
The console should display your Zendesk Support user information formatted as a JSON object.
You can pretty print the results to make it easier to read. See Converting JSON to data you can understand.
Common cURL flags
You'll see the following cURL flags in the examples in the Zendesk REST API docs.
-H
Specifies any extra header content to include in the HTTP request. API requests that submit data to our servers typically include the data's content type. Example:
Example: -H "Content-Type: application/json"
.
-u
Specifies the user name and password to use for server authentication. The user name and password are separated by a colon.
Example: -u myemail@example.com:mypassword
-v
Makes the response more verbose.
-X
Specifies the request method to use when communicating with the HTTP server. Example: PUT
or POST
.
Example: -X PUT
-G --data-urlencode
Used for API endpoints that send data in a query string, such as the Search API. The --data-urlencode
option url-encodes the query string. The -G
flag specifies that the url-encoded data is for a GET request rather than a POST request.
For example, suppose you want to run the following search using the List Search Results endpoint:
.../api/v2/search.json?query=type:ticket status:open
The cURL command looks like this:
curl "https://{subdomain}.zendesk.com/api/v2/search.json" \
-G --data-urlencode "query=type:ticket status:open" \
-v -u {email_address}:{password}
44 Comments
This is a really great article about installing cURL on Windows, and I want to link to it. Can you fix some of the Markdown formatting issues? (The bullets beneath numbered list items are getting formatted with pre tags instead of bullets.) Thanks.
Hi Tom, I think I fixed all the formatting issues. I added a little bit more info about using curl in Windows. For example, you can use the caret (^) as a line continuation character instead of the backslash in multiline statements.
Awesome. Thanks Charles. One more small thing. Can you make the Bookmarks ("This article covers the following topics...") work? The last three don't seem to jump to the headings.
@Tom All fixed now. Let me know if you spot anything else. Thanks.
Hi I followed all the steps and and installed curl on Windows 7 64-bit. When I test it I got a error, curl.exe has stopped working. Please help me fix this
Hi. I've encountered similar issues to Hugh Gallagher, could you please detail the resolution here?
Hi Oz, are you on Windows? If so, have you downloaded and installed the digital certificate file as described in steps 4 and 5 in https://support.zendesk.com/hc/en-us/articles/203691436-Installing-and-using-cURL#install above?
Hello, is there a way to pretty print the results? after our shortcuts are retrieved in the Command Prompt I have to manually format the data
OS - Windows 7 64bit
Terminal - "Console2"
@Lloyd, a Google search returns a number of solutions. The simplest in terms of setup is using the "JSON Formatter" extension in Chrome. You can get it from https://chrome.google.com/webstore/detail/json-formatter/bcjindcccaagfpapjjmafapmmgkkhgoa?hl=en. After installing it, in Chrome select Windows > Extensions, and select the "Allow access to file URLs" option for the JSON Formatter extension. This enables pretty-printing local files.
Paste your JSON results from the console to a text file and save it with a .json extension. Then open the file in Chrome (File > Open File).
I'm not seeing a file named ca-bundle.crt on https://curl.haxx.se/docs/caextract.html
Hi Kyle,
Looks like they changed the bundle's filename from ca-bundle.crt to cacert.pem. The .pem file is still a certificate bundle. I need to confirm it on my Windows machine at home tonight, but you should be able to move the cacert.pem file to your C:\curl folder and rename it curl-ca-bundle.crt (step 5 in the procedure above). Once I confirm this works, I'll update the doc.
@Kyle: Confirmed on my Window 10 machine. I updated the article with the new information. Thanks for pointing out the problem.
Indeed great article Charles, it helps big.
I've been using only Linux version so far but I have a need to try Windows version to help my colleagues and this article makes that so easy.
Hi Charles,
I save cacert.pem in c:\curl and rename to curl-ca-bundle.crt as per your instruction. But I get the following error when I run the curl statement in command prompt.
C:\Users\R30>curl https://stoneapplesolutions1371715803.zendesk.com/api/v2/users
/me.json \ -v -u {myemail}:{mypassword}
* Adding handle: conn: 0x1d5d7b0
* Adding handle: send: 0
* Adding handle: recv: 0
* Curl_addHandleToPipeline: length: 1
* - Conn 0 (0x1d5d7b0) send_pipe: 1, recv_pipe: 0
* About to connect() to stoneapplesolutions1371715803.zendesk.com port 443 (#0)
* Trying 192.161.156.1...
* Connected to stoneapplesolutions1371715803.zendesk.com (192.161.156.1) port 44
3 (#0)
* error setting certificate verify locations:
CAfile: c:\curl\curl-ca-bundle.crt
CApath: none
* Closing connection 0
curl: (77) error setting certificate verify locations:
CAfile: c:\curl\curl-ca-bundle.crt
CApath: none
* Rebuilt URL to: \/
* Adding handle: conn: 0x1d5d7b0
* Adding handle: send: 0
* Adding handle: recv: 0
* Curl_addHandleToPipeline: length: 1
* - Conn 1 (0x1d5d7b0) send_pipe: 1, recv_pipe: 0
* Could not resolve host: \
* Closing connection 1
curl: (6) Could not resolve host: \
Hi Keith,
It might be some folder permission issue. See this Microsoft doc on folder permissions.
Hi Charles,
I give the full control permission to the directory. I am still getting the same error.
Hi Keith,
Can you run through this troubleshooting checklist:
* Confirm you installed the SSL version of curl from the download page at https://curl.haxx.se/download.html. It's usually the second zip file in the list. Example for Win64 systems:
* Confirm the crt file is a plain text file and contains the certificates. You should be able to open it in a text editor and view the certificates (the dense blocks of characters).
* Try placing the crt file in another folder scanned by curl.exe. According to the curl docs at https://curl.haxx.se/docs/sslcerts.html, curl will look for the crt file in the following folders in order:
* If all else fails, I found a page that suggest installing a Windows version of OpenSSL might help. See step 3 on http://support.gnip.com/articles/curl-on-win7.html#enable-support-for-ssl.
You also have the option of running cURL in an insecure mode with the -k (or –insecure) option.
Fantastic tutorial, thanks!
Great instructions - made it easy to follow! Thanks!
I strictly followed the instructions on Win10, the screenshots totally matched to what I saw in my system, but still i got the error while testing, as if the installation never happened: https://cl.ly/262M0C3T0M3O
What could I do wrong?
If you don't want to go through the steps of installing cURL on Windows, install Postman and use the import function. 100X easier!!
Charles,
First thanks so much about this article, not too many companies go out of their way to explain in such detail a 3rd party application. It's one of the reason I pushed my company to switch to Zendesk.
To add to your comment about certificates I had similar issue, I was able to make handshake but kept getting error about the certificate.
With the help of IT I figured out that the issue is with our web filtering software.
Web filtering software acts like a middle man between the client and the server pinging request. In other words you are not taking directly to website, each back and forth request gets first read by the filter and then re-delivered to client/server.
To use an industry term, having a "man in the middle" is a security risk, and most websites who use https won't allow it. (like Banks etc)
We allowed Zendesk so traffic to Zendesk server bypasses the filter. and it fixed the problem.
Thanks,
Moshe
FYI your link to " Converting JSON to data you can understand" goes to an oops page :-)
Hey Heather! Thanks for the heads up! I'll let our Documentation team know. :)
@Heather - Link should be working now.
Thanks.
2018-Windows 10 latest updates... and still valid. Thanks. Some things just make life so much simpler. This is one of them.
One issue I has was then when I renamed cacert.pem file to curl-ca-bundle.crt it kept the .pem file extension, so it was called curl-ca-bundle.crt.pem
Removing the .pem extension so that its .crt resolved my issue with certificates.
Hi,
Your guide was exactly what I need but unfortenetly I can't seem to convert the LINUX/UNIX(??) syntax to windows correctly.
Can you help me with this?
Hi Alon,
Scroll down a little further to "Using cURL in Windows" - https://help.zendesk.com/hc/en-us/articles/229136847?page=1#curl_win
Thanks.
Hi,
I followed the guide and this is the best I could get:
curl -X POST "http://192.168.1.50:8123/api/states/sensor.office_temperature"^
-u {x-ha-access}:{password}^
-H "Content-Type: application/json"^
-d "{"state": "20", "attributes": {"unit_of_measurement": "°C", "friendly_name": "Office Temp"}}"
I get an error:
401: Unauthorizedcurl: (3) [globbing] unmatched close brace/bracket in column 5
Any help?
Please sign in to leave a comment.