Filters

Description

You can use filters to get a specified segment of your contacts.

Filters can be nested in and and or groups.

Operators

Operator Means Value
eq Equals string/integer/boolean/date
neq Not equals string/integer/boolean/date
sw Starts with string
ew Ends with string
ct Contains string
nct Not contains string
exists Exists boolean
gt Greater than integer/date
gte Greater than or equals integer/date
lt Less than integer/date
lte Less than or equals integer/date
in In array
nin Not in array

You can use the fields you have at GET /fields/account|contact using the owner_type as namespace. When you set a filter you can use either the field-name or the field id. If you use the id you have to use a id. prefix. You can also use these fields, but only with the name.

Field name Type
account.b2c boolean
account.created_at date
account.custom_fields.id.[field_id] integer
account.custom_fields.[field_name] string
account.fixed_fields.id.[field_id] integer
account.fixed_fields.[field_name] string
account.updated_at date
b2b_account.custom_fields.id.[field_id] integer
b2b_account.custom_fields.[field_name] string
b2b_account.fixed_fields.id.[field_id] integer
b2b_account.fixed_fields.[field_name] string
b2b_contact.custom_fields.id.[field_id] integer
b2b_contact.custom_fields.[field_name] string
b2b_contact.fixed_fields.id.[field_id] integer
b2b_contact.fixed_fields.[field_name] string
b2b_contact.consent.call.consent_given boolean, nullable
b2b_contact.consent.call.updated_at date
b2b_contact.consent.email.consent_given boolean, nullable
b2b_contact.consent.email.updated_at date
b2b_contact.consent.letter.consent_given boolean, nullable
b2b_contact.consent.letter.updated_at date
b2b_contact.consent.sms.consent_given boolean, nullable
b2b_contact.consent.sms.updated_at date
b2c_account.custom_fields.id.[field_id] integer
b2c_account.custom_fields.[field_name] string
b2c_account.fixed_fields.id.[field_id] integer
b2c_account.fixed_fields.[field_name] string
b2c_contact.custom_fields.id.[field_id] integer
b2c_contact.custom_fields.[field_name] string
b2c_contact.fixed_fields.id.[field_id] integer
b2c_contact.fixed_fields.[field_name] string
b2c_contact.consent.call.consent_given boolean, nullable
b2c_contact.consent.call.updated_at date
b2c_contact.consent.email.consent_given boolean, nullable
b2c_contact.consent.email.updated_at date
b2c_contact.consent.letter.consent_given boolean, nullable
b2c_contact.consent.letter.updated_at date
b2c_contact.consent.sms.consent_given boolean, nullable
b2c_contact.consent.sms.updated_at date
case.created_at date
case.extra_steps.id multiple_choice - Extra steps ids
case.latest_activity_at date
case.lead_type_id text - The id of the lead type
case.milestones.id multiple_choice - Milestone ids
case.milestones.type multiple_choice - Milestone type
case.milestones.created_at date
case.relations_path_id text - The id of the relations path
case.status single_choice - Can be open, closed and declined
case.supportive.id multiple_choice - Supportive ids
case.tasks.id string uuid
case.tasks.type single_choice - task type can be email, call, meeting, remind_me, or lettter
case.tasks.start_at date
case.tasks.end_at date
case.tasks.completed_at date
case.tasks.created_at date
case.tasks.user_id integer
case.tasks.status choice - can be pending, later, completed, overdue
case.stock_vehicle.id string uuid
contact.account.id text - the id of the account
contact.b2c boolean
contact.consent.call.consent_given boolean, nullable
contact.consent.call.updated_at date
contact.consent.email.consent_given boolean, nullable
contact.consent.email.updated_at date
contact.consent.letter.consent_given boolean, nullable
contact.consent.letter.updated_at date
contact.consent.sms.consent_given boolean, nullable
contact.consent.sms.updated_at date
contact.created_at date
contact.custom_fields.id.[field_id] integer, this currently means the same as b2c_contact, that behaviour is deprecated and will be changed
contact.custom_fields.[field_name] string, this currently means the same as b2c_contact, that behaviour is deprecated and will be changed
contact.fixed_fields.id.[field_id] integer, this currently means the same as b2c_contact, that behaviour is deprecated and will be changed
contact.fixed_fields.[field_name] string, this currently means the same as b2c_contact, that behaviour is deprecated and will be changed
contact.status single_choice - Can be lead, opportunity and customer
contact.team_id numeric - the id of the team
contact.updated_at date
lead.acceptions.team_id numeric
lead.account_id text
lead.assignments.team_id numeric
lead.case_id text
lead.contact_id text
lead.created_at date
lead.deleted_at date
lead.expires_at date
lead.interest text
lead.lead_source text
lead.lead_type text
lead.lead_type_id text
lead.rejections.team_id numeric
lead.status text
lead.team_id integer
lead.updated_at date
product_detail.product.category integer - The category ID
product_detail.product.comment text
product_detail.product.created_at date
product_detail.product.name text
product_detail.product.quantity integer

Date Values

Any date value can be passed to filtering in one of two formats. - Absolute

