Add multiple members to organization

Bulk adds multiple members to the authenticated organization. Each member must have a valid user ID that exists in the system. Members who already exist in the organization or have invalid data will be skipped with error details returned. Supports both API key authentication (X-API-Key header) and session authentication (cookies + X-Organization-Id header).

POST /v1/people/bulk

Try it

Add multiple members to organization

cURL

curl --request POST \
  --url http://localhost:3333/v1/people/bulk \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "members": [
    {
      "userId": "usr_abc123def456",
      "role": "admin",
      "department": "it",
      "isActive": true,
      "fleetDmLabelId": 123
    },
    {
      "userId": "usr_def456ghi789",
      "role": "member",
      "department": "hr",
      "isActive": true
    }
  ]
}
'

201

{
  "created": [
    {
      "id": "mem_abc123def456",
      "organizationId": "org_abc123def456",
      "userId": "usr_abc123def456",
      "role": "member",
      "createdAt": "2024-01-01T00:00:00Z",
      "department": "it",
      "isActive": true,
      "fleetDmLabelId": 123,
      "user": {
        "id": "usr_abc123def456",
        "name": "John Doe",
        "email": "[e-mail]",
        "emailVerified": true,
        "image": "https://example.com/avatar.jpg",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-15T00:00:00Z",
        "lastLogin": "2024-01-15T12:00:00Z"
      }
    }
  ],
  "errors": [
    {
      "index": 2,
      "userId": "usr_xyz789abc123",
      "error": "User [e-mail] is already a member of this organization"
    }
  ],
  "summary": {
    "total": 2,
    "successful": 1,
    "failed": 1
  },
  "authType": "api-key",
  "authenticatedUser": {
    "id": "usr_admin123",
    "email": "[e-mail]"
  }
}

Authorizations

X-API-Key · string · header · required

API key for authentication

Headers

X-Organization-Id · string

Organization ID (required for session auth, optional for API key auth)

Body

application/json

Bulk member creation data

members · object[] · required

Array of members to create

Show child attributes

members. userId · string · required

User ID to associate with this member

Example:

"usr_abc123def456"

members. role · string · required

Role for the member

Example:

"admin"

members. department · enum<string>

Member department

Available options: none, admin, gov, hr, it, itsm, qms

Example:

"it"

members. isActive · boolean

Whether member is active

Example:

true

members. fleetDmLabelId · number

FleetDM label ID for member devices

Example:

123

Example:

[
  {
    "userId": "usr_abc123def456",
    "role": "admin",
    "department": "it",
    "isActive": true,
    "fleetDmLabelId": 123
  },
  {
    "userId": "usr_def456ghi789",
    "role": "member",
    "department": "hr",
    "isActive": true
  }
]

Response

201

application/json

Bulk member creation completed

created · object[]

Successfully created members

Show child attributes

created. id · string · required

Member ID

Example:

"mem_abc123def456"

created. organizationId · string · required

Organization ID this member belongs to

Example:

"org_abc123def456"

created. userId · string · required

User ID associated with member

Example:

"usr_abc123def456"

created. role · string · required

Member role

Example:

"admin"

created. createdAt · string<date-time> · required

When the member was created

Example:

"2024-01-01T00:00:00Z"

created. department · enum<string> · required

Member department

Available options: none, admin, gov, hr, it, itsm, qms

Example:

"it"

created. isActive · boolean · required

Whether member is active

Example:

true

created. fleetDmLabelId · object · required

FleetDM label ID for member devices

Example:

123

created. user · object · required

User information

Show child attributes

created.user. id · string · required

User ID

Example:

"usr_abc123def456"

created.user. name · string · required

User name

Example:

"John Doe"

created.user. email · string · required

User email

Example:

"[e-mail]"

created.user. emailVerified · boolean · required

Whether email is verified

Example:

true

created.user. image · object · required

User profile image URL

Example:

"https://example.com/avatar.jpg"

created.user. createdAt · string<date-time> · required

When the user was created

Example:

"2024-01-01T00:00:00Z"

created.user. updatedAt · string<date-time> · required

When the user was last updated

Example:

"2024-01-15T00:00:00Z"

created.user. lastLogin · object · required

Last login time

Example:

"2024-01-15T12:00:00Z"

errors · object[]

Members that failed to be created with error details

Show child attributes

errors. index · number

Index in the original array where the error occurred

Example:

2

errors. userId · string

User ID that failed to be added

Example:

"usr_abc123def456"

errors. error · string

Error message explaining why the member could not be created

Example:

"User [e-mail] is already a member of this organization"

summary · object

Show child attributes

summary. total · number

Total number of members in the request

Example:

5

summary. successful · number

Number of members successfully created

Example:

3

summary. failed · number

Number of members that failed to be created

Example:

2

authType · enum<string>

How the request was authenticated

Available options: api-key, session

authenticatedUser · object

Show child attributes

authenticatedUser. id · string

User ID

Example:

"usr_abc123def456"

authenticatedUser. email · string

User email

Example:

"[e-mail]"