RequestRocketRequestRocketDocs
OrganisationsOrganisation and team

Organisation and team API

Create an organisation, its members, and its invites.

The client id in these paths is the organisation. User-scoped routes list the organisations and invites that belong to one user.

Roles

RoleOrganisation and team access
ownerRead, create, update, and delete the organisation; manage members and invites; grant or remove owner.
adminRead, create, and update the organisation; manage members and invites.
devopsRead the organisation; no member or invite access.
userRead the organisation; no member or invite access.
readerRead the organisation; no member or invite access.

Endpoints

MethodPathWhat it does
GET/api/clientsList organisations
POST/api/clientsCreate an organisation
GET/api/clients/:clientIdRead an organisation
PUT/api/clients/:clientIdUpdate an organisation
GET/api/clients/:clientId/membersList members
POST/api/clients/:clientId/membersNot supported. Invite a member instead
PUT/api/clients/:clientId/members/:memberIdChange roles
DELETE/api/clients/:clientId/members/:memberIdRemove a member
GET/api/clients/:clientId/invitesList invites
POST/api/clients/:clientId/invitesCreate an invite
PUT/api/clients/:clientId/invites/:inviteIdUpdate invite roles
DELETE/api/clients/:clientId/invites/:inviteIdDelete an invite
GET/api/users/:userId/membershipsList the user's organisations
GET/api/users/:userId/invitesList the user's invites
PUT/api/users/:userId/invites/:inviteIdAccept or reject an invite

List calls on this page return every matching record. They do not accept limit, cursor, or page query parameters. An organisation list is clients. A member list is members, each with userId, userFirstName, userLastName, userEmail, and roles. An invite list is invites.

Create an organisation

POST /api/clients creates the organisation. The name is unique.

Request

curl -X POST "https://api.requestrocket.com/api/clients" \
  -H "Authorization: u-your-token" \
  -H "Content-Type: application/json" \
  -d '{
  "clientName": "Example"
}'
import axios from "axios";

const response = await axios.request({
  method: "POST",
  url: "https://api.requestrocket.com/api/clients",
  headers: {
    "Authorization": "u-your-token",
    "Content-Type": "application/json",
  },
  data: {
  "clientName": "Example"
}
});

console.log(response.status, response.data);
import requests

response = requests.request(
    "POST",
    "https://api.requestrocket.com/api/clients",
    headers={
        "Authorization": "u-your-token",
        "Content-Type": "application/json",
    },
    data="{\n  \"clientName\": \"Example\"\n}"
)
print(response.status_code, response.json())
package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    payload := strings.NewReader(`{
  "clientName": "Example"
}`)
    req, _ := http.NewRequest("POST", "https://api.requestrocket.com/api/clients", payload)
    req.Header.Set("Authorization", "u-your-token")
    req.Header.Set("Content-Type", "application/json")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(resp.StatusCode, string(body))
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.requestrocket.com/api/clients"))
            .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"clientName\": \"Example\"\n}"))
            .header("Authorization", "u-your-token")
            .header("Content-Type", "application/json")
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}

Responses

{
  "clients": [
    {
      "clientId": "b3a1c7d2-5e44-4f0a-9c1e-7d2f8a6b1c90",
      "clientName": "Example",
      "clientMembers": [
        {
          "userId": "0f8e6c1a-2b7d-4c3e-9a55-1d2e3f4a5b6c",
          "roles": [
            "owner",
            "admin"
          ]
        }
      ]
    }
  ],
  "message": "client created successfully"
}
{
  "message": "Input failed data validation",
  "errors": [
    "/clientName: must have required property 'clientName'"
  ]
}
{
  "message": "Unauthorized"
}
{
  "Message": "User is not authorized to access this resource with an explicit deny in an identity-based policy"
}
{
  "message": "method / endpoint not supported"
}

Request body

ParameterTypeRequiredDescription
clientNamestring✓Organisation name. 3 to 256 characters. Letters, numbers, spaces, and hyphens, and at least one letter, number, or hyphen. The name must be unique.
returnUserboolean—When true, the response also includes the caller under user.

Returns the created organisation in clients, plus message. The caller is stored as a member with roles owner and admin.

Response

AttributeTypeDescription
clientsarrayThe organisation that was created.
clients[].clientIdstringOrganisation id.
clients[].clientNamestringName that was stored.
clients[].clientMembersarrayMembers. Each item has userId and roles.
clients[].clientMSPsarrayManaging partner ids, when any are linked.
messagestringConfirms the organisation was created.
userobjectPresent when returnUser is true. Includes userId, userFirstName, userLastName, userEmail, and roles.

Update an organisation

PUT /api/clients/:clientId renames the organisation. clientName follows the same rules as create, and it is still required.

Request body

