Claromentis API Docs logoClaromentis API Docs

People API v2

The base URL path for all REST requests for People API v2 is /api/people/v2/.

This documentation describes Version 2 of the People API, which is available from Claromentis v8.9.0 and above.

If you're looking for Version 1 of the People API, check out our People API v1 documentation.

Find out more about API versioning by reading our API versions documentation.

Overview

Method Path Summary
GET /user Get the currently authenticated user
GET /users Get a list of users
POST /users Create a new user
GET /users/{id} Get a user
PUT /users/{id} Update a user
POST /users/{id}/photo Upload a new photo for a user
PUT /users/{id}/manager Set a user's manager
GET /users/{id}/groups Get a user's roles
GET /users/{id}/roles Get a user's roles
GET /users/{id}/subordinates Get a user's subordinates
PUT /users/{id}/subordinates Set a user's subordinates
PUT /users/{id}/password Set a user's password
DELETE /users/{id} Delete a user
GET /groups Get a list of groups
POST /groups Create a group
GET /groups/{id} Get a group
PUT /groups/{id} Update a group
DELETE /groups/{id} Delete a group
GET /groups/{id}/users Get the users that belong to a group
PUT /groups/{id}/users Set the users that belong to a group
GET /roles Get a list of roles
POST /roles Create a new role
GET /roles/{id} Get a role
PUT /roles/{id} Update a role
DELETE /roles/{id} Delete a role
GET /roles/{id}/users Get the users that belong to a role
PUT /roles/{id}/users Set the users that belong to a role
GET /extranets Get a collection of extranets
POST /extranets Create a new extranet
GET /extranets/{id} Get an extranet
PUT /extranets/{id} Update an extranet
DELETE /extranets/{id} Delete an extranet
GET /extranets/{id}/users Get the users that belong to an extranet
PUT /extranets/{id}/users Set the users that belong to an extranet

Note:

https://yourintranet.com is used as an example hostname for this documentation.

Where you see a URL in these docs, such as "manager_url": "https://yourintranet.com/api/people/v2/users/{manager_id}", this is the URL to a resource on your own intranet site.

In the example above, it represents the endpoint to use to retrieve the User object of a User's manager.

Errors

Errors that occur when handling requests to any of these API endpoints will result in an appropriate HTTP error code, along with a JSON response containing the same error code and an error message:

{
    "code": 401,
    "error": "You are not authorized to carry out that request"
}

Pagination

Resource collection endpoints are paginated to 20 items by default.

Responses

Pagination data and URLs are included in the responses for all resource collection endpoints in pagination property of the response.

Property Type Description
offset int The offset of the items in the response. Defaults to 0.
limit int The limit of the number of items in the response. Defaults to 20, minimum of 0, maximum of 200.
total int The total number of items in the collection.
prev string Full URL to the previous page. null if there is no previous page.
next string Full URL to the next page. null if there is no next page.

For example, a response to a request such as GET /api/people/v2/users will contain a pagination property like the following:

{
    "data": [ Array of 20 User objects ],
    "pagination": {
        "offset": 0,
        "limit": 20,
        "total": 300,
        "prev": null,
        "next": "https://yourintranet.com/api/people/v2/users?offset=20"
    }
}

Requests

You can request different limit and offset values by using the limit and offset query parameters.

Parameter Type Description
offset int The offset of the items to include in the response. Defaults to 0.
limit int The limit of the number of items include in the response. Defaults to 20, minimum of 0, maximum of 200.

For example, a response to a request such as GET /api/people/v2/users?limit=100&offset=200 will look like the following:

{
    "data": [ Array of 100 User objects ],
    "pagination": {
        "offset": 200,
        "limit": 100,
        "total": 400,
        "prev": "https://yourintranet.com/api/people/v2/users?limit=100&offset=100",
        "next": "https://yourintranet.com/api/people/v2/users?limit=100&offset=300"
    }
}

Object types

There are several types of objects that you can interact with using the People API.

These object types and their JSON representations are documented below.

User

