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

# Bulk upsert entities

POST https://{tenant_name}.benchling.com/api/v2-beta/entities:bulk-upsert
Content-Type: application/json

All entities and their schemas must be within the same registry.

This operation performs the following actions:

1. Any existing objects are looked up in Benchling by the provided entity registry ID.
2. Then, all objects are either created or updated accordingly, temporarily skipping any schema field links between objects.
3. Schema field links can be populated using entity registry IDs or API IDs. In the `value` field of the [Field](#/components/schemas/FieldWithResolution) resource, the object `{"entityRegistryId": ENTITY_REGISTRY_ID}` may be provided instead of the API ID if desired (see example value). You may link to objects being created in the same operation.
4. Entities are registered, using the provided name and entity registry ID.

If any action fails, the whole operation is canceled and no objects are created or updated.

Reference: https://docs.benchling.com/docs/api/v2-beta/benchling-api-beta/entities/bulk-upsert-entities

## Authentication

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

## Request

### Query parameters

- `returning` (string, optional) — Comma-separated list of fields to return. Modifies the output shape. To return all keys at a given level, enumerate them or use the wildcard, '*'. For more information, [click here](https://docs.benchling.com/docs/getting-started-1#returning-query-parameter).

### Body (application/json)

This endpoint expects an EntitiesBulkUpsertRequest.

- `aaSequences` (list of AaSequenceBulkUpsertRequest, optional)
- `customEntities` (list of CustomEntityBulkUpsertRequest, optional)
- `dnaOligos` (list of OligoBulkUpsertRequest, optional)
- `dnaSequences` (list of DnaSequenceBulkUpsertRequest, optional)
- `molecules` (list of MoleculeBulkUpsertRequest, optional)
- `rnaOligos` (list of OligoBulkUpsertRequest, optional)

## Response

### 202

This endpoint launches a [long-running task](#/Tasks/getTask) and returns the Task ID of the launched task. When successful, the task returns the resources of the objects that were upserted.

- `taskId` (string, optional)

## Errors

### 400 Bad Request Error

Bad Request

- `error` (BadRequestErrorError, optional)

## Types

### AaSequenceBulkUpsertRequest

- `name` (string, required) — Name of the AA sequence.
- `registryId` (string, required)
- `schemaId` (string, required) — ID of the AA sequence's schema.
- `entityRegistryId` (string, required) — Registry ID of the entity in Benchling.
- `aminoAcids` (string, required) — Amino acids for the AA sequence.
- `annotations` (list of AaAnnotation, required) — Annotations to create on the AA sequence.
- `archiveRecord` (ArchiveRecordSet, optional) — Currently, we only support setting a null value for archiveRecord, which unarchives the item
- `fields` (map from string to FieldWithResolution, optional) — Fields to set on the AA sequence. Must correspond with the schema's field definitions. Every field should have its name as a key, mapping to an object with information about the value of the field.
- `aliases` (list of string, optional) — Aliases to add to the AA sequence
- `authorIds` (list of string, optional) — IDs of users to set as the AA sequence's authors.
- `customFields` (map from string to CustomField, optional) — Custom fields to add to the AA sequence. Every field should have its name as a key, mapping to an object with information about the value of the field.
- `folderId` (string, optional) — ID of the folder containing the AA sequence.

### CustomEntityBulkUpsertRequest

- `name` (string, required)
- `registryId` (string, required)
- `schemaId` (string, required)
- `entityRegistryId` (string, required) — Registry ID of the entity in Benchling.
- `archiveRecord` (ArchiveRecordSet, optional) — Currently, we only support setting a null value for archiveRecord, which unarchives the item
- `fields` (map from string to FieldWithResolution, optional) — Schema fields to set on the custom entity. Must correspond with the schema's field definitions. Every field should have its name as a key, mapping to an object with information about the value of the field.
- `aliases` (list of string, optional) — Aliases to add to the custom entity
- `authorIds` (list of string, optional) — IDs of users to set as the custom entity's authors.
- `customFields` (map from string to CustomField, optional) — Custom fields to add to the custom entity. Every field should have its name as a key, mapping to an object with information about the value of the field.
- `folderId` (string, optional) — ID of the folder that the entity is moved into

### OligoBulkUpsertRequest

- `name` (string, required) — Name of the Oligo.
- `registryId` (string, required)
- `schemaId` (string, required) — ID of the oligo's schema.
- `entityRegistryId` (string, required) — Registry ID of the entity in Benchling.
- `archiveRecord` (ArchiveRecordSet, optional) — Currently, we only support setting a null value for archiveRecord, which unarchives the item
- `fields` (map from string to FieldWithResolution, optional) — Fields to set on the Oligo. Must correspond with the schema's field definitions. Every field should have its name as a key, mapping to an object with information about the value of the field.
- `aliases` (list of string, optional) — Aliases to add to the Oligo
- `authorIds` (list of string, optional) — IDs of users to set as the Oligo's authors.
- `bases` (string, optional) — Base pairs of the oligo.
- `customFields` (map from string to CustomField, optional) — Custom fields to add to the Oligo. Every field should have its name as a key, mapping to an object with information about the value of the field.
- `folderId` (string, optional) — ID of the folder containing the Oligo.

### DnaSequenceBulkUpsertRequest

- `name` (string, required) — Name of the DNA sequence.
- `registryId` (string, required)
- `schemaId` (string, required) — ID of the DNA sequence's schema.
- `entityRegistryId` (string, required) — Registry ID of the entity in Benchling.
- `annotations` (list of DnaAnnotation, required) — Annotations to create on the DNA sequence.
- `bases` (string, required) — Base pairs for the DNA sequence.
- `isCircular` (boolean, required) — Whether the DNA sequence is circular or linear.
- `primers` (list of Primer, required)
- `archiveRecord` (ArchiveRecordSet, optional) — Currently, we only support setting a null value for archiveRecord, which unarchives the item
- `fields` (map from string to FieldWithResolution, optional) — Fields to set on the DNA sequence. Must correspond with the schema's field definitions. Every field should have its name as a key, mapping to an object with information about the value of the field.
- `aliases` (list of string, optional) — Aliases to add to the DNA sequence
- `authorIds` (list of string, optional) — IDs of users to set as the DNA sequence's authors.
- `customFields` (map from string to CustomField, optional) — Custom fields to add to the DNA sequence. Every field should have its name as a key, mapping to an object with information about the value of the field.
- `folderId` (string, optional) — ID of the folder containing the DNA sequence.
- `parts` (list of DnaSequencePart, optional)
- `translations` (list of Translation, optional) — Translations to create on the DNA sequence. Translations are specified by either a combination of 'start' and 'end' fields, or a list of regions. Both cannot be provided.

### MoleculeBulkUpsertRequest

- `name` (string, required) — Name of the Molecule.
- `registryId` (string, required)
- `schemaId` (string, required) — ID of the Molecule's schema.
- `entityRegistryId` (string, required) — Registry ID of the entity in Benchling.
- `chemicalStructure` (MoleculeStructure, required) — Chemical structure of the Molecule.
- `archiveRecord` (ArchiveRecordSet, optional) — Currently, we only support setting a null value for archiveRecord, which unarchives the item
- `fields` (map from string to FieldWithResolution, optional) — Fields to set on the Molecule. Must correspond with the schema's field definitions. Every field should have its name as a key, mapping to an object with information about the value of the field.
- `aliases` (list of string, optional) — Aliases to add to the Molecule.
- `authorIds` (list of string, optional) — IDs of users to set as the Molecule's authors.
- `customFields` (map from string to CustomField, optional) — Custom fields to add to the Molecule. Every field should have its name as a key, mapping to an object with information about the value of the field.
- `folderId` (string, optional) — ID of the folder containing the Molecule.

### BadRequestErrorError

- `message` (string, optional)
- `type` (enum, optional)
  - Allowed values: `invalid_request_error`
- `userMessage` (string, optional)

### AaAnnotation

- `color` (string, optional)
- `end` (integer, optional) — 0-based exclusive end index. The end of the AA sequence is always represented as 0.
- `id` (string, optional)
- `name` (string, optional)
- `notes` (string, optional)
- `start` (integer, optional) — 0-based inclusive start index.
- `type` (string, optional)

### ArchiveRecordSet

Currently, we only support setting a null value for archiveRecord, which unarchives the item

### FieldWithResolution

- `value` (FieldWithResolutionValue, required, nullable) — For single link fields, use the id of the item you want to link (eg. "seq_jdf8BV24"). For multi-link fields, use an array of ids of the items you want to link (eg. ["seq_jdf8BV24"])
- `displayValue` (string, optional, nullable)
- `isMulti` (boolean, optional)
- `textValue` (string, optional, nullable)
- `type` (enum, optional)
  - Allowed values: `dna_sequence_link`, `aa_sequence_link`, `custom_entity_link`, `entity_link`, `mixture_link`, `molecule_link`, `dropdown`, `part_link`, `translation_link`, `aa_part_link`, `base_molecule_link`, `blob_link`, `text`, `long_text`, `batch_link`, `storage_link`, `entry_link`, `assay_request_link`, `assay_result_link`, `assay_run_link`, `boolean`, `float`, `integer`, `datetime`, `date`, `json`

### CustomField

- `value` (string, optional)

### DnaAnnotation

- `color` (string, optional) — Hex color code used when displaying this feature in the UI.
- `customFields` (list of SequenceFeatureCustomField, optional)
- `name` (string, optional)
- `notes` (string, optional)
- `end` (integer, optional) — 0-based exclusive end index. The end of the sequence is always represented as 0.
- `start` (integer, optional) — 0-based inclusive start index.
- `strand` (integer, optional)
- `type` (string, optional)

### Primer

- `bases` (string, optional)
- `bindPosition` (integer, optional)
- `color` (string, optional)
- `end` (integer, optional) — 0-based exclusive end index. The end of the sequence is always represented as 0.
- `name` (string, optional)
- `oligoId` (string, optional)
- `overhangLength` (integer, optional)
- `start` (integer, optional) — 0-based inclusive start index.
- `strand` (integer, optional)

### DnaSequencePart

- `end` (integer, optional) — 0-based exclusive end index. The end of the sequence is always represented as 0.
- `sequenceId` (string, optional)
- `start` (integer, optional) — 0-based inclusive start index.
- `strand` (integer, optional)

### Translation

- `color` (string, optional) — Hex color code used when displaying this feature in the UI.
- `customFields` (list of SequenceFeatureCustomField, optional)
- `name` (string, optional)
- `notes` (string, optional)
- `aminoAcids` (string, optional)
- `coerceStartCodonToMethionine` (boolean, optional, default: false) — Whether to override the translation of the start codon to Methionine. Has no effect when the start codon already translates to Methionine.
- `end` (integer, optional) — 0-based exclusive end index. The end of the sequence is always represented as 0.
- `geneticCode` (enum, optional, default: STANDARD) — The genetic code to use when translating the nucleotide sequence into amino acids.
  - Allowed values: `STANDARD`, `VERTEBRATE_MITOCHONDRIAL`, `YEAST_MITOCHONDRIAL`, `MOLD_PROTOZOAN_COELENTERATE_MITOCHONDRIAL_MYCOPLASMA_SPIROPLASMA`, `INVERTEBRATE_MITOCHONDRIAL`, `CILIATE_DASYCLADACEAN_HEXAMITA_NUCLEAR`, `ECHINODERM_FLATWORM_MITOCHONDRIAL`, `EUPLOTID_NUCLEAR`, `BACTERIAL_ARCHAEAL_PLANT_PLASTID`, `ALTERNATIVE_YEAST_NUCLEAR`, `ASCIDIAN_MITOCHONDRIAL`, `ALTERNATIVE_FLATWORM_MITOCHONDRIAL`, `CHLOROPHYCEAN_MITOCHONDRIAL`, `TREMATODE_MITOCHONDRIAL`, `SCENEDESMUS_OBLIQUUS_MITOCHONDRIAL`, `THRAUSTOCHYTRIUM_MITOCHONDRIAL`, `RHABDOPLEURIDAE_MITOCHONDRIAL`, `CANDIDATE_DIVISION_SR1_GRACILIBACTERIA`, `PACHYSOLEN_TANNOPHILUS_NUCLEAR`, `MESODINIUM_NUCLEAR`, `PERITRICH_NUCLEAR`, `CEPHALODISCIDAE_MITOCHONDRIAL_UAA_TYR`
- `regions` (list of TranslationRegionsItems, optional)
- `start` (integer, optional) — 0-based inclusive start index.
- `strand` (integer, optional)

### MoleculeStructure

- `structureFormat` (enum, optional) — Format of the chemical structure. - smiles - molfile
  - Allowed values: `smiles`, `molfile`
- `value` (string, optional) — Chemical structure in SMILES or molfile format. Pass an empty SMILES string to create a Molecule with no defined structure (equivalent to leaving the structure blank in the app's sketcher).

### FieldWithResolutionValue

For single link fields, use the id of the item you want to link (eg. "seq_jdf8BV24"). For multi-link fields, use an array of ids of the items you want to link (eg. ["seq_jdf8BV24"])

### SequenceFeatureCustomField

A name and value pair associated with a sequence feature (annotation or translation). For genbank imports, these are the qualifiers associated with each feature.

- `name` (string, optional) — Name of the custom field
- `value` (string, optional) — Value of the custom field

### TranslationRegionsItems

- `end` (integer, optional) — 0-based exclusive end index. The end of the sequence is always represented as 0.
- `start` (integer, optional) — 0-based inclusive start index.

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "taskId": "string"
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v2-beta/entities:bulk-upsert"

payload = {}
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/v2-beta/entities:bulk-upsert';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};

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