Get client list

Used to return a list of clients matching a search criteria

Endpoint

POST - /Clients/GetClientList

Overview

The GetClientList API is used to query clients and return a list of clients that match the filter that is provided. This is useful for verifying the existence of a client, or simply returning data to be used for another purpose.

Filtering is based around building up a collection of filters that combine to form a logical “AND” expression. “OR” expressions are currently not supported.

Each filter set is made from the following parameters which are used to specify the search/filter criteria.

field
filterType
stringValue
integerValue
dateValue

Parameters

field

The field parameter is the field that is being filtered on. The following table displays the fields that are available for filtering, and the data type that they support.

Field StringValue IntegerValue DateValue Notes
PKID No Yes No PKID (integer) of client
ClientID Yes No No The ClientID of a client
FirstName Yes No No The first name of a client
LastName Yes No No The last name of a client
Email Yes No No The email of a client
Phone Yes No No The phone number of a client
Type Yes Yes No 0 = Client, 1 = Staff (Integer), or ‘Client’ or ‘Staff’ (string)
Site Yes Yes No The Primary site of the client. PKID (integer), or the Site (string)
Gender Yes Yes No PKID (integer), or the gender (string)
DateOfBirth No No Yes The date of birth of a client
Data types

Stringvalue: A text string. eg. “Matthew”

IntegerValue: A number. eg. 58

DateValue: A date string in ISO8601 format. eg. “2020-08-27T04:47:15.352Z”.

Note that the “T” appears literally in the string, to indicate the beginning of the time element, as specified in ISO 8601.

Year: YYYY (eg 1997)
Year and month: YYYY-MM (eg 1997-07)
Complete date: YYYY-MM-DD (eg 1997-07-16)
Complete date plus hours and minutes: YYYY-MM-DDThh:mmTZD (eg 1997-07-16T19:20+01:00)
Complete date plus hours, minutes and seconds: YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00)
Complete date plus hours, minutes, seconds and a decimal fraction of a second YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.45+01:00)

where:

 YYYY = four-digit year
 MM   = two-digit month (01=January, etc.)
 DD   = two-digit day of month (01 through 31)
 hh   = two digits of hour (00 through 23) (am/pm NOT allowed)
 mm   = two digits of minute (00 through 59)
 ss   = two digits of second (00 through 59)
 s    = one or more digits representing a decimal fraction of a second
 TZD  = time zone designator (Z or +hh:mm or -hh:mm)
  • Hour is 24 hour format
  • Z at end means date is in UTC. (No Z means local time)

filterType

FilterType is the type of filter used against the field. Options include:

  • Contains
  • StartsWith
  • Equals
  • NotEqualTo
  • GreaterThan
  • LessThan

StringValue

The StringValue is the text value used to filter a field. This value is case insensitive. For some fields, you can use the “IntegerValue” instead of the actual string value - see below.

Example of a single expression that filters on Priority and uses a text value of “Critical”

[
  {
    "field": "ClientID",
    "filterType": "StartsWith",
    "stringValue": "M",
    "integerValue": null,
    "dateValue": null
  }
]

IntegerValue

The IntegerValue is the internal/PKID/“under the hood” value of a field, that can be used instead of the actual text value. This is useful when you wish to filter by the internal number rather than the text-value of a field. The text value of a system code may change over time, however its internal number will always remain the same. See System Codes PKID for more information.

eg. The Priority code “Critical” has an internal “PKID” of 139.

Instead of using the “stringValue” parameter and using “Critical” as the value, the same list of jobs can be found by using the “IntegerValue”, and using the PKID value that corresponds to the text value of “Critical”.

[
  {
    "field": "PKID",
    "filterType": "Equals",
    "stringValue": null,
    "integerValue": 88,
    "dateValue": null
  }
]

DateValue

DateValue is a valid JSON date expression.

[
  {
    "field": "DateOfBirth",
    "filterType": "GreaterThan",
    "stringValue": null,
    "integerValue": null,
    "dateValue": "1995-03-15"
  }
]

See also

Clients