Request depth

Eloqua APIs can retrieve entities at three different levels of depth: minimal, partial, and complete. In general, requests at minimal depth will perform best, as they scan the least amount of data. For most application API endpoint properties, if a property in the root of the response does not have a value, that property will not be returned.

The descriptions below should help you choose the right level of depth for your request.

Minimal

Only a small number of the entity's properties are returned. Most properties common to most records: the entity name, type and id, and the dates the entity was created, last updated and last accessed.

Minimal depth typically results in the best performance, as the time needed to retrieve the information in minimized.

The following example shows a contact retrieved at minimal depth:

Request:

GET https://.../data/contact/1?depth=minimal
Accept: application/json

Response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Length: 169
Content-Type: application/json
X-Request-Id: 88f7d681-17b7-4607-9176-326e14227abc
P3P: CP="IDC DSP COR DEVa TAIa OUR BUS PHY ONL UNI COM NAV CNT STA",

Date: Tue,
 23 Jun 2015 19:57:02 GMT

{
    "type":"Contact",
    "id":"1",
    "createdAt":"1403034086",
    "depth":"minimal",
    "name":"erlich.bachman@aviato.com",
    "updatedAt":"1410193024",
    "emailAddress":"erlich.bachman@aviato.com"
}

Partial

All of the entity's properties are returned and if the entity is related to other objects, those entities are returned at minimal depth.

The following example shows a contact retrieved at partial depth:

Request:

GET https://.../data/contact/1?depth=partial
Accept: application/json

Response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Length: 358
Content-Type: application/json
X-Request-Id: b0417f68-07c0-4461-8339-42b40647e4d5
P3P: CP="IDC DSP COR DEVa TAIa OUR BUS PHY ONL UNI COM NAV CNT STA",

Date: Tue,
 23 Jun 2015 19:58:46 GMT

{
    "type":"Contact",
    "currentStatus":"Awaiting action",
    "id":"1",
    "createdAt":"1403034086",
    "depth":"partial",
    "name":"erlich.bachman@aviato.com",
    "updatedAt":"1410193024",
    "emailAddress":"erlich.bachman@aviato.com",
    "emailFormatPreference":"unspecified",
    "firstName":"erlich",
    "isBounceback":"false",
    "isSubscribed":"true",
    "lastName":"bachman",
    "subscriptionDate":"1403034086"
}

Complete

All of the entity's properties are returned and all related entities are returned at complete depth.

The following example shows a contact retrieved at complete depth:

Request:

GET https://.../data/contact/1?depth=partial
Accept: application/json

Response:

This is the response header and body:

HTTP/1.1 200 OK
Cache-Control: private
Content-Length: 2059
Content-Type: application/json
X-Request-Id: 94f4b31a-dc0f-4bb9-8756-3421378a085a
P3P: CP="IDC DSP COR DEVa TAIa OUR BUS PHY ONL UNI COM NAV CNT STA",

Date: Tue,
 23 Jun 2015 19:59:38 GMT

{
    "type":"Contact",
    "currentStatus":"Awaiting action",
    "id":"1",
    "createdAt":"1403034086",
    "depth":"complete",
    "name":"erlich.bachman@aviato.com",
    "updatedAt":"1410193024",
    "emailAddress":"erlich.bachman@aviato.com",
    "emailFormatPreference":"unspecified",
    "fieldValues":[
        {
            "type":"FieldValue",
            "id":"100005"
        },
        {
            "type":"FieldValue",
            "id":"100017"
        },
        {
            "type":"FieldValue",
            "id":"100023"
        },
        {
            "type":"FieldValue",
            "id":"100024"
        },
        {
            "type":"FieldValue",
            "id":"100032",
            "value":"CPLTO000000000001"
        },
        {
            "type":"FieldValue",
            "id":"100033"
        },
        {
            "type":"FieldValue",
            "id":"100034"
        },
        {
            "type":"FieldValue",
            "id":"100035"
        },
        {
            "type":"FieldValue",
            "id":"100036"
        },
        {
            "type":"FieldValue",
            "id":"100041"
        },
        {
            "type":"FieldValue",
            "id":"100043"
        },
        {
            "type":"FieldValue",
            "id":"100044"
        },
        {
            "type":"FieldValue",
            "id":"100045"
        },
        {
            "type":"FieldValue",
            "id":"100046"
        },
        {
            "type":"FieldValue",
            "id":"100047"
        },
        {
            "type":"FieldValue",
            "id":"100048"
        },
        {
            "type":"FieldValue",
            "id":"100049"
        },
        {
            "type":"FieldValue",
            "id":"100051"
        },
        {
            "type":"FieldValue",
            "id":"100065"
        },
        {
            "type":"FieldValue",
            "id":"100066"
        },
        {
            "type":"FieldValue",
            "id":"100068"
        },
        {
            "type":"FieldValue",
            "id":"100069"
        },
        {
            "type":"FieldValue",
            "id":"100072"
        },
        {
            "type":"FieldValue",
            "id":"100081"
        },
        {
            "type":"FieldValue",
            "id":"100171",
            "value":"avliato.com"
        },
        {
            "type":"FieldValue",
            "id":"100172",
            "value":"erlich bachman"
        },
        {
            "type":"FieldValue",
            "id":"100174"
        },
        {
            "type":"FieldValue",
            "id":"100175"
        },
        {
            "type":"FieldValue",
            "id":"100176"
        },
        {
            "type":"FieldValue",
            "id":"100177"
        },
        {
            "type":"FieldValue",
            "id":"100178"
        },
        {
            "type":"FieldValue",
            "id":"100179"
        },
        {
            "type":"FieldValue",
            "id":"100180"
        },
        {
            "type":"FieldValue",
            "id":"100184"
        },
        {
            "type":"FieldValue",
            "id":"100187"
        },
        {
            "type":"FieldValue",
            "id":"100188"
        },
        {
            "type":"FieldValue",
            "id":"100189",
            "value":"erlichbachman"
        },
        {
            "type":"FieldValue",
            "id":"100190"
        },
        {
            "type":"FieldValue",
            "id":"100191"
        },
        {
            "type":"FieldValue",
            "id":"100192"
        },
        {
            "type":"FieldValue",
            "id":"100193"
        },
        {
            "type":"FieldValue",
            "id":"100194"
        },
        {
            "type":"FieldValue",
            "id":"100195"
        },
        {
            "type":"FieldValue",
            "id":"100197"
        }
    ],
    "firstName":"erlich",
    "isBounceback":"false",
    "isSubscribed":"true",
    "lastName":"bachman",
    "subscriptionDate":"1403034086"
}