Skip to main content

Users

The user namespace provides a simple method to get the current, authenticated user. You can also use this method to test API access and authentication.

The users namespace provides API methods to retrieve all or specific users.

This page covers the following API methods:

GET /projects/{project_id}/users

Returns all users for a project.

This method uses pagination so you might need to request additional pages to retrieve all users.

icons8-dot-50(3).png project_id id required 
ID of the project.
 

Request

Parameters
Schema

icons8-dot-50.png page integer 
Number of page to return (default: first page)
 

icons8-dot-50.png per_page integer 
Maximum number of users to return (supported: 15, 25, 50, 100; default: 100)

"page": {
    "type": "integer",
    "format": "int64",
    "description": "Number of page (default: first page)."
},
"per_page": {
    "type": "integer",
    "format": "int64",
    "enum": [
        15,
        25,
        50,
        100
    ],
    "description": "Maximum number of items to return per page (default: 100)."
}


Response

GET /api/v1/projects/1/users

 
200 OK
{
    "page": 1,
    "prev_page": null,
    "next_page": 2,
    "last_page": 2,
    "per_page": 100,
    "total": 150,
    "result": [
        { "id": 1, "name": "User 1", },
        { "id": 2, "name": "User 2", },
        ..
    ]
}


Examples

// Get first 100 users for project with ID 5
GET /api/v1/project/5/users

// Get second result page (pagination)
GET /api/v1/project/5/users?page=2


Status codes

200 400 401 404 422 (details)

GET /user

Returns the current user. A typical use case for this method is to test API access and authentication.
 

Response

GET /api/v1/user

 
200 OK
{
    "id": 1,
    "name": "User 1",
    "timezone": null,
    "date_format": null,
    "time_format": null
}


Status codes

200 400 401 (details)

GET /users

Returns all users. Requires site admin access.

This method uses pagination so you might need to request additional pages to retrieve all users.
 

Request

Parameters
Schema

icons8-dot-50.png page integer 
Number of page to return (default: first page)
 

icons8-dot-50.png per_page integer 
Maximum number of users to return (supported: 15, 25, 50, 100; default: 100)
 

icons8-dot-50.png expands string 
Comma-separated list of expands to return.

"page": {
    "type": "integer",
    "format": "int64",
    "description": "Number of page (default: first page)."
},
"per_page": {
    "type": "integer",
    "format": "int64",
    "enum": [
        15,
        25,
        50,
        100
    ],
    "description": "Maximum number of items to return per page (default: 100)."
},
"expands": {
    "type": "string",
    "description": "Comma-separated list of expands to return."
}

This method supports the following expands so you can automatically include additional information for referenced objects:

  • groups

  • roles

  • users

Response

GET /api/v1/users

 
200 OK
{
    "page": 1,
    "prev_page": null,
    "next_page": 2,
    "last_page": 2,
    "per_page": 100,
    "total": 150,
    "result": [
        {
            "id": 1,
            "name": "User 1",
            "email": "user1@example.com",
            "type": 4,
            "timezone": null,
            "date_format": null,
            "time_format": null,
            ..
            "role_id": 4,
            "groups": [1, 2],
            "created_at": "..",
            "created_by": null,
            "updated_at": null,
            "updated_by": null
        },
        {
            "id": 2,
            "name": "User 2",
            "email": "user2@example.com",
            "type": 1,
            "timezone": null,
            "date_format": null,
            "time_format": null,
            ..
            "role_id": 2,
            "groups": [],
            "created_at": "..",
            "created_by": 1,
            "updated_at": null,
            "updated_by": null
        },
        ..
    ],
    "expands": {
        ..
    }
}


Examples

// Get first 100 users
GET /api/v1/users

// Get second result page (pagination)
GET /api/v1/users?page=2

// Get users and include group & role details
GET /api/v1/users?expands=groups,roles


Status codes

200 400 401 403 422 (details)

GET /users/{user_id}

Returns a single user. Requires site admin access.

icons8-dot-50(3).png user_id id required 
ID of the user to return.
 

Request

Parameters
Schema

icons8-dot-50.png expands string Comma-separated list of expands to return.

"expands": {
    "type": "string",
    "description": "Comma-separated list of expands to return."
}

This method supports the following expands so you can automatically include additional information for referenced objects:

  • groups

  • roles

  • users

Response

GET /api/v1/users/1

 
200 OK
{
    {
        "id": 1,
        "name": "User 1",
        "email": "user1@example.com",
        "type": 4,
        "timezone": null,
        "date_format": null,
        "time_format": null,
        ..
        "role_id": 4,
        "groups": [1, 2],
        "created_at": "..",
        "created_by": null,
        "updated_at": null,
        "updated_by": null
    },
    "expands": {
        ..
    }
}


Examples

// Get the user with ID 5
GET /api/v1/users/5

// Get a user and include group & role details
GET /api/v1/users/1?expands=groups,roles


Status codes

200 400 401 403 404 422 (details)

Was this article helpful?