HTTP verbs

There are 5 basic request patterns which apply to most Oracle Eloqua endpoints, and these are based on the HTTP verbs. The basic request patterns are:

Retrieve a single item (GET)
Retrieve a list of items (GET)
Create an item (POST)
Update an item (PUT)
Delete an item (DELETE)

Below are examples of each pattern.

Note: The following examples apply to the application and Bulk APIs. For examples of using the reporting API, see Getting started with the reporting API.

Retrieve a single item (GET)

To retrieve a single entity, perform a GET request for that entity's endpoint, optionally specifying the format to return the entity in. The below example retrieves the information for the contact with id#123.

Request:

GET https://.../data/contact/123
Accept: application/json

Response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Length: 2164
Content-Type: application/json
X-Request-Id: 34b3d527-d9b6-414d-8967-d9f976bf416d
P3P: CP="IDC DSP COR DEVa TAIa OUR BUS PHY ONL UNI COM NAV CNT STA",

Date: Wed,
 10 Jun 2015 19:36:18 GMT

{
    "type":"Contact",
    "currentStatus":"Awaiting action",
    "id":"123",
    "createdAt":"1424362751",
    "depth":"complete",
    "name":"john.a.macdonald@canada.com",
    "updatedAt":"1424362751",
    "accountName":"Government of Canada",
    "address1":"123 Front St.",
    "businessPhone":"011-555-5555",
    "city":"Kingston",
    "emailAddress":"john.a.macdonald@canada.com",
    "emailFormatPreference":"unspecified",
    "fieldValues":[...],
    "firstName":"John",
    "isBounceback":"false",
    "isSubscribed":"true",
    "lastName":"Macdonald",
    "salesPerson":"Chuckles",
    "subscriptionDate":"1424362751",
    "title":"Prime Minister"
}

Retrieve a list of items (GET)

To retrieve a list of entities, perform a GET request for that entity type's list endpoint, specifying the query parameters to use to filter the list, and optionally specifying the format to return the entities in. The below example retrieves a list of all contacts.

Note: Eloqua APIs generally employ different endpoint paths for retrieval of list versus single items. For example: GET https://.../data/contact/123 retrieves the contact with id#123 while GET https://.../data/contactsretrieves a list of all contacts. Notice the second example uses the plural "contacts" rather than the singular "contact" of the first example.

Request:

GET https://.../data/contacts
Accept: application/json

Response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Length: 119989
Content-Type: application/json
X-Request-Id: a7dcbbd4-c9b1-43b3-893a-e4094dd2a99b
P3P: CP="IDC DSP COR DEVa TAIa OUR BUS PHY ONL UNI COM NAV CNT STA",

Date: Tue,
 23 Jun 2015 19:17:21 GMT

{
    "elements":[
        {
            "type":"Contact",
            "id":"1",
            "createdAt":"1403034086",
            "depth":"minimal",
            "name":"adeline.wong@oracle.com",
            "updatedAt":"1410193024",
            "emailAddress":"adeline.wong@oracle.com"
        },
        {
            "type":"Contact",
            "id":"2",
            "createdAt":"1403113589",
            "depth":"minimal",
            "name":"demo-/contacts/imports/1-00@oracle.com",
            "updatedAt":"1403113589",
            "emailAddress":"demo-/contacts/imports/1-00@oracle.com"
        },

  ...

  ],
    "page":1,
    "pageSize":1000,
    "total":543
}

Create an item (POST)

To create an entity, perform a POST request to that entity's endpoint specifying the entity's send format (Content-Type), and optionally specifying its return format (Accept). The below example creates a contact with email address and last name values.

Request header:

POST https://.../data/contact/
Content-Type: application/json
Accept: application/json

Request body:

{
" emailAddress":"fortinbras@norway.com",
"lastName": "Fortinbras"
}

Response:

HTTP/1.1 201 Created
Cache-Control: private
Content-Length: 1995
Content-Type: application/json
X-Request-Id: 9bbee8c7-3522-49ab-8f93-236ce9042910
P3P: CP="IDC DSP COR DEVa TAIa OUR BUS PHY ONL UNI COM NAV CNT STA",

Date: Tue,
 23 Jun 2015 19:23:32 GMT

{
    "type":"Contact",
    "currentStatus":"Awaiting action",
    "id":"23648",
    "createdAt":"1435087412",
    "depth":"complete",
    "name":"fortinbras@norway.com",
    "updatedAt":"1435087412",
    "emailAddress":"fortinbras@norway.com",
    "emailFormatPreference":"unspecified",
    "fieldValues":[...],
    "isBounceback":"false",
    "isSubscribed":"true",
    "lastName":"Fortinbras",
    "subscriptionDate":"1434039531"
}

Update an item (PUT)

To update an entity, perform a PUT request to that entity's endpoint, specifying the entity's send format (Content-Type), and optionally specifying its return format (Accept). The below example updates the email address and phone number of the contact with #Id 22482.

Note: the id is a required parameter for PUT requests in both the request header and body (and the two must match). In addition to the id parameter, for contacts, the "emailAddress" is required for the request body, and for many other assets the "name" parameter is required. Please see the documentation for the specific asset you wish to work with for more information on endpoint constraints.

Request header:

PUT https://.../data/contact/22482
Content-Type: application/json
Accept: application/json

Request body:

{
"emailAddress":"fortinbras@norway.com",
"id":"22482",
"businessPhone":"555-555-5555"
}

Response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Length: 2052
Content-Type: application/json
X-Request-Id: 347249bc-4fbe-461b-a268-5488d7bc5bae
P3P: CP="IDC DSP COR DEVa TAIa OUR BUS PHY ONL UNI COM NAV CNT STA",

X-Powered-By: ASP.NET
Date: Thu,
 11 Jun 2015 19:39:39 GMT

{
    "type":"Contact",
    "currentStatus":"Awaiting action",
    "id":"22482",
    "initialId":"22482",
    "createdAt":"1434039531",
    "depth":"complete",
    "name":"fortinbras100@norway.com",
    "updatedAt":"1434051580",
    "businessPhone":"555-555-5555",
    "emailAddress":"fortinbras100@norway.com",
    "emailFormatPreference":"unspecified",
    "fieldValues":[...],
    "isBounceback":"false",
    "isSubscribed":"true",
    "subscriptionDate":"1434050717"
}

Delete an item (DELETE)

To delete an entity, perform a DELETE request to that entity's endpoint.

Request:

DELETE https://.../data/contact/123

Learn more

Getting started with Oracle Eloqua APIs