GetJobList API

Used to query jobs

Endpoint

POST - /Jobs/GetJobList

Overview

The GetJobList API is used to query jobs and return a list of jobs that match the filter that is provided. This is useful for verifying the existence of a job, 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

Input Parameters

excludeClosedJobs

Use this parameter to exclude closed job. This boolean field can be set to True, or False.

field

The job 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
JobNumber No Yes No
PrimaryClient No Yes No PKID of the Primary client
AssignedTo Yes Yes No PKID (integer) of client, or ClientID or Firstname Lastname (string) of a staff member
AssignedToSkillgroup Yes Yes No PKID (integer) of a Skillgroup, or its name (string)
DateLastUpdated No No Yes
DateLogged No No Yes
JobType Yes Yes No PKID (integer), or the Job Type (string)
Priority Yes Yes No PKID (integer), or the Priority (string)
ContactType Yes Yes No PKID (integer), or the Contact Type (string)
JobStatus Yes Yes No PKID (integer), or the Job Status (string)
Issue Yes Yes No PKID (integer), or the Issue (string)
LastActionedBy Yes Yes No PKID (integer) of client, or ClientID or Firstname Lastname (string) of a client
JobTemplatePKID No Yes No PKID of the Job Template that was used to log the job
Data types

Stringvalue: A text string. eg. “On hold”

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”

{
  "excludeClosedJobs": false,
  "filters": [
    {
      "field": "Priority",
      "filterType": "Equals",
      "stringValue": "Critical",
      "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”.

{
  "excludeClosedJobs": false,
  "filters": [
    {
      "field": "Priority",
      "filterType": "Equals",
      "stringValue": null,
      "integerValue": 139,
      "dateValue": null
    }
  ]
}

DateValue

DateValue is a valid JSON date expression.

{
  "excludeClosedJobs": false,
  "filters": [
    {
      "field": "dateLogged",
      "filterType": "GreaterThan",
      "stringValue": null,
      "integerValue": null,
      "dateValue": "2021-06-01T08:00:00"
    }
  ]
}

Combining Filters

Filter can be combined to form a logical “AND” filtering operation. Additional filter blocks are separated with a comma. Add multiple filter blocks to achieve the desired filtering.

The following example combines a “Job type” search with a “Priority” search.

{
  "excludeClosedJobs": false,
  "filters": 
  [
    {
      "field": "JobType",
      "filterType": "Equals",
      "stringValue": "Incident",
      "integerValue": null,
      "dateValue": null
    },
    {
      "field": "Priority",
      "filterType": "Equals",
      "stringValue": "High",
      "integerValue": null,
      "dateValue": null
    }
  ]
}

See also

Jobs Overview