ParameterTypeRequiredDescription
clientNamestring✓New organisation name. Same length and character rules as create, and it must be unique.
returnUserboolean—When true, the response also includes the caller under user.

Returns clients with the renamed organisation, and message. The response attributes match create.

Create an invite

POST /api/clients/:clientId/invites invites an email address and assigns roles.

Request

curl -X POST "https://api.requestrocket.com/api/clients/:clientId/invites" \
  -H "Authorization: u-your-token" \
  -H "Content-Type: application/json" \
  -d '{
  "userEmail": "person@example.com",
  "roles": [
    "user"
  ]
}'
import axios from "axios";

const response = await axios.request({
  method: "POST",
  url: "https://api.requestrocket.com/api/clients/:clientId/invites",
  headers: {
    "Authorization": "u-your-token",
    "Content-Type": "application/json",
  },
  data: {
  "userEmail": "person@example.com",
  "roles": [
    "user"
  ]
}
});

console.log(response.status, response.data);
import requests

response = requests.request(
    "POST",
    "https://api.requestrocket.com/api/clients/:clientId/invites",
    headers={
        "Authorization": "u-your-token",
        "Content-Type": "application/json",
    },
    data="{\n  \"userEmail\": \"person@example.com\",\n  \"roles\": [\n    \"user\"\n  ]\n}"
)
print(response.status_code, response.json())
package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    payload := strings.NewReader(`{
  "userEmail": "person@example.com",
  "roles": [
    "user"
  ]
}`)
    req, _ := http.NewRequest("POST", "https://api.requestrocket.com/api/clients/:clientId/invites", payload)
    req.Header.Set("Authorization", "u-your-token")
    req.Header.Set("Content-Type", "application/json")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(resp.StatusCode, string(body))
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.requestrocket.com/api/clients/:clientId/invites"))
            .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"userEmail\": \"person@example.com\",\n  \"roles\": [\n    \"user\"\n  ]\n}"))
            .header("Authorization", "u-your-token")
            .header("Content-Type", "application/json")
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}

Responses

{
  "invites": [
    {
      "inviteId": "d7f1a346-5c80-4b29-8e1a-0f3c6d9b2e54",
      "parentId": "b3a1c7d2-5e44-4f0a-9c1e-7d2f8a6b1c90",
      "clientName": "Example",
      "userEmail": "person@example.com",
      "roles": [
        "user"
      ]
    }
  ],
  "message": "User has been invited to the client's account"
}
{
  "message": "No email / invalid email provided in body, can't invite user"
}
{
  "message": "Unauthorized"
}
{
  "Message": "User is not authorized to access this resource with an explicit deny in an identity-based policy"
}
{
  "message": "method / endpoint not supported"
}

Request body

ParameterTypeRequiredDescription
userEmailstring✓Email address to invite.
rolesarray of string✓At least one of owner, admin, devops, user, reader. Only an owner can assign owner.
userNamestring—Name used in the invitation email greeting. It is not stored on the invite.

Returns the invite in invites, plus message. Sending the same email again updates the pending invite instead of creating a second one.

Response

AttributeTypeDescription
invitesarrayThe invite that was created or updated.
invites[].inviteIdstringInvite id.
invites[].parentIdstringOrganisation id the invite belongs to.
invites[].clientNamestringOrganisation name.
invites[].userEmailstringInvited email address.
invites[].rolesarray of stringRoles the person receives if they join.
messagestringConfirms the invite was created or that an existing invite was updated.

Change a member's roles

PUT /api/clients/:clientId/members/:memberId replaces the roles on an existing member.

Request body

ParameterTypeRequiredDescription
rolesarray of string✓One or more of owner, admin, devops, user, reader. Only an owner can grant or remove owner. The sole owner keeps owner.

Returns members for that person and message (Client user updated with roles). Each member includes userId, userFirstName, userLastName, userEmail, and roles when those fields are present.

Update invite roles

PUT /api/clients/:clientId/invites/:inviteId replaces the roles on a pending invite and extends it for 14 days. Accepting or rejecting an invite is PUT /api/users/:userId/invites/:inviteId.

Request body

ParameterTypeRequiredDescription
rolesarray of string✓At least one of owner, admin, devops, user, reader. Only an owner can assign or remove owner.

Returns the updated invite in invites and message (Invite updated). The invite attributes match create.

Respond to an invite

PUT /api/users/:userId/invites/:inviteId accepts or rejects an invite addressed to that user.

Request body

ParameterTypeRequiredDescription
acceptInviteboolean—false rejects the invite and deletes it. Omit the field to accept. Accepting adds the user to the organisation with the invite's roles and deletes the invite.

Returns message: Invite accepted or Invite rejected.

Shared status codes, the 5.5 MB cap, and plan rate limits are on Platform limits.

Next

On this page