Resource: Users ( /api/users )
Allows the search and retrieval of users.
Root Relation: Users
This resource supports the following methods: GET, POST
Methods
GET
Retrieves all (or a subset) of users.
This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.
Supported Expansions
- DisplayName
- Groups
For more details on expansions, please see the Expand help topic.
Status Codes
These are the expected status codes returned by the service - in addition, some other status codes may be returned if either an internal error occurs or there is an authentication issue (such as an expired OAuth token).
| Status | Description |
|---|---|
| 200 - OK | Returned if the request was completed successfully. |
Example - Get All Users
An example of fetching all users.
Request Headers
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
Response Headers
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json; charset=utf-8 |
Response Body
[
{
"Id": "3464e9da-f1b7-49aa-87db-7e1eebfd17a5",
"UserName": "joeb",
"Email": "joeb@unknown.net",
"FirstName": "Joe",
"LastName": "Bloggs",
"Phone": "(09)-555-999",
"LastLogIn": null,
"Self": "http://localhost/api/user/3464e9da-f1b7-49aa-87db-7e1eebfd17a5",
"Links": [
{
"Href": "http://localhost/api/user/3464e9da-f1b7-49aa-87db-7e1eebfd17a5/password",
"Rel": "ChangePassword"
},
{
"Href": "http://localhost/api/user/3464e9da-f1b7-49aa-87db-7e1eebfd17a5/permissions/global",
"Rel": "GlobalPermissions"
},
{
"Title": "Group Memberships",
"Href": "http://localhost/api/user/3464e9da-f1b7-49aa-87db-7e1eebfd17a5/groups",
"Rel": "Groups"
},
{
"Href": "http://localhost/api/user/3464e9da-f1b7-49aa-87db-7e1eebfd17a5/notifications",
"Rel": "Notifications"
},
{
"Href": "http://localhost/api/user/3464e9da-f1b7-49aa-87db-7e1eebfd17a5/permissions/projects",
"Rel": "ProjectPermissions"
},
{
"Href": "http://localhost/api/user/3464e9da-f1b7-49aa-87db-7e1eebfd17a5/mailmessages",
"Rel": "MailMessages"
}
]
},
{
"Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
"UserName": "janed",
"Email": "janed@unknown.net",
"FirstName": "Jane",
"LastName": "Doe",
"Phone": "(09)-555-999",
"LastLogIn": null,
"Self": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610",
"Links": [
{
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/password",
"Rel": "ChangePassword"
},
{
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/permissions/global",
"Rel": "GlobalPermissions"
},
{
"Title": "Group Memberships",
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/groups",
"Rel": "Groups"
},
{
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/notifications",
"Rel": "Notifications"
},
{
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/permissions/projects",
"Rel": "ProjectPermissions"
},
{
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/mailmessages",
"Rel": "MailMessages"
}
]
}
]
Status Code
200 - OK
Example - Get Users filtered by first name
An example of fetching a set of users by first name, by using the ODATA $filter query parameter.
Request Headers
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
Request Parameters
| Key | Value | Description |
|---|---|---|
| $filter | FirstName eq 'Jane' | The ODATA $filter parameter, this query parameter should be url encoded i.e. $filter=FirstName%20eq%20'Jane'. |
Response Headers
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json; charset=utf-8 |
Response Body
[
{
"Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
"UserName": "janed",
"Email": "janed@unknown.net",
"FirstName": "Jane",
"LastName": "Doe",
"Phone": "(09)-555-999",
"LastLogIn": null,
"Self": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610",
"Links": [
{
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/password",
"Rel": "ChangePassword"
},
{
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/permissions/global",
"Rel": "GlobalPermissions"
},
{
"Title": "Group Memberships",
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/groups",
"Rel": "Groups"
},
{
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/notifications",
"Rel": "Notifications"
},
{
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/permissions/projects",
"Rel": "ProjectPermissions"
},
{
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/mailmessages",
"Rel": "MailMessages"
}
]
}
]
Status Code
200 - OK
POST
Create a new user
Required Permissions
- Administration/Organisation/ManageUserAndGroupSecurity
Status Codes
These are the expected status codes returned by the service - in addition, some other status codes may be returned if either an internal error occurs or there is an authentication issue (such as an expired OAuth token).
| Status | Description |
|---|---|
| 200 - OK | Returned if the request was completed successfully. |
| 403 - Forbidden | Returned if request contained invalid data or would cause a conflict with an existing user record. |
| 404 - NotFound | Returned if user does not exists. |
Example - Create new User (minimum values populated)
An example of creating a new user.
Request Headers
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
Request Body
{
"UserName": "janed",
"Email": "janed@unknown.net"
}
Response Headers
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json; charset=utf-8 | |
| Location | http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610 |
Response Body
[
{
"Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
"UserName": "janed",
"Email": "janed@unknown.net",
"FirstName": null,
"LastName": null,
"Phone": null,
"LastLogIn": null,
"Self": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610",
"Links": [
{
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/password",
"Rel": "ChangePassword"
},
{
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/permissions/global",
"Rel": "GlobalPermissions"
},
{
"Title": "Group Memberships",
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/groups",
"Rel": "Groups"
},
{
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/notifications",
"Rel": "Notifications"
},
{
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/permissions/projects",
"Rel": "ProjectPermissions"
},
{
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/mailmessages",
"Rel": "MailMessages"
}
]
}
]
Status Code
201 - Created
Example - Create new User (all values populated)
An example of creating a new user.
Request Headers
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
Request Body
{
"UserName": "janed",
"Email": "janed@unknown.net",
"FirstName": "Jane",
"LastName": "Doe",
"Phone": "(09)-555-999",
"Password": "Password123"
}
Response Headers
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json; charset=utf-8 | |
| Location | http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610 |
Response Body
[
{
"Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
"UserName": "janed",
"Email": "janed@unknown.net",
"FirstName": "Jane",
"LastName": "Doe",
"Phone": "(09)-555-999",
"LastLogIn": null,
"Self": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610",
"Links": [
{
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/password",
"Rel": "ChangePassword"
},
{
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/permissions/global",
"Rel": "GlobalPermissions"
},
{
"Title": "Group Memberships",
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/groups",
"Rel": "Groups"
},
{
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/notifications",
"Rel": "Notifications"
},
{
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/permissions/projects",
"Rel": "ProjectPermissions"
},
{
"Href": "http://localhost/api/user/4bb709c2-e0e7-4af3-9f60-a045016a9610/mailmessages",
"Rel": "MailMessages"
}
]
}
]
Status Code
201 - Created