Getting Started With the API

Retrieve Access Token Endpoint

• URL
  • /api/v1/oauth/token
• Type
  • POST
• Content-Type
  • application/x-www-form-urlencoded
• POST params
  • grant_type
    • client_credentials
  • client_id
    • [client_id]
  • client_secret
    • [client_secret]
  • scope
    • public_api

Access Token Responses

On Success return bearer token (life time 4 hours):

{
    "access_token": "tokenStringHere",
    "expires_in": 14400, 
    "scope": "public_api", 
    "token_type": "Bearer" 
}

If an app is disabled, show error:

{
    "ErrorCode" : 401001,
    "Message"   : "The application is disabled"
}

If clientId/clientSecret pair wasn't found, show error:

{
    "ErrorCode" : 401002,
    "Message"   : "Invalid client_id and/or client_secret"
}

If site plan is less than Pro, show error:

{
    "ErrorCode" : 401003,
    "Message"   : "Public API is restricted for your site plan"
}

If scope is invalid, show error:

{
    "ErrorCode" : 401006,
    "Message"   : "Invalid Scope"
}

If grand_type is invalid, show error:

{
    "ErrorCode" : 401007,
    "Message"   : "Invalid Grant Type"
}

API Endpoint Token Errors

If any request doesn't contain access token or token can't be found in DB, show error:

{
    "ErrorCode" : 401000,
    "Message"   : "Invalid Access Token"
}

ElseIf any request contains access token but it has been expired, show error:

{
    "ErrorCode" : 401004,
    "Message"   : "Access Token expired"
}

ElseIf an app asociated with the access token is disabled, show error:

{
    "ErrorCode" : 401001,
    "Message"   : "The application is disabled"
}

ElseIf access token is revoked, show error:

{
    "ErrorCode" : 401005,
    "Message"   : "The Access Token has been revoked"
}

Supported Condition Operators by Type

Certain data types (Boolean, String, Numeric, DateTime, Array) are more suited to, or only work with, certain condition operators. For example, a Boolean (true or false), is only ever equal, or not equal, to true or false. So operators such as greater ($gt) or less than ($lt) can not be applied.

The table below indicates which operators work with those data types.

null: Data type has null value support so you can use null in your filter values. For example:

{ "$not_eq": {"Name":null} }
{ "$in": {"Array":null} }
{ "$in": {"Array":[null]} }

*: For system properties, there is no implemented support for a null value since null values are not possible in system properties. However, there is null support for custom properties since they can contain null values (ie: if a new property is added to a module with already existing items, those item's property values will be null unless resaved).

Examples of 'Where' Filter Syntax

In this example we want to retrieve Event items that match all of the following conditions:

• Is enabled (the API will also return disabled items).
• Has a start and end date of 5th Apr 2024.

We need all of these conditions to be true, so we set our condition operators within an AND ($and) conjuncture so they are all matched at the same level, which will look like this:

{
    "$and": [
    	{"$eq":{"Enabled":true}},
	    {"$gte":{"EventDateStart":"2024-04-05"}},
	    {"$lte":{"EventDateEnd":"2024-04-05"}}
    ]
}

In this next example we have a more complex search criteria. We want to retrieve Module items that match ALL of some conditions but only when matched for SOME of other conditions:

• Is enabled (the API will also return disabled items).
• Has a release date on or after 5th Apr 2024 AND before 27th Apr 2024.
  If both the above are matched:
  • Has a Name starting with "Publish" OR ending with "FINAL".
    If either the above are matched:
    • Has a Weighting between 12 AND 23 OR between 25 AND 123.

We need some of these conditions to be true while others can be either-or and at different levels, so we nest our condition operators within various conjunctures, which will look like this:

{
    "$and": [
        {"$eq":{"Enabled":true}},
    	{"$gte":{"ReleaseDate":"2024-04-05"}},
	    {"$lt":{"ReleaseDate":"2024-04-27"}},
    	{
    	    "$or": [
                {"$starts":{"Name":"Publish"}},
	            {"$ends":{"Name":"FINAL"}},
    			{
                    "$or": [
                        {
    						"$and": [
    							{"$gt": {"Weighting": 12}}, 
    							{"$lt": {"Weighting": 23}}
    						]
    					},             
    					{
    						"$and": [
    							{"$gt": {"Weighting": 25}}, 
    							{"$lt": {"Weighting": 123}}
    						]
    					}
    				]
    			}
        	]
    	}
    ]
}

Examples of Valid Value by Type

Boolean

The true or false values can be expressed as a keyword or a string (in quotation marks).

{ "$and": [ {"$eq":{"Enabled":true}}, ] }
{ "$and": [ {"$eq":{"Enabled":"true"}}, ] }

String

String values are to be expresses in quotaion marks and can be included in comma separated arrays (denoted by square brackets), or arrays using the unique system delimiter |||;/;|||.

{ "$and": [ {"$eq":{"Name":"test1"}}, ] }
{ "$and": [ {"$in":{"Name":["test1","test2"]}}, ] }
{ "$and": [ {"$in":{"Name":"test1|||;/;|||test2"}}, ] }

Numeric

Numbers/Integer values can to be expresses with or without quotaion marks and can be included in comma separated arrays (denoted by square brackets), or arrays using the unique system delimiter |||;/;|||.

{ "$and": [ {"$eq":{"Weighting":0}}, ] }
{ "$and": [ {"$eq":{"Weighting":"0"}}, ] }
{ "$and": [ {"$in":{"Weighting":[0,1]}}, ] }
{ "$and": [ {"$in":{"Weighting":["0","1"]}}, ] }
{ "$and": [ {"$in":{"Weighting":""0"|||;/;|||"1""}}, ] }

DateTime

The time component of a dateTime strings can be omitted if only the date is needed.

{ "$and": [ {"$eq":{"ReleaseDate":"2024-12-31T14:42:00"}}, ] }
{ "$and": [ {"$eq":{"ReleaseDate":"2024-12-31"}}, ] }

Array

Arrays can to be expresses in comma separated format (denoted by square brackets), or using the unique system delimiter |||;/;|||.

{ "$and": [ {"$in":{"SiteSearchKeywords":["test1","test2"]}}, ] }
{ "$and": [ {"$in":{"SiteSearchKeywords":"test1|||;/;|||test2"}}, ] }

Examples of Conditional Logic

Let's assume we have 3 items in our data collection that each have an ID, Name and some keywords assigned.

These items are represented by the JSON object below:

[
    {
        "Id": 1,
        "Name": "Cat"
        "SiteSearchKeywords": ["pet", "tail", "best"]
    },
    {
        "Id": 2,
        "Name": "Dog"
        "SiteSearchKeywords": ["pet", "tail"]
    },
    {
        "Id": 3,
        "Name": "Ape"
        "SiteSearchKeywords": ["pet"]
    }
]

Using $eq for exact match

The below syntax is searching for items that exactly equal only the Site Search Keywords of "pet" and "tail".

{ "$eq": {"SiteSearchKeywords": ["pet", "tail"]} }

The resulting item returned would be 'Dog'.

Using $contains for search by array occurrence

The below syntax is searching for items that contain both the Site Search Keywords of "pet" and "tail".

{ "$contains": {"SiteSearchKeywords": ["pet", "tail"]} }

The resulting items returned would be 'Cat' and 'Dog'.

Using $in for search by occurrence of one of the array elements

The below syntax is searching for items that include any one, or more, of the Site Search Keywords of "pet", "tail" and "farmyard".

{ "$in": {"SiteSearchKeywords": ["pet", "tail", "farmyard"]} }

The resulting items returned would be 'Cat', 'Dog' and 'Ape'.