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/jsonResponse:
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/contacts
retrieves 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/jsonResponse:
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/jsonRequest 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/jsonRequest 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