Placeholder Users

Actions

Link Description Condition
showUser Link to the OpenProject placeholder user page (HTML)
updateImmediately Update a placeholder from the instance Permission: manage_placeholder_user
delete Permanently remove a placeholder from the instance Permission: manage_placeholder_user

Linked Properties

Link Description Type Constraints Supported operations Condition
self This user User not null READ
memberships Link to collection of all the user’s memberships. The list will only include the memberships in projects in which the requesting user has the necessary permissions. MemberCollection READ Permission: view members or manage members in any project

Local Properties

Property Description Type Constraints Supported operations Condition
id Placeholder user’s id Integer x > 0 READ
name Placeholder user’s full name, formatting depends on instance settings String READ
createdAt Time of creation DateTime READ
updatedAt Time of the most recent change to the user DateTime READ

PlaceholderUser 

View placeholder user
/api/v3/placeholder_users/{id}
  • Parameters
  • id
    integer (required) 
  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_type": "PlaceholderUser",
        "_links": {
            "self": {
                "href": "/api/v3/placeholder_users/1",
                "title": "placeholder"
            },
            "show": {
                "href": "/placeholder_users/1",
                "type": 'text/html'
            },
            "delete": {
                "href": "/api/v3/placeholder_users/1",
                "method": "DELETE"
            },
        },
        "id": 1,
        "name": "placeholder",
        "createdAt": "2014-05-21T08:51:20Z",
        "updatedAt": "2014-05-21T08:51:20Z"
    }
  • Response  404
  • Returned if the user does not exist or if the API user does not have permission to view them.

    Required permission The user needs to have the manage_placeholder_user permission

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The specified user does not exist or you do not have permission to view them."
    }
Update placeholder user
/api/v3/placeholder_users/{id}

Updates the placeholder user’s writable attributes. When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body.

  • Parameters
  • id
    integer (required) Example: 1

    Placeholder user id

  • Request  Update PlaceholderUser
  • Headers
    Content-Type: application/json
    Body
    {
      "name": "New name"
    }
  • Response  200
  • Body
    {
        "_type": "PlaceholderUser",
        "_links": {
            "self": {
                "href": "/api/v3/placeholder_users/1",
                "title": "placeholder"
            },
            "show": {
                "href": "/placeholder_users/1",
                "type": 'text/html'
            },
            "delete": {
                "href": "/api/v3/placeholder_users/1",
                "method": "DELETE"
            },
        },
        "id": 1,
        "name": "placeholder",
        "createdAt": "2014-05-21T08:51:20Z",
        "updatedAt": "2014-05-21T08:51:20Z"
    }
  • Response  400
  • Occurs when the client did not send a valid JSON object in the request body.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
      "message": "The request body was not a single JSON object."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: Administrators, manage_placeholder_user global permission

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not allowed to access this resource."
    }
  • Response  404
  • Returned if the user does not exist.

    Required permission: Administrators, manage_placeholder_user global permission

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The requested resource could not be found."
    }
  • Response  422
  • Returned if:

    • the client tries to modify a read-only property (PropertyIsReadOnly)

    • a constraint for a property was violated (PropertyConstraintViolation)

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
      "message": "Name is already taken.",
      "_embedded": {
        "details": {
          "attribute": "name"
        }
      }
    }
Delete placeholder user
/api/v3/placeholder_users/{id}

Permanently deletes the specified placeholder. This action will be performed asynchronously and the response will only accept the deletion request. The actual deletion will then potentially take a while.

  • Parameters
  • id
    integer (required) Example: 1

    Placeholder user id

  • Response  202
  • Returned if the account was successfully scheduled for deletion.

  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: Administrators or manage_placeholder_user permission

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not authorized to access this resource"
    }
  • Response  404
  • Returned if the user does not exist.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The requested resource could not be found."
    }

PlaceholderUsers 

List Placeholder Users
/api/v3/users{?offset,pageSize,filters,sortBy}

Lists placeholders. Only administrators or users with manage_placeholder_user global permission have permission to do this.

  • Parameters
  • offset
    integer (optional) Default: 1 Example: 25

    Page number inside the requested collection.

    pageSize
    integer (optional) Example: 25

    Number of elements to display per page.

    filters
    string (optional) Example: [{ "group": { "operator": "=", "values": ["1"] } }, { "name": { "operator": "=", "values": ["placeholder"] } }]

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

    • group: Name of the group in which to-be-listed placeholder users are members.

    • name: Filter placeholder users in whose first or last names, or email addresses the given string occurs.

    • status: Filter placeholder users by their status. Possible values are “active” and “locked”

    sortBy
    string (optional) Example: [["name", "asc"]]

    JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint.

    Currently supported orders are:

    • id

    • name

    • group

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
        "_links": {
            "self": { "href": "/api/v3/placeholder_users" }
        },
        "total": 2,
        "count": 1,
        "_type": "Collection",
        "_embedded": {
            "elements": [
                {
                    "_type": "PlaceholderUser",
                    "_links": {
                        "self": {
                            "href": "/api/v3/placeholder_users/1",
                            "title": "placeholder"
                        },
                        "showUser": {
                            "href": "/placeholder_users/1",
                            "type": 'text/html'
                        },
                        "updateImmediately": {
                            "href": "/api/v3/placeholder_users/1",
                            "title": "Update placeholder"
                            "method": "PATCH"
                        },
                        "delete": {
                            "href": "/api/v3/placeholder_users/1",
                            "title": "Delete placeholder"
                            "method": "DELETE"
                        }
                    },
                    "id": 1,
                    "name": "placeholder",
                    "createdAt": "2014-05-21T08:51:20Z",
                    "updatedAt": "2014-05-21T08:51:20Z"
                }
            ]
        }
    }
  • Response  400
  • Returned if the client sends an unknown sort column.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
      "message": "Unknown sort column."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: Administrator or manage_placeholder_user permission

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not authorized to access this resource."
    }

Create placeholder user 

Create Placeholder User
/api/v3/placeholder_users

Creates a new placeholder user. Only administrators and users with manage_placeholder_user global permission are allowed to do so. When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body.

  • Request  Create User
  • Headers
    Content-Type: application/json
    Body
    {
      "name": "placeholder"
    }
  • Response  201
  • Body
    {
        "_type": "PlaceholderUser",
        "_links": {
            "self": {
                "href": "/api/v3/placeholder_users/1",
                "title": "placeholder"
            },
            "show": {
                "href": "/placeholder_users/1",
                "type": 'text/html'
            },
            "delete": {
                "href": "/api/v3/placeholder_users/1",
                "method": "DELETE"
            },
        },
        "id": 1,
        "name": "placeholder",
        "createdAt": "2014-05-21T08:51:20Z",
        "updatedAt": "2014-05-21T08:51:20Z"
    }
  • Response  400
  • Occurs when the client did not send a valid JSON object in the request body.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
      "message": "The request body was not a single JSON object."
    }
  • Response  403
  • Returned if the client does not have sufficient permissions.

    Required permission: Administrator or manage_placeholder_user

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not authorized to access this resource."
    }
  • Response  422
  • Returned if:

    • a constraint for a property was violated (PropertyConstraintViolation)
    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
      "message": "Name is already taken.",
      "_embedded": {
        "details": {
          "attribute": "name"
        }
      }
    }