Now that we've seen how to Authenticate, and looked at HTTP Verbs, let's move on to the URL parameters supported by the API endpoints.


Most Eloqua API endpoints accept one or more standard parameters, but not all endpoints support ALL of these parameters.

 

The available parameters are outlined in the table below.

 

 

Id

Identifier for the entity on which to perform the operation  This value is actually part of the base URL, and not a URL parameter. An example can been seen in the request below, which would return a representation of the contact entity with the identifier 123:

GET https://.../data/contact/123

Note: The format of entity identifiers may change over time, so developers should treat entity identifiers as opaque strings and not as numbers.
DepthDepth or level of detail returned. This can be "minimal", "partial", or "complete". An example can been seen in the request below, which would return the root form folder with a depth of "complete":
GET https://.../assets/form/folder/root?depth=complete
CountMaximum number of entities to return. The value can be any whole number between 1 and 1000. An example can been seen in the request below, which would return a maximum of 20 landing pages:
GET https://.../assets/landingPages?count=20

Note: If the count parameter is not supplied, 1000 will be used by default.
Page

Specifies which page of entities to return, and can be any positive whole number.  The Count parameter determines the size (number of results) per page.  An example can been seen in the request below, which return the first page of 20 landing pages (results 1...20):


GET https://.../assets/landingPages?count=20


To return the second page of 20 landing pages (results 21...40):

 

GET https://.../assets/landingPages?page=2&count=20

 

To return the third page of 20 landing pages (results 41...60):

 

GET https://.../assets/landingPages?page=3&count=20


Note: If the page parameter is not supplied, 1 will be used by default.

Search

Specifies the search criteria used to retrieve entities. This is in the form of:

[{term} {operator}] {value}

 

Where {term} is the name of a field to filter on, {operator} is the comparison operator, and {value} is the value to compare the field with.

 

The following request would return all landing pages whose name contains the word "Test":

GET https://.../assets/landingPages?search=Test

 

Note: If {term} and {operator} are not supplied, the name field is compared to the value using the equality operator.

SortSpecifies the name of the property used to sort the returned entities. The value depends on the type of entity being sorted, with each entity having its own list of sortable properties. An example can been seen in the request below, which returns a list of contacts sorted by first name (Note: firstName and lastName are only relevant to contacts):

 

GET https://.../data/contacts?sort=firstName

 

...or by last name


GET https://.../data/contacts?sort=lastName

 

 

 

 

Note: If  the Sort parameter is not supplied, the the results are returned with a default sort.

Dir

Specifies the direction in which to sort the returned entities. The value can be "asc" for ascending or "desc" for descending.  So, for the sorting example by first name above:

GET https://.../data/contacts?sort=firstName&dir=asc

Note: If the dir parameter is not supplied, the default value "asc" is used.

StatusCodeOverride

Allows HTTP clients that don't support or expose HTTP status codes, other than HTTP 200 OK, to indicate that the server should always respond with a specific HTTP status code. If a value is supplied for the parameter, that value will be used as the status code. An example can been seen in the request below, which will always return HTTP 200 OK, regardless of whether or not the actual status is OK:

 

GET https://.../data/contact/123?statusCodeOverride=200

JsonpCallback

Indicates that the response should be returned as JSONP (or JSON with Padding). The value is used as the name of the callback function in the returned JavaScript. The value of the Accept request header is ignored, and the content returned is always of type application/javascript.

An example can been seen in the request below, which does not include the jsonpCallback parameter, and so the response is plain JSON:

GET https://.../system/user/current?depth=complete  HTTP/1.1 200 OK Content-Type: application/json  {"type":"User","createdAt":"1237228178","depth":"complete", ...}
...and the same request made with the jsonpCallback parameter.  (returns application/javascript, and the original JSON is now wrapped in a call to the specified callback function):
GET https://.../system/user/current?depth=complete &jsonpCallback=loadCurrentUser  HTTP/1.1 200 OK Content-Type: application/javascript  loadCurrentUser({"type":"User","id":"9","createdAt":"1237228178","depth":"complete",...});