For example `2017-11-31 08:00:00`

  • Relative

    For example NOW+1d, that means this moment add one day. Or NOW-1d, that means this moment substract one day.

There are number of markers to use:

Time Marker Meaning
y years
M months
w weeks
d days
h hours
m minutes
s seconds

Filter format

The filter below will find all contacts that:

  • Have recieved a product detail with a product in the category which is eq to 17,
  • And will also get
    • OR (
      • Lastname contains an e
      • AND (
        • Belongs to an account named account.name
        • Have a custom field with value id 1, 3 or 5
      • )
    • )

Example

{
  "filter": [
    {
      "field": "product_detail.product.category",
      "operator": "eq",
      "value": 17
    },
    {
      "or": [
        {
          "field": "contact.fixed_fields.id.12",
          "operator": "ct",
          "value": "e"
        },
        {
          "and": [
            {
              "field": "account.fixed_fields.name",
              "operator": "eq",
              "value": "account name"
            },
            {
              "field": "contact.custom_fields.something_custom",
              "operator": "in",
              "value": [1,3,5]
            }
          ]
        }
      ]
    }
  ]
}

When using fields for a b2c account or contact you will have to specify that in the field-namespace.
If you want all your contacts, both b2c and b2b you can make a or group and set both account.fixed_fields.name and b2c_account.fixed_fields.name

When testing a filter or getting contacts based on a saved filter the resource is filter singular, and when creating/reading/updating/deleting filters it is filters plural!

Testing a filter

POST /contacts/filter

POST /accounts/filter

Parameters

Payload

{
  "filter": [
    {
      "field": "contact.fixed_fields.last_name",
      "operator": "ct",
      "value": "e"
    }
  ]
}

Response
Status code 200

{
  "data": [
    {
      "id": "263006cf-958c-3725-8e4e-4194805c3565",
      "b2c": false,
      "account": {
        "id": "2f215f8b-b98d-3c62-b812-68c89dc26ff3",
        "name": "Example"
      },
      "user": {
        "id": 10,
        "name": "John Doe"
      },
      "status": "customer",
      "fixed_fields": [
        {
          "type": "text",
          "name": "salutation",
          "label": "Salutation",
          "value": "Dr.",
          "validation": null,
          "required": false
        }
      ],
      "custom_fields": [],
      "created_at": "2015-02-24 12:34:56",
      "updated_at": "2015-02-24 12:34:56"
    }
  ],
  "pagination": {
    "total": 12,
    "page": 1,
    "per_page": 15,
    "urls": {
      "previous": null,
      "next": null
    }
  }
}

Create a filter

POST /contacts/filters

POST /accounts/filters

Parameters

Payload

{
  "name": "Test filter",
  "filter": [
    {
      "field": "contact.fixed_fields.last_name",
      "operator": "ct",
      "value": "e"
    }
  ]
}

Response
Status code 201

{
  "id": "addbefff-f2f0-49f7-be29-33a9444fb9ee",
  "name": "Test filter",
  "filter": [
    {
      "field": "contact.fixed_fields.last_name",
      "operator": "ct",
      "value": "e"
    }
  ],
  "created_at": "2015-04-21 11:51:10",
  "updated_at": "2015-04-21 11:51:10"
}

Updating a filter

PUT /contacts/filters/:filter_id

PUT /accounts/filters/:filter_id

Parameters

Payload

{
  "name": "Test filter. UPDATED",
  "filter": [
    {
      "field": "contact.fixed_fields.last_name",
      "operator": "ew",
      "value": "a"
    }
  ]
}

Response
Status code 200

{
  "id": "addbefff-f2f0-49f7-be29-33a9444fb9ee",
  "name": "Test filter. UPDATED",
  "filter": [
    {
      "field": "contact.fixed_fields.last_name",
      "operator": "ew",
      "value": "a"
    }
  ],
  "created_at": "2015-04-21 11:51:10",
  "updated_at": "2015-04-21 11:52:39"
}

List filters

GET /contacts/filters

GET /accounts/filters

Query string parameters

Response
Status code 200

{
  "data": [
    {
      "id": "1151abf3-3b11-49c1-90a1-d922bc429e76",
      "name": "Test filter",
      "created_at": "2015-04-21 08:27:12",
      "updated_at": "2015-04-21 08:27:12"
    }
  ],
  "pagination": {
    "total": 14,
    "page": 1,
    "per_page": 15,
    "urls": {
      "previous": null,
      "next": null
    }
  }
}

Get a filter

GET /contacts/filters/:filter_id

GET /accounts/filters/:filter_id

Response
Status code 200

{
  "id": "1151abf3-3b11-49c1-90a1-d922bc429e76",
  "name": "Test filter",
  "filter": [
    {
      "field": "contact.fixed_fields.last_name",
      "operator": "ct",
      "value": "e"
    }
  ],
  "created_at": "2015-04-21 08:27:12",
  "updated_at": "2015-04-21 08:27:12"
}

Delete a filter

DELETE /contacts/filters/:filter_id

DELETE /accounts/filters/:filter_id

Response
Status code 204