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.
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.
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 #
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
toISOString(). In the API reference they are demarked with the
Endpoints for updating entities support partial updates. Leave fields as
undefined that you don't want to change, falsish values such as
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.
- Go (coming soon)
- Python (coming soon)
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.
if specified, return this user’s teams
all associated teams
followers and members referenced by teams
parents and children of the teams
RPC: Read Team #
Fetch data about a team, related users, and related teams.
users directly related to this team
list of ancestors, order from root of org
all descendant teams
RPC: Create Team #
Start a new team or subteam.
team to use as the parent, empty for root team
unique path identifier to go in URLs
the team’s name
the team's charter or purpose
an emoji-one code for thye team, e.g. :bear:
RPC: Update Team Relation #
Make a user join or follow a team, or update their role.
RPC: Delete Team Relation #
Leave a team or stop following it.
RPC: List Users #
Looks up a user by their Range user id.
Users in this team
Explicit set of users to fetch data for
Users on teams this user is a member of or who follows
Default to zero, meaning no limit
RPC: Read User #
Looks up a user by their Range user id.
RPC: Update User Profile #
Update the profile portion of a user entity. Non-admins may only update their own profile.
Full or partial user profile
The full user profile
RPC: Update User State #
Update the state portion of a user entity. Only admins may update state properties.
Full or partial user state
The full user state
RPC: Auth User #
Looks up the user who owns the API key.
RPC: Find User #
Looks up a Range user account via email or a linked identity on another service.
plain text email address
which integration provider to lookup
the accounts ID on provider
whether to include the user object
whether to include deactivated users
whether to include newly invited users
if include_ref == true
RPC: List Updates #
Request a list of updates (check-ins) associated with a user, team, or organization.
if specified, fetch updates by this user, team, or organization
used instead of target_id to fetch updates from a user's teammates
only fetch updates before this time
only fetch updates after this time
limit the number of updates returned
whether to order oldest first
whether to localize each update's time such that the request is for a specific calendar day relative to the author
if target_id is a team, then also include updates from descendent teams
whether to return snippets, attachments, and users
line items referenced by the updates
attachments from integrations, referenced by snippetd
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.
idempotency_key is used to simplify de-duplication of interactions. If omitted, a five minute debounce window will be used by default.
The user who should receive the activity
Timestamp when the interaction occurred or is scheduled to occur.
The type of interaction
Range ID for the attachment receiving activity
A full attachment object to be upserted with the activity
Always true for 200 response
False if duplicate record was debounced
ID for the upserted attachment
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.
Entity: Team Ref #
Partial definition of a team, used primarily for display purposes.
Entity: Team Relation #
Defines the member/follower relationship between a user and a team.
Entity: User #
A full user object.
only visible to self and admins
only visible to self and admins
Entity: UserProfile #
User profile information is visible to other members of the workspace.
Latest client timezone offset
Latest mood emoji
Latest mood color
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.
Entity: User Ref #
A partial representation of the User, primarily for display.
last known tz offset in minutes
Entity: Update #
Defines the data published in a check-in.
timezone offset in minutes west of UTC, when the update was published
an emojione short code.
list of snippet IDs published in this update
Entity: Snippet #
Snippets are line items that make up a check-in/update.
if specified, the id of attachment created by an integration
the raw text content of the snippet
cleaned up content for printing
1 = Plan, 2 = What happened, 3 = Question answer, 4 = Backlog
whether the snippet is the main focus for that update
a callout/flag that amplifies the snippet
when the callout was resolved, if at all
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.
identifier on the integration source
identifier of the integration
display name for the integration
display string for the attachment
longer form description
web link to view the attachment
display string for the attachment's parent object, e.g. a repo name
description of the parent object
web link to view the attachment's parent. If parent_name is specified, required.
Different attachment types have different requirements and additional fields
display string for project the code change is associated with
identifier of the code change in the project
the reason for the change being suggested, e.g. OPENED, MERGED
display string for project the issue is associated with
identifier of the issue in the project
the reason for the issue being suggested, e.g. OPEN, CLOSED
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: AccessLevel #
Enum of possible access levels
GUEST = 0 STANDARD = 1 ADMIN = 5 OWNER = 10
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;