API v3 Search Request Overview

The Foundation Platform version 3(v3) API was designed to give the scope and power of our internal Development Team to the user managing his or her data.  One powerful facet of the v3 API is the Search action.  The Search action allows the querying of any Endpoint  to receive desired data that has been filtered. The user may choose to manipulate the response by adding one or more filters that adjust the range of data returned.  There is no limit on the number of filters that can be used in the API request.

A common example of a v3 API Search Request.

API Search Request Breakdown

  • Endpoint: The Endpoint represents the object, or collection of objects, that the request is intended to interact with.  In the above example, the Endpoint in the 'Example API Request' is 'User'.  This will limit what can be done with the API request to Actions that are specifically designed to manipulate 'User' data objects.
  • Action: The Action tells the system what to do with the specified Endpoint. For this Action we are going to Search. Search is used to obtain data from an Endpoint that meets a specific set of parameters. These parameters are called Filters.
  • Filter Array: The Filter Array holds the list of required parameters that must be met before a data object will be returned by the API request.  A Search can have an infinite number of Filters that are formatted as an array. An array is defined as: 'an arrangement of interrelated objects or items for accomplishing a particular task'. For use with the v3 API, an array is structured as follows: [{Key:Value}].
    • Key represents the attribute that is to be searched against an must be enclosed in double quotes (").
    • Value represents the string or number to be matched against the Key.  For example: [ action=search&args=[{"fname":"Bob","lname":"Selfridge"}] ] would only return records where [ "fname" ](Key) is [ "Bob" ] (Value) AND [ "lname" ](Key) is [ "Selfridge" ] (Value).  Any number of Filters can be used as long as they fit the Key:Value structure and are separated by commas. Note: When adding the Filter values to the API search request, remember that strings must be inside quotes and numbers must not.

Note: The Foundation Platform API Endpoint Search Action is limited to simple queries.  Compound Search requests must be against different keys.  For example: [{"A":"Bob"},{"B":"Test"}].  Querying a key twice in the same Search request will result in the response containing all results that match ONLY the second condition.  Complex queries against a single key are possible via the source interface endpoint using js_filter.

API Response Data

Every successful v3 API request will return data in the form of a JSON object.  A JSON object is a standard format for representing structured data which is commonly used for representing and transmitting data on web sites.1  In this article we will focus on a simple API response.

The v3 API Request

First there must be a well-formed API request. The API request that will be used is the 'Example API Request' above.2  A breakdown of the example follows:


  • This request connects to the system at [ https://my.tmmlog.in/ ] and tells the system that this is a v3 API request with [ /api/3 ]
  • Next comes the Endpoint [ /User ]  This is core of the API request and everything that follows will point to it. In this example, access to the User Endpoint is requested.  
  • Before granting access the system must determine if the request comes from an authorized source.  The request provides credentials for the server to authenticate [ ?userkey=45354645654 ]3
    • As this is the first variable in the request URL, it must be prepended with a question mark (?).  
  • After passing authentication, the system moves to the Action.  [ &action=search  ]  This Action configures the system to accept a Filter Array that will determine the search parameters.
    • Note that this configuration variable is separated from the userkey by an ampersand (&), all variables following the first are prepended with an ampersand.
  • At this point, the Filter Array is read. [ &args=[{"fname":"Steve"}] ] The Filter Array instructs the system to search the User data objects and return all that have an attribute of fname that is equal to "Steve"
  • The system returns the JSON object containing all of the results.


The Response Object

The response received from an API request is a JSON object containing all User data objects with attribute "fname" with a value of "Steve".  All Response Objects have the same basic structure and they are returned as a JSON Formatted String.

The JSON Formatted String

{"data":[{"type":"User","id":"999","attributes":{"user_id":"999","user_guid":"558877tu8822","fname":"Steve","mname":"Robert","lname":"Smith","email":"[email protected]","phone":"","user_type_id":"66","cust_id":"1","adobe_key":null,"login":null,"theme":"","last_active":null,"is_active":"1","exceptions":[],"notes":"","two_factor":"0","auth_token":null,"expires":null,"password_history":null,"access_type":"40","notification_preference":"noti","primary_id":"user_id","primary_guid":"user_guid"},"meta":{"valid":true,"getters":{"EXCEPTIONSON":"getExceptionsOn","FULLUSERLIST":"getFullUserList","CUSTOMERUSERLIST":"getCustomerUserList","NOTIFICATIONS":"getNotifications","DBSTATUS":"getDBStatus","DBTABLES":"getDBTables","DBVIEWS":"getDBViews","JOBS":"getJobs","UIREFRESH":"getUIRefresh","USERGUID":"getUserGUID","USERID":"getUserID","NAME":"getName","FULLNAME":"getFullName","FNAME":"getFName","MNAME":"getMName","LNAME":"getLName","EMAIL":"getEmail","PHONE":"getPhone","ADOBEKEY":"getAdobeKey","LOGIN":"getLogin","CUSTID":"getCustId","USERTYPEID":"getUserTypeID","THEME":"getTheme","LASTACTIVE":"getLastActive","ISACTIVE":"getIsActive","EXCEPTIONS":"getExceptions","NOTES":"getNotes","TWOFACTOR":"getTwoFactor","AUTHTOKEN":"getAuthToken","EXPIRES":"getExpires","PASSWORDHISTORY":"getPasswordHistory","CUSTOMERSTATS":"getCustomerStats","RELATIVES":"getRelatives","ACCESSTYPE":"getAccessType","NOTIFICATIONPREFERENCE":"getNotificationPreference","ACTIVEUSERS":"getActiveUsers","CONTYPE":"getConType","ID":"getID","PRIMARYID":"getPrimaryID","GUID":"getGUID","PRIMARYGUID":"getPrimaryGUID","PROPERTIES":"getProperties"},"setters":{"CDBO":"setCDBO","USERGUID":"setUserGUID","FNAME":"setFName","MNAME":"setMName","LNAME":"setLName","EMAIL":"setEmail","PHONE":"setPhone","ADOBEKEY":"setAdobeKey","LOGIN":"setLogin","CUSTID":"setCustID","USERTYPEID":"setUserTypeID","THEME":"setTheme","LASTACTIVE":"setLastActive","ISACTIVE":"setIsActive","PASSWORD":"setPassword","NOTES":"setNotes","TWOFACTOR":"setTwofactor","AUTHTOKEN":"setAuthToken","EXPIRES":"setExpires","PASSWORDHISTORY":"setPasswordHistory","ACCESSTYPE":"setAccessType","NOTIFICATIONPREFERENCE":"setNotificationPreference","ID":"setID","DBO":"setDBO"},"actions":{"load":{"parameters":[{"name":"args"}]},"loadExceptions":{"parameters":[]},"addException":{"parameters":[{"name":"args"}]},"updateException":{"parameters":[{"name":"args"}]},"removeException":{"parameters":[{"name":"args"}]},"clearExceptions":{"parameters":[]},"search":{"parameters":[{"name":"args"}]},"remove":{"parameters":[]},"checkPassword":{"parameters":[{"name":"password"}]},"checkPasswordHistory":{"parameters":[{"name":"password"}]},"runDBSQL":{"parameters":[{"name":"args"}]},"removeUIRefresh":{"parameters":[{"name":"args"}]},"createUIRefresh":{"parameters":[{"name":"args"}]},"systemLog":{"parameters":[{"name":"args"}]},"checkLogIn":{"parameters":[{"name":"args"}]},"logIn":{"parameters":[{"name":"args"}]},"removeUser":{"parameters":[]},"whois":{"parameters":[{"name":"auth_token"}]},"auth":{"parameters":[{"name":"args"}]},"commit":{"parameters":[]},"purge":{"parameters":[{"name":"args"}]},"checkRequirements":{"parameters":[{"name":"password"}]},"checkHistory":{"parameters":[{"name":"password"},{"name":"limt"}]},"grantAccess":{"parameters":[{"name":"args"}]},"removeAccess":{"parameters":[{"name":"args"}]},"notify":{"parameters":[{"name":"args"}]},"sharableList":{"parameters":[]},"slackAccounts":{"parameters":[]},"sendSupportRequest":{"parameters":[{"name":"args"}]},"downloadActiveUsers":{"parameters":[{"name":"args"}]},"message":{"parameters":[]},"beginTransaction":{"parameters":[]},"commitTransaction":{"parameters":[]},"rollbackTransaction":{"parameters":[]},"restrictCustomer":{"parameters":[]},"permissionRequired":{"parameters":[{"name":"args"}]}}}}],"meta":{"data_type":"array"},"self":"https:\/\/my.tmmlog.in\/api\/3\/User?userkey=5555888817ab43&action=search&args=[{%22fname%22:%22Steve%22}]"}

1: Definition of 'JSON object' was based on a definition located on the Mozilla Developer Network web site.
2: The Example API Request contains an invalid userkey for demonstration purposes and will result in an error if used as is. This is for security purposes. A valid userkey was substituted to generate a valid API response.
3: The userkey provided is for demonstration purposes only.  A valid userkey must be provided or the API Request will result in an error.