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:

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 a Content-Type. All POST and PUT requests to the Application and Cloud APIs should be application/json, while the Bulk API supports application/json and text/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"
  ...
}

Related

Eloqua API tutorials

cURL request formatting

Uploading file data using cURL