RoadOps Developer Docs - Travel Parties

List user groups

GET/v1/teams/{teamId}/user-groups

Lists user groups for a team.

Required scopes: user_group:read

Parameters

`path.teamId`required	`string:uuid` Team identifier.
`query.limit`	`integer` Maximum number of records to return. Defaults to 50 and is capped at 200.
`query.cursor`	`string` Cursor returned by page.nextCursor from the previous list response.

Response 200

`data`	`object[]`
`data[].name`	`string`
`data[].labelColor`	`string \| null`
`data[].id`	`string:uuid`
`data[].orgId`	`string:uuid`
`data[].isDeleted`	`boolean`
`data[].version`	`integer` Current user group aggregate version.
`data[].createdAt`	`string:date-time` ISO 8601 timestamp when the user group was created.
`data[].createdBy`	`string` User identifier that created the user group.
`data[].updatedAt`	`string:date-time` ISO 8601 timestamp when the user group was last updated.
`data[].updatedBy`	`string` User identifier that last updated the user group.
`data[].cursor`	`integer` Latest event-ledger cursor projected into this user group record.
`page`	`object`
`page.limit`	`integer` Maximum number of records returned in this page.
`page.nextCursor`	`string \| null` Cursor to pass as the next request's cursor query parameter, or null when there are no more results.
`meta`	`object`
`meta.cursor`	`number \| null` Highest record cursor represented by this response.

Create a user group

POST/v1/teams/{teamId}/user-groups

Accepts a command to create a user group.

Required scopes: user_group:write

Parameters

`path.teamId`required	`string:uuid` Team identifier.
`header.Idempotency-Key`	`string:uuid` Optional caller-generated UUID used to make mutation retries safe. Reuse the same UUID only when retrying the same request.

Request body (application/json)

`name`required	`string`
`labelColor`	`string \| null`
`id`	`string:uuid` Optional caller-supplied user group ID. RoadOps generates one when omitted.

Response 202

`commandId`	`string:uuid` Command identifier accepted into the RoadOps command ledger.
`resourceId`	`string:uuid` Identifier of the resource targeted by the command.
`resourceType`	`string` Resource type targeted by the command.
`status`	`"applied"` Command dispatch status.
`aggregateVersion`	`integer` Aggregate version produced by the accepted command.
`cursor`	`integer` Event-ledger cursor for the accepted update. Refetch until returned records reach this cursor.
`links`	`object`
`links.refetch`	`string` Relative URL to refetch the affected resource.

Retrieve a user group

GET/v1/teams/{teamId}/user-groups/{userGroupId}

Returns one user group by ID.

Required scopes: user_group:read

Parameters

`path.teamId`required	`string:uuid` Team identifier.
`path.userGroupId`required	`string:uuid` User group identifier.

Response 200

`data`	`object`
`data.name`	`string`
`data.labelColor`	`string \| null`
`data.id`	`string:uuid`
`data.orgId`	`string:uuid`
`data.isDeleted`	`boolean`
`data.version`	`integer` Current user group aggregate version.
`data.createdAt`	`string:date-time` ISO 8601 timestamp when the user group was created.
`data.createdBy`	`string` User identifier that created the user group.
`data.updatedAt`	`string:date-time` ISO 8601 timestamp when the user group was last updated.
`data.updatedBy`	`string` User identifier that last updated the user group.
`data.cursor`	`integer` Latest event-ledger cursor projected into this user group record.
`meta`	`object`
`meta.cursor`	`integer` Highest record cursor represented by this response.

Update a user group

PATCH/v1/teams/{teamId}/user-groups/{userGroupId}

Accepts a command to update user group fields.

Required scopes: user_group:write

Parameters

`path.teamId`required	`string:uuid` Team identifier.
`path.userGroupId`required	`string:uuid` User group identifier.
`header.Idempotency-Key`	`string:uuid` Optional caller-generated UUID used to make mutation retries safe. Reuse the same UUID only when retrying the same request.

Request body (application/json)

`expectedVersion`	`integer` Optional aggregate version guard.
`name`	`string` Updated user group name.
`labelColor`	`string \| null` Updated user group label color as a 6 digit hex string, or null to clear it.

Response 202

`commandId`	`string:uuid` Command identifier accepted into the RoadOps command ledger.
`resourceId`	`string:uuid` Identifier of the resource targeted by the command.
`resourceType`	`string` Resource type targeted by the command.
`status`	`"applied"` Command dispatch status.
`aggregateVersion`	`integer` Aggregate version produced by the accepted command.
`cursor`	`integer` Event-ledger cursor for the accepted update. Refetch until returned records reach this cursor.
`links`	`object`
`links.refetch`	`string` Relative URL to refetch the affected resource.

Delete a user group

DELETE/v1/teams/{teamId}/user-groups/{userGroupId}

Accepts a command to delete a user group.

Required scopes: user_group:write

Parameters

`path.teamId`required	`string:uuid` Team identifier.
`path.userGroupId`required	`string:uuid` User group identifier.
`header.Idempotency-Key`	`string:uuid` Optional caller-generated UUID used to make mutation retries safe. Reuse the same UUID only when retrying the same request.

Request body (application/json)

`reason`	`string` Optional deletion reason.

Response 202

