Update User Membership

PATCH/users/{id}/memberships

Caller

Requires write:users and an active, verified key owner with permission to perform the membership action.

Key	Memberships
Company-scoped	Company users assigned to companies; project users assigned to projects
Agency-scoped	Agency users assigned to agencies

Summary

Adds or removes memberships for an existing user. Each request performs one action. The user's existing role determines whether the IDs identify companies, projects or agencies; no membership type is supplied. The user's base role and custom role assignments cannot be changed through this endpoint.

The user must already belong to at least one company or agency within the key scope. Every requested entity must be within that scope. Other memberships are preserved. Once the user's last membership within the key scope is removed, that key can no longer update their memberships.

Membership type	Supported user roles
company	companyAdmin, companyFinance
project	projectAdmin, projectFinance, projectApprover, projectRequestor
agency	ldAdmin, ldUser

Project assignments update the associated company membership and apply relevant permission templates. Removals perform the corresponding permission, access and membership cleanup. Activity records and assignment/removal notifications follow the usual membership rules. Users must be active when adding memberships. Self updates are rejected.

If notification delivery fails after memberships have changed, the endpoint can return 500. Check the user's current memberships before retrying.

URL Parameters

Name	Type	Required	Description
id	string	Yes	User ObjectId or reference

Request Fields

Field	Type	Required	Description
action	enum(add, remove)	Yes	Add or remove the selected memberships
ids	array[string]	Yes	Non-empty list of unique company, project or agency ObjectIds or references within the key scope

Request Example

cURL

curl -X PATCH 'https://api.requidex.com/api/open/v1/users/{id}/memberships' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"action":"add","ids":["507f1f77bcf86cd799439016"]}'

JavaScript

const response = await fetch(
  "https://api.requidex.com/api/open/v1/users/{id}/memberships",
  {
    method: "PATCH",
    headers: {
      Authorization: "Bearer <API_KEY>",
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify({
      action: "add",
      ids: ["507f1f77bcf86cd799439016"],
    }),
  },
);

const json = await response.json();

Python

import requests

response = requests.patch(
    'https://api.requidex.com/api/open/v1/users/{id}/memberships',
    headers={
        'Authorization': 'Bearer <API_KEY>',
        'Accept': 'application/json',
    },
    json={
        'action': 'add',
        'ids': ['507f1f77bcf86cd799439016'],
    },
    timeout=30,
)

print(response.json())

Go

package main

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

func main() {
  body := strings.NewReader(`{"action":"add","ids":["507f1f77bcf86cd799439016"]}`)
  req, _ := http.NewRequest("PATCH", "https://api.requidex.com/api/open/v1/users/{id}/memberships", body)
  req.Header.Set("Authorization", "Bearer <API_KEY>")
  req.Header.Set("Content-Type", "application/json")
  req.Header.Set("Accept", "application/json")

  client := &http.Client{}
  resp, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  payload, _ := io.ReadAll(resp.Body)
  fmt.Println(string(payload))
}

Remove project memberships

{
  "action": "remove",
  "ids": ["507f1f77bcf86cd799439016", "507f1f77bcf86cd799439020"]
}

For project updates, projects already assigned during add, or not assigned during remove, are skipped when another requested project can be changed. Requests where no project can be changed return 400.

Add company memberships

Use a company-scoped key for a company admin or company finance user.

{
  "action": "add",
  "ids": ["507f1f77bcf86cd799439011"]
}

To remove the company membership, use the same body with action: "remove".

Add agency memberships

Use an agency-scoped key for an agency admin or agency staff user.

{
  "action": "add",
  "ids": ["507f1f77bcf86cd799439017"]
}

To remove the agency membership, use the same body with action: "remove". Adding memberships already present for every requested company or agency returns 404.

Response Fields

Field	Type	Description
success	boolean	true
data	object	Show child attributes message (string): outcome of the membership action membershipType (string): inferred membership type: company, project or agency assignedCount (integer): number of memberships added removedCount (integer): number of memberships removed skippedCount (integer): number of requested memberships left unchanged assignedNames (array[string]): names of assigned companies, projects or agencies removedNames (array[string]): names of removed companies, projects or agencies skippedNames (array[string]): names of companies, projects or agencies left unchanged
meta	object	Empty object

Response Example (200)

{
  "success": true,
  "data": {
    "message": "User assigned",
    "membershipType": "project",
    "assignedCount": 1,
    "removedCount": 0,
    "skippedCount": 0,
    "assignedNames": ["Central Site"],
    "removedNames": [],
    "skippedNames": []
  },
  "meta": {}
}

Company and agency memberships that are not assigned are skipped during removal without removal activities or notifications. If every requested company or agency membership is unassigned, the request returns 200 with all memberships skipped.

Company, project and agency updates use the same response fields. Unused counts are 0 and unused name arrays are empty. Existing workflow errors still apply when an entire request cannot be performed.

Errors

HTTP Status	Description
400	Invalid or unsupported fields, role mismatch, self update, deactivated user on addition, or project membership workflow restriction
401	Missing, invalid, revoked, or expired API key
403	Missing write:users, inactive or unverified owner, incompatible key scope, or insufficient permissions
404	User or requested entity not found within key scope, or no new company/agency memberships to add
405	Method not allowed on Open API routes
429	Rate limit exceeded
500	Membership update or notification failed