HTTP verbs

There are 5 basic request patterns which apply to most 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:

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:

{
    "type":"Contact",
    "currentStatus":"Awaiting action",
    "id":"123",
    "createdAt":"1424362751",
    "depth":"complete",
    "name":"[e-mail]",
    "updatedAt":"1424362751",
    "accountName":"Government of Canada",
    "address1":"123 Front St.",
    "businessPhone":"011-555-5555",
    "city":"Kingston",
    "emailAddress":"[e-mail]",
    "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/json
			

Response:

{
    "elements":[
        {
            "type":"Contact",
            "id":"1",
            "createdAt":"1403034086",
            "depth":"minimal",
            "name":"[e-mail]",
            "updatedAt":"1410193024",
            "emailAddress":"[e-mail]"
        },
        {
            "type":"Contact",
            "id":"2",
            "createdAt":"1403113589",
            "depth":"minimal",
            "name":"demo-/contacts/imports/[e-mail]",
            "updatedAt":"1403113589",
            "emailAddress":"demo-/contacts/imports/[e-mail]"
        },

  ...

  ],
    "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 it's 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": "[e-mail]",
  "lastName": "Fortinbras"
}
			

Response:

{
    "type":"Contact",
    "currentStatus":"Awaiting action",
    "id":"23648",
    "createdAt":"1435087412",
    "depth":"complete",
    "name":"[e-mail]",
    "updatedAt":"1435087412",
    "emailAddress":"[e-mail]",
    "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 it's 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": "[e-mail]",
  "id": "22482",
  "businessPhone": "555-555-5555"
}
			

Response:

{
    "type":"Contact",
    "currentStatus":"Awaiting action",
    "id":"22482",
    "initialId":"22482",
    "createdAt":"1434039531",
    "depth":"complete",
    "name":"[e-mail]",
    "updatedAt":"1434051580",
    "businessPhone":"555-555-5555",
    "emailAddress":"[e-mail]",
    "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