`commandId`	`string:uuid` Command identifier accepted into the RoadOps command ledger.
`resourceId`	`string:uuid` Identifier of the resource targeted by the command.
`resourceType`	`string` Resource type targeted by the command.
`status`	`"applied"` Command dispatch status.
`aggregateVersion`	`integer` Aggregate version produced by the accepted command.
`cursor`	`integer` Event-ledger cursor for the accepted update. Refetch until returned records reach this cursor.
`links`	`object`
`links.refetch`	`string` Relative URL to refetch the affected resource.

List user group members

GET/v1/teams/{teamId}/user-groups/{userGroupId}/members

Lists members assigned to a travel party.

Required scopes: user_group:read

Parameters

`path.teamId`required	`string:uuid` Team identifier.
`path.userGroupId`required	`string:uuid` User group identifier.
`query.limit`	`integer` Maximum number of records to return. Defaults to 50 and is capped at 200.
`query.cursor`	`string` Cursor returned by page.nextCursor from the previous list response.

Response 200

`data`	`object[]`
`data[].id`	`string:uuid` Stable user group membership identifier.
`data[].orgId`	`string:uuid` Team identifier.
`data[].groupId`	`string:uuid` Travel party identifier.
`data[].userId`	`string:uuid` RoadOps user identifier for the member.
`data[].memberName`	`string` Member display name visible to the caller.
`data[].givenName`	`string` Member first or given name visible to the caller.
`data[].familyName`	`string` Member last or family name visible to the caller.
`data[].memberEmail`	`string:email` Member email address visible to the caller.
`data[].memberPicture`	`string:uri` Member profile photo URL.
`data[].createdAt`	`string:date-time` ISO 8601 timestamp when the member was added.
`data[].createdBy`	`string` User identifier that added the member.
`data[].updatedAt`	`string:date-time` ISO 8601 timestamp when the membership was last updated.
`data[].updatedBy`	`string` User identifier that last updated the membership.
`data[].version`	`integer` Current user group membership version.
`data[].cursor`	`integer` Latest cursor represented by this user group membership record.
`page`	`object`
`page.limit`	`integer` Maximum number of records returned in this page.
`page.nextCursor`	`string \| null` Cursor to pass as the next request's cursor query parameter, or null when there are no more results.
`meta`	`object`
`meta.cursor`	`number \| null` Highest record cursor represented by this response.

Response: List user group members

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000942",
      "orgId": "00000000-0000-4000-8000-000000000100",
      "groupId": "00000000-0000-4000-8000-000000000941",
      "userId": "00000000-0000-4000-8000-000000000103",
      "memberName": "Taylor Jordan",
      "givenName": "Taylor",
      "familyName": "Jordan",
      "memberEmail": "taylor@example.com",
      "memberPicture": "https://assets.roadops.app/public/profiles/taylor.jpg",
      "createdBy": "00000000-0000-4000-8000-000000000101",
      "createdAt": "2026-09-01T12:00:00.000Z",
      "updatedBy": "00000000-0000-4000-8000-000000000101",
      "updatedAt": "2026-09-01T12:00:00.000Z",
      "version": 1,
      "cursor": 87235
    }
  ],
  "page": {
    "limit": 50,
    "nextCursor": null
  },
  "meta": {
    "cursor": 87234
  }
}

Add a user group member

POST/v1/teams/{teamId}/user-groups/{userGroupId}/members

Accepts a command to add an existing team member to a travel party.

Required scopes: user_group:write

Parameters

`path.teamId`required	`string:uuid` Team identifier.
`path.userGroupId`required	`string:uuid` User group identifier.
`header.Idempotency-Key`	`string:uuid` Optional caller-generated UUID used to make mutation retries safe. Reuse the same UUID only when retrying the same request.

Request body (application/json)

`userId`required	`string:uuid` RoadOps user identifier to add to the travel party. The user must already be a member of the team.

Response 202

`commandId`	`string:uuid` Command identifier accepted into the RoadOps command ledger.
`resourceId`	`string:uuid` Identifier of the resource targeted by the command.
`resourceType`	`string` Resource type targeted by the command.
`status`	`"applied"` Command dispatch status.
`aggregateVersion`	`integer` Aggregate version produced by the accepted command.
`cursor`	`integer` Event-ledger cursor for the accepted update. Refetch until returned records reach this cursor.
`links`	`object`
`links.refetch`	`string` Relative URL to refetch the affected resource.

Remove a user group member

DELETE/v1/teams/{teamId}/user-groups/{userGroupId}/members/{userId}

Accepts a command to remove a member from a travel party.

Required scopes: user_group:write

Parameters

`path.teamId`required	`string:uuid` Team identifier.
`path.userGroupId`required	`string:uuid` User group identifier.
`path.userId`required	`string:uuid` RoadOps user identifier for the member to remove.
`header.Idempotency-Key`	`string:uuid` Optional caller-generated UUID used to make mutation retries safe. Reuse the same UUID only when retrying the same request.

Response 202

`commandId`	`string:uuid` Command identifier accepted into the RoadOps command ledger.
`resourceId`	`string:uuid` Identifier of the resource targeted by the command.
`resourceType`	`string` Resource type targeted by the command.
`status`	`"applied"` Command dispatch status.
`aggregateVersion`	`integer` Aggregate version produced by the accepted command.
`cursor`	`integer` Event-ledger cursor for the accepted update. Refetch until returned records reach this cursor.
`links`	`object`
`links.refetch`	`string` Relative URL to refetch the affected resource.