Page tree
Skip to end of metadata
Go to start of metadata

Use the REST API to automate Approvals within your organisations Confluence system.

Recommendation

It's recommended to use the 'Page Approval' feature when scripting - the Macro instances require a Macro ID (unique to the page version) and UUID (unique to macro across page versions) in addition to the Page ID and Page Version - making them more complicated to script, unless you already know the UUID and have access to the Wiki Markup of the page to determine the value of the Macro ID.


Search Approvals by Member

Search by Approval Member Status

Path/rest/approvalmacro/1.0/search/all
MethodGET
Query Parameters
status"pending", "approved", "rejected" or "expired"Optional - will search "pending" and "expired" by if not provided
userNamee.g. ff80808160e8c8810160e8d6a1210000Optional - will search your User if not provided
spaceKeye.g. ABCOptional - will search all if not provided
Response Body
Search Approvals Response
{
	"type": "macro",
	"title": "Yes",
	"spaceKey": "T1",
	"status": "pending",
	"pageId": 819206,
	"pageTitle": "avc",
	"pageVersion": 2,
	"creatorUsername": "admin",
	"updatorUsername": "admin"
	"createdOn": 1550521247694,
	"updatedOn": 1550521280029,
	"creator": "ff80808160e8c8810160e8d6a1210000",
	"creatorDisplayName": "Janet Plum",
	"creatorProfilePicture": "/confluence/download/attachments/65573/user-avatar",
	"updator": "ff80808160e8c8810160e8d6a1210000",
	"updatorDisplayName": "Janet Plum",
	"updatorProfilePicture": "/confluence/download/attachments/65573/user-avatar",
	"members": [  
		{
			"approvalId": 2,
			"userKey": "ff80808160e8c8810160e8d6a1210000",
			"status": "pending",
			"date": 1550521280031,
			"avatarUrl": "/confluence/download/attachments/65573/user-avatar",
			"displayName": "Janet Plum",
			"username": "admin"
		}
	]
}

Search Approvals by Creator/Updater

Search by Approval Creator or Updater.

Path/rest/approvalmacro/1.0/search/meta
MethodGET
Query Parameters
status"pending", "approved", "rejected" or "expired"Optional - will search "pending" and "expired" by if not provided
userNamee.g. ff80808160e8c8810160e8d6a1210000Optional - will search your User if not provided
spaceKeye.g. ABCOptional - will search all if not provided
Response Body
Search Approvals Response
{
	"type": "macro",
	"title": "Yes",
	"spaceKey": "T1",
	"status": "pending",
	"pageId": 819206,
	"pageTitle": "avc",
	"pageVersion": 2,
	"creatorUsername": "admin",
	"updatorUsername": "admin"
	"createdOn": 1550521247694,
	"updatedOn": 1550521280029,
	"creator": "ff80808160e8c8810160e8d6a1210000",
	"creatorDisplayName": "Janet Plum",
	"creatorProfilePicture": "/confluence/download/attachments/65573/user-avatar",
	"updator": "ff80808160e8c8810160e8d6a1210000",
	"updatorDisplayName": "Janet Plum",
	"updatorProfilePicture": "/confluence/download/attachments/65573/user-avatar",
	"members": [  
		{
			"approvalId": 2,
			"userKey": "ff80808160e8c8810160e8d6a1210000",
			"status": "pending",
			"date": 1550521280031,
			"avatarUrl": "/confluence/download/attachments/65573/user-avatar",
			"displayName": "Janet Plum",
			"username": "admin"
		}
	]
}

Page Approval

Get Page Approval Details

Get Page Approval Details, including member status and settings.

Path/rest/approvalmacro/1.0/approval
MethodPOST
Request Body
Macro Approval Request Body
{
	"type": 	"page",		// Type = Macro
	"pageId": 	786462,		// The Confluence Page ID
	"version": 	1			// The Confluence Page Version
}
Response Body
Macro Approval Response
{
	"type": 				"page",
	"creatorUsername":		"ff80808160e8c8810160e8d6a1210000",
	"pageId":				786462,
	"title":				"Test",
	"requestNotifications":	true,
	"statusNotifications":	true,
	"expireOnEdit":			false,
	"quorumSize":			0,
	"postCommentsEnabled":	false,
	"members": [
		{
			"approvalId":	14,
			"userKey":		"ff80808160e8c8810160e8d6a1210000",
			"status":		"approved",
			"date":			1550055298599,
			"avatarUrl":	"/confluence/download/attachments/65573/user-avatar",
			"displayName":	"John"
		}
	],
	"version":		1,
	"superseded":	false
}
Possible Errors
  • 404
    • No Page exists as provided
    • No Page Version exists as provided
    • No Approvals for Confluence Record exists as provided
  • 401
    • Anonymous User
    • No Permissions on the Space (Space Permissions)
    • No Permissions on the Page (Page Restrictions)
  • 400
    • Invalid JSON

