Skip to navigation
Benchling APIStudy

Create Study

Create a study in a folder.

Always required

FieldDescription
descriptionDescription of the study. May be an empty string, up to 2048 characters.
folderIdTarget folder ID. List folders with the folder list endpoint.
A schema pairOne schema-fields pair, see below.

Schema fields

Provide exactly one of these pairs. Do not mix them:

  • schemaId with schemaFields (preferred). Keys in schemaFields must be field system names or field API IDs, not display names.
  • The deprecated studySchemaId with the deprecated tags. Keys in tags must be field display names or field API IDs.

List schemas with the study-schema list endpoint. See the request example for supported field value shapes.

name

  • Required when the study schema has no naming template.
  • Must be omitted when the schema has a naming template (the server generates the name).

designEntryId

  • Required when the schema’s studyType is CUSTOM.
  • Must be omitted for every other studyType.
  • Read studyType from the study-schema get-by-ID endpoint. List entries with the entry list endpoint. A design entry can belong to only one study.

displayId

Behavior depends on the schema’s idGenerationMode, which you can read from the study-schema get-by-ID endpoint:

  • AUTO_GENERATED_FROM_PREFIX: omit displayId. The server assigns an ID from the schema prefix. Providing displayId fails validation.
  • MANUAL: you may provide displayId (must be unique within the tenant), or omit it to have the server generate one.

authorIds

  • Omit to default authors to the creator.
  • Provide an array of user or app IDs to set a specific author list. List users with the user list endpoint.
  • Pass an empty array to create the study without authors.
  • Do not pass null.

The request example includes name, designEntryId, and displayId together for a Custom study on a MANUAL schema with no naming template. Other schema configurations require a different subset of these fields.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
descriptionstringRequired
folderIdstringRequired
The ID of the folder to create the study in.
authorIdslist of stringsOptional
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.
designEntryIdstringOptional
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.
displayIdstringOptional

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.

namestringOptional
The name of the study. Should be omitted if using a study schema with a naming template.
schemaFieldsmap from strings to objectsOptional
schemaIdstringOptional
The ID of the schema to associate with this object.
studySchemaIdstringOptionalDeprecated

Deprecated. Use schemaId instead. The ID of the study schema.

tagsmap from strings to anyOptionalDeprecated

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.

Response

Created
__typenamestringOptional
archiveReasonstring or nullOptional
archivedbooleanOptional
authorsstring or nullOptionalformat: "uri"
Users and apps designated as authors of the study.
createdAtstring or nullOptional
creatorobjectOptional
descriptionstring or nullOptional
designEntryobject or nullOptional
displayIdstring or nullOptional

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.

folderobjectOptional
idstringOptional
modifiedAtstring or nullOptional
namestringOptional
phaseenum or nullOptional
Allowed values:
schemaobject or nullOptional
schemaFieldslist of objects or nullOptional
studySchemaobjectOptional
Use schema instead. The schema of the study.
archiveDatetimestring or nullOptionalDeprecated
No longer supported.
archiveUserobject or nullOptionalDeprecated
No longer supported.

Errors

400
Study Create Request Bad Request Error
403
Study Create Request Forbidden Error
404
Study Create Request Not Found Error
409
Study Create Request Conflict Error
429
Study Create Request Too Many Requests Error
500
Study Create Request Internal Server Error