Common Room Core API (1.0.0)

Download OpenAPI specification:Download

Common Room Community REST APIs for accessing Community scoped resources.

For SCIM APIs see the SCIM documentation.

To use the Common Room API, or get started with the Common Room Zapier integration, you will need to create an API token. To create an API token:

Navigate to Setting | API tokens
Click on “Request Access to API”. Our API is currently in beta, so you need to first apply for access.
Once access is granted, return to the Settings | API tokens screen, and you will see a button to create a “New Token”.

Authentication

BearerAuth

Use a Community API JWT as a Bearer token in the Authentication header.

Tokens can be created by Community Owners through https://app.commonroom.io/

Example:

curl -H "Authorization: Bearer abcd123.xzy" \
  https://api.commonroom.io/community/v1

Security Scheme Type	HTTP
HTTP Authorization Scheme	bearer
Bearer format	"JWT"

Members

Add or Edit User

Adds a new user into the destination source, or updates existing user matching the id

path Parameters

destinationSourceId

required

integer

The Destination Source ID of the created API source. See https://docs.commonroom.io/get-started/integrations/zapier-api#create-an-api-source for details.

Request Body schema: application/json

id required	string Unique identifier for the user within this source (identifier unrelated to Common Room). Used as the primary key for this user within this source, to group all the user's activity together.
fullName	string or null The full name of the user.
firstName	string or null The first name of the user. Used if no full name given.
lastName	string or null The last name of the user. Used if no full name given.
username	string or null The username the user.
avatarUrl	string or null The url for the users avatar.
bio	string or null The biography for the user, to be used in the members "About" section.
email	string or null <email> The email for the user, used to help enrich details about the person.
	object or null Information about the users LinkedIn account
	object or null Information about the users Github account
	object or null Information about the users Twitter account
	object or null Information about the users Discord account, taken from the form username#discriminator
	Array of objects or null An optional list of known external profiles.
roleAtCompany	string or null The users role at their company, such as Engineering, Marketing, Sales
titleAtCompany	string or null The users title at their company
companyName	string or null The name of the users company
companyDomain	string or null The web domain of the users company
country	string or null The country the user resides in
city	string or null The city the user resides in
region	string or null The state, prefecture or region the user resides in, such as Washington, New York, Ontario, New South Whales
rawLocation	string or null Loose description of a location to be interpreted, such as 'Seattle, WA', USA, Kyiv, Ukraine, Hong Kong
	Array of objects (ApiTagAssignment) Optional list of member tags to assign to this user
	Array of objects (ApiCustomFields) Optional list of custom fields to update for this user

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"fullName": "string",
"firstName": "string",
"lastName": "string",
"username": "string",
"avatarUrl": "string",
"bio": "string",
"email": "user@example.com",
"linkedin": {"type": "handle",
"value": "in/person"
},
"github": {"type": "handle",
"value": "Person"
},
"twitter": {"type": "handle",
"value": "@Person"
},
"discord": {"type": "username",
"username": "person",
"discriminator": 1234
},
"externalProfiles": [{"url": "string",
"name": "string"
}
],
"roleAtCompany": "Engineering",
"titleAtCompany": "string",
"companyName": "Common Room",
"companyDomain": "commonroom.io",
"country": "string",
"city": "string",
"region": "Washington",
"rawLocation": "Seattle, WA",
"tags": [{"type": "id",
"id": "string"
}
],
"customFields": [{"id": "string",
"value": {"type": "boolean",
"value": true
}
}
]
}

Response samples

400
429

Content type

application/json

{"reason": "string",
"docs": "string"
}

Create or update Community Member Deprecated

Create or Update a Community Member

Request Body schema: application/json

source required	string Source of the information
fullName	string
avatarUrl	string
description	string Member Bio
	Array of social (object) or email (object)
segment	number Segment Id
company	string Name of the organization member is employed at
domain	string Domain of the organization member is employed at
title	string Member's job title
role	string Member's job category
	object Geographical data for the user

Responses

Request samples

Payload

Content type

application/json

{"source": "string",
"fullName": "Greg",
"avatarUrl": "https://img.example.com/profile/zyx.png",
"description": "string",
"socials": [{"type": "github",
"value": {"handle": "string"
}
}
],
"segment": 0,
"company": "Common Room",
"domain": "commonroom.io",
"title": "CFO",
"role": "Finance",
"location": {"city": "San Francisco",
"region": "California",
"country": "United States of America"
}
}

Response samples

400
429

Content type

application/json

{"reason": "string",
"docs": "string"
}

Add a Note to a Community Member

Request Body schema: application/json

socialType	string Must be email, twitter, github, or linkedin
value	string Value corresponding to socialType
note	string Note content

Responses

Request samples

Payload

Content type

application/json

{"socialType": "email",
"value": "email@domail.com",
"note": "string"
}

Response samples

400
429

Content type

application/json

{"reason": "string",
"docs": "string"
}

