Search Using the API

The Momentus Connect V2 API provides you robust searching capabilities much like you have in the back office application. The API uses a combination of OData notation and a paging mechanism to power API searching using HTTP GET endpoints.

Search Limits

There are no data, request, or size limits using the  API. However, we ask that you not abuse your API with too many requests as this results in poor performance for both you and other users if you are in the Cloud. What qualifies as abuse? Actual numbers depends on factors such as call frequency within a process, response quantity, response model size and how often a process happens so it is determined on a case-by-case basis.

For example, if you request 100,000 accounts through the API, that's a large quantity and the default Accounts model is large, so you can expect slow performance. Another example is if you request 10,000 events every second for days at a time. That is a large quantity in a very frequent hit on the server, resulting in a hard churn. This also might result in a negative effect. 

The API does provide provide a paging mechanism which can help with the larger datasets.

OData

Use OData notation to form search queries. Here is an example:

/api/v2/Accounts?orgCode=10&orderby=AccountCode&page=3&pagesize=10

What does this do? Let’s break it down.

  • /api/v2/ is the base API Url. Every call to the API has this.

  • Accounts represents the subject you are searching.

  • ?orgCode represents the organization code you are searching over. Searches are per organization only.

  • Next is sorting, denoted by the &orderby operator. After this operator, you list the properties you want to order your search by, also qualifying it with desc if you want to have that property sort descending. Each property added is sorted ascending by default. Multiple levels of sorting are achieved by comma-delimited property names.

  • &page and &pagesize parameter defines page number how many items per page are returned respectively. The default is page 1 and page size 200. It is optional.

Supported OData Operators

  • Equals (eq)

  • Greater Than (gt)

  • Greater Than Or Equal (ge)

  • Less Than (lt)

  • Less Than Or Equal (le)

  • Not Equal (ne)

  • Substring of (substringof)

  • Starts With (startswith)

  • Ends With (endswith)

Also, the API can do AND and ORs together but no parentheses. It's suggested to group the ORs together to get expected results. For example:

  • ODATA:  A and B or C              Result:  A and (B or C)

  • ODATA:  A and B or C and D    Result:  A and (B or C) and D

  • ODATA:  A or B or C and D      Result:  (A or B or C) and D 

Paging

The API provides a paging mechanism for all searching. By default, the page size is 200. Below are the parameters you can send in to your search query to control how paging works:

  • &pagesize – Determines how many results are returned in each search call.

  • &page – Gets a specific page from a result set.

The paged results are cached within the server that accepted the query. If future calls are load balanced, the call may not work due to hitting a different server that doesn't have that search cached.

OData Examples By Type

Strings

  • Find all accounts in organization 10 where the first name equals 'John' and last name equals = 'Smith'

    • /api/v2/Accounts?orgCode=10&search=FirstName eq 'John' and LastName eq 'Smith'

Dates

  • Find bookings after September 29, 2019

    • /api/v2/Bookings?orgCode=10&search=StartDateTime eq DateTime'2019-09-28T00:00:00'

  • Find bookings with the start date on 2019-09-28

    • /api/v2/Bookings?orgCode=10&search=StartDateTime ge DateTime'2019-09-28T00:00:00' and StartDateTime lt DateTime'2019-09-29T00:00:00'

Search for Null and Not Null

You can search for null and not null values. You can use this in conjunction with other filters.

Examples:

/api/v2/Accounts?orgCode=10&search=Phone ne null

This finds all Accounts with Phone fields not null.

New v2 API Query Params:

  1. Search On Demand: This feature is exclusive to Search APIs. By using the search query parameter, you can perform nested searches within Lookup Objects based on unique key.

    Eg:- /api/v2/Accounts?orgCode=10&search=Class eq 'O' and Type.Code eq '1B'
    In the example above, for the Accounts List, the query searches within the Type Lookup for entries where the Code matches '1B'. Here, the Code is the unique key within the Type Lookup Object. Executing this query returns all accounts with Type.Code as '1B'.

  2. Get By Demand: This feature is available for both Search and Get By Id APIs. By using the includeFields query parameter, you can retrieve additional keys in lookup objects beyond the usual ones.

    Eg:- /api/v2/Accounts/10/00014166?includeFields=Type.Category
    In the above Get By Id example, for Accounts, passing includeFields with the value Type.Category will also include the Category key in the existing Type Lookup Object. By default, the existing Lookup Object only contains Code and Description keys.

  3. Get All Fields: This feature is available for both Search and Get By Id APIs. By using the includeAllFields query parameter, you can fetch extra keys present in the v1 API.

    Eg:- /api/v2/Accounts/10/00020002?includeAllFields=true
    In the above Get By Id example, for Accounts, passing includeAllFields with the value true will return all the extra keys present in the v1 API. This feature is designed to reduce the chattiness of the API. If not specified, includeAllFields defaults to false, and only a limited number of keys are returned.