Common Room Operations Reference

This page covers the parameters and expected output for each operation available in the Common Room integration.

Check API Token Status

Verify that your Common Room API token is valid and retrieve basic details about the associated community.

Input ParametersOutput Parameters

This operation has no input parameters.

Parameter	Description
jti	The unique identifier for the API token.
communityName	The name of the Common Room community associated with the API token.
communityId	The unique identifier of the Common Room community.

Add or Edit User

Add a new contact or update an existing contact in the Common Room.

Input ParametersOutput Parameters

Parameter	Description	Type	Required/Optional
Destination Source Id	The Destination Source ID retrieved from Common Room.	string	. Required.
User	An object containing the contact details: id, email, fullName, firstName, lastName, username, avatarUrl, bio, linkedin, github, twitter, discord, roleAtCompany, titleAtCompany, companyName, companyDomain, country, city, region, rawLocation, tags, and customFields. The id field is mandatory. To add a new user, use any unique identifier. To edit an existing user, use the member ID from the Common Room member profile URL: https://app.commonroom.io/community/<COMMUNITY-ID>-<COMMUNITY-NAME>/member/<MEMBER-ID>-<member-name>.	object	Required.

Returns a status and message confirming whether the user information was accepted for processing.

Get Activity Types

Retrieve the list of activity types available in your Common Room community.

Input ParametersOutput Parameters

This operation has no input parameters.

Returns an activityTypes array. Each item contains the following fields:

Parameter	Description
id	The unique identifier of the activity type. Use this value in the activityType field of the Add or Edit Activity operation.
name	The name of the activity type.
displayName	The human-readable label of the activity type.

Add or Edit Activity

Add a new activity or update an existing activity in Common Room to track community interactions such as forum posts, GitHub contributions, and Slack messages.

Input ParametersOutput Parameters

Parameter	Description	Type	Required/Optional
Destination Source Id	The Destination Source ID retrieved from Common Room.	string	. Required.
Activity	An object containing the activity details. It can include the following parameters: Parameter Description activity.id The unique identifier of the activity in the source system. activity.activityType The type of activity. Must be a valid activity type ID returned by the Get Activity Types operation. activity.user An object representing the user associated with the activity. Must contain an id field. activity.timestamp The date and time the activity occurred, in ISO 8601 format. activity.activityTitle An object representing the title of the activity. activity.content An object representing the content of the activity. activity.url The URL associated with the activity, such as a link to the post or contribution. activity.tags A list of tags to associate with the activity. activity.parentActivity An object representing the parent activity, if this activity is a reply or sub-activity. activity.subSource An object representing the sub-source of the activity within the integration source.	object	Required.

Returns a status and message confirming whether the activity information was accepted for processing.

Get Custom Fields

Retrieve the list of custom fields defined in your Common Room community.

Input ParametersOutput Parameters

Parameter	Description	Type	Required/Optional
Destination Source Id	The Destination Source ID retrieved from Common Room.	string	Optional.

Returns a customFields array. Each item contains the following fields:

Parameter	Description
id	The unique identifier of the custom field.
name	The name of the custom field.
type	The data type of the custom field, such as date, string, int etc.
multivalue	Indicates whether the custom field accepts multiple values.
values	The predefined values for the custom field, if applicable.

Get Segments

Retrieve the list of segments defined in your Common Room community.

Input ParametersOutput Parameters

This operation has no input parameters.

Returns a segments array. Each item contains the following fields:

Parameter	Description
id	The unique identifier of the segment.
name	The name of the segment.

Get Segment Statuses

Retrieve the list of statuses available for a specific segment in your Common Room community.

Input ParametersOutput Parameters

Parameter	Description	Type	Required/Optional
Segment Id	The unique identifier of the segment. Use the id value returned by the Get Segments operation.	integer	Required.

Returns a statuses array. Each item contains the following fields:

Parameter	Description
id	The unique identifier of the segment.
name	The name of the status.

List Tags

Retrieve the list of tags defined in your Common Room community.

Input ParametersOutput Parameters

This operation has no input parameters.

Returns a labels array. Each item contains the following fields:

Parameter	Description
id	The unique identifier of the tag.
name	The name of the tag.
description	The description of the tag.
entityTypes	The entity types the tag applies to.
createdAt	The date and time the tag was created, in ISO 8601 format.
deletedAt	The date and time the tag was deleted, in ISO 8601 format. Returns null if the tag has not been deleted.

Create Tag

Create a new tag in your Common Room community.

Input ParametersOutput Parameters

Parameter	Description	Type	Required/Optional
Name	The name of the tag.	string	Required.
Entity Types	The entity types the tag applies to. Supported values: member activity company	array	Required.
Description	The description of the tag.	string	Optional.

Parameter	Description
id	The unique identifier of the created tag.
name	The name of the tag.
description	The description of the tag.
entityTypes	The entity types the tag applies to.
createdAt	The date and time the tag was created, in ISO 8601 format.
deletedAt	The date and time the tag was deleted, in ISO 8601 format. Returns null if the tag has not been deleted.

Update Tag

Update the name or description of an existing tag in your Common Room community.

Input ParametersOutput Parameters

Parameter	Description	Type	Required/Optional
Tag Id	The unique identifier of the tag to update. Use the id value returned by the Create Tag or List Tags operation.	string	Required.
Name	The updated name of the tag.	string	Required.
Description	The updated description of the tag.	string	Optional.

Parameter	Description
id	The unique identifier of the tag.
name	The name of the tag.
description	The description of the tag.
entityTypes	The entity types the tag applies to.
createdAt	The date and time the tag was created, in ISO 8601 format.
deletedAt	The date and time the tag was deleted, in ISO 8601 format. Returns null if the tag has not been deleted.

Delete Tag

Delete an existing tag from your Common Room community.

Input ParametersOutput Parameters

Parameter	Description	Type	Required/Optional
Tag Id	The unique identifier of the tag to delete. Use the id value returned by the Create Tag or List Tags operation.	string	Required.

Returns a status and message confirming whether the tag was deleted successfully.

Get Tag

Retrieve the details of a specific tag in your Common Room community.

Input ParametersOutput Parameters

Parameter	Description	Type	Required/Optional
Tag Id	The unique identifier of the tag to retrieve. Use the id value returned by the Create Tag or List Tags operation.	string	Required.

Parameter	Description
id	The unique identifier of the tag.
name	The name of the tag.
description	The description of the tag.
entityTypes	The entity types the tag applies to.
createdAt	The date and time the tag was created, in ISO 8601 format.
deletedAt	The date and time the tag was deleted, in ISO 8601 format. Returns null if the tag has not been deleted.

Related pages

• Common Room Integration with Orkes Conductor