> This page is for Developer Documentation.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.benchling.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.benchling.com/_mcp/server.

# Batch create Collaboration

POST https://{tenant_name}.benchling.com/api/v3/collaboration:batch-create
Content-Type: application/json

Batch create Collaboration synchronously in one transaction. Maximum 25 items per request.

Reference: https://docs.benchling.com/docs/api/benchling-api/collaboration/batchcreate

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Headers

- `EARLY-ACCESS` (string, optional) — Set to true to access beta operations via /api/v3.

### Body (application/json)

This endpoint expects an object.

- `items` (list of CreateCollaborationInput, required)

## Response

### 201

Created

- `items` (list of Collaboration, required)

## Errors

### 400 Collaboration Batch Create Request Bad Request Error

Bad Request

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 403 Collaboration Batch Create Request Forbidden Error

Forbidden

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 404 Collaboration Batch Create Request Not Found Error

Not Found

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 409 Collaboration Batch Create Request Conflict Error

Conflict

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 429 Collaboration Batch Create Request Too Many Requests Error

Too Many Requests

- `detail` (TooManyRequestsErrorBodyDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)
- `violated-policies` (list of enum, optional) — The budget policies that rejected the request, in canonical order: `user`, `integration`, then `tenant`.
  - Allowed values: `user`, `integration`, `tenant`

### 500 Collaboration Batch Create Request Internal Server Error

Internal Server Error

- `detail` (InternalServerErrorBodyDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `errorId` (string, optional)

## Types

### CreateCollaborationInput

- `accessPolicyId` (string, required)
- `collaborator` (CreateCollaborationInputCollaborator, required) — The collaborator to grant the policy to. Provide `role` for a group collaborator; omit it for a principal collaborator.
- `itemId` (string, required)
- `isAuditor` (boolean, optional)

### Collaboration

A Collaboration indicates that a Principal or Group is granted a Policy on a Resource. Some Collaborations represent Ownership, while others indicate that a Resource was shared with the Principal or Group.

- `__typename` (string, optional)
- `accessPolicy` (PolicyRef, optional)
- `collaboratorInfo` (CollaborationCollaboratorInfo, optional) — Union of PrincipalCollaboratorInfo, GroupCollaboratorInfo
- `createdAt` (string, optional)
- `fromOwnership` (boolean, optional)
- `id` (string, optional)
- `isAuditor` (boolean, optional)
- `modifiedAt` (string, optional)
- `resource` (CollaboratableRef, optional)

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

### CreateCollaborationInputCollaborator

The collaborator to grant the policy to. Provide `role` for a group collaborator; omit it for a principal collaborator.

### PolicyRef

- `__typename` (string, optional)
- `id` (string, optional)

### CollaborationCollaboratorInfo

Union of PrincipalCollaboratorInfo, GroupCollaboratorInfo

### CollaboratableRef

- `__typename` (string, optional)
- `id` (string, optional)

### PrincipalCollaboratorInput

- `collaboratorId` (string, required) — API ID of the principal collaborator.

### GroupCollaboratorInput

- `collaboratorId` (string, required) — API ID of the group collaborator.
- `role` (enum, required) — The role within the group this collaboration applies to.
  - Allowed values: `MEMBER`, `ADMIN`

### PrincipalCollaboratorInfo

Represents a Principal that is the subject for a Collaboration.

- `__typename` (string, optional)
- `collaborator` (PrincipalRef, optional)

### GroupCollaboratorInfo

Represents a Group that is the subject of a Collaboration, along with sub-group information. In Group Collaborations, the Resource may be shared with a sub-group of the Group, e.g. the Admins of a Team.

- `__typename` (string, optional)
- `collaborator` (Group, optional)
- `role` (enum, optional)
  - Allowed values: `MEMBER`, `ADMIN`

### PrincipalRef

- `__typename` (string, optional)
- `id` (string, optional)

### Group

### Organization

Represents a group of users within Benchling, typically corresponding to a company, department, or research group. Organizations provide a many-to-many relationship between users—each user can belong to multiple organizations, and each organization can have multiple users. Users are designated as either ADMIN (with management privileges) or MEMBER within the organization via `GroupMembership`. Organizations can own resources like Projects and Folders, and can contain Teams for finer-grained user grouping. Organizations also control access settings such as whether members can create personal ownables and what default policies apply to new resources. In the UI, organizations appear in user profiles and are used for sharing and access control throughout Benchling.

- `__typename` (string, optional)
- `createdAt` (string, optional)
- `handle` (string, optional)
- `id` (string, optional)
- `memberships` (string, optional)
- `modifiedAt` (string, optional)
- `name` (string, optional, nullable)

### Team

Represents a subgroup of users within an `Organization`, enabling finer-grained user management and data sharing. Teams belong to exactly one organization, and users may only join a team if they are already members of that team's parent organization. Each team member has either ADMIN or MEMBER role (see `GroupMembership`): admins can manage team membership, while members receive standard access. Unlike Organizations, teams cannot directly own Projects or Folders—they are used for collaboration and access control purposes. Teams can be configured with `provisionedCapabilities` to grant specific Benchling capabilities to members upon joining. The `membersAreAdministratorsOfSchemas` flag controls whether team members can create and update automation, result, and request schemas.

- `__typename` (string, optional)
- `createdAt` (string, optional)
- `description` (string, optional)
- `id` (string, optional)
- `membersAreAdministratorsOfSchemas` (boolean, optional) — Team members can create and update automation, result, and request schemas.
- `memberships` (string, optional)
- `modifiedAt` (string, optional)
- `name` (string, optional)
- `organization` (OrganizationRef, optional)

### OrganizationRef

- `__typename` (string, optional)
- `id` (string, optional)

## Examples

**Request**

```json
{
  "items": [
    {
      "accessPolicyId": "accessPolicyId",
      "collaborator": {
        "collaboratorId": "collaboratorId"
      },
      "itemId": "itemId"
    }
  ]
}
```

**Response**

```json
{
  "items": [
    {
      "__typename": "__typename",
      "createdAt": "createdAt",
      "fromOwnership": true,
      "id": "id",
      "isAuditor": true,
      "modifiedAt": "modifiedAt"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/collaboration:batch-create"

payload = { "items": [
        {
            "accessPolicyId": "accessPolicyId",
            "collaborator": { "collaboratorId": "collaboratorId" },
            "itemId": "itemId"
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://{tenant_name}.benchling.com/api/v3/collaboration:batch-create';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"items":[{"accessPolicyId":"accessPolicyId","collaborator":{"collaboratorId":"collaboratorId"},"itemId":"itemId"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```