REST API Documentation (v 3.5)

Owned by Andreas Ebert
Last updated: Aug 01, 2024 by Tino Winkler
8 min read

About

User Profiles for Confluence provides a REST API which gives (read-only) access to data of the user profiles. Using the API you can get hold of the following data:

  • all profile elements and their configuration

  • the data which is stored for those elements for each user

Content

General Information

We tried to keep as close as possible to the REST-Guidelines of Atlassian. So if you are familar with the REST API of Confluence, it should be quite easy for you to consume our API.

If you are using the Developer Tools Plugin, you can use the REST API Browser to play around with our API.

 

To access the API use the following URL

<Server Base URL>/rest/communardo/upp/<version>/<path to resource>

where

  • <server base URL> is the server base URL of your Confluence instance

  • <version> is the version of the API

    • currently there is only one version: 1.0

    • if you want to always use the most recent version of the API, use "latest" instead of  "1.0"

  • <path to resource> is the resource which you want to access, see below for details

 

Authentication

Depending on how you request the API you might have to consider authentication. If you are issuing requests using AJAX calls from a browser session you probably will not have to bother about this. Those calls will be authenticated using the browser session.

However, requests coming from other systems will have to authenticate in order to access the API. Currently the only authentication supported is basic access authentication:

  • you have to provide an Authorization header containing "Basic username:password", with "username:password" being Base64 encoded

  • add the query parameter os_authType=basic to the URL (e.g. http://localhost:8080/rest/communardo/upp/latest/some/resource?os_authType=basic)

 

Data Formats

Currently responses by the API contain all data in JSON format only. There are no other formats supported.

Expansion

If you are familiar with the REST API of Confluence you might know the concept known as "expansion". It is basically allows you to control the amount of data, which each request to a resource returns by means of a request query parameter:
For each request to a resource supporting expansion you can provide a list of  attributes with the parameter expand. The entities of those attributes will than contain more information. In order to find out which attributes you can expand on, you just have to check the attribute "expand" of the response. The value of this attribute lists all the supported attributes for expansion.
More details about this concept can be found in the Atlassian REST API Design Guidelines. Our examples below will also cover this topic in more detail.

 

 

Resources

The following sections describe the resources that are available via the API.

Profile Element Configuration

There are two resources which provide information about the profile element configuration.

Get a list of all profile elements (/profileElements)

  • provides a list of all profile elements

  • this are exactly the same elements as those accessible via the configuration of the user profile plugin

  • the elements returned have the same order as defined via the configuration of the user profile plugin

  • the result can be expanded on "profileElements", which will cause the returned list to contain all the information available for each element (see /profileElements/{elementKey} below for details)

Returned Data

The data structure returned by the request has the following attributes:

Attribute

Type

Value

Attribute

Type

Value

expand

String

the name of the attribute which can be expanded on ("profileElements")

profileElements

List

the list of profile elements

  • each element is represented by the URL to the resource of the element

    • see /profileElements/{elementKey} below for details

Example (without expansion)

Request:

http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/

Response:

{"expand":"profileElements", "profileElements":[{"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/178640080"}, {"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/im"}, {"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/01050669159"}, {"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/0861244944"}, {"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/phone"}, {"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/website"}, {"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/department"}, {"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/1185300867"}, {"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/location"}, {"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/position"}, {"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/personalInformation"}] }

Get information about a specific profile element - /profileElements/{elementKey}

Returned Data

The entity returned by the request has the following attributes:

Attribute

Type

Value

Attribute

Type

Value

expand

String

the name of the attribute which can be expanded on ("options")

key

String

the key of the profile element

nameForCurrentLocale

String

the title of the profile element with the translation for the currently authenticated user (default or German)

defaultName

String

the Default Title of the profile element

germanName

String

the German Title of the profile element

helpTextForCurrentLocale

String

the help text of the profile element with the translation for the currently authenticated user (default or German)

defaultHelpText

String

the Default Help Text of the profile element

germanHelpText

String

the German Help Text of the profile element

profileGroup

String

the profile group which this element belongs to (either "personal" or "business")

elementType

String

the Field Type of the profile element, one of:

  • TEXT_FIELD (for elements of type "Textfield")

  • TEXT_AREA (for elements of type "Textarea")

  • USER_FIELD (for elements of type "Userfield")

  • AUTOCOMPLETE_TEXTFIELD (for elements of type "Textfield with Autocomplete")

  • SELECT_SINGLE (for elements of type "Single Select (Radiobuttons)")

  • SELECT_MULTIPLE (for elements of type "Multiple Select (Checkboxes)")

  • PHONE_NUMBER (for elements of type "Phone Number")

ldapAttributeMapping

String

The value for the configured LDAP attribute mapping

displayInCustomMode

Boolean

whether or not this element is displayed using the mode "prioritized" of the enhanced profile macro

hidden

Boolean

whether this element is hidden (always false for additional profile elements, as those can currently not be hidden)

personalInformationElement

Boolean

whether this element is the element containing the "About Me" information of the standard Confluence profile

standard

Boolean

whether this element is a standard (true) or additional (false) profile element

options

Object

 since 3.3.2

list of the options of the profile element

  • represented by the URL to the resource of options for the profile element

    • see /profileElements/{elementKey}/options below for details

only available for elementType SELECT_SINGLE and SELECT_MULTIPLE 

 

self

String

the URL of the returned resource

Example (for request authenticated to user with German locale)

Request:

Response:

example1

 

example2

Get a list of all options for a profile element - /profileElements/{elementKey}/options

since 3.3.2

  • provides a list of all options for a profile element

Returned Data - option list

The data structure returned by the request has the following attributes:

Attribute

Type

Value

Attribute

Type

Value

options

List

the list of options as object

self

String

the URL of the returned resource

Returned Data - option

The data structure of an option:

Attribute

Type

Value

Attribute

Type

Value

id

String

the id of the option

nameForCurrentLocale

String

the name for the current locale

defaultName

String

the default name of the option

germanName

String

the gernam name of the option

 

Example

Request:

Response:

Profile Element Data

There are two resources provided to access profile data for individual users.

Get all profile data for a specific user (/profileData/{user})

  • lists the profile data for each profile element for the user provided by {user}

  • the returned list of element data has the same order as defined via the configuration of the user profile plugin

  • the result can be expanded on "profileData.profileElement", which will cause the result to contain additional information about the profile elements (see /profileData/{user}/{elementKey} for an example)

Returned Data

The entity returned by the request has the following attributes:

Attribute

Type

Value

Attribute

Type

Value

expand

String

the name of the attribute which can be expanded on ("profileData")

Please Note: Expansion on "profileData" will not provide more information. But the entities of profile elements can also be expanded. You can use dot notation ("profileData.profileElement") to achieve this. See example below.

profileData

List

the list of profile data for each profile element

  • each profile data item on the list has the same attributes as the data structures for the individual resources

    • see /profileData/{user}/{elementKey} below for details

Example (w/o expansion)

Request:

Response:

 

Example (with expansion)

Request

Note the request query parameter ?expand=profileData.profileElement, which causes the response to contain additional information about the profile elements.

Response (excerpt):

 

Get the data for a specific user and profile element (/profileData/{user}/{elementKey})

  • returns the data for the user provided by {user} and the profile element with the key {elementKey}

  • the result can be expanded on "profileElement", which will cause the data structure to contain all the information available for the associated profile element (see /profileElements/{elementKey} above for details and example below)

Returned Data

The entity returned by the request has the following attributes:

Attribute

Type

Value

Attribute

Type

Value

expand

String

the name of the attribute which can be expanded on ("profileElement")

profileElement

Object

the profile element for which the data is returned

data

String

the data of the profile element for the given user

Please Note: The data is returned in the same way as it would be for the enhanced profile macro. I.e. the data is rendered depending on the Field Type of the element. (See example below for the data of a field of type USER_FIELD)

self

String

the URL of the returned resource

Example (w/o expansion)

Request:

Response:

Example (with expansion)

Request:

Note the request query parameter ?expand=profileElement, which causes the response to contain additional information about the profile element.

Response:

 

Back to Top