REST API for users (people application)

The base URL for all REST calls for people is /intranet/rest/people/v1/

This page describes Version 1 of this API - Find out more about API versions here.

Get a list of users

GET /intranet/rest/people/users/

This request has optional CGI-style parameters for pagination, filtering, sorting and which user properties to return.

When successful, returns JSON-formatted array as shown below. Otherwise a suitable HTTP error code is returned.

{
    "data": [
        {
            "id": 1,
            "firstname": "Claromentis",
            "surname": "Administrator"
        },
        {
            "id": 2,
            "firstname": "Joe",
            "surname": "Bloggs"
        }
    ],
    "paging": {
        "offset": 0,
        "limit": 2,
        "total": 61,
        "prev": "",
        "next": "http://host.name/intranet/rest/people/users/?limit=2&offset=2"
    }
}

entry	type	description
data	array	Contains the user data
id	number	The unique user id
firstname	string	First name of the user
surname	string	Surname of the user
-	-	-
paging	array	Contains information used for pagination
offset	number	Of the total set of results, where this set of results starts begins
limit	number	The maxium number of results being returned
total	number	The total number of results found, of which this is a subset
prev	string	REST request URI to return the previous subset of results (empty if this is the first set)
next	string	REST request URI to return the next subset of results (empty if this is the last set)

Pagination

As mentioned above, an offset and number of records to be returned can be specified using query string parameters limit and offset. By default 50 records are returned. To prevent adversely effecting the speed of the server, the max number of results that can be returned at a time is 500.

Example: /people/users/?limit=30&offset=60

Filtering

It's possible to filter the users list by one or more parameters. If more than one filter criteria are specified, only users matching all of them will be returned.

Filtering by name

To filter by name the query string parameter is name_filter.

The value of this parameter is a string to be matched against first name and surname. The search string can contain an asterisk at the beginning and/or end of string to indicate a wildcard where more characters can be present. Without asterisks, the search is performed as case-insensitive exact word match against first name and/or surname.

Example 1: /people/users/?name_filter=alex

This query returns users whose name or surname is exactly "Alex" (case-insensitive). Will match "Alex Smith" and "John Alex", but won't match "Alexander Brown".

Example 2: /people/users/?name_filter=ale*

This query will match "Alex Smith" and "Alexander Brown" but won't match "John Mickale"

Example 3: /people/users/?name_filter=*son

This query will match "Boris Johnson" but won't match "John Suttersond"

Example 4: /people/users/?name_filter=*son*

Performs simple substring search within name and surname. Will match "Boris Johnson" and "John Suttersond".

Filtering by groups, roles, extranets

Query string parameters are:

/people/users/?groups=NN[,NN[,..]]
/people/users/?roles=NN[,NN[,..]]
/people/users/?extranets=NN[,NN[,..]]

Where NN is a numeric id for the group, role or extranet. You can supply multiple ids and the request will return users who match all the given ids. For example: if a user is in groups 1 and 5 and you filter for groups 1, 5 and 7 that user will not be returned.

Filtering by keywords

Query string parameters are:

query - The keywords to search. This can contain multiple keywords separated by spaces
query_area - A comma-separated list of User fields to search for keywords. If not given, the search is performed on: firstname, surname, company, job_title and email
query_type - (optional) The word AND or OR (in capitals) to indicate if the search should match for all or any of the given keywords. the default for this parameter is "AND".

Sorting

To sort the users list, specify a sort parameter in the query string with the value of column name by which to sort in ascending order. To sort in descending order put a minus sign in front of it.

Example 1: /people/users/?sort=firstname

Example 2: /people/users/?sort=-company

Properties to return

With the fields parameter you can specify what user properties you would like to have returned in the search results. To specify fields you simple include a comma-separated list of them.

Example usage: /people/users/?fields=id,firstname,surname,email

Available properties:

id
firstname
surname
email (alias - emailad)
job_title - or "job title", with space
company
intranetuser (alias - "account state")
ex_area_id (alias - "extranet area")
photo - returns URL to the photo, which may or may not include the host name
Any metadata field starting from prefix meta_, such as meta_usr_phone

Any Properties with a space should be encoded using the standard URL encoding schema (for example, ?field=id,firstname,account**%20**state,email)

Predefined property sets to return

Example: /people/users/?fieldset=profile

In addition to specifying properties individually it is possible to ask for a named set of properties to be returned. See #get_list_of_field_sets for information on the fieldsets.

Get user info for a single user

Returns user info for user with the unique id :user_id

GET /intranet/rest/people/users/:user_id

Has optional CGI-style parameter list:

Users properties to return: ...?fields=id,firstname,surname,email
Named property sets to return: ...?fieldset=profile

Returns JSON-formatted array in the following format:

{
    "id": 1,
    "firstname": "Claromentis",
    "surname": "Administrator",
    "email": "admin@claromentis.com"
}

Get groups/roles/extranets list

Three very similar functions return lists of groups, roles, or extranet areas:

GET /intranet/rest/people/groups/

GET /intranet/rest/people/roles/

GET /intranet/rest/people/extranets/

The three requests all have optional CGI-style parameters to filter the list by keywords - ...?query=managers

Returns JSON array in the following format:

{
    "data": [
        {
            "id": 1,
            "name": "All staff",
        },
        {
            "id": 2,
            "name": "Managers",
        },
        {
            "id": 3,
            "name": "Designers",
        }
    ],
    "paging": {
        "offset": 0,
        "limit": 3,
        "total": 12,
        "prev": "",
        "next": "http://host.name/intranet/rest/groups/?limit=3&offset=3"
    }
}

Get a list of fieldsets

Returns list of field set names matching the system-defined user lists on the sidebar at /intranet/panels/peopleadmin_fields.php

These sets match common Claromentis user displays such as the user profile and People list, with visible columns and permissions configured by the system administrator.

Returns JSON-formatted array of strings mathing the names of fieldsets like this:

[
    "userslist",
    "profile"
]

Get field set info

GET /intranet/rest/people/fieldsets/:name

Returns list of user attribute fields defined by the named system-defined list

Returns JSON-formatted array like this:

[
    {
        "name": "fullname",
        "type": "text",
        "repeatable": "false"
    },
    {
        "name": "emailad",
        "type": "text",
        "repeatable": "false"
    },
    {
        "name": "meta_file",
        "type": "file",
        "repeatable": "true"
    },
],