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 firstname.lastname@example.org.
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.
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.
All dates and times are in UTC and specified in ISO8601 format, for example
Endpoints for updating entities support partial updates. Leave fields as
undefined that you don't want to change, falsish values such as
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.
- Go (coming soon)
- Python (coming soon)
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.
|?string||user_id||if specified, return this user’s teams|
|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.
|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.
|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:|
RPC: Update Team Relation
Make a user join or follow a team, or update their role.
RPC: Delete Team Relation
Leave a team or stop following it.
RPC: Read User
Looks up a user by their Range user id.
RPC: Find User
Looks up a Range user account via email or a linked identity on another service.
|?string||plain text email address|
|?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|
|User||user||if include_ref == true|
RPC: List Updates
Request a list of updates (check-ins) associated with a user, team, or organization.
|?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|
|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|
Defines the team. The team hierarchy must be constructed client-side using the team_id and parent_id.
Entity: Team Ref
Partial definition of a team, used primarily for display purposes.
Entity: Team Relation
Defines the member/follower relationship between a user and a team.
A full user object.
|UserSettings||settings||only visible to self and admins|
|UserState||state||only visible to self and admins|
Entity: User Ref
A partial representation of the User, primarily for display.
|int32||timezone_offset||last known tz offset in minutes|
Defines the data published in a check-in.
|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|
Snippets are line items that make up a check-in/update.
|?string||attachment_id||if specified, the id of attachment created by an integration|
|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|
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||source_id||identifier on the integration source|
|string||provider||identifier of the integration|
|string||provider_name||display name for the integration|
|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|