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.

Drop us a line

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}/users

Arguments:

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}/profile

Arguments:

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}/state

Arguments:

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

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: 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;