Key Concepts

Members

Members represent the people in the community. Members have attributes like name, company, location, tags, and more. Each member is associated with many activities, and many identities.

The Members Overview contains a full list of member properties with their descriptions and data types.

One of name, email, github, or twitter is required when creating a new member.

Identities

An identity represents a profile on a system other than Orbit, such as GitHub, Twitter, a Discourse, an email address, a Slack, a product or external ID, etc. A member can have many identities and more than one of each type (e.g. multiple GitHub profiles or emails).

Identities are how activities are attached to the correct member.

For example, if a new activity is introduced to an Orbit workspace for a Twitter handle, Orbit seeks out a member with that Twitter identity. If a member is found with that Twitter identity then the activity is added to their profile. If a member is not found with that Twitter identity then a new member is created.

Note: In the Orbit product’s UI, we split the concept of identities into two: emails and linked profiles. Linked profiles includes usernames/identifiers from any source that is not email. You'll see these terms on a member's profile page, the member's table, and in the member filter options. This is purely a UI-level difference that helps our non-API users more easily understand and work with identities.

Identities have the following fields:

Field Name	Description	Required
`source`	The source of the identity (`string`). Any one of: `github`, `twitter`, `discourse`, `email`, `linkedin`, `devto` Custom string value can also be supplied, but will not create an attribute on the member (see below).	Yes
`source_host`	Location of the source, such as the host of a Discourse instance (`string`).	No
`username`	The username of the person in the source system (`string`)	Yes (unless `email` or `uid` is provided)
`email`	The email of the person in the source system	Yes (unless `username` or `uid` is provided)
`uid`	The user ID of the person in the source	Yes (unless `username` or `email` is provided)
`url`	For custom identities, a link to the profile on the source (`string`)	No

A member's identities are returned and displayed in the order they were attached to the member.

Identity-related member attributes

The following member attributes are shortcut methods to values in the identities:

member.github: the username of the first github_identity
member.twitter: the username of the first twitter_identity
member.linkedin: the username of the first linkedin_identity
member.devto: the username of the first devto_identity
member.email: the email of the first email_identity

Member attributes as shortcuts are only available for first-party identities that are a single global platform (i.e. GitHub, Twitter, etc.) and not for either custom identities or networks that exist as specific instances (Discourse, Slack, etc.) where there could be many workspaces of the same network for a single member.

Activities

Activities are instances of community participation and contribution, such as GitHub issues, pull requests, Discourse posts, mentions on Twitter, and more. Orbit integrations come with built-in activities but you can also add your own.

Currently only creating "custom" activities is supported by the Orbit API. If you want to create GitHub/Twitter/Discourse activities use their respective integrations.

A custom activity is one that does not have an Orbit pre-defined activity type.

The information about the activity type is supplied for each activity using the following attributes:

Activities have the following fields:

Field Name	Description	Required
`title`	A title for the activity (`string`)	Yes
`activity_type_key`	A unique type of activity. Recommend the following format: `source:activity`, e.g. `tweet:sent` (`string`). Custom activities can be provided, e.g. `conference:attended`.	Yes
`description`	Description of the activity (`string`)	No
`link`	URL that links to activity externally (`string`)	No
`link_text`	Text for `link` (`string`)	No
`key`	A unique identifier for the activity (`string`) If not provided, Orbit generates a random ID. The API will only create one activity for each `key`. Subsequent `POST` requests for the same `key` will be ignored.	No

Organizations

An Organization represents a company that is present in your community and can have many members associated with it. Members are associated with an Organization based on their email address but it is also possible to manually associate members with an Organization from their member profile within the Orbit app.

Currently, the Orbit API supports the ability for you to identify an organization as a customer.

Otherwise, you can perform read only actions on Organizations so that you can extract the data for use elsewhere. From the /organizations endpoint you can return all of the Organizations that exist in your workspace, get a single Organization, list all of the Members associated with an Organization, and get all of the activities performed by Members associated with a particular Organization.

Notes

A member's notes are free-form areas to attach information to a member's profile. Notes support markdown.