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

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:

?stringuser_idif specified, return this user’s teams
boolinclude_archived
boolinclude_following

Returns:

[]Teamteamsall associated teams
[]UserRefusersfollowers and members referenced by teams
[]TeamRefrelated_teamsparents and children of the teams

RPC: Read Team

Fetch data about a team, related users, and related teams.

      GET /v1/teams/{team_id}
    

Arguments:

stringteam_id

Returns:

Teamteam
[]UserRefusersusers directly related to this team
[]TeamRefparent_teamslist of ancestors, order from root of org
[]TeamRefchild_teamsall descendant teams

RPC: Create Team

Start a new team or subteam.

      POST /v1/teams
    

Arguments:

stringparent_idteam to use as the parent, empty for root team
stringslugunique path identifier to go in URLs
stringnamethe team’s name
stringdescriptionthe team's charter or purpose
stringmascotan 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:

stringteam_id
stringuser_id

Returns:

TeamRelation.

RPC: Delete Team Relation

Leave a team or stop following it.

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

Arguments:

stringteam_id
stringuser_id

Returns:

boolsuccess

RPC: Read User

Looks up a user by their Range user id.

      GET /v1/users/{user_id}
    

Arguments:

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

?stringemailplain text email address
?stringemail_hashlower(sha1(email))
?stringproviderwhich integration provider to lookup
?stringprovider_idthe accounts ID on provider
boolinclude_refswhether to include the user object
boolallow_inactivewhether to include deactivated users
boolallow_pendingwhether to include newly invited users

Returns:

stringuser_id
Useruserif include_ref == true

Entity: Team

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

stringteam_id
stringparent_id
stringslug
stringname
stringdescription
stringmascot
stringcreated_at
stringarchived_at
[]TeamRelationsrelation

Entity: Team Ref

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

stringteam_id
stringparent_id
stringslug
stringname

Entity: Team Relation

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

stringteam_id
stringuser_id
boolis_member
stringrole
stringcreated_at

Entity: User

A full user object.

stringuser_id
UserProfileprofile
UserSettingssettingsonly visible to self and admins
UserStatestateonly visible to self and admins
Absencecurrent_absence
stringcreated_at
stringlast_update_published_at

Entity: User Ref

A partial representation of the User, primarily for display.

stringuser_id
stringfull_name
stringpreferred_name
stringmood
stringprofile_photo
stringlast_update_published_at
stringpurpose
boolis_absent
boolis_birthday
boolis_anniversary
int32timezone_offsetlast known tz offset in minutes
We use cookies to offer you a better browsing experience, analyze site traffic, personalize content, and serve targeted advertisements. Read about how we use cookies in our privacy policy. If you continue to use this site, you consent to our use of cookies.