Common Room Core API (1.0.0)

Download OpenAPI specification:Download

Common Room Core REST APIs for getting data in to Common Room.

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
Create a “New Token"

Authentication

BearerAuth

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

Tokens can be created by room 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"

Contacts

Add or Edit User

Adds a new user into the destination source, or updates existing user previously added via API with the same ID

path Parameters

destinationSourceId

required

integer

The Destination Source ID of the created API signal. See https://www.commonroom.io/docs/signals/custom-integrations/zapier-api/#create-an-api-signal for details.

Request Body schema: application/json

id required	string Unique identifier for the user within this source (identifier unrelated to Common Room). This ID must be unique for each individual user, and should be generated by the third party system you are pulling data from (this ID does not come from 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 contact's "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 contact 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": 0,
"value": {"type": "boolean",
"value": true
}
}
]
}

Response samples

400
429

Content type

application/json

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

Create or update Contact Deprecated

Create or Update a Contact

Request Body schema: application/json

source required	string Source of the information
fullName	string
avatarUrl	string
description	string Contact Bio
	Array of social (object) or email (object)
segment	number Segment Id
company	string Name of the organization the contact is employed at
domain	string Domain of the organization the contact is employed at
title	string Contact's job title
role	string Contact'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 Contact

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 contact custom fields for a room

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 Contact Deprecated

Set an existing Custom Field for a Contact

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 Contact

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 Contact by E-Mail

A Contact's profile based on an email address.

path Parameters

email

required

string <email>

Example: contact@example.commonroom.io

Responses

Response samples

200
404
429

Content type

application/json

[null
]

Anonymize Contact

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

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

path Parameters

email

required

string <email>

Example: contact@example.commonroom.io

Responses

Response samples

200
404
429

Content type

No sample

Get Contact 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 previously added via API with the same activity ID and activity type

path Parameters

destinationSourceId

required

integer

The Destination Source ID of the created API signal. See https://www.commonroom.io/docs/signals/custom-integrations/zapier-api/#create-an-api-signal for details.

Request Body schema: application/json

id required	string Unique identifier for the activity within this source. This ID must be unique for each individual activity, and should be generated by the third party system you are pulling data from (this ID does not come from Common Room). 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": 0,
"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 contact(s) Deprecated

Add an activity to existing contact(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 room

Gets all segments in a room

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 Contact(s) to Segment

Add existing contacts 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 Contact

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

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

path Parameters

email

required

string <email>

Example: contact@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

Contacts

Add or Edit User

path Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Create or update Contact Deprecated

Request Body schema: application/json

Responses

Request samples

Response samples

Add a Note to a Contact

Request Body schema: application/json

Responses

Request samples

Response samples

Gets all contact custom fields for a room

query Parameters

Responses

Response samples

Set an existing Custom Field for a Contact Deprecated

Request Body schema: application/json

Responses

Request samples

Response samples

Adds a new or existing tag to a Contact

Request Body schema: application/json

Responses

Request samples

Response samples

Get Contact by E-Mail

path Parameters

Responses

Response samples

Anonymize Contact

path Parameters

Responses

Response samples

Get Contact 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 contact(s) Deprecated

Request Body schema: application/json

Responses

Request samples

Response samples

Get Activity Types

Responses

Response samples

Segments

Get segments in a room

Responses

Response samples

Gets all status for a segment

Responses

Response samples

Add Contact(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