This section is an overview of each type of object in the Orbit API.

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 Orbit creates new activities for specific members.

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.

Identities are how activities are attached to the correct member.

Identities have the following fields:

Field NameDescriptionRequired
sourceThe 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_hostLocation of the source, such as the host of a Discourse instance (string).No
usernameThe username of the person in the source system (string)Yes (unless email or uid is provided)
emailThe email of the person in the source systemYes (unless username or uid is provided)
uidThe user ID of the person in the sourceYes (unless username or email is provided)
urlFor 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 NameDescriptionRequired
titleA title for the activity (string)Yes
activity_type_keyA 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
descriptionDescription of the activity (string)No
linkURL that links to activity externally (string)No
link_textText for link (string)No
keyA 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 is able to perform read only actions on Organizations so 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.