{
    "id"                         : 335,
    "blocked"                    : false,
    "username"                   : "JSmith",
    "firstname"                  : "Jane",
    "surname"                    : "Smith",
    "fullname"                   : "Jane Smith",
    "email"                      : "jane.smith@jsconsulting.co.uk",
    "company"                    : "Jane Smith Consulting Ltd",
    "job_title"                  : "Managing Director",
    "last_time_login"            : "2020-01-01T12:00:00+00:00",
    "last_time_used"             : "2020-01-01T12:00:00+00:00",
    "user_code"                  : "user_code_here",
    "language"                   : "en",
    "ldap_guid"                  : null,
    "external_directory_id"      : null,
    "external_directory_user_id" : null,
    "extranet_id"                : 1,
    "extranet"                   : {Extranet object},
    "metadata"                   : {Metadata object},
    "photo_url"                  : "https://yourintranet.com/appdata/people/335.jpg",
    "subordinates_url"           : "https://yourintranet.com/api/people/v2/users/335/subordinates",
    "extranet_url"               : "https://yourintranet.com/api/people/v2/extranets/1",
    "groups_url"                 : "https://yourintranet.com/api/people/v2/users/335/groups",
    "roles_url"                  : "https://yourintranet.com/api/people/v2/users/335/roles"
}

The returned fields will be different if you have specified the fields to be be returned in your request.

See the section on filtering and sorting for the GET /users endpoint.

Role

{
    "id"                : 10,
    "name"              : "Training Content Creators",
    "description"       : "Users who create content for training courses",
    "date_created"      : "2020-01-01T12:00:00+00:00",
    "inactive"          : false,
    "owner_id"          : 123,
    "extranet_id"       : 1,
    "extranet_url"      : null,
    "owner_url"         : "https://yourintranet.com/api/people/v2/users/123",
    "extranet"          : {Extranet Object}
}

Group

{
    "id"                : 10,
    "name"              : "External Consultants",
    "description"       : "All external consultants should be added to this group",
    "date_created"      : "2020-01-01T12:00:00+00:00",
    "inactive"          : false,
    "parent_id"         : 9,
    "owner_id"          : 123,
    "extranet_id"       : 2,
    "extranet"          : {Extranet Object},
    "owner_url"         : "https://yourintranet.com/api/people/v2/users/123",
    "parent_url"        : "https://yourintranet.com/api/people/v2/groups/9",
    "extranet_url"      : "https://yourintranet.com/api/people/v2/extranets/2",
    "subgroups_url"     : "https://yourintranet.com/api/people/v2/groups?parent_id=10"
}

Extranet

{
    "id"                : 10,
    "name"              : "External Consultants Extranet",
    "description"       : "All external consultants belong to this extranet",
    "inactive"          : false,
    "primary"           : false,
    "read_only"         : false,
    "admin_id"          : 9,
    "logo_url"          : null,
    "admin_url"         : "https://yourintranet.com/api/people/v2/users/9",
    "groups_url"        : "https://yourintranet.com/api/people/v2/groups?extranet_id=10",
    "roles_url"         : "https://yourintranet.com/api/people/v2/roles?extranet_id=10",
    "users_url"         : "https://yourintranet.com/api/people/v2/extranets/10/users"
}

Metadata

For more information about Metadata object types, read our Metadata documentation.

Endpoints

User Endpoints

GET /user

Get the currently authenticated User.

Returns 200 OK and a User objects if successful.

GET /users

Get a collection of Users, optionally matching the provided filter.

{
    "data": [
        // Array of User objects
    ],
    "pagination": {
        "offset": 10,
        "limit": 10,
        "total": 61,
        "prev": "https://yourintranet.com/api/people/v2/users/?{filter}&fields={fields}&limit=10&offset=0",
        "next": "https://yourintranet.com/api/people/v2/users/?{filter}&fields={fields}&limit=10&offset=20"
    }
}

This endpoint returns an array of user objects in the same format as GET /user/{id}

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 Users, Groups, Roles, Extranets

