API Reference
Start typing to search…

Criteria

The Criteria clause is used to filter records.

SearchQuery

The SearchQuery (object under the Criteria) is composed of logical and comparison operators and represented as JSON objects, making it easy to create complex, nested searches.

The general format for comparison operators is as follows:

{
    "Criteria": {
        "SearchQuery": {
            "{FieldKey}": {
                "{Operator}": "{Value}"
            }
        }
    }
}

Here, {Operator} is the name of the operator, such as $EQ or $LIKE. {FieldKey} is the name of the object field under comparison, such as "LastName" or "CompanyName". {Value} is the value to be compared.

Comparison operators can be combined together using logical operators to form a compound search. The general format for logical operators is as follows:

{
    "Criteria": {
        "SearchQuery": {
            "$AND": [
                {
                    "{FieldKey1}": {
                        "{Operator1}": "{Value1}"
                    }
                },
                {
                    "{FieldKey2}": {
                        "{Operator2}": "{Value2}"
                    }
                }
            ]
        }
    }
}

This example illustrates how to combine multiple operators together by using the logical $AND operator.

Logical Operators

Some of the logical operators may be used to combine comparison operators to create compound searches.

$AND

The $AND operator combines one or more operands with a logical AND, meaning that all of the supplied operands must be true in order for a record to match the criteria. The $AND operator will accept an array containing any combination of comparison or logical operators as operands, including another $AND operator, thus allowing you to create complex nested conditional searches.

$AND - Return a list of contacts with a specific name

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "FirstName": 1,
                "LastName": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "$AND": [
                    {
                        "Type": {
                            "$EQ": "Contact"
                        }
                    },
                    {
                        "$PHRASE": "Name: Johnson"
                    }
                ]
            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

$OR

The $OR operator combines one or more operands with a logical OR, meaning that any records for which one or more of the supplied operands are true will match the criteria. The $OR operator will accept an array containing any combination of comparison or logical operators as operands, including another $OR operator, thus allowing you to create complex nested conditional searches.

$OR - Return a list of contacts and individuals

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "FirstName": 1,
                "LastName": 1,
                "Type": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "$OR": [
                    {
                        "Type": {
                            "$EQ": "Contact"
                        }
                    },
                    {
                        "Type": {
                            "$EQ": "Individual"
                        }
                    }
                ]
            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

$AND and $OR combined

$AND and $OR - Return a list of companies with a specific CompanyName

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "$AND": [
                    {
                        "Type": {
                            "$EQ": "Company"
                        }
                    },
                    {
                        "$OR": [
                            {
                                "CompanyName": {
                                    "$LIKE": "del%"
                                }
                            },
                            {
                                "CompanyName": {
                                    "$LIKE": "dup%"
                                }
                            }
                        ]
                    }
                ]
            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

Comparison Operators

Comparison operators are used to specify the field and value comparisons used for the search.

$EQ and $NE

  • Available Since API Version – 2.7\

The $EQ and $NE operators are used for doing exact comparisons against the value in a field. When an $EQ operator is included in a search, only those entries with a value that exactly matches the supplied value for the specified field will be returned. Conversely, when the $NE operator is included in a search, any entries that do not exactly match the supplied value for the specified field will be returned.

Certain entity types may contain some fields that do not support all available search operators. If you try to search on a field using an unsupported operator, the response will contain an error message indicating that the operator is unsupported for that field.

$EQ (equal) - Get 10 companies

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "Type": {
                    "$EQ": "Company"
                }
            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

$NE (not equal) - Get 10 contacts or individuals

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1,
                "FirstName": 1,
                "LastName": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "Type": {
                    "$NE": "Company"
                }
            },
            "Top": 10
        }
    }
    // Not available in the SQL driver yet
    // "Configuration": {
    //     "Drivers": {
    //         "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
    //     }
    // }
}

$GE and $LE

  • Available Since API Version – 2.7\

The $GE operator is used for doing searches for values that are greater than or equal to the specified value, and the $LE operator is used for doing searches for values that are less than or equal to the specified value.

Certain entity types may contain some fields that do not support all available search operators. If you try to search on a field using an unsupported operator, the response will contain an error message indicating that the operator is unsupported for that field.

$GE (greater than or equal) - Get 10 companies with last contact after January 2024

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1,
                "LastContactDate": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "$AND": [
                    {
                        "Type": {
                            "$EQ": "Company"
                        }
                    },
                    {
                        "LastContactDate": {
                            "$GE": "2024-01-01T00:00:00"
                        }
                    }
                ]

            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

