> 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 Study

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

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

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

## Authentication

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

## Request

### Body (application/json)

This endpoint expects an object.

- `items` (list of CreateStudyInput, required)

## Response

### 201

Created

- `items` (list of Study, required)

## Errors

### 400 Study 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 Study 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 Study 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 Study 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 Study 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 Study 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

### CreateStudyInput

- `description` (string, required)
- `folderId` (string, required) — The ID of the folder to create the study in.
- `authorIds` (list of string, optional) — The IDs of the users or apps to set as study authors. Omit to default to the creator. Pass an empty array to create the study without authors.
- `designEntryId` (string, optional) — The ID of an entry to use as the study design entry. Optional for custom studies. Should always be omitted for all other study types.
- `displayId` (string, optional) — The ID to assign to the study. Only allowed when the study schema is configured for manual ID assignment (i.e., `idGenerationMode` is `MANUAL`). Must be unique within the tenant.
- `name` (string, optional) — The name of the study. Should be omitted if using a study schema with a naming template.
- `schemaFields` (map from string to FieldValueInput, optional)
- `schemaId` (string, optional) — The ID of the schema to associate with this object.
- `studySchemaId` (string, optional, deprecated) — Deprecated. Use `schemaId` instead. The ID of the study schema.
- `tags` (map from string to any, optional, deprecated) — Deprecated. Use `schemaFields` instead. Schema fields to set on the study. Must correspond with the study schema's field definitions. Every field should have its display name (not system name) or API ID as a key, mapping to the value of the field. See the example for the supported field value types and formatting. For date and datetime fields, use the RFC 3339 format. For single link fields, supply a single object specifying the id of the item you want to link, (eg. `{'targetFiles': [{'id': 'bfi_jdf8BV24'}]}`). For multi-link fields, supply an array of objects specifying the ids of the items you want to link, (eg. `{'targetFiles': [{'id': 'bfi_jdf8BV24'}, {'id': 'bfi_laGnl8vB'}]}`). Must be paired with the deprecated `studySchemaId`, not `schemaId`. Prefer `schemaId` with `schemaFields` instead.

### Study

A structured unit used to plan and organize research in Benchling. Each study progresses through phases (see `StudyPhase`) sequentially from design to execution to completion. The current phase determines what modifications are permitted on the study and its associated data.

- `__typename` (string, optional)
- `archiveReason` (string, optional, nullable)
- `archived` (boolean, optional)
- `authors` (string, optional, nullable) — Users and apps designated as authors of the study.
- `createdAt` (string, optional, nullable)
- `creator` (PrincipalRef, optional)
- `description` (string, optional, nullable)
- `designEntry` (EntryRef, optional, nullable)
- `displayId` (string, optional, nullable) — Human-readable identifier for the study. For schemas with auto-generated IDs, assigned by the server at creation. For MANUAL schemas, may be set at creation or update.
- `folder` (FolderRef, optional)
- `id` (string, optional)
- `modifiedAt` (string, optional, nullable)
- `name` (string, optional)
- `phase` (enum, optional, nullable)
  - Allowed values: `DESIGN`, `EXECUTION`, `COMPLETE`
- `schema` (StudySchemaRef, optional, nullable)
- `schemaFields` (list of SchemaFieldValue, optional, nullable)
- `studySchema` (StudySchemaRef, optional) — Use schema instead. The schema of the study.
- `archiveDatetime` (string, optional, nullable, deprecated) — No longer supported.
- `archiveUser` (PrincipalRef, optional, nullable, deprecated) — No longer supported.

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

### FieldValueInput

- `value` (any, required)

### PrincipalRef

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

### EntryRef

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

### FolderRef

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

### StudySchemaRef

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

### SchemaFieldValue