Query string parameters are:

  • /users?ids=NN[,NN[,..]]
  • /users?group_ids=NN[,NN[,..]]
  • /users?role_ids=NN[,NN[,..]]
  • /users?extranet_id=NN[,NN[,..]]

Where NN is a numeric ID for the Users, Groups, Roles or Extranet.

You can supply multiple comma-separated IDs and the request will return Users who match all of 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 status and view context

Query string parameters:

  • view - The user view context. user or admin. Defaults to user.
    • ?view=user - List users visible in as a front-end user
    • ?view=admin - List users visible as an administrator
  • status - User status filter. active, blocked or all. Defaults to active. Only takes effect if view=admin is given.
    • ?status=active - List active users
    • ?status=blocked - List blocked users
    • ?status=all - List active and blocked users

The user status filter will only take effect if the viewing context is admin. Otherwise, it is ignored and locked to active.

  • ?view=user - List active users that you can see as a front-end user
  • ?view=admin&status=active - List active users that you can see as an administrator
  • ?view=admin&status=blocked - List blocked users that you can see as an administrator
  • ?view=admin&status=all - List active and blocked users that you can see as an administrator

If the current user does not have any administrator permissions, an empty list will be returned.

Filtering by keywords

Query string parameters are:

  • query - The keywords to search. This can contain multiple keywords separated by spaces
  • query_fields - 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 (case insensitive) to indicate if the search should match for all or any of the given keywords. The default value for this parameter is AND.
Sorting

To sort the users list, you can 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 - firstname ascending sort

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

Fields to return

With the fields parameter you can specify which user fields you would like to have returned in the search results.

To specify fields you simple include a comma-separated list of them.

If no fields parameter is present, then you will receive the default user format as specified above.

The id field is always returned.

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

POST /users

Create a new user.

{
    "username"          : "JSmith",
    "blocked"           : false,
    "firstname"         : "Jane",
    "surname"           : "Smith",
    "email"             : "jane.smith@jsconsulting.co.uk",
    "password"          : "correcthorsebatterystaple",
    "company"           : "Jane Smith Consulting Ltd",
    "extranet_id"       : 1,
    "job_title"         : "Managing Director",
    "user_code"         : "user12345",
    "language"          : "en",
    "metadata"          : {Metadata Object}
}
Field Type Description
username string (required)
firstname string (required)
surname string (required)
email string (required)
password string (optional) Local users will be unable to login without this set.
blocked bool (optional) Whether the user is blocked. false by default.
company string (optional)
extranet_id int (optional) Set to the Primary Extranet ID by default
job_title string (optional) Job title
user_code string (optional)
language string (optional) Language code (e.g. 'en','ru','fr'). Set to the system language by default.
metadata object (optional) Metadata values.

Returns 200 code and the new User object on success.

GET /users/{id}

Get the User matching the provided {id}.

Returns 200 OK and a User object if successful or a 404 Not Found error if the User is not found.

PUT /users/{id}

Update the user matching the provided {id}.

This includes metadata, blocking/unblocking, language.

Accepts the same fields as the POST request above but all fields are optional. Those fields not included are assumed to be unchanged.

Returns HTTP status code 200 OK and the updated User object on success.

DELETE /users/{id}

Delete the User matching the provided {id}.

{
    "migration_user_id": 123
}

Optionally accepts a migration_user_id for migrating any content owned by the deleted user. This defaults to user ID 1 (Claromentis Administrator).

Returns HTTP status code 204 No Content on success.

POST /users/{id}/photo

Upload a new profile photo for User matching the provided {id}.

The request must have a content type of multipart/form-data.

Request body
Field Description
photo (Required) The image to set as the user's profile photo.
x Crop X coordinate in pixels
y Crop Y coordinate in pixels
width Crop width in pixels

Returns HTTP status code 204 No Content on success.

DELETE /users/{id}/photo

Remove the profile photo for the User matching the provided {id}.

This sets the user's profile photo to the system's default profile photo.

Return HTTP status code 204 No Content on success.

PUT /users/{id}/password

Set the password for the User matching the provided {id}.

{
    "password" : "correcthorsebatterystaple"
}