$LE (lower than or equal) - Get 10 companies with last contact before January 2024

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1,
                "LastContactDate": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "$AND": [
                    {
                        "Type": {
                            "$EQ": "Company"
                        }
                    },
                    {
                        "LastContactDate": {
                            "$LE": "2024-01-01T00:00:00"
                        }
                    }
                ]

            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

$GT and $LT

  • Available Since API Version – 2.7\

The $GT operator is used for doing searches for values that are larger than the specified value, and the $LT operator is used for doing searches for values that are smaller than the specified value.

Certain entity types may contain some fields that do not support all available search operators. If you try to search on a field using an unsupported operator, the response will contain an error message indicating that the operator is unsupported for that field.

$GT (greater than) - Get 10 companies with last contact after January 2024

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1,
                "LastContactDate": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "$AND": [
                    {
                        "Type": {
                            "$EQ": "Company"
                        }
                    },
                    {
                        "LastContactDate": {
                            "$GT": "2024-01-01T00:00:00"
                        }
                    }
                ]

            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

$LT (lower than) - Get 10 companies with last contact before January 2024

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1,
                "LastContactDate": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "$AND": [
                    {
                        "Type": {
                            "$EQ": "Company"
                        }
                    },
                    {
                        "LastContactDate": {
                            "$LT": "2024-01-01T00:00:00"
                        }
                    }
                ]

            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

$IN, $NIN and $ALL

  • Available Since API Version – 2.7\

The $IN, $NIN, and $ALL operators are used for doing searches on tablevalued fields. The $IN operator will return entries where any of the specified values match, the $NIN operator will return entries where none of the specified entries match, and the $ALL operator will only return entries where all of the specified values match.

Certain entity types may contain some fields that do not support all available search operators. If you try to search on a field using an unsupported operator, the response will contain an error message indicating that the operator is unsupported for that field.

$IN (in) - Get 10 contacts or individuals

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1,
                "FirstName": 1,
                "LastName": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "Type": {
                    "$IN": ["Contact", "Individual"]
                }
            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

$NIN (not in) - Get 10 companies, except 2 specified

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "CompanyName": {
                    "$NIN": ["New World", "Maximizer"]
                }
            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

$ALL (all) - Get 10 abentries where a table UDF contains provided values

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "Udf/$NAME(Table UDF)": {
                    "$ALL": [
                        "1",
                        "3",
                        "5"
                    ]
                }
            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

$LIKE and $NLIKE

  • Available Since API Version – 2.7\

The $LIKE and $NLIKE operators are used for doing wildcard comparisons against string-valued fields. The function of the $LIKE operator is similar to that of the "LIKE" operator in a SQL query, and similar wildcards are used.

The operators accepts the following wildcards:

  • % - Matches any sequence of zero or more characters.\

  • _ - Matches any single character.\

Certain entity types may contain some fields that do not support all available search operators. If you try to search on a field using an unsupported operator, the response will contain an error message indicating that the operator is unsupported for that field.

$LIKE (search by a substring) - Search for a contact with name Steve or Steven

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "FirstName": 1,
                "LastName": 1,
                "CompanyName": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "FirstName": {
                    "$LIKE": "Steve%"
                }
            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

$NLIKE (search by a substring) - Search for a contact with name is not Steve

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "FirstName": 1,
                "LastName": 1,
                "CompanyName": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "FirstName": {
                    "$NLIKE": "Steve%"
                }
            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

$PHRASE

  • Available Since API Version – 2.4\

The $PHRASE operator is a special unary comparison operator that accepts only a search phrase and searches for the supplied phrase within a fixed set of fields.

The functionality of the $PHRASE operator is identical to the quick search bar in Maximizer Web Access. When you use the $PHRASE operator, any AbEntry objects with a matching FirstName, LastName, or CompanyName value are returned.

The $PHRASE operator also matches partial names that start with the search phrase. For example, searching for the name “John” would retrieve entries named “John Adams”, “Samantha Johnston”, and “Johnson Brothers Co”.

You can also use the $PHRASE operator to search for AbEntry objects by email address or phone number. If you supply all or part of an email address containing an @ symbol as the operand for the $PHRASE operator, all AbEntry objects with a matching email address are returned. Similarly, if you supply all or part of a numeric phone number as the operand, all AbEntry objects with a matching phone number are returned.

Certain entity types may contain some fields that do not support all available search operators. If you try to search on a field using an unsupported operator, the response will contain an error message indicating that the operator is unsupported for that field.

$PHRASE (search) - Retrieve 10 abentries for which the FirstName, LastName, or CompanyName field starts with the phrase "John"

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "$PHRASE":"John"
            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

