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
| Role | Organisation and team access |
|---|---|
owner | Read, create, update, and delete the organisation; manage members and invites; grant or remove owner. |
admin | Read, create, and update the organisation; manage members and invites. |
devops | Read the organisation; no member or invite access. |
user | Read the organisation; no member or invite access. |
reader | Read the organisation; no member or invite access. |
Endpoints
| Method | Path | What it does |
|---|---|---|
| GET | /api/clients | List organisations |
| POST | /api/clients | Create an organisation |
| GET | /api/clients/:clientId | Read an organisation |
| PUT | /api/clients/:clientId | Update an organisation |
| GET | /api/clients/:clientId/members | List members |
| POST | /api/clients/:clientId/members | Not supported. Invite a member instead |
| PUT | /api/clients/:clientId/members/:memberId | Change roles |
| DELETE | /api/clients/:clientId/members/:memberId | Remove a member |
| GET | /api/clients/:clientId/invites | List invites |
| POST | /api/clients/:clientId/invites | Create an invite |
| PUT | /api/clients/:clientId/invites/:inviteId | Update invite roles |
| DELETE | /api/clients/:clientId/invites/:inviteId | Delete an invite |
| GET | /api/users/:userId/memberships | List the user's organisations |
| GET | /api/users/:userId/invites | List the user's invites |
| PUT | /api/users/:userId/invites/:inviteId | Accept 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": "User is not authorized to access this resource with an explicit deny in an identity-based policy"
}{
"message": "method / endpoint not supported"
}Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
clientName | string | ✓ | Organisation name. 3 to 256 characters. Letters, numbers, spaces, and hyphens, and at least one letter, number, or hyphen. The name must be unique. |
returnUser | boolean | — | 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
| Attribute | Type | Description |
|---|---|---|
clients | array | The organisation that was created. |
clients[].clientId | string | Organisation id. |
clients[].clientName | string | Name that was stored. |
clients[].clientMembers | array | Members. Each item has userId and roles. |
clients[].clientMSPs | array | Managing partner ids, when any are linked. |
message | string | Confirms the organisation was created. |
user | object | Present 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
| Parameter | Type | Required | Description |
|---|---|---|---|
clientName | string | ✓ | New organisation name. Same length and character rules as create, and it must be unique. |
returnUser | boolean | — | 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": "User is not authorized to access this resource with an explicit deny in an identity-based policy"
}{
"message": "method / endpoint not supported"
}Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
userEmail | string | ✓ | Email address to invite. |
roles | array of string | ✓ | At least one of owner, admin, devops, user, reader. Only an owner can assign owner. |
userName | string | — | 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
| Attribute | Type | Description |
|---|---|---|
invites | array | The invite that was created or updated. |
invites[].inviteId | string | Invite id. |
invites[].parentId | string | Organisation id the invite belongs to. |
invites[].clientName | string | Organisation name. |
invites[].userEmail | string | Invited email address. |
invites[].roles | array of string | Roles the person receives if they join. |
message | string | Confirms 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
| Parameter | Type | Required | Description |
|---|---|---|---|
roles | array 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
| Parameter | Type | Required | Description |
|---|---|---|---|
roles | array 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
| Parameter | Type | Required | Description |
|---|---|---|---|
acceptInvite | boolean | — | 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.