Range API Reference

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 and Teams.

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

---

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