See response body (JSON) for detailed error information.

Create or Update a Page Approval

Create or update a Page Approval (e.g. change members or settings).

Updating an existing Approval will invalidate any current approved statuses.

Path/rest/approvalmacro/1.0/approval/page
MethodPUT
Request Body
Create/Update Page Approval Request Body
{
	"title":	"Test Space Home",
	"members":	["ff80808160e8c8810160e8d6a1210000"],
	"pageId":"2621443",
	"requestNotificationsEnabled":true,
	"statusNotificationsEnabled":true,
	"expiryDate":"", // YYYY-MM-DD or empty string
	"quorumSize":0
}
Response
  • 200 OK
Response Body
Create/Update Page Approval Response Body
{
	"type": 				"page",
	"creatorUsername":		"ff80808160e8c8810160e8d6a1210000",
	"pageId":				786462,
	"title":				"Test",
	"requestNotifications":	true,
	"statusNotifications":	true,
	"expireOnEdit":			false,
	"quorumSize":			0,
	"postCommentsEnabled":	false,
	"members": [
		{
			"approvalId":	14,
			"userKey":		"ff80808160e8c8810160e8d6a1210000",
			"status":		"approved",
			"date":			1550055298599,
			"avatarUrl":	"/confluence/download/attachments/65573/user-avatar",
			"displayName":	"John"
		}
	],
	"version":		1,
	"superseded":	false
}
Possible Errors
  • 404
    • No Page exists as provided
    • No Page Version exists as provided
    • No Approvals for Confluence Record exists as provided
  • 401
    • Anonymous User
    • No Permissions on the Space (Space Permissions)
    • No Permissions on the Page (Page Restrictions)
  • 400
    • Invalid Request - e.g. trying to change an old page version
    • Invalid JSON

See response body (JSON) for detailed error information.

Approve/Reject a Page Approval

Approve or Reject the specified Page Approval under the current User.

Path/rest/approvalmacro/1.0/approval/action
MethodPOST
Request Body
Macro Approval Action Request Body
{
	"type":		"page",
	"action":	"rejected", 	// "rejected" or "approved"
	"pageId":	786462, 		// The Confluence Page ID
	"version":	1				// The Confluence Page Version
}
Response
  • 200 OK
Possible Errors
  • 404
    • No Page exists as provided
    • No Page Version exists as provided
    • No Approvals for Confluence Record exists as provided
  • 401
    • Anonymous User
    • No Permissions on the Space (Space Permissions)
    • No Permissions on the Page (Page Restrictions)
  • 400
    • Invalid Request - e.g. trying to change an old page version
    • Invalid JSON

See response body (JSON) for detailed error information.

Macro Approval

Get Approval Macro Details

Get Macro Details, including member status and settings.

Path/rest/approvalmacro/1.0/approval
MethodPOST
Request Body
Macro Approval Request Body
{
	"type": 	"macro",								// Type = Macro
	"pageId": 	786462,									// The Confluence Page ID
	"macroId":	"23e21970-43d6-4411-aca6-49043737e2ba", // Stored in the Wiki Markup (Unique to Page Version)
	"uuid":"	f5c54fa2-a6ec-433f-afbb-877b9d05fb3d", 	// Unique Identifier stored in Macro Parameters
	"version": 	1										// The Confluence Page Version
}
Response Body
Macro Approval Response
{
	"type": 				"macro",
	"creatorUsername":		"ff80808160e8c8810160e8d6a1210000",
	"pageId":				786462,
	"macroId":				"23e21970-43d6-4411-aca6-49043737e2ba",
	"title":				"Test",
	"requestNotifications":	true,
	"statusNotifications":	true,
	"expireOnEdit":			false,
	"quorumSize":			0,
	"postCommentsEnabled":	false,
	"members": [
		{
			"approvalId":	14,
			"userKey":		"ff80808160e8c8810160e8d6a1210000",
			"status":		"approved",
			"date":			1550055298599,
			"avatarUrl":	"/confluence/download/attachments/65573/user-avatar",
			"displayName":	"John"
		}
	],
	"version":		1,
	"uuid":			"f5c54fa2-a6ec-433f-afbb-877b9d05fb3d",
	"superseded":	false
}
Possible Errors
  • 404
    • No Page exists as provided
    • No Page Version exists as provided
    • No Approvals for Confluence Record exists as provided
  • 401
    • Anonymous User
    • No Permissions on the Space (Space Permissions)
    • No Permissions on the Page (Page Restrictions)
  • 400
    • Invalid JSON

See response body (JSON) for detailed error information.

