/Emails/filter POST

Overview

Lists filtered records.

Summary

This endpoint will return a set of records filtered by an expression. The filter can be applied to multiple fields and have multiple and/or conditions in it. Alternatively, you may use an existing filter by specifying its id. If both a filter definition and a filter id are passed, the two filters will be joined with an AND. Care will need to be taken to make sure that any filters used have appropriate indexes on the server side otherwise the runtime of the endpoint will be very long. Related fields can be searched by specifying the field name as: "link_name.remote_field", so if you wished to search the Accounts module by a related member account you would use "members.sic_code".

Request Arguments

Name	Type	Description	Required
filter	String	The filter expression. Filter expressions are explained below.	False
filter_id	String	Identifier for a preexisting filter. If filter is also set, the two filters are joined with an `AND`.	False
max_num	Integer	A maximum number of records to return. Default is 20.	False
offset	Integer	The number of records to skip over before records are returned. Default is 0.	False
fields	String	Comma delimited list of fields to return. The field date_modified will always be returned. Example: `name,account_type,description`	False
view	String	Instead of defining the fields argument, the view argument can be used instead. The field list is constructed at the server side based on the view definition which is requested. This argument can be used in combination with the fields argument. Common views are "record" and "list". Example: `record`	False
order_by	String	How to sort the returned records, in a comma delimited list with the direction appended to the column name after a colon. Example: `name:DESC,account_type:DESC,date_modified:ASC`	False

Filter Expressions

There are four types of filters:

Basic

This will filter the results by checking the field "name" for value "Nelson Inc". This will only find exact matches.

Example

{
   "filter":[
      {
         "name":"Nelson Inc"
      }
   ]
}

Full

This expression allows you to specify what operation you want to use for filtering on the field. In the example you would match any record where the field "name" starts with the value "Nelson".

Example

{
   "filter":[
      {
         "name":{
            "$starts":"Nelson"
         }
      }
   ]
}

Below is a list of operation types:

Operation	Description
$equals	Performs an exact match on that field.
$not_equals	Performs an exact match on that field.
$not_equals	Matches on non-matching values.
$starts	Matches on anything that starts with the value.
$ends	Matches anything that ends with the value.
$contains	Matches anything that contains the value
$in	Finds anything where field matches one of the values as specified as an array.
$not_in	Finds anything where field does not matches any of the values as specified as an array.
$is_null	Checks if the field is null. This operation does not need a value specified.
$not_null	Checks if the field is not null. This operation does not need a value specified.
$lt	Matches when the field is less than the value.
$lte	Matches when the field is less than or equal to the value.
$gt	Matches when the field is greater than the value.
$gte	Matches when the field is greater than or equal to the value.

Sub-expressions

This allows you to group filter expressions into or/and groupings. By default all expressions are and'ed together. The example expression would match if the field "name" was either "Nelson Inc" or "Nelson LLC". The only currently accepted sub-expression types are "$and" and "$or".

Example

{
   "filter":[
      {
         "$or":[
            {
               "name":"Nelson Inc"
            },
            {
               "name":"Nelson LLC"
            }
         ]
      }
   ]
}

Modules

There are two module expressions, they operate on modules instead of fields. The current module can be specified by either using the module name "_this" or by leaving the module name as a blank string. The example expression would filter the records in the current module to only your favorites. The only currently accepted module expressions are "$favorite" and "$owner".

Example

{
   "filter":[
      {
         "$favorite":"_this"
      }
   ]
}

Response Arguments

Name	Type	Description
next_offset	Integer	Displays the next offset for retrieval of additional results. -1 will be returned when there are no more records.
records	Array	An array of results containing matched records.

Response

