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:

?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

RPC: List Updates

Request a list of updates (check-ins) associated with a user, team, or organization.

GET /v1/updates

Arguments:

?stringtarget_idif specified, fetch updates by this user, team, or organization
?stringfor_user_idused instead of target_id to fetch updates from a user's teammates
?stringbeforeonly fetch updates before this time
?stringafteronly fetch updates after this time
?intcountlimit the number of updates returned
boolascendingwhether to order oldest first
booluse_client_offsetwhether to localize each update's time such that the request is for a specific calendar day relative to the author
boolinclude_child_teamsif target_id is a team, then also include updates from descendent teams
boolinclude_refswhether to return snippets, attachments, and users

Returns:

[]Updateupdatesthe updates
[]Snippetsnippetsline items referenced by the updates
[]Attachmentattachmentsattachments from integrations, referenced by snippetd
[]UserRefusersusers 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.

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

Entity: Update

Defines the data published in a check-in.

stringupdate_id
stringuser_id
stringpublished_at
int32client_timezone_offsettimezone offset in minutes west of UTC, when the update was published
stringmoodan emojione short code.
[]stringsnippetslist of snippet IDs published in this update

Entity: Snippet

Snippets are line items that make up a check-in/update.

stringid
stringuser_id
stringupdate_id
?stringattachment_idif specified, the id of attachment created by an integration
stringpublished_at
stringcontentthe raw text content of the snippet
stringtransformed_contentcleaned up content for printing
uint32snippet_type1 = Plan, 2 = What happened, 3 = Question answer, 4 = Backlog
boolis_main_focuswhether the snippet is the main focus for that update
?stringcallouta callout/flag that amplifies the snippet
?stringresolved_atwhen the callout was resolved, if at all
[]Tagtagstags 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.

stringid
stringsource_ididentifier on the integration source
stringprovideridentifier of the integration
stringprovider_namedisplay name for the integration
AttachmentTypetype
stringsubtype
stringnamedisplay string for the attachment
stringdescriptionlonger form description
stringhtml_urlweb link to view the attachment
stringparent_nameDisplay string for the attachments parent object
stringparent_descriptionDescription of the parent object
stringparent_html_urlWeb link to view the attachment's parent