Search Scope Documentation

Search criteria are specified as a json object.

Valid parameters for the search field(s): field, fields.

Valid parameters for the search value(s): value, values.

Possible combinations of search criteria: OR-Search, AND-Search and combination of both.

To combine the search fields and/or the search values via the OR operator, they must be provided as a comma separated list:

The AND combination would be:

Example: Find all people who live in the area with postal code starting with 530 or 531.

And here is the whole request:

curl -X POST "https://appload.scopevisio.com/rest/contacts" -H "accept: application/json" -H "Authorization: Bearer [TOKEN]" -H "content-type: application/json" -d "search : [{\"fields\" : \"isAccount\",\"values\" : \"true\",\"operator\": \"equals\" }, {\"fields\" : \"postcode1,\"values\" : \"530, 531\",\"operator\": \"startswith\"}]"

Search Operators

Available operators for string values:
startswith – if the string starts with your value, it will match
endswith – if the string ends with your value, it will match
contains – if your value is somewhere in the string, it will match
icontains – if your value is somewhere in the string, it will match in case-insensitive manner
notequal – if your value does not equal, it will match
equal – if your value equals, it will match
is null – if the field is null, it will match
is not null – if the field is not null, it will match

Available operators for numbers:
equal – if your value equals, it will match
notequal – if your value does not equal, it will match
less – if your value is less than, itll match
greater – if your value is greater than, it will match
lessorequal - if your value is less than or equals, it will match
greaterorequal - if your value is grater than or equals, it will match
is null – if the field is null, it will match
is not null – if the field is not null, it will match

Available operators for boolean values:
equal – if your value equals, it will match
notequal – if your value does not equal, it will match
is null – if the field is null, it will match
is not null – if the field is not null, it will match

"is null" search

It is also possible to use the is null operator in combination with all other operators. The result is an OR-search combination. When the is null is used alone, without combining with another operator, the values parameter can be skipped.

In this example the contacts having no postal code at all are returned:

In this example the contacts having postal code starting with "53" or having no postal code at all are returned:

"is not null" search

It is also possible to use the is not null. This operator however cannot be combined with other operators. When the is not null operator is used the values parameter can be skipped.

In this example only the contacts with a non-null postal code are returned:

Paging, fields, ordering and formatting

Retrieving data may result in a high number of items. Therefore, results may be returned over a number of pages.

The number of the first page is 0 which is also the page default. A value smaller than 0 will be replaced with 0.

The pageSize default is 100. It can be set to a maximum value of 1000. A value greater than 1000 will be replaced with 1000.

Which fields should the result contain can be specified by the fields element.

Certain value types are by default formatted in a specific manner. All value formatting can be disabled by setting the "formatValues" attribute to false. This attribute affects the output only when at least one field is specified.

Here is an example:

curl -s -d '{ "page": 2, "pageSize": 250, "fields": ["id", "firstname", "lastname", "postcode1" ]}' -H "Content-Type: application/json" -H "Authorization: Bearer [TOKEN]" https://appload.scopevisio.com/rest/contacts

A combination of search criteria and paging or formatting is also possible:

To order the returned records the array element order is used. This list contains elements using the format "<db-field>=<sortOrder>" with possble values asc and desc for sortOrder.

For example the ordering of the contacts from the previous example by name descending and then by firstname ascending would look like:

Count

It is also possible to retrieve only the record count of the result by using the count element. Count retrieves the number of objects depending on the search. If search is given the count of elements fulfilling the search criteria is returned, if not - the total count elements is retrieved.

Example: A total of 20 contacts exist in a Scopevisio Organisation. Eight of the contacts are personal, the others are company contacts. The following count combined with search criteria should return eight - the number of personal contacts.

The following example should return the total count of contacts in the organisation which is 20.

All other search criteria, page, pageSize, fields, order are ignored when using the count element.

Special searches

Some webservices allow also some special search or filter criteria, depending on the context.

Journal, personal journal and statistics journal

For /journal, /personaljournal and /statisticspostings the following filter criteria are available:

createdSince - postings created (Erstellungsdatum) since the given date
createdBefore postings created (Erstellungsdatum) before the given date
postingDateSince - postings with posting date (Buchungsdatum) since the given date
postingDateBefore - postings with posting date (Buchungsdatum) before the given date
externalDocumentDateSince - postings with externalDocumentDate (Externes Belegdatum) since the given date

The date must be provided as milliseconds since the UNIX epoch (1970-01-01T00:00:00.000Z).

The following example returns all postings with creation date from 01.01.2018 to 31.12.2018 containing the word "Rabatt".

Statisticspostings

For /statisticspostings the following filter criteria are available:

createdSince - postings created (Erstellungsdatum) since the given date
createdBefore postings created (Erstellungsdatum) before the given date
postingDateSince - postings with posting date (Buchungsdatum) since the given date
postingDateBefore - postings with posting date (Buchungsdatum) before the given date
accountNumber - filter on the statistics accountnumber

Availability of human resources

For /humanresourcesAvailability the following filter criteria are available:

validFrom - human resources available since this point in time
validTill - human resources available until this point in time

For /humanresourcesavailability/v2 the following filter criteria are available:
Note, that the values must be formatted as yyyy-MM

validFrom - human resources available since this month
validTill - human resources available until this month