Represents a field value on a schematized object, pairing a `fieldDefinition` (describing the field's type and constraints) with its actual `value` (a `BenchlingValue` such as text, number, date, or link to another object). The value may be null if no value has been set. Used within the `schemaFields` collection on objects that implement `HasSchema` to provide access to all custom field values defined by the object's schema.

- `__typename` (string, optional)
- `fieldDefinition` (SchemaFieldDefinitionRef, optional)
- `id` (string, optional)
- `linkedEntityId` (string, optional, nullable)
- `value` (SchemaFieldValueValue, optional, nullable) — Union of BooleanValue, DateTimeValue, DateValue, DecimalValue, IntegerValue, JsonValue, ObjectLinkValue, ObjectLinkListValue, TextAndUrlValue, TextValue, ArrayValue

### SchemaFieldDefinitionRef

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

### SchemaFieldValueValue

### BooleanValue

A type that represents boolean values.

- `__typename` (string, optional)
- `value` (boolean, optional) — The boolean value.

### DateTimeValue

A type that represents datetime values.

- `__typename` (string, optional)
- `value` (string, optional) — The datetime value with UTC as the timezone.

### DateValue

A type that represents date values.

- `__typename` (string, optional)
- `value` (date, optional) — The date value.

### DecimalValue

A type that represents decimal value as strings.

- `__typename` (string, optional)
- `value` (string, optional, nullable) — The decimal value in a string representation
- `numericValue` (double, optional, nullable, deprecated) — Deprecated. The float representation of the decimal value.

### IntegerValue

A type that represents integer values.

- `__typename` (string, optional)
- `value` (integer, optional) — The integer value.

### JsonValue

A type that represents JSON values.

- `__typename` (string, optional)
- `value` (map from string to any, optional) — The JSON value.

### ObjectLinkValue

A type that represents links to other objects.

- `__typename` (string, optional)
- `value` (ObjectRef, optional) — The object that this value links to, or an Inaccessible object if not found with the current permission set.

### ObjectLinkListValue

A type that represents a list of links to other objects.

- `__typename` (string, optional)
- `value` (list of ObjectRef, optional) — The list of objects that this value links to. Inaccessible objects may be returned instead if the object is not found with the current permission set.

### TextAndUrlValue

A type that represents text (string) values with an associated URL.

- `__typename` (string, optional)
- `url` (string, optional) — The URL associated with the value. Please use `TextValue` if you don't want a URL.
- `value` (string, optional) — The text value. It may or may not be an empty string.

### TextValue

A type that represents text (string) values.

- `__typename` (string, optional)
- `value` (string, optional) — The text value. It may or may not be an empty string.

### ArrayValue

A type that represents a list of BenchlingValues, used for multi-value cells (e.g. alias columns).

- `__typename` (string, optional)
- `value` (list of ArrayValueValueItem, optional)

### ObjectRef

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

### ArrayValueValueItem

Union of BooleanValue, DateTimeValue, DateValue, DecimalValue, IntegerValue, JsonValue, ObjectLinkValue, ObjectLinkListValue, TextAndUrlValue, TextValue

## Examples

**Request**

```json
{
  "items": [
    {
      "description": "Study Description",
      "folderId": "lib_o2thOLlq",
      "authorIds": [
        "ent_a0SApq3z"
      ],
      "designEntryId": "etr_kT6BHBdZ",
      "displayId": "STUDY-001",
      "name": "Study Name",
      "schemaFields": {
        "boolean_field_system_name": {
          "value": true
        },
        "date_field_system_name": {
          "value": "2025-01-01"
        },
        "datetime_field_system_name": {
          "value": "2025-01-01T00:00:00Z"
        },
        "dropdown_field_system_name": {
          "value": "sfso_UcQuhAwx"
        },
        "entity_field_system_name": {
          "value": [
            "bfi_jdf8BV24",
            "bfi_laGnl8vB"
          ]
        },
        "inventory_field_system_name": {
          "value": "con_YvTFCWmh"
        },
        "json_field_system_name": {
          "value": {
            "key": "value"
          }
        },
        "number_field_system_name": {
          "value": 123
        },
        "text_field_system_name": {
          "value": "Text value"
        }
      },
      "schemaId": "stdysch_ztQQGSSF"
    }
  ]
}
```

**Response**

```json
{
  "items": [
    {
      "__typename": "__typename",
      "archiveReason": "archiveReason",
      "archived": true,
      "authors": "authors",
      "createdAt": "createdAt",
      "description": "description",
      "displayId": "displayId",
      "id": "id",
      "modifiedAt": "modifiedAt",
      "name": "name",
      "phase": "DESIGN",
      "schemaFields": [
        {}
      ]
    }
  ]
}
```

**SDK Code**

```python
import requests

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

payload = { "items": [
        {
            "description": "Study Description",
            "folderId": "lib_o2thOLlq",
            "authorIds": ["ent_a0SApq3z"],
            "designEntryId": "etr_kT6BHBdZ",
            "displayId": "STUDY-001",
            "name": "Study Name",
            "schemaFields": {
                "boolean_field_system_name": { "value": True },
                "date_field_system_name": { "value": "2025-01-01" },
                "datetime_field_system_name": { "value": "2025-01-01T00:00:00Z" },
                "dropdown_field_system_name": { "value": "sfso_UcQuhAwx" },
                "entity_field_system_name": { "value": ["bfi_jdf8BV24", "bfi_laGnl8vB"] },
                "inventory_field_system_name": { "value": "con_YvTFCWmh" },
                "json_field_system_name": { "value": { "key": "value" } },
                "number_field_system_name": { "value": 123 },
                "text_field_system_name": { "value": "Text value" }
            },
            "schemaId": "stdysch_ztQQGSSF"
        }
    ] }
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/study:batch-create';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"items":[{"description":"Study Description","folderId":"lib_o2thOLlq","authorIds":["ent_a0SApq3z"],"designEntryId":"etr_kT6BHBdZ","displayId":"STUDY-001","name":"Study Name","schemaFields":{"boolean_field_system_name":{"value":true},"date_field_system_name":{"value":"2025-01-01"},"datetime_field_system_name":{"value":"2025-01-01T00:00:00Z"},"dropdown_field_system_name":{"value":"sfso_UcQuhAwx"},"entity_field_system_name":{"value":["bfi_jdf8BV24","bfi_laGnl8vB"]},"inventory_field_system_name":{"value":"con_YvTFCWmh"},"json_field_system_name":{"value":{"key":"value"}},"number_field_system_name":{"value":123},"text_field_system_name":{"value":"Text value"}},"schemaId":"stdysch_ztQQGSSF"}]}'
};

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