People API
Tip: If you are looking for information on how to integrate Active Directory or another LDAP system with R-Service, please refer to the Directory Services page of the Import API.
- List people
- Get a single person
- Create a person
- Update a person
- Archive a person
- Trash a person
- Restore a person
- Fields
List people
List all people for an account and the related directory 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.
Predefined Filters
The following predefined filters are available:
/people/disabled
: List all disabled people/people/enabled
: List all enabled people/people/internal
: List all internal people/people/directory
: List all people registered in the directory account of the support domain account from which the data is requested/people/support_domain
: List all people registered in the account from which the data is requested (and not the related directory account)
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.
Filtering
Filtering is available for the following fields:
id
source
sourceID
name
disabled
organization
site
manager
created_at
updated_at
employeeID
primary_email
supportID
roles
The filters on primary_email
and supportID
are not case sensitive.
The other string and text filters are case sensitive, unless they are used in combination with the roles
filter.
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,
"work_hours": {
"name": "Monday through Friday, 9:00am until 5:00pm"
},
"contacts": [
{
"label": "work",
"id": 327,
"telephone": "+1 (713) 987 2967"
},
{
"label": "fax",
"id": 326,
"telephone": "+1 (713) 987 2911"
}
],
"source": null,
"supportID": null,
"custom_fields": 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 a R-Service 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 R-Service 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 R-Service 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
Archive a person
POST /people/:id/archive
Moves a given person to the Archive. This action requires the Account Administrator or Directory Administrator role in the account of the person.
Response
Status: 200 OK
{
"archived": "true",
"addresses": "...",
"...": "..."
}
The response contains all fields of the archived person and is similar to the response in Get a single person
Trash a person
POST /people/:id/trash
Moves a given person to the Trash. This action requires the Account Administrator or Directory Administrator role in the account of the person.
Response
Status: 200 OK
{
"trashed": "true",
"addresses": "...",
"...": "..."
}
The response contains all fields of the trashed person and is similar to the response in Get a single person
Restore a person
POST /people/:id/restore
Moves a given person from the Archive or the Trash back into the active state. This action requires the Account Administrator or Directory Administrator role in the account of the person.
Response
Status: 200 OK
{
"addresses": "...",
"...": "..."
}
The response contains all fields of the restored 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.
- attachments
- Readonly aggregated Attachments
- authenticationID
- Optional string (max 128) - The Authentication ID field may be used by the Single Sign-On feature to uniquely identify a user.
- auto_translation
- Optional boolean, default:
false
— The Auto translation box is checked when the person should be offered translations for texts that are written in languages other than the ones selected in the Language (locale) and the Do not translate (do_not_translate_languages) fields. Such texts are translated automatically into the language selected in the Language (locale) field. - 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.
- cost_per_hour_currency
- Optional enum — The currency of the Cost per hour field value of the person. For valid values, see the list of currencies in the Currency field of the Account API.
- created_at
- Readonly datetime — The date and time at which the person was created.
- custom_fields
- Optional custom fields — Custom fields provided in JSON format by the UI Extension that is linked to the person.
- custom_fields_attachments
- Writeonly attachments The attachments used in Custom fields.
- disabled
- Optional boolean, default:
false
— The Disabled box is checked when the person may no longer be related to other records. - do_not_translate_languages
- Optional string — The Do not translate field is used to select the languages that should not be translated automatically for the person. Translations will not be offered to the person for texts in any of these languages. This field can contain a comma-separated list of language codes. Supported language codes are: en, nl, de, fr, es, pt, it, da, fi, sv, pl, cs, tr, ru, ar, id, fa, no, zh, ja, ko, he, hi, ms.
- employeeID
- Optional string (max 128) - The Employee ID field is the unique identifier for a person typically based on order of hire or association with an organization.
- exclude_team_notifications
- Optional boolean, default:
false
— Indicates whether the person wants to receive team notifications. - guest
- Optional boolean, default:
false
— Indicates whether the person was registered as a guest in Self Service. - 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.
- information_attachments
- Writeonly attachments The attachments used in the Information field.
- 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.
- oauth_person_enablement
- Optional boolean, default:
false
— An enabled OAuth person is mentionable and visible in suggest fields, just like a real person. - 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
- Optional string — The hyperlink to the image file 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 R-Service account. This primary email address also acts as the person’s login name if he/she is a user of the R-Service service.
- send_email_notifications
- Optional enum — Indicates when to send email notifications to the person. Valid values are:
-
always
: Alwayswhen_offline
: Only when the person is offlinenever
: Never
- show_notification_popup
- Optional enum — Indicates when to show a notification popup to the person. Valid values are:
-
always
: Always, for all notificationsimportant_only
: Only for important notificationsnever
: Never
- 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 R-Service service in the 24-hour format or not (in which case the 12-hour format is applied).
- time_zone
- Optional time_zone — 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. - work_hours
- Optional reference to Calendar — The Work hours field is used to select a Calendar that represents the work hours of the person.