API Reference

Build your own applications that interact 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’d love your feedback on this initial API and anything you'd like to see in the future. Drop us a line at feedback@range.co.

Authentication

Range will 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! 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.

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 formats

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().

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)

Incoming webhooks

Range integrates with other software to create suggested items for users to add to their updates.

For tools that are not supported, you can create an incoming webhook and programmatically send suggestions to yourself or your teammates. Find out more about setting up incoming webhooks in our help center.

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:

?string	user_id	if specified, return this user’s teams
bool	include_archived
bool	include_following

Returns:

[]Team	teams	all associated teams
[]UserRef	users	followers and members referenced by teams
[]TeamRef	related_teams	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:

string

team_id

Returns:

Team	team
[]UserRef	users	users directly related to this team
[]TeamRef	parent_teams	list of ancestors, order from root of org
[]TeamRef	child_teams	all descendant teams

RPC: Create Team

Start a new team or subteam.

POST /v1/teams

Arguments:

string	parent_id	team to use as the parent, empty for root team
string	slug	unique path identifier to go in URLs
string	name	the team’s name
string	description	the team's charter or purpose
string	mascot	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:

string	team_id
string	user_id

Returns:

TeamRelation

RPC: Delete Team Relation

Leave a team or stop following it.

DELETE /v1/teams/{team_id}/relations/{user_id}

Arguments:

string	team_id
string	user_id

Returns:

bool

success

RPC: Read User

Looks up a user by their Range user id.

GET /v1/users/{user_id}

Arguments:

string

user_id

Returns:

User

RPC: Find User

Looks up a Range user account via email or a linked identity on another service.

GET /v1/users/find

Arguments:

?string	email	plain text email address
?string	email_hash	lower(sha1(email))
?string	provider	which integration provider to lookup
?string	provider_id	the accounts ID on provider
bool	include_refs	whether to include the user object
bool	allow_inactive	whether to include deactivated users
bool	allow_pending	whether to include newly invited users

Returns:

string	user_id
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:

?string	target_id	if specified, fetch updates by this user, team, or organization
?string	for_user_id	used instead of target_id to fetch updates from a user's teammates
?string	before	only fetch updates before this time
?string	after	only fetch updates after this time
?int	count	limit the number of updates returned
bool	ascending	whether to order oldest first
bool	use_client_offset	whether to localize each update's time such that the request is for a specific calendar day relative to the author
bool	include_child_teams	if target_id is a team, then also include updates from descendent teams
bool	include_refs	whether to return snippets, attachments, and users

Returns:

[]Update	updates	the updates
[]Snippet	snippets	line items referenced by the updates
[]Attachment	attachments	attachments from integrations, referenced by snippetd
[]UserRef	users	users referenced by the updates and snippets

Entity: Team

Defines the team. The team hierarchy must be constructed client-side using the team_id and parent_id.

string	team_id
string	parent_id
string	slug
string	name
string	description
string	mascot
string	created_at
string	archived_at
[]TeamRelations	relation

Entity: Team Ref

Partial definition of a team, used primarily for display purposes.

string	team_id
string	parent_id
string	slug
string	name

Entity: Team Relation

Defines the member/follower relationship between a user and a team.

string	team_id
string	user_id
bool	is_member
string	role
string	created_at

Entity: User

A full user object.

string	user_id
UserProfile	profile
UserSettings	settings	only visible to self and admins
UserState	state	only visible to self and admins
Absence	current_absence
string	created_at
string	last_update_published_at

Entity: User Ref

A partial representation of the User, primarily for display.

string	user_id
string	full_name
string	preferred_name
string	mood
string	profile_photo
string	last_update_published_at
string	purpose
bool	is_absent
bool	is_birthday
bool	is_anniversary
int32	timezone_offset	last known tz offset in minutes

Entity: Update

Defines the data published in a check-in.

string	update_id
string	user_id
string	published_at
int32	client_timezone_offset	timezone offset in minutes west of UTC, when the update was published
string	mood	an emojione short code.
[]string	snippets	list of snippet IDs published in this update

Entity: Snippet

Snippets are line items that make up a check-in/update.

string	id
string	user_id
string	update_id
?string	attachment_id	if specified, the id of attachment created by an integration
string	published_at
string	content	the raw text content of the snippet
string	transformed_content	cleaned up content for printing
uint32	snippet_type	1 = Plan, 2 = What happened, 3 = Question answer, 4 = Backlog
bool	is_main_focus	whether the snippet is the main focus for that update
?string	callout	a callout/flag that amplifies the snippet
?string	resolved_at	when the callout was resolved, if at all
[]Tag	tags	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) will be unique.

string	id
string	source_id	identifier on the integration source
string	provider	identifier of the integration
string	provider_name	display name for the integration
AttachmentType	type
string	subtype
string	name	display string for the attachment
string	description	longer form description
string	html_url	web link to view the attachment
string	parent_name	Display string for the attachments parent object
string	parent_description	Description of the parent object
string	parent_html_url	Web link to view the attachment's parent