$RANGE and $NRANGE

  • Available Since API Version – 2.7\

The $RANGE and $NRANGE operators are used for doing searches for values that fall within or outside a specified range in numeric or date fields.

Certain entity types may contain some fields that do not support all available search operators. If you try to search on a field using an unsupported operator, the response will contain an error message indicating that the operator is unsupported for that field.

$RANGE (search in the range) - Get 10 companies with the last contact in January 2024

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1,
                "LastContactDate": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "$AND": [
                    {
                        "Type": {
                            "$EQ": "Company"
                        }
                    },
                    {
                        "LastContactDate": {
                            "$RANGE": [
                                "2024-01-01T00:00:00",
                                "2024-01-31T23:59:59"
                            ]
                        }
                    }
                ]

            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

$NRANGE (search outside of the range) - Get 10 companies with the last contact NOT in January 2024 Copy

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1,
                "LastContactDate": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "$AND": [
                    {
                        "Type": {
                            "$EQ": "Company"
                        }
                    },
                    {
                        "LastContactDate": {
                            "$NRANGE": [
                                "2024-01-01T00:00:00",
                                "2024-01-31T23:59:59"
                            ]
                        }
                    }
                ]

            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

DateTime Operators

Octopus API provides a number of special functions that can be used when searching on DateTime fields. These functions allow you to search for dates and date ranges relative to the current date.

Each of the DateTime functions outlined in this section evaluates to a specific date range. However, when included in a search query, only the upper- or lower-bound of that range is used in the evaluation of the search, depending on whether the search operator being used is inclusive or exclusive.

The following conventions are used when evaluating search queries that include a special date range operator:

  • $LT - The lower-bound of the operator's range is used, and the query matches all entries with a value below the lower-bound, excluding values within the range.\

  • $LE - The upper-bound of the operator's range is used, and the query matches all entries with a value below the upper-bound, including values within the range.\

  • $GT - The upper-bound of the operator's range is used, and the query matches all entries with a value above the lower-bound.\

  • $GE - The lower-bound of the operator's range is used, and the query matches all entries with a value above the upper-bound, including values within the range.\

  • $RANGE - When used as the lower-bound of a $RANGE query, the operator's lower-bound is used, and when used as the upper-bound of a $RANGE query, the operator's upper-bound is used, so values within the operator's range are included in the results.\

  • $NRANGE - When used as the lower-bound of a $RANGE query, the operator's upper-bound is used, and when used as the upper-bound of a $RANGE query, the operator's lower-bound is used, so values within the operator's range are not included in the results.\

For example, the $TODAY() function evaluates to a date range from a time of 00:00:00 to 23:59:59 on the current date. When used in a $LT (less-than) query, the lower-bound of the range (00:00:00) would be used, and the search would return all entries with a DateTime occurring before the current date. Alternatively, when used in a $LE (less-than-or-equal-to) query, the upper-bound of the range (23:59:59) would be used, and the search would return all entries with a DateTime occuring on or before the current date.

$NOW()

  • Available Since API Version – 2.7\

The $NOW() function may be used to search for DateTime values relative to the current time. When included in a search query, it evaluates to the current date and time.

$NOW() - Get 10 companies created before the current time

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1,
                "CreationDate": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "$AND": [
                    {
                        "Type": {
                            "$EQ": "Company"
                        }
                    },
                    {
                        "CreationDate": {
                            "$LT": "$NOW()"
                        }
                    }
                ]

            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

$TODAY()

  • Available Since API Version – 2.7\

The $TODAY() function may be used to search for DateTime values relative to the current day. When included in a search query, it evaluates to a date range spanning the current day from 00:00:00 in the morning to 23:59:59 at night.

$TODAY() - Get 10 companies created before today

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1,
                "CreationDate": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "$AND": [
                    {
                        "Type": {
                            "$EQ": "Company"
                        }
                    },
                    {
                        "CreationDate": {
                            "$LT": "$TODAY()"
                        }
                    }
                ]

            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

$THISWEEK()

  • Available Since API Version – 2.7\

The $THISWEEK() function may be used to search for DateTime values relative to the current week. When included in a search query, it evaluates to a date range including the first and last days of the current calendar week.

$THISWEEK() - Get 10 companies created before the current week

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1,
                "CreationDate": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "$AND": [
                    {
                        "Type": {
                            "$EQ": "Company"
                        }
                    },
                    {
                        "CreationDate": {
                            "$LT": "$THISWEEK()"
                        }
                    }
                ]

            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

$THISMONTH()

  • Available Since API Version – 2.7\

