People API

If you are looking for information on how to integrate Active Directory or another LDAP system with ITRP, please refer to the Directory Services page of the Import API.

List people

List all people for an account:

GET /people

Response

Status: 200 OK
[
  {
    "name": "Ashok Kumar",
    "created_at": "2016-03-14T03:09:55-06:00",
    "sourceID": null,
    "updated_at": "2016-03-14T03:10:31-06:00",
    "manager": {
      "name": "Howard Tanner",
      "id": 5
    },
    "id": 30,
    "site": {
      "name": "Widget Data Center",
      "id": 13
    },
    "organization": {
      "name": "Widget Data Center, External IT",
      "id": 30
    },
    "disabled": false
  },
  {
    "name": "Barney Turban",
    "created_at": "2016-03-14T03:09:57-06:00",
    "sourceID": null,
    "updated_at": "2016-03-14T03:10:32-06:00",
    "manager": {
      "name": "Howard Tanner",
      "id": 5
    },
    "id": 58,
    "site": {
      "name": "Widget Data Center",
      "id": 13
    },
    "organization": {
      "name": "Widget Data Center, External IT",
      "id": 30
    },
    "disabled": false
  },
  "..."
]

The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of people.

States

The following states are available:

Collection Fields

By default the following fields will appear in collections of people:

id sourceID name organization site manager created_at updated_at

Obtain a different set of fields using the ?fields= parameter.

Sorting

By default a collection of people is sorted ascending by name.

The following fields are accepted by the ?sort= parameter:

id sourceID name organization site manager created_at updated_at

Get a single person

GET /people/:id

Response

Status: 200 OK
{
  "picture_uri": null,
  "name": "Ashok Kumar",
  "location": "Room 201, Desk 06",
  "created_at": "2016-03-14T03:09:55-06:00",
  "sourceID": null,
  "primary_email": "ashok.kumar@virtualsupport.com",
  "job_title": "Trainee",
  "addresses": [

  ],
  "updated_at": "2016-03-14T03:10:31-06:00",
  "manager": {
    "name": "Howard Tanner",
    "id": 5
  },
  "cost_per_hour": "80.0",
  "information": "Temporarily working at the Widget Data Center to learn about network and system monitoring, before returning to India to provide first line support to Widget's IT users.",
  "id": 30,
  "time_format_24h": false,
  "site": {
    "name": "Widget Data Center",
    "id": 13
  },
  "time_zone": "Central Time (US & Canada)",
  "organization": {
    "name": "Widget Data Center, External IT",
    "id": 30
  },
  "locale": "en-US",
  "disabled": false,
  "vip": false,
  "contacts": [
    {
      "label": "work",
      "id": 327,
      "telephone": "+1 (713) 987 2967"
    },
    {
      "label": "fax",
      "id": 326,
      "telephone": "+1 (713) 987 2911"
    }
  ],
  "source": null,
  "supportID": null,
  "custom_data": null,
  "ui_extension": null
}

The response contains these fields.

Using a phone number to get a person

A person’s telephone number can also be used to retrieve the data of a person record.

GET /sd?telephone=1234567890

The matching of telephone numbers works the same way as for the Computer Telephony Integration (CTI) interface.

The API user needs to have the Service Desk Analyst role of an ITRP account to be able to use a telephone number to look up people records of that account.

When multiple person records contain the same telephone number (regardless of whether the contact.label is work, mobile or home), the data of all these person records will be retrieved, up to a maximum of 10 people.

Create a person

If you are looking for information on how to integrate your Active Directory or LDAP systems with ITRP please see the Import API.

POST /people

When creating a new person these fields are available.

Response

Status: 201 Created
{
  "addresses": "...",
  "...": "..."
}

The response contains all fields of the created person and is similar to the response in Get a single person

Update a person

If you are looking for information on how to integrate your Active Directory or LDAP systems with ITRP please see the Import API.

PATCH /people/:id

When updating a person these fields are available.

Response

Status: 200 OK
{
  "addresses": "...",
  "...": "..."
}

The response contains all fields of the updated person and is similar to the response in Get a single person

Fields

addresses
Readonly aggregated Addresses — The Address fields are used to enter the home and mailing addresses of the person.
contacts
Readonly aggregated Contacts — The Contact fields are used to enter the personal/work email addresses, fax/mobile/etc. of the person.
cost_per_hour
Optional decimal — The Cost per hour field is used to enter the person’s estimated total cost per work hour for the service provider organization. The value in this field should include the costs of the person’s salary (or rate in case of a long-term contractor), office space, service subscriptions, training, etc.
created_at
Readonly datetime — The date and time at which the person was created.
custom_data
Optional hash — Custom data provided in JSON format by the UI Extension that is linked to the person.
disabled
Optional boolean, default: false — The Disabled box is checked when the person may no longer be related to other records.
id
Readonly integer — The unique ID of the person.
information
Optional text (max 64KB) — The Information field is used to add any additional information about the person that might prove useful.
job_title
Optional string (max 80) — The Job title field is used to enter the person’s job title.
locale
Optional string (max 5) — The locale field has the label “Language” in the user interface. It is used to select the language preference of the person.
location
Optional string (max 80) — The Location field is used to enter the name or number of the room, cubicle or area where the person has his/her primary work space.
manager
Optional reference to Person — The Manager field is used to select the manager or supervisor to whom the person reports.
name
Required string (max 128) — The Name field is used to enter the person’s name.
organization
Optional reference to Organization — The Organization field is used to select the Organization for which the person works as an employee or long-term contractor.
picture_uri
Readonly TODO — The hyperlink to the image file that was uploaded for the person.
primary_email
Required string (max 128) — The Primary email field is used to enter the email address to which email notifications are to be sent. This email address acts as the unique identifier for the person within the ITRP account. This primary email address also acts as the person’s login name if he/she is a user of the ITRP service.
site
Optional reference to Site — The Site field is used to select the Site where the person is stationed.
source
Optional string (max 30) - See source
sourceID
Optional string (max 128) - See source
supportID
Optional string (max 50) - The Support ID field is used to enter a number or code that a service desk analyst can ask the person for when the person contacts the service desk for support.
time_format_24h
Optional boolean - The Time format field is used to indicate whether the person prefers to see times displayed within the ITRP service in the 24-hour format or not (in which case the 12-hour format is applied).
time_zone
Optional string (max 50) — The Time zone field is used to select the time zone in which the person normally resides.
ui_extension
Readonly reference to UI Extension — The UI extension field indicates the UI extension that is applied to the person.
updated_at
Readonly datetime — The date and time of the last update of the person. If the person has no updates it contains the created_at value.
vip
Optional boolean, default: false — The VIP box is checked to indicate that the person is a very important person.