Data Types

All data is sent and received as JSON.

Output

null
native: all blank fields are included as null instead of being omitted

"solved_at": null

string, text
native

"name": "Windows for Sales Tracking Production"

boolean
native

"known_error": true

integer
native

"nr_of_cores": 3

decimal, float
native

"rate": 3.2313

enum
string: one of the options defined for the enumeration

"status": "registered"

reference
hash: composed of multiple values, or null if the reference is not filled out

"team": {"id": 12, "name": "Service Desk"} "team": null

timestamp
string: yyyy-mm-ddThh:mm:ssZ

"completed_at": "2010-01-05T23:00:00Z"

ISO 8601 format, with a seconds resolution, with timezone.

datetime
string: yyyy-mm-ddThh:mm

"start_at": "2010-12-30T23:00"

ISO 8601 format, with a minutes resolution, without timezone.

date
string: yyyy-mm-dd

"start_date": "2011-06-24"

time of day
string: hh:mm

"time_from": "08:30"

In military format. 00:00 = midnight at the start of the day, 12:00 = noon, 24:00 = midnight at the end of the day

duration
integer: with resolution in minutes

"response_target": 240

Input

null
all blank fields should be omitted from the input
string, text
any value

?name=Windows%20for%20Sales%20Tracking%20Production

boolean
truthy values are true, t, TRUE, T, 1, falsy values are anything else, like: false, f, FALSE, F, 0

?known_error=true

integer
any integer (0, 1, 2, …)

?nr_of_cores=3

decimal, float
any number with decimals, separated by a dot (.)

?rate=3.2313

enum
one of the options defined for the enumeration

?status=registered

reference
the id of the referenced resource, always append _id to the field name

?team_id=12

timestamp
yyyy-mm-ddThh:mm:ssZ

?completed_at=2010-01-05T23:00:00Z

ISO 8601 format (with a seconds resolution, with timezone)

datetime
yyyy-mm-ddThh:mm

?start_at=2010-12-30T23:00

ISO 8601 format (with a minutes resolution, without timezone)

date
yyyy-mm-dd

?start_date=2011-06-24

time of day
hh:mm

?time_from=08:30

In military format. 00:00 = midnight at the start of the day, 12:00 = noon, 24:00 = midnight at the end of the day

duration
integer: with resolution in minutes

?response_target=150

Alternatively it accepts a string in the format hhh:mm, for example:

?response_target=2:30

References

A reference to another resource is composed of one or more of the following fields.

Note: In the input, use only the id of the referenced resource and append _id to the field name, e.g. ?team_id=12.

ID

All references contain an id property with which the details of the resource can be retrieved using a separate API call.

Note that when a record is opened in the ITRP user interface, the id can be found in the Address bar of the browser. It is the unique identifier at the end of the URL. The id of an account can be found in the user interface by going to the Account Overview section of the Settings console.

For aggregated references (arrays of ~) an id is not returned. Instead, all available fields are contained in aggregated references so that an id is not needed.

Display Properties

The reference will always contain the properties necessary to display the (list of) reference(s) to the end-user. In most cases this will expose the name and/or subject properties, but there are some exceptions like label for Configuration Item references.

Account

When the account of the referenced resource is different from the account of the authenticated user, the account reference will be provided. The account field is itself a reference and will always only show name and id. The name is intended as a display property for the end-user. The id can be used to switch to that account if appropriate, see Multiple Accounts.

If a resource or reference to a resource does not expose an account field, the account of the resource is equal to the account of the authenticated user.

The following example shows a request that is completed by a member of the Service Desk team from a different account (Virtual Support).

 $ curl -u "API-TOKEN:x" https://api.itrp.com/v1/requests/70384
Status: 200 OK
{
  "id": 70384,
  "status": "completed",
  "service_instance": {
    "name": "Time Off Request Production",
    "id": 97
  },
  "team": {
    "name": "Service Desk",
    "account": {
      "name": "VirtualSupport",
      "id": "virtualsupport"
    },
    "id": 2
  },
  "member": {
    "name": "Krish Hanuang",
    "account": {
      "name": "VirtualSupport",
      "id": "virtualsupport"
    },
    "id": 16
  }
}

Not all request fields are shown above to keep the example simple.

Source ID

When references to resources with a Source ID are retrieved from the API, the sourceID field will always be provided.

 $ curl -u "API-TOKEN:x" https://api.itrp.com/v1/requests?per_page=1
Status: 200 OK
[
  {
    "subject": "NewRequest",
    "category": "compliment",
    "status": "assigned",
    "sourceID": "N1C3AP1"
  }
]

Not all request fields are shown above to keep the example simple.

See source for more information on the usage of the sourceID field.

Disabled

In case a referenced resource is disabled, the disabled: true property will be provided. When a referenced resource is enabled, the disabled property is omitted.

 $ curl -u "API-TOKEN:x" https://api.itrp.com/v1/services/23
Status: 200 OK
{
  "id": 23,
  "name": "Short Term Production Planner",
  "created_at": "2016-03-10T02:05:27-06:00",
  "updated_at": "2016-03-10T02:10:51-06:00",
  "sourceID": null,
  "support_team": {
    "name": "Application Development",
    "id": 7
  },
  "provider": {
    "name": "Widget Data Center, External IT",
    "id": 30,
    "disabled": true
  }
}