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