API Reference
Automate your team's workflows with Range
The Range API allows you to build applications and tools that interact with Range to support custom workflows and organization specific needs. The API provides a JSON-REST interface to Range resources, starting with Users, Teams, and Check-ins (aka Updates).
Users within Range are organized into a directory of purpose oriented teams. This hierarchy of teams is used to determine which updates different people see. It also provides a valuable reflection of the real working relationships within an organization, which are often cross-functional and not discernible from traditional org charts.
We follow a use-case based approach to developing and expanding this API, so please share feedback on your experiences with the API and functionality you would like to see. love your feedback on this initial API and anything you'd like to see in the future.
Authentication #
Range can authenticate your requests using API keys. Keys are associated with a user account and can execute requests on behalf of that user.
API keys can be created by visiting your developer settings and can be passed using basic authentication. Use your API key as the username, leave password blank. For example:
curl https://api.range.co/v1/teams -u $API_KEY:
Your API keys carry the same privileges as your user account, so keep them secure! An admin's API keys will have different capabilities to a standard user account. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
All API requests must be made over HTTPS with TLS1.2 or higher. Calls made over plain HTTP will fail. API requests without authentication will also fail.
OAuth #
Range also supports OAuth bearer tokens.
If you wish to authenticate an app on behalf of other users, OAuth is a mechanism for requesting tokens with the approval of the end user. OAuth Apps can be scoped to a specific workspace or configured to work for any Range user.
At this time, OAuth Apps are operating in a closed program. If you would like to build an app for your team, or build a first-class integration, then please reach out to our support teamand we'll be happy to get you started.
Request Format #
Payloads
The payloads for PUT and POST requests should be Content-Type: application/json. Form encoded data is partially supported, but not recommended. Response payloads will always be JSON.
Date and Time
All dates and times are in UTC and specified in ISO8601 format, for example 2006-01-02T15:04:05.999Z, and match JavaScript's implementation of toISOString(). In the API reference they are demarked with the Time type.
Partial Updates
Endpoints for updating entities support partial updates. Leave fields as undefined that you don't want to change, falsish values such as "" and 0 will erase the field.
Software Development Kits
Our intent is to support libraries for major languages. If you would like to contribute support for a new language please get in touch.
- Node.js
- Go (coming soon)
- Python (coming soon)
Capturing Activity
One of the main ways Range integrates with other software is by pulling in activity, such as documents edited, commits made, or tasks completed. This activity shows in the sidebar and users can then easily add the activity to their check-in.
For tools that aren't natively supported by Range or the Range Chrome Extension, you can easily build a small integration that records activity on behalf of your teammates.
To get started, refer to the RecordInteraction RPC below.
RPC: List Teams #
Request a list of teams associated with an organization or a user.
GET /v1/teams
GET /v1/users/{user_id}/teams
Arguments:
user_id ?string
if specified, return this user’s teams
include_archived bool
include_following bool
Returns:
teams []Team
all associated teams
users []UserRef
followers and members referenced by teams
related_teams []TeamRef
parents and children of the teams
RPC: Read Team #
Fetch data about a team, related users, and related teams.
GET /v1/teams/{team_id}Arguments:
team_id string
Returns:
team Team
users []UserRef
users directly related to this team
parent_teams []TeamRef
list of ancestors, order from root of org
child_teams []TeamRef
all descendant teams
RPC: Create Team #
Start a new team or subteam.
POST /v1/teams
Arguments:
parent_id string
team to use as the parent, empty for root team
slug string
unique path identifier to go in URLs
name string
the team’s name
description string
the team's charter or purpose
mascot string
an emoji-one code for thye team, e.g. :bear:
Returns:
. Team
RPC: Update Team Relation #
Make a user join or follow a team, or update their role.
PUT /v1/teams/{team_id}/relations/{user_id}Arguments:
team_id string
user_id string
Returns:
. TeamRelation
RPC: Delete Team Relation #
Leave a team or stop following it.
DELETE /v1/teams/{team_id}/relations/{user_id}Arguments:
team_id string
user_id string
Returns:
success bool
RPC: List Users #
Looks up a user by their Range user id.
GET /v1/orgs/{org_id}/usersArguments:
team_id string
Users in this team
user_ids []string
Explicit set of users to fetch data for
for_user_id []string
Users on teams this user is a member of or who follows
limit uint32
Default to zero, meaning no limit
Returns:
users []User
RPC: Read User #
Looks up a user by their Range user id.
GET /v1/users/{user_id}Arguments:
user_id string
Returns:
. User
RPC: Update User Profile #
Update the profile portion of a user entity. Non-admins may only update their own profile.
PUT /v1/users/{user_id}/profileArguments:
user_id string
profile UserProfile
Full or partial user profile
Returns:
. UserProfile
The full user profile
RPC: Update User State #
Update the state portion of a user entity. Only admins may update state properties.
PUT /v1/users/{user_id}/stateArguments:
user_id string
state UserState
Full or partial user state
Returns:
. UserState
The full user state
RPC: Auth User #
Looks up the user who owns the API key.
GET /v1/users/auth-user
Arguments:
Returns:
user User
org Org
RPC: Find User #
Looks up a Range user account via email or a linked identity on another service.
GET /v1/users/find
Arguments:
email ?string
plain text email address
email_hash ?string
lower(sha1(email))
provider ?string
which integration provider to lookup
provider_id ?string
the accounts ID on provider
include_refs bool
whether to include the user object
allow_inactive bool
whether to include deactivated users
allow_pending bool
whether to include newly invited users
Returns:
user_id string
user User
if include_ref == true
RPC: List Updates #
Request a list of updates (check-ins) associated with a user, team, or organization.
GET /v1/updates
Arguments:
target_id ?string
if specified, fetch updates by this user, team, or organization
for_user_id ?string
used instead of target_id to fetch updates from a user's teammates
before ?Time
only fetch updates before this time
after ?Time
only fetch updates after this time
count ?int
limit the number of updates returned
ascending bool
whether to order oldest first
use_client_offset bool
whether to localize each update's time such that the request is for a specific calendar day relative to the author
include_child_teams bool
if target_id is a team, then also include updates from descendent teams
include_refs bool
whether to return snippets, attachments, and users
Returns:
updates []Update
the updates
snippets []Snippet
line items referenced by the updates
attachments []Attachment
attachments from integrations, referenced by snippetd
users []UserRef
users referenced by the updates and snippets
RPC: Record Interaction #
Records integration activity for a user, which will then show up in their sidebar.
Interactions should correspond to an activity performed by or for a user, and should be at a frequency that approximates how a human might describe the activity. For example, instead of recording 20 interactions for 20 keystrokes, you should record one interaction for editing a document.
The idempotency_key is used to simplify de-duplication of interactions. If omitted, a five minute debounce window will be used by default.
POST /v1/activity
Arguments:
user_id string
The user who should receive the activity
interaction_at Time
Timestamp when the interaction occurred or is scheduled to occur.
interaction_type InteractionType
The type of interaction
idempotency_key string
attachment_id string
Range ID for the attachment receiving activity
attachment Attachment
A full attachment object to be upserted with the activity
Returns:
success bool
Always true for 200 response
was_recorded bool
False if duplicate record was debounced
attachment_id string
ID for the upserted attachment
interaction_id string
If new activity was recorded, the interaction ID
Entity: Team #
Defines the team. The team hierarchy must be constructed client-side using the team_id and parent_id.
team_id string
parent_id string
slug string
name string
description string
mascot string
created_at Time
archived_at Time
relation []TeamRelations
Entity: Team Ref #
Partial definition of a team, used primarily for display purposes.
team_id string
parent_id string
slug string
name string
Entity: Team Relation #
Defines the member/follower relationship between a user and a team.
team_id string
user_id string
is_member bool
role string
created_at Time
Entity: User #
A full user object.
user_id string
profile UserProfile
settings UserSettings
only visible to self and admins
state UserState
only visible to self and admins
current_absence Absence
created_at Time
last_update_published_at Time
Entity: UserProfile #
User profile information is visible to other members of the workspace.
full_name string
display_name string
email string
alt_email string
phone_cell string
phone_work string
location string
timezone_offset int32
Latest client timezone offset
timezone string
IANA timezone
profile_photo string
mood string
Latest mood emoji
mood_color string
Latest mood color
birth_date string
start_date string
myers_briggs string
true_colors string
pronounciation string
pronouns string
free_time string
mascot string
Emoji code
link_linked_in string
link_github string
link_instagram string
link_twitter string
link_personal string
Entity: UserState #
User state information is only visible to the current user and to admins. Only the listed fields may be updated via the API.
status EntityStatus
access_level AccessLevel
Entity: User Ref #
A partial representation of the User, primarily for display.
user_id string
full_name string
preferred_name string
mood string
profile_photo string
last_update_published_at Time
purpose string
is_absent bool
is_birthday bool
is_anniversary bool
timezone_offset int32
last known tz offset in minutes
Entity: Update #
Defines the data published in a check-in.
update_id string
user_id string
published_at Time
client_timezone_offset int32
timezone offset in minutes west of UTC, when the update was published
mood string
an emojione short code.
snippets []string
list of snippet IDs published in this update
Entity: Snippet #
Snippets are line items that make up a check-in/update.
id string
user_id string
update_id string
attachment_id ?string
if specified, the id of attachment created by an integration
published_at Time
content string
the raw text content of the snippet
transformed_content string
cleaned up content for printing
snippet_type uint32
1 = Plan, 2 = What happened, 3 = Question answer, 4 = Backlog
is_main_focus bool
whether the snippet is the main focus for that update
callout ?string
a callout/flag that amplifies the snippet
resolved_at ?Time
when the callout was resolved, if at all
tags []Tag
tags and entities extracted from the snippet
Entity: Attachment #
Attachments represent metadata associated with an artifact in a service that integrates with Range. An attachment may be referenced by multiple users and snippets. For a given org, the tuple (source_id, provider) should be unique.
id string
source_id string
identifier on the integration source
provider string
identifier of the integration
provider_name string
display name for the integration
type AttachmentType
subtype AttachmentSubType
name string
display string for the attachment
description string
longer form description
html_url string
web link to view the attachment
parent_name ?string
display string for the attachment's parent object, e.g. a repo name
parent_description ?string
description of the parent object
parent_html_url ?string
web link to view the attachment's parent. If parent_name is specified, required.
Different attachment types have different requirements and additional fields
Type: CODE_CHANGE
parent_name string
display string for project the code change is associated with
change_id string
identifier of the code change in the project
change_state string
the reason for the change being suggested, e.g. OPENED, MERGED
Type: ISSUE
parent_name string
display string for project the issue is associated with
issue_id string
identifier of the issue in the project
issue_state string
the reason for the issue being suggested, e.g. OPEN, CLOSED
Type: TASK
task_state string
the reason for the task being suggested, e.g. OPEN, COMPLETED
Enum: EntityStatus #
Enum of possible status fields for users and orgs
PENDING = 2 ENABLED = 4 DISABLED = 8
Enum: AttachmentType #
Enum of possible attachment types
# Link is a generic attachment
LINK = 0;
# Binary files (e.g. uploaded to dropbox, etc.)
FILE = 1;
# Cloud based documents; spreadsheets, presentations, google docs, etc.
DOCUMENT = 2;
# Calendar events.
EVENT = 3;
# Pull requests, commits, or merges
CODE_CHANGE = 4;
# Issues used in bug tracking software
ISSUE = 5;
# Task is something that can be completed
TASK = 6;
# Meeting is used for a Range meeting with notes.
MEETING = 7;
# Email campaigns, intercom campaigns, or apollo sequences.
CAMPAIGN = 8;
# The container of tasks and may include administrative work.
PROJECT = 9;
Enum: AttachmentSubType #
Enum of possible attachment subtypes.
NONE = 0;
GOOGLE_DOCUMENT = 1;
GOOGLE_DRIVE = 2;
GOOGLE_FORMS = 3;
GOOGLE_PRESENTATION = 4;
GOOGLE_SPREADSHEET = 5;
MICROSOFT_WORD = 6;
MICROSOFT_POWERPOINT = 7;
MICROSOFT_EXCEL = 8;
DROPBOX_FILE = 9;
PDF = 10;
IMAGE = 11;
CODE = 12;
VIDEO = 13;
FIGMA_DOCUMENT = 14;
Enum: InteractionType #
Enum of possible interaction types when activity is recorded against an attachment.
ADDED = 1;
EDITED = 2;
COMMENTED = 3;
CLOSED = 4;
CREATED = 5;
OPENED = 6;
STATUS_UPDATED = 7;
REVIEWED = 8;
RESOLVED = 9;
MERGED = 10;
COMPLETED = 11;
ASSIGNED = 12;
ATTENDED = 13;
CHANGED = 14
SUBMITTED = 15;
VIEWED = 16;
BUILT = 17;
BOUGHT = 18;
READ = 19;
SAW = 20;
WATCHED = 21;
SOLD = 22;
MENTIONED = 23;
ONBOARDED = 24;
