Using cURL

Some examples in the Cornerstone API documentation use cURL. cURL is a lightweight command line tool that allows you to make HTTP requests without a web browser. Specifically, for APIs, cURL lets you try out API calls without first building a working application.

TIP

While Cornerstone provides cURL commands to help you get started with our APIs, you can use any third party tool to construct your API requests. Note that cURL is an open source tool. Cornerstone does not provide any support for installing or troubleshooting cURL.

Installing cURL

MacOS and Linux

cURL comes pre-installed on most Linux and Mac OS systems. To try it out, see Using cURL below.

Windows

cURL is installed by default if you have version 1803 or later of Windows 10. If you have a version of Windows that's earlier than Windows 10, version 1803, download and install cURL from here: https://curl.haxx.se/download.html.

Using cURL in MacOS and Linux

You can use cURL for trying out Cornerstone's APIs. For example, the following cURL command makes an HTTP request to get an OAuth2 access token.

• Replace corpname with your portal's name.
• Modify the values for clientId and clientSecret with your OAuth 2.0 application's credentials.

curl -X POST \
 https://[corpname].csod.com/services/api/oauth2/token \
 -H 'Content-Type: application/json' \
 -d '{
    "clientId": "dbq2kjiql2c4",
    "clientSecret": "l4nqwza+7RbK0rrzs16VMeH+5dWEsFjsRSXtQ0MwL+TSSWvZGliUkgUfIenAk0+1Yx0yPtTs+bSmlotR2KCVGA==",
    "grantType": "client_credentials",
    "scope": "employee:read"
  }'

This returns a JSON object with the OAuth2 token.

Status: 200 OK

{
  "access_token": "ZWRnZQ:sh97VjZWQJ9pvYVqKiapZYDeLjM8pvFrnku8i6ckuTx8QXaSnIkI4rV7MF21LD2A2A5vKXQqSydq7kGIGV2bQA==",
  "expires_in": 3600,
  "scope": "employee:read employee:create",
  "token_type": "Bearer"
}

You can then use the token in your subsequent API calls. The below command to the Employee API returns details of a user whose User ID is johndoe. Replace the bearer token in the header with the token you received above.

TIP

Notice the OAuth 2.0 scopes we included in the token request above only allow us to GET employee data. If you want to access another API or a different operation with the Employee API, you will need to adjust the scope values in the token request.

curl https://[corpname].csod.com/services/api/x/users/v1/employees/userid-johndoe \
  - H 'Authorization: Bearer ZWRnZQ:sh97VjZWQJ9pvYVqKiapZYDeLjM8pvFrnku8i6ckuTx8QXaSnIkI4rV7MF21LD2A2A5vKXQqSydq7kGIGV2bQA=='

TIP

We didn't include the -X GET before the URL because GET is the default method in cURL.

Using cURL in Windows

If you are using the Windows command prompt to run the cURL examples, you will need to modify the examples in our API documentation a bit to get them to work correctly.

Request Bodies

The Windows command prompt does not support single quotes. This is a problem when you are working with JSON data in request bodies for POST, PUT, and PATCH operations. cURL statements use single quotes to specify JSON data. There are two ways to fix this problem:

Option 1: Use escaped double quotes

Use double quotes around the JSON data in the cURL statement and escape the inner double quotes with backslashes.

For example, the request to get an access token would look like this:

• Replace corpname with your portal's name.
• Modify the values for clientId and clientSecret with your OAuth 2.0 application's credentials.

curl -X POST "https://[corpname].csod.com/services/api/oauth2/token" -H "Content-Type: application/json" -d "{\"clientId\": \"dbq2kjiql2c4\", \"clientSecret\": \"l4nqwza+7RbK0rrzs16VMeH+5dWEsFjsRSXtQ0MwL+TSSWvZGliUkgUfIenAk0+1Yx0yPtTs+bSmlotR2KCVGA==\", \"grantType\": \"client_credentials\", \"scope\": \"employee:read\"}"

Option 2: Move request body to a file

Save the JSON data in a separate file and reference file name in the -d command. Modify the example above by creating a requestbody.txt file. Within the file, include the following text and save the file:

• Modify the values for clientId and clientSecret with your OAuth 2.0 application's credentials):

{ "clientId": "dbq2kjiql2c4", "clientSecret": "l4nqwza+7RbK0rrzs16VMeH+5dWEsFjsRSXtQ0MwL+TSSWvZGliUkgUfIenAk0+1Yx0yPtTs+bSmlotR2KCVGA==", "grantType": "client_credentials", "scope": "employee:read" }

Then, in the command prompt, use the cd command to change the directory to the folder that contains your file. Lastly, modify the cURL command as shown below and run it. Note the -d @filename syntax.

• Replace corpname with your portal's name.

curl -X POST "https://[corpname].csod.com/services/api/oauth2/token" -H "Content-Type: application/json" -d @requestbody.txt

You may prefer this over option 1 because there are other differences with how Windows handles certain characters in cURL statements. The following characters must be escaped with the caret (^) symbol: &, , <, >, ^, |. Finding and replacing these characters in your JSON data can be time consuming and error prone. Due to these reasons, we recommend option 2 - moving all request body data to a file.

Line-ending Backslashes

The cURL examples above and in the rest of Cornerstone's API documentation have a backslash () at the end of lines to break up long statements. This makes it easier to read. The backslash is a line continuation character in UNIX. However, Windows does not recognize that. To use the examples in Windows, replace any backslash at the end of lines with the caret (^) sign, the escape character in Windows. Be sure to not leave any trailing spaces after the ^ character else the caret will escape the space instead of the new line.

Additionally, you will have to replace any single quotes in headers with double quotes.

For example, the Employee API command above would look like this:

• Replace corpname with your portal's name.
• Replace the bearer token in the header with the token you received above.

curl https://[corpname].csod.com/services/api/x/users/v1/employees/userid-johndoe ^
  -H "Authorization: Bearer ZWRnZQ:sh97VjZWQJ9pvYVqKiapZYDeLjM8pvFrnku8i6ckuTx8QXaSnIkI4rV7MF21LD2A2A5vKXQqSydq7kGIGV2bQA=="

cURL Options Used in Examples

For a full list of options supported by cURL, please see this page: https://curl.haxx.se/docs/manpage.html. We use the following cURL options in the examples within the API documentation.

• -X Indicates the request method. For example, -X POST.
• -H Indicates header data. For example, most of your API request will include this in the header:

-H 'Content-Type: application/json'
-H 'Authorization: Bearer ZWRnZQ:d0ba3ae342f3061d87378fcb929e785e82969b942dcbc728f2639c2fbaced2d'

• -d Indicates the data that must be sent in the request body. For example, -d @requestbody.txt OR

-d '{
  "clientId": "dbq2kjiql2c4",
  "clientSecret": "l4nqwza+7RbK0rrzs16VMeH+5dWEsFjsRSXtQ0MwL+TSSWvZGliUkgUfIenAk0+1Yx0yPtTs+bSmlotR2KCVGA==",
  "grantType": "client_credentials",
  "scope": "employee:read"
}'

If you would like to see additional details about the request and response operations, consider using the -v option. It makes cURL verbose during the operation. This is especially useful for debugging.