Account Groups API Basics

Liferay DXP/Portal 7.4+

You can manage account groups from the Applications menu or use Liferay’s REST APIs. Call these services to create and manage account groups.

Adding an Account Group

Start a new Liferay DXP instance by running

docker run -it -m 8g -p 8080:8080 liferay/dxp:2024.q2.11

Sign in to Liferay at http://localhost:8080 using the email address [e-mail] and the password test. When prompted, change the password to learn.

Then, follow these steps:

1. Download and unzip Account Groups API Basics.

   curl https://resources.learn.liferay.com/dxp/latest/en/users-and-permissions/developer-guide/liferay-v2w6.zip -O
   

   unzip liferay-v2w6.zip
   

2. Use the cURL script to add a new account group to your instance. On the command line, navigate to the curl folder. Execute the AccountGroups_POST_ToInstance.sh script.

   ./AccountGroups_POST_ToInstance.sh
   

   The JSON response shows a new account group has been added:

   {
      "customFields" : [ ],
      "dateCreated" : "2025-01-29T12:50:22Z",
      "dateModified" : "2025-01-29T12:50:22Z",
      "description" : "",
      "externalReferenceCode" : "2891fd33-3afb-a175-6e7e-2fdd1acb7a32",
      "id" : 37403,
      "name" : "Foo"
   }
   

3. Navigate to Global Menu () → Applications → Account Groups. Verify the addition of a new account group.

   

4. The REST service can also be called using the Java client. Navigate out of the curl folder and into the java folder. Compile the source files with the following command:

   javac -classpath .:* *.java
   

5. Run the AccountGroups_POST_ToInstance.java class with the following command.

   java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* AccountGroups_POST_ToInstance
   

   If you’re using an older version of Liferay on Java 8, use the following command:

   java -classpath .:* AccountGroups_POST_ToInstance
   

Important

If you’re using an older version of Liferay on Java 8, remove --add-opens java.base/java.net=ALL-UNNAMED in the subsequent sections.

Examine the cURL Command

The AccountGroups_POST_ToInstance.sh script calls the REST service with a cURL command.

curl \
	"http://localhost:8080/o/headless-admin-user/v1.0/account-groups" \
	--data-raw '
		{
			"name": "Foo"
		}' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "[e-mail]:learn"

Here are the command’s arguments:

Arguments	Description
--header "Content-Type: application/json"	Indicates that the request body format is JSON.
--request "POST"	The HTTP method to invoke at the specified endpoint
http://localhost:8080/o/headless-admin-user/v1.0/account-groups	The REST service endpoint
--data-raw '{ "name": "Foo" }	The data you are requesting to post
--user "[e-mail]:learn"	Basic authentication credentials

Note

Basic authentication is used here for demonstration purposes. For production, you should authorize users via OAuth2. See Using OAuth2 to Authorize Users for a sample React application that uses OAuth2.

The other cURL commands use similar JSON arguments.

Examine the Java Class

The AccountGroups_POST_ToInstance.java class adds an account by calling the Account-related service.

public static void main(String[] args) throws Exception {
	AccountGroupResource.Builder builder = AccountGroupResource.builder();

	AccountGroupResource accountGroupResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	AccountGroup accountGroup = accountGroupResource.postAccountGroup(
		new AccountGroup() {
			{
				name = "Foo";
			}
		});

	System.out.println(accountGroup);
}

This class invokes the REST service using only three lines of code:

Line (abbreviated)	Description
AccountGroupResource.Builder builder = ...	Gets a Builder for generating an AccountGroupResource service instance.
AccountGroupResource accountGroupResource = builder.authentication(...).build();	Specifies basic authentication and generates a AccountGroupResource service instance.
AccountGroup accountGroup = accountResource.postAccount(...);	Calls the accountGroupResource.postAccountGroup method and passes the data to post.

Note that the project includes the com.liferay.headless.admin.user.client.jar file as a dependency. You can find client JAR dependency information for all REST applications in the API explorer in your installation at /o/api.

Note

The main method’s comment demonstrates running the class.

The other example Java classes are similar to this one, but call different AccountGroupResource methods.

Important

See AccountGroupResource for service details.

Below are examples of calling other AccountGroup REST services using cURL and Java.