The $THISMONTH() function may be used to search for DateTime values relative to the current month. When included in a search query, it evaluates to a date range including the first and last days of the current calendar month.

$THISMONTH() - Get 10 companies created before the current month

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1,
                "CreationDate": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "$AND": [
                    {
                        "Type": {
                            "$EQ": "Company"
                        }
                    },
                    {
                        "CreationDate": {
                            "$LT": "$THISMONTH()"
                        }
                    }
                ]

            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

$THISYEAR()

  • Available Since API Version – 2.7\

The $THISYEAR() function may be used to search for DateTime values relative to the current year. When included in a search query, it evaluates to a date range including the first and last days of the current calendar year.

$THISYEAR() - Get 10 companies created before the current year

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1,
                "CreationDate": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "$AND": [
                    {
                        "Type": {
                            "$EQ": "Company"
                        }
                    },
                    {
                        "CreationDate": {
                            "$LT": "$THISYEAR()"
                        }
                    }
                ]

            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

$OFFSET()

  • Available Since API Version – 2.7\

The $OFFSET() function allows you to search for DateTime values relative to a specified date part value. When included in a search query, the function evaluates to a specific date based on the given rule.

Syntax

$OFFSET(rule, date)

Rule syntax

[offset by][+|-][specific date|funclet]

Offset By Values

The offset by part can have the following values:

  • Y = Year\

  • M = Month\

  • D = Day\

  • W = Week\

  • Q = Quarter\

  • h = Hour\

  • m = Minute\

  • s = Second\

Funclets

The use of funclets as parameters for the $OFFSET() function is allowed, and the evaluation will depend on the context of the funclet used.

  1. Single/Exact Date

    • The $NOW() funclet for example, evaluates to a specific date and time, meaning that when it is used as a parameter for $OFFSET(), the resulting value will also be a single, exact date.\

    • For example, if you apply an offset of 2 hours to $NOW(), the result will be a precise timestamp reflecting that offset.\

  2. Range of Dates

    • In contrast, the $TODAY() funclet for example, evaluates to a range of dates, specifically from the beginning of the day at 00:00:00 to the end of the day at 23:59:59.\

    • When you use $TODAY() as a parameter for $OFFSET(), the evaluation will yield a corresponding range of dates. For instance, if you apply an offset of 1 day to $TODAY(), the result will cover the entire day of tomorrow.\

The Octopus engine automatically evaluates these funclets based on their context. It is crucial to select the appropriate funclet based on your requirements to achieve the desired outcome.

Examples

  • Example 1
    $OFFSET(M+6, $NOW())
    This expression returns the date and time exactly 6 months from the current date and time. For instance, if the current date and time is 2025-07-09T18:34:45, this expression will evaluate to the exact date 2026-01-09T18:34:45.\

  • Example 2
    $OFFSET(Y-1, $TODAY())
    This expression returns the date range for exactly 1 year ago. If today is 2025-07-09, this expression will evaluate to the range [2024-07-09T00:00:00, 2024-07-09T23:59:59].\

  • Example 3
    $RANGE($THISMONTH(), $OFFSET(M+6, $THISMONTH()))

    The $OFFSET() function can also be used as a parameter for other funclets. In this example, here's a breakdown of how this will be evaluated:

    • The $RANGE() funclet accepts both single dates and ranges as parameters, and it will choose which date to use based on the context.\

    • The first parameter is the "start" of the range (lower value). Since $THISMONTH() evaluates to a range of dates, the engine is smart enough to select the lower value from that range.\

    • The same logic applies to the second parameter, which is the "end" of the range (upper value). The engine will choose the upper value resulting from the $OFFSET().\

    • Considering the current date is 2025-07-09:

      • $THISMONTH() evaluates to the range [2025-07-01, 2025-07-31].\

      • $OFFSET(M+6, $THISMONTH()) evaluates to the range [2026-01-01, 2026-01-31] (as $THISMONTH() evaluates to a range of dates and the M+6 offset will be applied to both dates in the range).\

    • Thus, $RANGE() will use the "lower value" of the first parameter, which is 2025-07-01, and the "upper value" of the second parameter, which is 2026-01-31.\

    • In summary, the expression $RANGE($THISMONTH(), $OFFSET(M+6, $THISMONTH())) will evaluate to the range [2025-07-01, 2026-01-31].

$OFFSET() - Get 10 companies created in the past 90 days

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1,
                "CreationDate": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "$AND": [
                    {
                        "Type": {
                            "$EQ": "Company"
                        }
                    },
                    {
                        "CreationDate": {
                            "$GT": "$OFFSET(D-90, $TODAY())"
                        }
                    }
                ]

            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