Gets all member custom fields for a community

query Parameters

destinationSourceId

string

If a value is provided provided, the API will only return custom fields that can be written to by the specified destination source

Responses

Response samples

200

Content type

application/json

[{"id": 12345,
"name": "Preferred programming language",
"type": "enum",
"multivalue": false,
"values": ["Python"
]
}
]

Set an existing Custom Field for a Community Member Deprecated

Set an existing Custom Field for a Community Member

Request Body schema: application/json

One of

socialType	string Must be email, twitter, github, or linkedin
value	string Value corresponding to socialType
customFieldId	number ID of the custom field to set
	object

Responses

Request samples

Payload

Content type

application/json

Example

{"socialType": "email",
"value": "email@domail.com",
"customFieldId": 12345,
"customFieldValue": {"type": "boolean",
"value": true
}
}

Response samples

400
429

Content type

application/json

{"reason": "string",
"docs": "string"
}

Adds a new or existing tag to a Community Member

Request Body schema: application/json

socialType	string Must be email, twitter, github, or linkedin
value	string Value corresponding to socialType
tags	string Comma separated list of tags

Responses

Request samples

Payload

Content type

application/json

{"socialType": "email",
"value": "email@domail.com",
"tags": "tag1, tag2, tag3"
}

Response samples

400
429

Content type

application/json

{"reason": "string",
"docs": "string"
}

Get Community Member by E-Mail

A Community Member's profile based on an email address.

path Parameters

email

required

string <email>

Example: member@example.commonroom.io

Responses

Response samples

200
404
429

Content type

application/json

[null
]

Anonymize Community Member

Request removal of all personally identifiable information (PII) for the Community Member associated by this email address.

This does not immediately anonymize the community member. The anonymization is queued and will happen at a future time within 15 days.

path Parameters

email

required

string <email>

Example: member@example.commonroom.io

Responses

Response samples

200
404
429

Content type

No sample

Get Community Member By E-Mail or Socials

query Parameters

twitter	string Example: twitter=twitterHandle
email	string Example: email=email@domain.com
github	string Example: github=githubHandle
linkedin	string Example: linkedin=in/username

Responses

Response samples

200
429

Content type

application/json

[{"fullName": "Greg",
"activities_count": 0,
"avatar": "string",
"bio": "string",
"organization": "string",
"title": "string",
"first_seen": "string",
"last_active": "string",
"location": { },
"member_tags": [ ],
"segments": [{"id": 0,
"name": "string"
}
],
"url": "string",
"twitter": "string",
"github": "string",
"linkedin": "string",
"discord": "string",
"youtube": "string",
"common_room_member_url": "string",
"custom_fields": [{"name": "string",
"type": "boolean",
"value": true
}
]
}
]

Activities

Add or Edit Activity

Adds new activity into the destination source, or updates existing activity matching the id & activity type

path Parameters

destinationSourceId

required

integer

The Destination Source ID of the created API source. See https://docs.commonroom.io/get-started/integrations/zapier-api#create-an-api-source for details.

Request Body schema: application/json

id required	string Unique identifier for the activity within this source. Used to deduplicate and keep the latest values for a given activity when combined with the activityType.
activityType required	string Type of activity being added or edited. Check /activityTypes route for accepted values. Used to deduplicate and keep the latest values for a given activity when combined with the id.
required	object (ApiUser) Information about a user. Provide as many fields as possible to enable better matching and merging into a single Common Room profile.
	object or null An optional title to use when rendering the activity. Useful for things like a post title, merge request title, etc.
	object or null Optional content to display when rendering the activity, used to hold a message which was posted or information about what occurred.
timestamp	string <date-time> Time the activity occurred, current UTC time is used if not supplied
url	string or null URL pointing to the activity on a third party source, allows linking from Common Room to the source activity
	Array of objects (ApiTagAssignment) Optional list of activity tags to assign to this activity
	object or null Optional field which allows for "conversational threading", structuring activities as nested, associated with or in reply to another activity.
	object or null Optional "sub source" the activity took place in. This allows further sub-dividing the sources data into third-party concepts like a slack channel, github repository or meetup group. Common examples include a slack channel name, meetup group hosting an event, a github repo an issue was created in.

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"activityType": "string",
"user": {"id": "string",
"fullName": "string",
"firstName": "string",
"lastName": "string",
"username": "string",
"avatarUrl": "string",
"bio": "string",
"email": "user@example.com",
"linkedin": {"type": "handle",
"value": "in/person"
},
"github": {"type": "handle",
"value": "Person"
},
"twitter": {"type": "handle",
"value": "@Person"
},
"discord": {"type": "username",
"username": "person",
"discriminator": 1234
},
"externalProfiles": [{"url": "string",
"name": "string"
}
],
"roleAtCompany": "Engineering",
"titleAtCompany": "string",
"companyName": "Common Room",
"companyDomain": "commonroom.io",
"country": "string",
"city": "string",
"region": "Washington",
"rawLocation": "Seattle, WA",
"tags": [{"type": "id",
"id": "string"
}
],
"customFields": [{"id": "string",
"value": {"type": "boolean",
"value": true
}
}
]
},
"activityTitle": {"type": "text",
"value": "string"
},
"content": {"type": "text",
"value": "string"
},
"timestamp": "2019-08-24T14:15:22Z",
"url": "string",
"tags": [{"type": "id",
"id": "string"
}
],
"parentActivity": {"id": "string",
"activityType": "string"
},
"subSource": {"type": "name",
"name": "slack-channel-1"
}
}

