REST API Documentation (v 3.5)

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

1 General Information
- 1.1 Authentication
- 1.2 Data Formats
- 1.3 Expansion
2 Resources
- 2.1 Profile Element Configuration
- 2.2 Profile Element Data
  - 2.2.1 Get all profile data for a specific user (/profileData/{user})
  - 2.2.2 Get the data for a specific user and profile element (/profileData/{user}/{elementKey})

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}

provides the information of the element with the key {elementKey}
provides the same information as the configuration of the user profile plugin and some additional information

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