API: Principals

Principals are the superclass of users, groups and placeholder users. This end point returns all principals within a joined collection but can be filtered to e.g. only return groups or users.

Methods

List principals

List all principals. The client can choose to filter the principals similar to how work packages are filtered. In addition to the provided filters, the server will reduce the result set to only contain principals who are members in projects the client is allowed to see.

filters
string

optional query

JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. Currently supported filters are:

  • type: filters principals by their type (User, Group, PlaceholderUser).

  • member: filters principals by the projects they are members in.

  • name: filters principals by the user or group name.

  • any_name_attribute: filters principals by the user or group first- and last name, email or login.

  • status: filters principals by their status number (active = 1, registered = 2, locked = 3, invited = 4)

Example:
[{ "type": { "operator": "=", "values": ["User"] } }]

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "delete": {
            "href": "/api/v3/users/4",
            "method": "delete",
            "title": "Delete Eliza92778"
          },
          "lock": {
            "href": "/api/v3/users/4/lock",
            "method": "post",
            "title": "Set lock on Eliza92778"
          },
          "self": {
            "href": "/api/v3/users/4",
            "title": "Danika O'Keefe"
          },
          "showUser": {
            "href": "/users/4",
            "type": "text/html"
          },
          "updateImmediately": {
            "href": "/api/v3/users/4",
            "method": "patch",
            "title": "Update Eliza92778"
          }
        },
        "_type": "User",
        "admin": false,
        "avatar": "https://example.org/users/4/avatar",
        "createdAt": "2015-03-20T12:57:02Z",
        "email": "jackie@dicki.org",
        "firstName": "Danika",
        "id": 4,
        "identityUrl": null,
        "lastName": "O'Keefe",
        "login": "Eliza92778",
        "name": "Danika O'Keefe",
        "status": "active",
        "updatedAt": "2015-06-16T15:28:14Z"
      },
      {
        "_links": {
          "delete": {
            "href": "/api/v3/users/2",
            "method": "delete",
            "title": "Delete Sebastian9686"
          },
          "lock": {
            "href": "/api/v3/users/2/lock",
            "method": "post",
            "title": "Set lock on Sebastian9686"
          },
          "self": {
            "href": "/api/v3/users/2",
            "title": "Peggie Feeney"
          },
          "showUser": {
            "href": "/users/2",
            "type": "text/html"
          },
          "updateImmediately": {
            "href": "/api/v3/users/2",
            "method": "patch",
            "title": "Update Sebastian9686"
          }
        },
        "_type": "User",
        "admin": false,
        "avatar": "https://example.org/users/4/avatar",
        "createdAt": "2015-03-20T12:56:55Z",
        "email": null,
        "firstName": "Peggie",
        "id": 2,
        "identityUrl": null,
        "lastName": "Feeney",
        "login": "Sebastian9686",
        "name": "Peggie Feeney",
        "status": "active",
        "updatedAt": "2015-03-20T12:56:55Z"
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/groups/9",
            "title": "The group"
          }
        },
        "_type": "Group",
        "createdAt": "2015-09-23T11:06:36Z",
        "id": 9,
        "name": "The group",
        "updatedAt": "2015-09-23T11:06:36Z"
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/placeholder_users/29",
            "title": "UX Designer"
          }
        },
        "_type": "PlaceholderUser",
        "createdAt": "2018-09-23T11:06:36Z",
        "id": 29,
        "name": "UX Designer",
        "updatedAt": "2019-10-23T11:06:36Z"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/principals"
    }
  },
  "_type": "Collection",
  "count": 4,
  "total": 4
}

PrincipalsModel

{
  "type": "object",
  "example": {
    "_type": "Collection",
    "total": 4,
    "count": 4,
    "_embedded": {
      "elements": [
        {
          "_type": "User",
          "id": 4,
          "login": "Eliza92778",
          "admin": false,
          "firstName": "Danika",
          "lastName": "O'Keefe",
          "name": "Danika O'Keefe",
          "email": "jackie@dicki.org",
          "avatar": "https://example.org/users/4/avatar",
          "createdAt": "2015-03-20T12:57:02Z",
          "updatedAt": "2015-06-16T15:28:14Z",
          "status": "active",
          "identityUrl": null,
          "_links": {
            "self": {
              "href": "/api/v3/users/4",
              "title": "Danika O'Keefe"
            },
            "showUser": {
              "href": "/users/4",
              "type": "text/html"
            },
            "updateImmediately": {
              "href": "/api/v3/users/4",
              "title": "Update Eliza92778",
              "method": "patch"
            },
            "lock": {
              "href": "/api/v3/users/4/lock",
              "title": "Set lock on Eliza92778",
              "method": "post"
            },
            "delete": {
              "href": "/api/v3/users/4",
              "title": "Delete Eliza92778",
              "method": "delete"
            }
          }
        },
        {
          "_type": "User",
          "id": 2,
          "login": "Sebastian9686",
          "admin": false,
          "firstName": "Peggie",
          "lastName": "Feeney",
          "name": "Peggie Feeney",
          "email": null,
          "avatar": "https://example.org/users/4/avatar",
          "createdAt": "2015-03-20T12:56:55Z",
          "updatedAt": "2015-03-20T12:56:55Z",
          "status": "active",
          "identityUrl": null,
          "_links": {
            "self": {
              "href": "/api/v3/users/2",
              "title": "Peggie Feeney"
            },
            "showUser": {
              "href": "/users/2",
              "type": "text/html"
            },
            "updateImmediately": {
              "href": "/api/v3/users/2",
              "title": "Update Sebastian9686",
              "method": "patch"
            },
            "lock": {
              "href": "/api/v3/users/2/lock",
              "title": "Set lock on Sebastian9686",
              "method": "post"
            },
            "delete": {
              "href": "/api/v3/users/2",
              "title": "Delete Sebastian9686",
              "method": "delete"
            }
          }
        },
        {
          "_type": "Group",
          "id": 9,
          "name": "The group",
          "createdAt": "2015-09-23T11:06:36Z",
          "updatedAt": "2015-09-23T11:06:36Z",
          "_links": {
            "self": {
              "href": "/api/v3/groups/9",
              "title": "The group"
            }
          }
        },
        {
          "_type": "PlaceholderUser",
          "id": 29,
          "name": "UX Designer",
          "createdAt": "2018-09-23T11:06:36Z",
          "updatedAt": "2019-10-23T11:06:36Z",
          "_links": {
            "self": {
              "href": "/api/v3/placeholder_users/29",
              "title": "UX Designer"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/api/v3/principals"
      }
    }
  }
}