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