How to search for users who updated their custom fields during a daterange via API?

You can use our API to query for users who have updated their custom fields during a specific time period.

Example request:

curl --location --request POST 'https://sandbox.piano.io/api/v3/publisher/user/search?api_token=<TOKEN>' \\
--header 'Content-Type: application/x-www-form-urlencoded' \\
--data-urlencode 'aid=<AID>' \\
--data-urlencode 'exclude_cf_metadata=true' \\
--data-urlencode 'source=CF' \\
--data-urlencode 'custom_fields=[{"field_name": "birthday","data_type": "NUMBER","condition": {"type": "ANY"},"response_time": {"type": "MORE","more":"2020-10-28"}}, {"field_name": "age","data_type": "NUMBER","condition": {"type": "ANY"},"response_time": {"type": "EQUAL","equal":"2020-10-28"}}]'

In the above, you would be searching for 2 conditions: the custom field birthday updated after 2020-10-28 and the custom field age updated on 2020-10-28.

If you want to do a search for records updated between two dates, then the condition would look like this:

"response_time": {"type": "BETWEEN","less":"2020-10-28", "more":"2020-10-31"}

The timezone used to evaluate the response time is UTC.

The parameter custom_fields is a JSON array where each search item is an object with a specifc format.

Below are the possible conditions for all custom field types.

Single select

{
    "field_name": "occupation_status",
    "data_type": "SINGLE_SELECT_LIST",
    "condition": {
      "type": "EQUAL",
      "optionsEqual": {
        "value": "Full-time work"
      }
    }
  }

  {
    "field_name": "occupation_status",
    "data_type": "SINGLE_SELECT_LIST",
    "condition": {
      "type": "EMPTY" // or "ANY"
    }
  }

Multi select

 {
    "field_name": "occupation_status",
    "data_type": "MULTI_SELECT_LIST",
    "condition": {
      "type": "EMPTY" // or "ANY"
    }
  }

  {
    "field_name": "occupation_status",
    "data_type": "MULTI_SELECT_LIST",
    "condition": {
      "type": "IN",
      "optionsIn": [
        { "value": "Antilles" },
        { "value": "Antigua and Barbuda" }
      ]
    }
  }

Date

  {
    "field_name": "age",
    "data_type": "ISO_DATE",
    "condition": {
      "type": "EMPTY" // or "ANY"
    }
  }
 
  {
    "field_name": "age",
    "data_type": "ISO_DATE",
    "condition": {
      "type": "EQUAL", // or "MORE" or "LESS"
      "equal": "2025-03-04"
    }
  }
 
  {
    "field_name": "age",
    "data_type": "ISO_DATE",
    "condition": {
      "type": "BETWEEN",
      "more": "2025-03-03",
      "less": "2025-03-12"
    }
  }

Text

  {
    "field_name": "Text",
    "data_type": "TEXT",
    "condition": {
      "type": "EMPTY" // or "ANY"
    }
  }
  
  {
    "field_name": "Text",
    "data_type": "TEXT",
    "condition": {
      "type": "LIKE", // or "EQUAL" or "EXACT_MATCH"
      "like": "Test"
    }
  }

Number

  {
    "field_name": "ltnumber1",
    "data_type": "NUMBER",
    "condition": {
      "type": "EMPTY" // or "ANY"
    }
  }
  
  {
    "field_name": "ltnumber1",
    "data_type": "NUMBER",
    "condition": {
      "type": "EQUAL", // or "MORE" or "LESS"
      "equal": "12"
    }
  }
  
  {
    "field_name": "ltnumber1",
    "data_type": "NUMBER",
    "condition": {
      "type": "BETWEEN",
      "more": "12",
      "less": "13"
    }
  }

Boolean

  {
    "field_name": "Approve",
    "data_type": "BOOLEAN",
    "condition": {
      "type": "EMPTY" // or "ANY"
    }
  }
  
  {
    "field_name": "Approve",
    "data_type": "BOOLEAN",
    "condition": {
      "type": "EQUAL",
      "equal": true // or false
    }
  }

How the rules of condition types work is described here.

Last updated: June 26, 2026