Get Account Groups from Instance

You can list account groups by executing the following cURL or Java command.

AccountGroups_GET_FromInstance.sh

Command:

./AccountGroups_GET_FromInstance.sh

Code:

curl \
	"http://localhost:8080/o/headless-admin-user/v1.0/account-groups" \
	--user "[e-mail]:learn"

AccountGroups_GET_FromInstance.java

Command:

java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* AccountGroups_GET_FromInstance

Code:

public static void main(String[] args) throws Exception {
	AccountGroupResource.Builder builder = AccountGroupResource.builder();

	AccountGroupResource accountGroupResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	System.out.println(
		accountGroupResource.getAccountGroupsPage(
			null, null, Pagination.of(1, 2), null));
}

The Instance’s AccountGroup objects appear in JSON.

Filtering, Paginating, and Sorting Account Groups

This API also accepts parameters to filter, paginate, and sort the account groups. See the getAccountGroupsPage method for more information. You can use the following AccountGroup fields in your queries to filter and sort the results.

• Liferay DXP 2025.Q1+/GA132+customFields
• dateCreated
• dateModified
• name

Filter Query	Description
name eq 'Foo'	The account group name must equal ‘Foo’
customFields/orgSize eq '100.0'	Custom field named orgSize equals 100

Sort Query	Description
dateModified:desc	Sort by dateModified in descending order
name:desc	Sort by name in descending order

Note

You can only use custom fields that don’t contain spaces.

Read API Query Parameters for more information.

Get an Account Group

Get a specific account group with the following cURL or Java command. Replace 1234 with your account group’s ID.

Tip

Use AccountGroups_GET_FromInstance.[java|sh] to get instance AccountGroup IDs.

AccountGroups_GET_ById.sh

Command:

./AccountGroups_GET_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-admin-user/v1.0/account-groups/${1}" \
	--user "[e-mail]:learn"

AccountGroups_GET_ById.java

Command:

java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DaccountGroupId=1234 AccountGroups_GET_ById

Code:

public static void main(String[] args) throws Exception {
	AccountGroupResource.Builder builder = AccountGroupResource.builder();

	AccountGroupResource accountGroupResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	System.out.println(
		accountGroupResource.getAccountGroup(
			Long.valueOf(System.getProperty("accountGroupId"))));
}

The AccountGroup fields appear in JSON.

Put an Account Group

Completely overwrite an existing account group with the following cURL and Java commands. Replace 1234 with your account group’s ID.

AccountGroups_PUT_ById.sh

Command:

./AccountGroups_PUT_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-admin-user/v1.0/account-groups/${1}" \
	--data-raw '
		{
			"name": "Bar"
		}' \
	--header "Content-Type: application/json" \
	--request "PUT" \
	--user "[e-mail]:learn"

AccountGroups_PUT_ById.java

Command:

java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DaccountGroupId=1234 AccountGroups_PUT_ById

Code:

public static void main(String[] args) throws Exception {
	AccountGroupResource.Builder builder = AccountGroupResource.builder();

	AccountGroupResource accountGroupResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	AccountGroup accountGroup = accountGroupResource.putAccountGroup(
		Long.valueOf(System.getProperty("accountGroupId")),
		new AccountGroup() {
			{
				name = "Bar";
			}
		});

	System.out.println(accountGroup);
}

Delete an Account Group

Delete an existing account group with the following cURL and Java commands. Replace 1234 with your account group’s ID.

AccountGroups_DELETE_ById.sh

Command:

./AccountGroups_DELETE_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-admin-user/v1.0/account-groups/${1}" \
	--request "DELETE" \
	--user "[e-mail]:learn"

AccountGroups_DELETE_ById.java

Command

java --add-opens java.base/java.net=ALL-UNNAMED -classpath .:* -DaccountGroupId=1234 AccountGroups_DELETE_ById

Code:

public static void main(String[] args) throws Exception {
	AccountGroupResource.Builder builder = AccountGroupResource.builder();

	AccountGroupResource accountGroupResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	accountGroupResource.deleteAccountGroup(
		Long.valueOf(System.getProperty("accountGroupId")));
}

The API Explorer shows all Account services and schemas and has an interface to try out each service.

Related Topics

• Account Groups
• API Explorer