Returns HTTP status code 204 No Content on success.

PUT /users/{id}/manager

Set the Manager for the User matching the provided {id}.

The provided Manager will be considered their Manager for Org Charts.

{
    "manager_id": 321
}

Only accepts an ID field.

Returns HTTP status code 204 No Content on success.

GET /users/{id}/subordinates

Get a collection of Users who are subordinates of the provided User {id}.

{
    "data": [Array of User objects],
    "pagination": {
        "offset": 10,
        "limit": 10,
        "total": 61
    }
}

PUT /users/{id}/subordinates

Set the subordinates of the User matching the provided {id}, using an array of User IDs.

Any users that used to be subordinates of User matching the provided {id} will no longer have a manager set.

[
    {"id": 4},
    {"id": 6},
    {"id": 7}
]

Only accepts ID fields for each subordinate.

Returns HTTP status code 204 No Content on success.

GET /users/{id}/groups

Get a collection of Groups that the given User is a member of.

{
    "data": [Array of Group objects],
    "pagination": {
        "offset": 10,
        "limit": 10,
        "total": 61
    }
}

PUT /users/{id}/groups

Set the Groups that a User belongs to.

This will replace any Groups the User currently belongs to. Provide an empty array to remove them from all Groups.

[
    {"id": 4},
    {"id": 6},
    {"id": 7}
]

Only accepts ID fields.

Returns HTTP status code 204 No Content on success.

GET /users/{id}/roles

Get a collection of Roles that a User belongs to.

{
    "data": [Array of User objects],
    "pagination": {
        "offset": 10,
        "limit": 10,
        "total": 61
    }
}

PUT /users/{id}/roles

Set the Roles that a User belongs to.

This will replace any Roles the User currently belongs to. Provide an empty array to remove them from all Roles.

[
    {"id": 4},
    {"id": 6},
    {"id": 7}
]

Only accepts ID fields.

Returns HTTP status code 204 No Content on success.

Group Endpoints

GET /groups

Get a collection of Group objects matching the provided filter.

{
    "groups": [
        // Array of Group Objects
    ],
    "pagination": {
        "offset": 10,
        "limit": 10,
        "total": 33,
        "prev": "https://yourintranet.com/api/people/v2/groups/?{filter}&fields={fields}&limit=10&offset=0",
        "next": "https://yourintranet.com/api/people/v2/groups/?{filter}&fields={fields}&limit=10&offset=20"
    }
}

This endpoint has an optional CGI-style parameters to filter the list by:

keywords - ...?query=managers Returns all groups with the word 'managers' in the name or description

owner - ...?owner=4 Returns all groups where the owner's user ID is 4

parent_group - ...?parent_group=5 Returns all groups that are the children of the group with ID 5

status - ...?status=all Possible statuses active, inactive and all. If all, the returned results will include both active and inactive groups. If inactive the returned results will include only inactive groups. By default, the endpoint only returns active groups.

POST /groups

Create a group.

{
    "name"              : "External Consultants",
    "description"       : "All external consultants should be added to this group",
    "inactive"          : false,
    "owner_id"          : 10,
    "parent_id"         : 2
}
Field Type Description
name string (required) Group name.
description string (optional) Group description. Defaults to empty.
inactive bool (optional) Whether the group is inactive. Defaults to false.
owner_id int (optional) ID of the user who owns this group. Set to current user by default.
parent_id int (optional) ID of the parent group. Defaults to 0 (no parent).

Returns HTTP status code 200 OK and the new group object on success.

GET /groups/{id}

Get a Group matching the provided {id}.

Returns a Group object matching {id} or a 404 Not Found error.

PUT /groups/{id}

Update the Group matching the provided {id}.

Accepts the same fields as the POST request above but all fields are optional. Those fields not included are assumed to be unchanged.

Returns HTTP status code 200 OK and the updated group object on success.

DELETE /groups/{id}

Delete group matching the provided {id}.

Returns HTTP status code 204 No Content on success.

GET /groups/{id}/users

Get the users that belong to a group.

Returns a list of User objects.