$OFFSET() - Get 10 opportunities planned to be closed between the beginning of this month and the end of the 6th month from this month

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "Opportunity": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Objective": 1,
                "CloseDate": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "CloseDate": {
                    // Will evaluate to the first day of the current month and the last day of the month 6 months from now
                    "$RANGE": [
                        "$THISMONTH()",
                        "$OFFSET(M+6, $THISMONTH())"
                    ]
                }
            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IOpportunitySearcher": "Maximizer.Model.Access.Sql.OpportunitySearcher"
        }
    }
}

Searching by a nested property - search a company by ZipCode

  • Available Since API Version – 2.7\

The $EQ operator is used for doing exact comparisons against the value in a field. When an $EQ operator is included in a search, only those entries with a value that exactly matches the supplied value for the specified field will be returned.

Certain entity types may contain some fields that do not support all available search operators. If you try to search on a field using an unsupported operator, the response will contain an error message indicating that the operator is unsupported for that field.

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1,
                "Address/ZipCode": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "$AND": [
                    {
                        "Type": {
                            "$EQ": "Company"
                        }
                    },
                    {
                        "Address": {
                            "ZipCode": {
                                "$EQ": "83814"
                            }
                        }
                    }
                ]
            },
            "Top": 10
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

Top

The Top operator is used to limit the number of results.

Top - Get 3 company

  • Available Since API Version – 2.7\

The $EQ operator is used for doing exact comparisons against the value in a field. When an $EQ operator is included in a search, only those entries with a value that exactly matches the supplied value for the specified field will be returned.

Certain entity types may contain some fields that do not support all available search operators. If you try to search on a field using an unsupported operator, the response will contain an error message indicating that the operator is unsupported for that field.

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Type": 1,
                "CompanyName": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "Type": {
                    "$EQ": "Company"
                }
            },
            "Top": 3
        }
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

FavoriteList

The FavoriteList operator limits records to a chosen list.

Retrieve all AbEntries from a FavoriteList

The $AND operator combines one or more operands with a logical AND, meaning that all of the supplied operands must be true in order for a record to match the criteria. The $AND operator will accept an array containing any combination of comparison or logical operators as operands, including another $AND operator, thus allowing you to create complex nested conditional searches.

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "AbEntry": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "FirstName": 1,
                "LastName": 1
            }
        },
        "Criteria": {
            "FavoriteList": "RmF2b3JpdGVMaXN0CTQ1Mzk1MDI0"
        }
    },
    "Compatibility": {
        "AbEntryKey": "2.0"
    },
    "Configuration": {
        "Drivers": {
            "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
        }
    }
}

Retrieve all Opportunities from a FavoriteList

The $AND operator combines one or more operands with a logical AND, meaning that all of the supplied operands must be true in order for a record to match the criteria. The $AND operator will accept an array containing any combination of comparison or logical operators as operands, including another $AND operator, thus allowing you to create complex nested conditional searches.

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "Opportunity": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Objective": 1,
                "Description": 1
            }
        },
        "Criteria": {
            "FavoriteList": "RmF2b3JpdGVMaXN0CTQxOTY5NjE1MA=="
        }
    },
    "Configuration": {
        "Drivers": {
            "IOpportunitySearcher": "Maximizer.Model.Access.Sql.OpportunitySearcher"
        }
    }
}

Retrieve all Cases from a FavoriteList

The $AND operator combines one or more operands with a logical AND, meaning that all of the supplied operands must be true in order for a record to match the criteria. The $AND operator will accept an array containing any combination of comparison or logical operators as operands, including another $AND operator, thus allowing you to create complex nested conditional searches.

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "Case": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Subject": 1,
                "Description": 1
            }
        },
        "Criteria": {
            "FavoriteList": "RmF2b3JpdGVMaXN0CTQxOTY5OTE1MQ=="
        }
    },
    "Configuration": {
        "Drivers": {
            "ICaseSearcher": "Maximizer.Model.Access.Sql.CaseSearcher"
        }
    }
}

Retrieve all Leads from a FavoriteList

The $AND operator combines one or more operands with a logical AND, meaning that all of the supplied operands must be true in order for a record to match the criteria. The $AND operator will accept an array containing any combination of comparison or logical operators as operands, including another $AND operator, thus allowing you to create complex nested conditional searches.

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "Lead": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "FirstName": 1,
                "LastName": 1
            }
        },
        "Criteria": {
            "FavoriteList": "RmF2b3JpdGVMaXN0CTMJMg=="
        }
    }
}