Sending API requests using cURL
Client for URLs (or cURL) is a software project comprised of two development efforts - cURL and libcurl.
libcurl is a free, client-side URL transfer library with support for a wide range of protocols. libcurl is portable, thread-safe, feature rich, and well supported on virtually any platform. It is probably the most popular C-based, multi-platform file transfer library in use.
cURL is a command-line tool for getting or sending files using URL syntax. Since cURL uses libcurl, it supports the same range of common Internet protocols that libcurl does.
This tutorial will walk through the format and syntax used when making Oracle Eloqua API requests with cURL. If you are not yet familiar with the structure of requests, see API requests.
In this tutorial:
- Authentication
- Sending a GET request
- Sending a DELETE request
- Sending a POST request
- Sending a PUT request
Note: The code samples in this tutorial are developed for bash. See cURL request formatting for more information on how to structure cURL requests for other command line tools.
Authentication
The easiest way to authenticate with Oracle Eloqua's APIs is to use basic authentication which uses your Eloqua company name, user name, and password to authenticate. To use basic authentication, use the cURL --user
option followed by your company name and user name as the value. cURL will then prompt you for your password.
curl --user "<companyName>\<userName>" --request GET https://secure.p0<podNumber>.eloqua.com/api/<apiType>/<apiVersion>/<endpoint>
Enter host password for user '<companyName>\<userName>':
To avoid the password prompt, append your password after your user name by following the syntax --user "<companyName>\<userName>:<password>"
, but this will leave your password in shell history and isn't recommended.
Note: For this tutorial, the company name we use is APITest
, our user name is API.User
, and our pod is 3
.
Sending a GET request
Let's retrieve the first two contacts within your database. Only the --user
option is required. The --request
option is optional, but we include it in the example below for conformity with other requests to establish a pattern.
curl --user "APITest\API.User" --request GET https://secure.p03.eloqua.com/api/REST/1.0/data/contacts?count=2
{
"elements":[
{
"type":"Contact",
"id":"1",
"createdAt":"1403034086",
"depth":"minimal",
"name":"george.washington@america.com",
"updatedAt":"1410193024",
"emailAddress":"george.washington@america.com"
},
{
"type":"Contact",
"id":"2",
"createdAt":"1403113589",
"depth":"minimal",
"name":"john.a.macdonald@canada.com",
"updatedAt":"1403113589",
"emailAddress":"john.a.macdonald@canada.com"
}
],
"page":1,
"pageSize":2,
"total":527
}
Sending a DELETE request
For DELETE
requests, the --user
option and --request
option are both required. Let's delete a contact whose contact id is 1
.
curl --user "APITest\API.User" --request DELETE https://secure.p03.eloqua.com/api/REST/1.0/data/contact/1
200 OK
Note that for DELETE
requests, there is no body is returned, just a response status code.
Sending a POST request
POST
requests are a little different. Let's look at an example of how to create a contact whose email address is "george.washington@america.com".
curl --user "APITest\API.User" --header "Content-Type: application/json" --request POST --data '{"emailAddress":"george.washington@america.com"}' https://secure.p03.eloqua.com/api/REST/1.0/data/contact
{
"type": "Contact",
"currentStatus": "Awaiting action",
"id": "1",
"name": "george.washington@america.com",
"emailAddress": "george.washington@america.com",
...
}
As you can see POST
requests are much different than the other verbs we've looked at so far, so let's take a closer look at what's happening in the request.
- The
--header
option is required with aContent-Type
. AllPOST
andPUT
requests to the Application and Cloud APIs should beapplication/json
, while the Bulk API supportsapplication/json
andtext/csv
. To confirm the media types supported, see the "Supported Media Types" per endpoint in our endpoint documentation. - The
--data
option is optional, but we include it for readability.
Sending a PUT request
PUT
requests follow the same format as POST
requests. Let's take a look at an example of how to update a contact to change the contact's business phone number when the contact id
is 1
and email address is "george.washington@america.com".
curl --user "APITest\API.User" --header "Content-Type: application/json" --request PUT --data '{"id":"1","emailAddress":"george.washington@america.com","businessPhone":"555-555-5555"}' https://secure.p03.eloqua.com/api/REST/1.0/data/contact/1
{
"type": "Contact",
"currentStatus": "Awaiting action",
"id": 1,
"name": "george.washington@america.com",
"emailAddress": "george.washington@america.com"
...
}