{
   "next_offset":-1,
   "records":[
      {
         "id":"fa300a0e-0ad1-b322-9601-512d0983c19a",
         "name":"Dale Spivey",
         "date_entered":"2013-02-26T19:12:00+00:00",
         "date_modified":"2013-02-28T05:03:00+00:00",
         "modified_user_id":"1",
         "modified_by_name":"Administrator",
         "created_by":"1",
         "created_by_name":"Administrator",
         "description":"",
         "img":"",
         "deleted":false,
         "assigned_user_id":"seed_sally_id",
         "assigned_user_name":"Sally Bronsen",
         "team_name":[
            {
               "id":"East",
               "name":"East",
               "name_2":"",
               "primary":false
            },
            {
               "id":1,
               "name":"Global",
               "name_2":"",
               "primary":false
            },
            {
               "id":"West",
               "name":"West",
               "name_2":"",
               "primary":true
            }
         ],
         "salutation":"",
         "first_name":"Dale",
         "last_name":"Spivey",
         "full_name":"Dale Spivey",
         "title":"VP Operations",
         "linkedin":"",
         "facebook":"",
         "twitter":"",
         "googleplus":"",
         "department":"",
         "do_not_call":false,
         "phone_home":"(523) 825-4311",
         "email":[
            {
               "email_address":"sugar.dev.sugar@example.co.jp",
               "opt_out":"0",
               "invalid_email":"0",
               "primary_address":"1"
            },
            {
               "email_address":"the.support@example.biz",
               "opt_out":"0",
               "invalid_email":"0",
               "primary_address":"0"
            }
         ],
         "phone_mobile":"(373) 861-0757",
         "phone_work":"(212) 542-9596",
         "phone_other":"",
         "phone_fax":"",
         "email1":"sugar.dev.sugar@example.co.jp",
         "email2":"the.support@example.biz",
         "invalid_email":false,
         "email_opt_out":false,
         "primary_address_street":"345 Sugar Blvd.",
         "primary_address_street_2":"",
         "primary_address_street_3":"",
         "primary_address_city":"Denver",
         "primary_address_state":"CA",
         "primary_address_postalcode":"87261",
         "primary_address_country":"USA",
         "alt_address_street":"",
         "alt_address_street_2":"",
         "alt_address_street_3":"",
         "alt_address_city":"",
         "alt_address_state":"",
         "alt_address_postalcode":"",
         "alt_address_country":"",
         "assistant":"",
         "assistant_phone":"",
         "picture":"",
         "email_and_name1":"",
         "lead_source":"Campaign",
         "account_name":"Smallville Resources Inc",
         "account_id":"d5db6292-5c24-eb61-e202-512d09f0134e",
         "opportunity_role_fields":"",
         "opportunity_role_id":"",
         "opportunity_role":"",
         "reports_to_id":"",
         "report_to_name":"",
         "portal_name":"DaleSpivey97",
         "portal_active":true,
         "portal_password":"$1$yKMAONHM$Y5S.8CY.WZCZCwfGD1a1Q\/",
         "portal_password1":"",
         "portal_app":"",
         "preferred_language":"en_us",
         "campaign_id":"",
         "campaign_name":"",
         "c_accept_status_fields":"",
         "m_accept_status_fields":"",
         "accept_status_id":"",
         "accept_status_name":"",
         "sync_contact":"",
         "my_favorite":false,
         "_acl":{
            "fields":{

            }
         }
      },
      {
         "id":"95e17367-9b3d-0e26-22dc-512d0961fedf",
         "name":"Florence Haddock",
         "date_entered":"2013-02-26T19:12:00+00:00",
         "date_modified":"2013-02-26T19:12:00+00:00",
         "modified_user_id":"1",
         "modified_by_name":"Administrator",
         "created_by":"1",
         "created_by_name":"Administrator",
         "description":"",
         "img":"",
         "deleted":false,
         "assigned_user_id":"seed_sally_id",
         "assigned_user_name":"Sally Bronsen",
         "team_name":[
            {
               "id":"East",
               "name":"East",
               "name_2":"",
               "primary":false
            },
            {
               "id":1,
               "name":"Global",
               "name_2":"",
               "primary":false
            },
            {
               "id":"West",
               "name":"West",
               "name_2":"",
               "primary":true
            }
         ],
         "salutation":"",
         "first_name":"Florence",
         "last_name":"Haddock",
         "full_name":"Florence Haddock",
         "title":"Director Sales",
         "linkedin":"",
         "facebook":"",
         "twitter":"",
         "googleplus":"",
         "department":"",
         "do_not_call":false,
         "phone_home":"(729) 845-3137",
         "email":[
            {
               "email_address":"dev.vegan@example.de",
               "opt_out":"1",
               "invalid_email":"0",
               "primary_address":"0"
            },
            {
               "email_address":"section71@example.it",
               "opt_out":"0",
               "invalid_email":"0",
               "primary_address":"1"
            }
         ],
         "phone_mobile":"(246) 233-1382",
         "phone_work":"(565) 696-6981",
         "phone_other":"",
         "phone_fax":"",
         "email1":"section71@example.it",
         "email2":"dev.vegan@example.de",
         "invalid_email":false,
         "email_opt_out":false,
         "primary_address_street":"111 Silicon Valley Road",
         "primary_address_street_2":"",
         "primary_address_street_3":"",
         "primary_address_city":"Denver",
         "primary_address_state":"CA",
         "primary_address_postalcode":"79900",
         "primary_address_country":"USA",
         "alt_address_street":"",
         "alt_address_street_2":"",
         "alt_address_street_3":"",
         "alt_address_city":"",
         "alt_address_state":"",
         "alt_address_postalcode":"",
         "alt_address_country":"",
         "assistant":"",
         "assistant_phone":"",
         "picture":"",
         "email_and_name1":"",
         "lead_source":"Support Portal User Registration",
         "account_name":"Smallville Resources Inc",
         "account_id":"d5db6292-5c24-eb61-e202-512d09f0134e",
         "opportunity_role_fields":"",
         "opportunity_role_id":"",
         "opportunity_role":"",
         "reports_to_id":"",
         "report_to_name":"",
         "portal_name":"FlorenceHaddock169",
         "portal_active":true,
         "portal_password":"$1$nWFhTbK6$JF9BCGSqL\/NCrbhueX5ia0",
         "portal_password1":"",
         "portal_app":"",
         "preferred_language":"en_us",
         "campaign_id":"",
         "campaign_name":"",
         "c_accept_status_fields":"",
         "m_accept_status_fields":"",
         "accept_status_id":"",
         "accept_status_name":"",
         "sync_contact":"",
         "my_favorite":false,
         "_acl":{
            "fields":{

            }
         }
      }
   ]
}

Change Log

Version	Change
v10	Added `/<module>/filter` POST endpoint.