Using the search URL parameter

The URL parameter search is used to customize API requests to Eloqua's application API endpoints by specifying search criteria to filter results.

The search parameter enables developers to filter for many use cases. Some examples include getting lists of assets that have been created or updated within a certain time frame, retrieving assets created by specific users, and retrieving lists of contact or account data created or updated after a specified date and time.

In this tutorial:

Understanding how the search URL parameter works

The syntax for the search parameter is: search={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 term with. Searches for exact full matches, and a * symbol can be used as a wildcard for partial matches.

You can search with fields even if they are not returned at the depth being used.

Terms

When selecting a term to search on, note that there are two categories of terms: properties and fields.

  • Properties: Endpoint specific properties such as updatedAt, createdAt, accessedAt, and so on that can be found within that endpoint's documentation. Generally supported by application API /asset endpoints. For example: api/rest/<version>/asset/<endpoint>.
  • Fields: System generated fields or Custom fields created in Eloqua. Generally supported by application API /data endpoints. For example: api/rest/<version>/data/<endpoint>.

Some terms support searching for blank values by including two single quotes (?search=M_City='').

The endpoint you are using may support specific properties, fields, or a combination or both. See the list of terms supported with search for more information on which properties and fields are supported.

Searching using a property as a term

Here's an example using the campaigns endpoint where we are using the updatedAt property to search a time frame.

GET /api/REST/2.0/assets/campaigns?search=updatedAt<'1417726743'updatedAt>'1417725656'

Note: When using search with a property (in example when interacting with most /asset endpoints) the time is expressed as a Unix time stamp for the date and time.

For most application API asset endpoints you can search with the createdBy and updatedBy properties, but the search value must be the login name, and not the user ID. For example:

GET /api/REST/2.0/assets/campaigns?search=createdBy=John.Doe

The login name is retrieved by user id with the retrieve a user or retrieve a list of users endpoints. Login name is returned with the name property.

Searching using a field as a term

Here's an example using the contact data endpoint where we are using the internal field name C_DateModified to search a time frame.

GET /api/REST/1.0/data/contacts?search=C_DateModified<'2018-02-06 18:50:05'C_DateModified>'2018-01-06 18:50:05'

Internal field names such as C_DateModified shown above can be retrieved using the appropriate endpoints. The table below outlines which endpoints are used to retrieve internal field names.

Entity API Endpoint
Accounts Bulk API Retrieve a list of account field definitions
Contacts Application API Retrieve a contact field
Retrieve a list of contact fields
  Bulk API Retrieve a list of account field definitions
Custom object records Application API Retrieve custom object
  Bulk API Retrieve a list of fields for a custom object

Note: To return the internal field name for application API endpoints, depth must be set to partial or complete. You can search with fields even if they are not returned at the depth being used.

Searching using a field also requires the time to be expressed in one of the following formats:

  • YYYY-MM-DD hh:mm:ss
  • MM-DD-YYYY hh:mm:ss
  • YYYY/MM/DD hh:mm:ss
  • MM\/DD/YYYY hh:mm:ss

    Note:

    • The date value will need to be using Eastern Time.
    • The specificity is limited as far as seconds.
    • The time should use military time.
    • Although some date and timestamps in Eloqua may display in milliseconds, the date and time fields retrieved using the search parameter, is accurate down to seconds. For example, a last modified date of 2016-03-08 14:47:10.650 may appear for a campaign, however the search query can only request greater than 2016-03-08 14:47:10.

Operators

The following operators are supported on most endpoints:

  • = (Equal To)
  • != (Not equal to)
  • > (Greater than)
  • < (Less than)
  • >= (Greater than or Equal to)
  • <= (Less than or Equal to)

If chaining more than one search criteria, each value must be placed in single quotes and will be chained as ANDs if using date fields.

?search=updatedAt<'1493347821'updatedAt>'1393347819'name='update*'

If including more than one non-date field, where they are the same field, they will be ORs.

?search=name='Test1'name='Test2'

This request would return two records, assuming they exist in Eloqua.

If including more than one different field, they will be ANDs.

?search=name='Test1'name='Test2'C_Company='Oracle'

This request will return records with a name of "Test1" or "Test2" and a Company of "Oracle".

Values

If there are spaces in the value, the value needs to be placed in single quotes:

?search=C_DateCreated>'2018-03-06 18:50:05'

Otherwise, single quotes are not required:

?search=updatedAt<1493347821

Note: If there are spaces and a single quote in the value, the value needs to be placed in single quotes and the single quote in the value needs to be escaped using a single quote.

Here is example searching for an email named "Test's Test Email":

?search='Test''s Test Email'

Examples

Using the search URL parameter to search a time frame for most application API asset endpoints:

GET /api/REST/2.0/assets/campaigns?search=updatedAt<'1417726743'updatedAt>'1417725656'

Also works with createdAt.

Using the search URL parameter to filter results by the user who created the asset:

GET /api/REST/2.0/assets/campaigns?search=createdBy=John.Doe

Also works with updatedBy.

Using the search URL parameter to search a time frame for application API data endpoints:

  • Contacts
    GET /api/REST/1.0/data/contacts?search=C_DateModified<'2018-02-06 18:50:05'C_DateModified>'2018-01-06 18:50:05'

    Also works with C_DateCreated.

  • Accounts
    GET /api/REST/1.0/data/accounts?search=M_DateModified<'2018-02-06 18:50:05'M_DateModified>'2018-01-06 18:50:05'

    Also works with M_DateCreated.

  • Custom objects
    GET /api/REST/1.0/data/customObject/9?search=ModifiedAt<'2017-06-28 00:00:00'ModifiedAt>'2017-01-09 10:15:00'
    Also works with CreatedAt.

Using the search URL parameter to search for blank values:

GET /api/REST/1.0/data/accounts?search=M_City=''

Using the search URL parameter to search for contacts that are linked to an account.

GET /api/REST/1.0/data/contacts?search=accountId>0

Best practices for using the wildcard character - "*"

A " * " symbol can be used for partial matches. It is recommended to use the " * " after the value whenever possible, as this produces the most efficient search.

Here are some common searches using a leading wildcard that can be changed to a more efficient search:

Endpoint Search value Leading wildcard search Alternative search
/api/REST/1.0/data/contacts Full email address
  • search=C_EmailAddress=*<fullEmailAddress>
  • search=emailAddress=*<fullEmailAddress>
  • search=common_fields=*<fullEmailAddress>
  • search=name=*<fullEmailAddress>
  • search=*<fullEmailAddress>
The same results are returned by removing the leading wildcard:
  • search=C_EmailAddress=<fullEmailAddress>
  • search=emailAddress=<fullEmailAddress>
  • search=common_fields=<fullEmailAddress>
  • search=name=<fullEmailAddress>
  • search=<fullEmailAddress>
/api/REST/1.0/data/contacts Email domain
  • search=C_EmailAddress=*<emailDomain>
  • search=emailAddress=*<emailDomain>
  • search=common_fields=*<emailDomain>
  • search=name=*<emailDomain>
  • search=*<emailDomain>
The same results are returned by using the C_EmailAddressDomain field without a leading wildcard:
  • search=C_EmailAddressDomain=<emailDomain>
The C_EmailAddressDomain field can also be used efficiently with a trailing wildcard:
  • search=C_EmailAddressDomain=<emailDomain>*

Best practices for searching custom object data

  • Do not use leading wildcard searches

    It is recommended to use the " * " after the value whenever possible, as this produces the most efficient search.

  • Searching for custom object records using custom fields

    If you plan to heavily search for custom object records by a custom field, then this custom field should be set to unique code, email, or display name field. In this case, an index will be added to the custom field.

  • Maintain a low custom object record volume

    Keep the number of records as low as possible in custom objects. For example, you can regularly delete unneeded custom object records.

List of terms supported with search

Note: For custom object records, you can only search by system dates using the 1.0 endpoint. The 2.0 endpoint does not support searching by system dates.

Endpoint Properties Fields
Accounts 1.0
  • name
  • createdAt

    YYYY-MM-DD hh:mm:ss format or similar

  • city
  • country
All system and custom fields
Contact fields 1.0
  • id

  • createdAt

    Unix format

  • name
 
Contact lists 1.0
  • id
  • folderId

  • updatedAt

    Unix format

  • createdAt

    Unix format

  • name
 
Contact segments 1.0
  • id
  • folderId

  • createdBy

    Value must be User login name

  • updatedBy

    Value must be User login name

  • name
 
Contacts 1.0
  • id
  • createdAt

    YYYY-MM-DD hh:mm:ss format or similar

  • name
  • emailAddress
  • lastName
  • accountId
All system and custom fields
Content Sections 1.0
  • id
  • folderId
  • createdBy
  • name
 
Custom object data1.0
  • id
  • uniqueCode
  • System
    • ModifiedAt

    • CreatedAt

  • Custom fields
Custom objects 1.0
  • id
  • name

  • createdBy

    Value must be User login name

  • updatedBy

    Value must be User login name

  • displayNameFieldId

 
Email folders 1.0
  • id
  • name
  • createdAt
  • updatedAt
  • folderId

  • createdBy

    Value must be User login name

  • updatedBy

    Value must be User login name

  
Email footers 1.0
  • id
  • name
  • folderId

  • createdBy

    Value must be User login name

  • updatedBy

    Value must be User login name

  
Email groups 1.0
  • id
  • name
 
Email headers 1.0
  • id
  • name
  • folderId
 
Emails 1.0
  • id
  • name

  • createdBy

    Value must be User login name

  • updatedBy

    Value must be User login name

  
Forms 1.0
  • id
  • name

  • createdBy

    Value must be User login name

  • updatedBy

    Value must be User login name

  
Images 1.0
  • id
  • name

  • createdAt

    Unix format

  • createdBy

    Value must be User login name

  • updatedBy

    Value must be User login name

  
Landing pages 1.0
  • id
  • name

  • createdAt

    Unix format

  • createdBy

    Value must be User login name

  • updatedBy

    Value must be User login name

  
Microsites 1.0
  • id
  • name

  • createdBy

    Value must be User login name

  • updatedBy

    Value must be User login name

  
Option lists 1.0

  • id

    Value must be user ID

  • name
 
Users 1.0
  • id
  • name

  • createdBy

    Value must be User login name

  • updatedBy

    Value must be User login name

  
Account groups 2.0
  • id
  • name
  • folderId

  • createdBy

    Value must be User login name

  • updatedBy

    Value must be User login name

  
Campaigns 2.0
  • id
  • name
  • createdAt

    Unix format

  • updatedAt

    Unix format

  • createdBy

    Value must be User login name

  • updatedBy

    Value must be User login name

  • campaignCategory

    Must be specified by ID. 1 being a contact campaign, 2 being an emailMarketing campaign.

  • endAt
  • crmId
  • currentStatus

    Must be specified by ID:

    • Active = 1
    • Draft = 2
    • Scheduled = 5
    • Completed = 7
  
Contact segments 2.0
  • id
  • name

  • createdBy

    Value must be User login name

  • updatedBy

    Value must be User login name

  
Custom object data 2.0
  • name
  • uniqueCode

  • contactId

    Only the = operator

  • accountId

    Only the = operator
  • System

    • CreatedAt

  • Custom fields
Custom objects 2.0
  • uniqueCode
  • name

 
Emails 2.0
  • name
  • createdAt

    Unix format

  • updatedAt

    Unix format

  • createdBy

    Value must be User login name

  • updatedBy

    Value must be User login name

  • emailGroupId

  • updatedByUserId

    Value must be User ID

  • createdByUserId

    Value must be User ID

  • contentSource

    Filters emails by content source ID. Specify the content source ID when searching.

    • editor = 0
    • upload = 1
    • responsive = 3
  
Event registrants 2.0
  • name
  • uniqueCode
 
Events 2.0
  • id
  • name

  • createdBy

    Value must be User login name

  • updatedBy

    Value must be User login name

  
External asset types 2.0
  • id
  • name

  • createdBy

    Value must be User login name

  • updatedBy

    Value must be User login name

  
External assets 2.0
  • id
  • name
 
Forms 2.0
  • name
  • createdAt

    Unix format

  • updatedAt

    Unix format

  • createdBy

    Value must be User login name

  • updatedBy

    Value must be User login name

  • updatedByUserId

    Value must be User ID

  • createdByUserId

    Value must be User ID

  • contentSource

    Filters forms by content source ID. Specify the content source ID when searching.

    • editor = 0
    • responsive = 3
  
Form Data 2.0 (Form Spam)

  • blockreason

    The reason for blocking the form submission. You can filter on the block reasons below:

    • Unknown

      Blocked because of an unknown reason.

    • InvalidToken

      Blocked because the form submitter had an invalid authentication token. Submitted using the form submit endpoint (a POST formsubmissionsource).

    • SiteIdMismatch

      Blocked because of a Site ID mismatch issue. Submitted using the form submit endpoint (a POST formsubmissionsource).

    • UserAgentMismatch

      Blocked because of a user agent mismatch issue. Submitted using the form submit endpoint (a POST formsubmissionsource).

    • TimestampTooFast

      Blocked because the form submit timestamp was submitted too quickly since the last form submit. Submitted using the form submit endpoint (a POST formsubmissionsource).

    • TimestampExpired

      Blocked because the timestamp expired. Submitted using the form submit endpoint (a POST formsubmissionsource).

    • InvalidHoneypotValue

      Blocked because of an invalid honey pot value. Submitted using the form submit endpoint (a POST formsubmissionsource).

    • AuthHashMismatch

      Blocked because of an authentication hash mismatch issue. Submitted using a blind form submit within an email (a GET formsubmissionsource).

  • formsubmissionsource

    • get

      Indicates the form was submitted through a blind form submit within an email.

    • post

      Indicates the form was submitted through a form submit endpoint.

  
Landing pages 2.0

  • name

    You can search a landing page's name and relativePath by using the leading wildcard "*". This is because the relativePath always starts with a "/". For example: ?search=name=*My_Landing_Page or ?search=*My_Landing_Page.

  • createdAt

    Unix format

  • updatedAt

    Unix format

  • createdBy

    Value must be User login name

  • updatedBy

    Value must be User login name

  • updatedByUserId

    Value must be User ID

  • createdByUserId

    Value must be User ID

  • contentSource

    Filters landing pages by content source ID. Specify the content source ID when searching.

    • editor = 0
    • upload = 1
    • migration = 2
    • responsive = 3
  
Programs 2.0
  • id
  • name
  • createdAt

    Unix format

  • updatedAt

    Unix format

  • createdBy

    Value must be User login name

  • updatedBy

    Value must be User login name

  • defaultEntityType

    Possible values:

    • Contacts
    • CustomObjectRecords
  • currentStatus

    Possible values:

    • Draft
    • Paused
    • Active
  • defaultEntityId

    For custom object programs, this is the ID of the selected custom object

  

Learn more

URL parameters

Application API

Eloqua API tutorials