Response samples

400
429

Content type

application/json

{"reason": "string",
"docs": "string"
}

Add an activity to existing community member(s) Deprecated

Add an activity to existing community member(s) with matching socials

Request Body schema: application/json

source required	string Source of the information
socialType required	string Must be email, twitter, github, or linkedin
value required	string Value corresponding to socialType
activityType required	object ActivityType. Use the GetActivityType API to get a list of types
activityBody required	string
occurredAt	string Date when the activity occurred in ISO 8601 format
tags	string Comma separated string of tags to apply to the activity

Responses

Request samples

Payload

Content type

application/json

{"source": "string",
"socialType": "email",
"value": "email@domail.com",
"activityType": "link",
"activityBody": "string",
"occurredAt": "2021-08-19T05:43:45.677Z",
"tags": "Tag1, Tag2"
}

Response samples

400
429

Content type

application/json

{"reason": "string",
"docs": "string"
}

Get Activity Types

Gets all activity types

Responses

Response samples

200
429

Content type

application/json

[{"id": "started_training",
"displayName": "Started training",
"name": "started_training"
}
]

Segments

Get segments in a community

Gets all segments in a community

Responses

Response samples

200
429

Content type

application/json

[{"id": 0,
"name": "string"
}
]

Gets all status for a segment

Responses

Response samples

200
429

Content type

application/json

[{"id": 0,
"name": "string"
}
]

Add Community Member(s) to Segment

Add existing community members to an existing segment

Request Body schema: application/json

socialType required	string Must be email, twitter, github, or linkedin
value required	string Comma separated list of values corresponding to socialType
statusId	number

Responses

Request samples

Payload

Content type

application/json

{"socialType": "email",
"value": "email@domail.com, email2@domain.org",
"statusId": 1234
}

Response samples

400
429

Content type

application/json

{"reason": "string",
"docs": "string"
}

Add a Note to a Segment

Request Body schema: application/json

segmentId	number
note	string Note content

Responses

Request samples

Payload

Content type

application/json

{"segmentId": 12345,
"note": "string"
}

Response samples

400
429

Content type

application/json

{"reason": "string",
"docs": "string"
}

Right to be Forgotten

Anonymize Community Member

Request removal of all personally identifiable information (PII) for the Community Member associated by this email address.

This does not immediately anonymize the community member. The anonymization is queued and will happen at a future time within 15 days.

path Parameters

email

required

string <email>

Example: member@example.commonroom.io

Responses

Response samples

200
404
429

Content type

No sample

API Token status information

Status information about the API token used in the request.

Responses

Response samples

200
403
429

Content type

application/json

{"jti": "tcpgph92",
"communityName": "Uncommon",
"communityId": "8p980hdo0"
}

name required	string Name of the tag
description	string or null Optional description of the tag
entityTypes required	Array of strings Items Enum: "member" "activity" "company" The list of entity types the tag may be assigned to

name required	string Name of the tag
description	string or null Optional description of the tag

Common Room Core API (1.0.0)

Authentication

BearerAuth

Members

Add or Edit User

path Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Create or update Community Member Deprecated

Request Body schema: application/json

Responses

Request samples

Response samples

Add a Note to a Community Member

Request Body schema: application/json

Responses

Request samples

Response samples

Gets all member custom fields for a community

query Parameters

Responses

Response samples

Set an existing Custom Field for a Community Member Deprecated

Request Body schema: application/json

Responses

Request samples

Response samples

Adds a new or existing tag to a Community Member

Request Body schema: application/json

Responses

Request samples

Response samples

Get Community Member by E-Mail

path Parameters

Responses

Response samples

Anonymize Community Member

path Parameters

Responses

Response samples

Get Community Member By E-Mail or Socials

query Parameters

Responses

Response samples

Activities

Add or Edit Activity

path Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Add an activity to existing community member(s) Deprecated

Request Body schema: application/json

Responses

Request samples

Response samples

Get Activity Types

Responses

Response samples

Segments

Get segments in a community

Responses

Response samples

Gets all status for a segment

Responses

Response samples

Add Community Member(s) to Segment

Request Body schema: application/json

Responses

Request samples

Response samples

Add a Note to a Segment

Request Body schema: application/json

Responses

Request samples

Response samples

Tags

List Tags