Approve/Reject a Macro Approval

Approve or Reject the specified Macro Approval under the current User.

Path/rest/approvalmacro/1.0/approval/action
MethodPOST
Request Body
Macro Approval Action Request Body
{
	"type":		"macro",
	"action":	"rejected", 							// "rejected" or "approved"
	"pageId":	786462, 								// The Confluence Page ID
	"macroId":	"23e21970-43d6-4411-aca6-49043737e2ba",	// Macro ID stored in the Wiki Markup (Unique to Page Version)
	"uuid":		"f5c54fa2-a6ec-433f-afbb-877b9d05fb3d",	// Unique Identifier stored in Macro Parameters
	"version":	1										// The Confluence Page Version
}
Response
  • 200 OK
Possible Errors
  • 404
    • No Page exists as provided
    • No Page Version exists as provided
    • No Approvals for Confluence Record exists as provided
  • 401
    • Anonymous User
    • No Permissions on the Space (Space Permissions)
    • No Permissions on the Page (Page Restrictions)
  • 400
    • Invalid Request - e.g. trying to change an old page version
    • Invalid JSON

See response body (JSON) for detailed error information.

Settings

Get System Settings

Obtain the Global Settings (like terminology and whether features are enabled.

Path/rest/approvalmacro/1.0/settings/system
MethodGET
Response Body
System Settings Response Body
{
	"enabled":				true,
	"notificationsInApp":	true,
	"notificationsEmail":	true,
	"pendingText":			"Pending",
	"approvedText":			"Approved",
	"rejectedText":			"Rejected",
	"expiredText":			"Expired",
	"createApprovalGroups":	[] // List of Groups
}
Response Status

200 - OK

401 - Not a Confluence Administrator

Get Space Settings

Get the settings for a particular Space.

Path/rest/approvalmacro/1.0/settings/space?key=<SPACE KEY>
MethodGET
Response Body
System Settings Response Body
{
	"spaceId":		2785281,
	"enabled":		true,
	"pendingText":	"Pending (1)",
	"approvedText":	"Approved (2)",
	"rejectedText":	"Rejected (3)",
	"expiredText":	"Expired (4)",
	"createApprovalGroups":
		[
			"confluence-administrators",
			"confluence-users"
		],
	"teams":[],
	"override":false
}
Response Status

200 - OK

401 - Not a Confluence Administrator

Get Consolidated Settings

Get the settings for a particular Space and merge this with the Global Settings to get the correct values (when system settings should override Space ones etc.).

Path/rest/approvalmacro/1.0/settings/consolidated?key=<SPACE KEY>
MethodGET
Response Body
System Settings Response Body
{
	"spaceId":		2785281,
	"enabled":		true,
	"pendingText":	"Pending (1)",
	"approvedText":	"Approved (2)",
	"rejectedText":	"Rejected (3)",
	"expiredText":	"Expired (4)",
	"createApprovalGroups":
		[
			"confluence-administrators",
			"confluence-users"
		],
	"teams":[],
	"override":false
}
Response Status

200 - OK

401 - Not a Confluence Administrator

Teams (in Space)

Create or Update Team

Create a Team, or update an existing one, inside a Space:

Path/rest/approvalmacro/1.0/settings/team?key=<SPACE KEY>
MethodPOST
Response Body
System Settings Response Body
{
	"id":39,										// If updating a Team, specify the ID, otherwise do not.
	"name":"Team Alpha",
	"description":"Avengers Assemble!",
	"members":[
		"ff80808160e8c8810160e8d6a1210000" 			// List of User Keys
	]
}
Response Status

200 - OK

401 - Not a Space Administrator

Delete Team

Delete a team, inside a Space:

Path/rest/approvalmacro/1.0/settings/team?id=<TEAM ID>
MethodDELETE
Response Status

200 - OK

401 - Not a Space Administrator

Maintenance

You should only use the maintenance features when you are experiencing an issue with the App - a better course of action is to contact the support team.

Remove Invalid Approval Entries

Perform maintenance on the Approvals for Confluence database table.

Note this can take a long time depending on how many Approvals are in your database.

Path/rest/approvalmacro/1.0/settings/maintenance
MethodPOST
Response Status

200 - OK

401 - Not a Confluence Administrator

Reset Current User In-App Notifications

Remove all of the current users In-App Notification items:

Path/rest/approvalmacro/1.0/settings/reset-my-notifications
MethodPOST
Response Status

200 - OK

401 - Not Logged In

Reset All In-App Notifications

Remove all Approval In-App Notifications, as a Confluence Administrator:

Path/rest/approvalmacro/1.0/settings/reset-all-notifications
MethodPOST
Response Status

200 - OK

401 - Not a Confluence Administrator

  • No labels