PUT /groups/{id}/users

Set the users that belong to a group.

[
    { "id":  4 },
    { "id":  5 },
    { "id":  6 }
]

Returns HTTP status code 204 No Content on success.

Role Endpoints

GET /roles

Get a list of roles matching the provided filter.

Query parameters

The optional query parameters to filter the list are as follows:

query - ?query=manager

Returns all roles with the word 'manager' in the name or description

owner - ?owner_id=4

Returns all roles where the owner's user ID is 4

status - ?status=all

Possible statuses are active, inactive and all.

If all, the returned results will include both active and inactive roles.

If inactive ,the returned results will include only inactive roles. By default, the endpoint only returns active roles.

POST /roles

Create a new role.

{
    "name":        "Training Content Creators",
    "description": "Users who create content for training courses",
    "inactive":    false,
    "owner_id":    123,
    "extranet_id": 1
}
Field Type Description
name string (required) Role name.
description string (optional) Role description. Defaults to empty.
inactive bool (optional) Whether the role is active. Defaults to false.
owner_id int (optional) ID of the User who owns this Role. Set to the currently authenticated User by default.
extranet_id int (optional) ID of the Extranet that this Role belongs to. Defaults to 0 (no Extranet).

Returns HTTP status code 201 Created and the new role object on success.

GET /roles/{id}

Get the Role matching the provided {id}.

Returns a Role object or a 404 Not Found error.

PUT /roles/{id}

Update the Role matching the provided {id}.

Accepts the same fields as the POST request above but all fields are optional. Fields that are not included are assumed to be unchanged.

Returns HTTP status code 200 OK and the changed role object on success.

DELETE /roles/{id}

Delete the Role matching the provided {id}.

Returns HTTP status code 204 No Content on success.

GET /roles/{id}/users

Get the users that belong to a role.

Returns a list of User objects.

PUT /roles/{id}/users

Set the users that belong to a role.

[
    { "id":  4 },
    { "id":  5 },
    { "id":  6 }
]

Returns HTTP status code 204 No Content on success.

Extranet Endpoints

GET /extranets

Get a list of Extranets matching the provided filter.

Query parameters
keywords - ?query=consultants

Returns all extranets with the word 'consultants' in the name or description.

owner - ?admin=4

Returns all extranets administrated by the user with ID 4.

status - ?status=all

Possible statuses active, inactive and all.

If all, the returned results will include both active and inactive roles. If inactive ,the returned results will include only inactive roles. By default, the endpoint only returns active roles.

POST /extranets

Create a new extranet.

{
    "name"              : "External Consultants Extranet",
    "description"       : "All external consultants belong to this extranet",
    "admin"             : 23,
    "is_inactive"       : false,
    "is_read_only"      : false
}
Field Type Description
name string (required) Extranet name.
description string (optional) Extranet description. Empty by default.
admin_id int (optional) ID of user who administrates this extranet. Set to the currently authenticated user by default.
inactive bool (optional) Whether the extranet is active. false by default.
read_only bool (optional) Whether the extranet is read-only. false by default.

Returns HTTP status code 200 OK and the new extranet object on success.

GET /extranets/{id}

Get an Extranet matching the provided {id}

Returns an Extranet object or a 404 Not Found error.

PUT /extranets/{id}

Update the Extranet matching the provided {id}.

Accepts the same fields as the POST request above but all fields are optional. Fields that are not included are assumed to be unchanged.

Returns HTTP status code 200 OK with the updated extranet object on success.

DELETE /extranets/{id}

Delete an Extranet matching the provided {id}. 

{
  "migration_extranet_id": 1
}

Requires an Extranet ID to migrate users to before deleting the Extranet.

Returns HTTP status code 204 No Content on success.

GET /extranets/{id}/users

Get the users that belong to an extranet.

Returns a list of User objects.

PUT /extranets/{id}/users

Set the users that belong to an extranet.

[
    { "id":  4 },
    { "id":  5 },
    { "id":  6 }
]

Returns HTTP status code 204 No Content on success.

GET /extranets/primary

Get the current primary extranet.