---
title: "Bulk upsert custom entities"
method: POST
path: "/custom-entities:bulk-upsert"
tags: ["customEntities"]
---

# Bulk upsert custom entities

`POST /custom-entities:bulk-upsert`

## Request

- Base URL: `https://{tenant_name}.benchling.com/api/v2`
- URL: `https://{tenant_name}.benchling.com/api/v2/custom-entities:bulk-upsert`
- Auth: HTTP bearer

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

Limit of 2500 custom entities per request.

## Request body

- CustomEntitiesBulkUpsertRequest
  - `customEntities` CustomEntityBulkUpsertRequest[], required
    - `archiveRecord` ArchiveRecordSet: Currently, we only support setting a null value for archiveRecord, which unarchives the item
    - `fields` FieldsWithResolution
    - `name` string, required
    - `registryId` string, required
    - `schemaId` string, required
    - `entityRegistryId` string, required: Registry ID of the entity in Benchling.
    - `aliases` string[]: Aliases to add to the custom entity
    - `authorIds` string[]: IDs of users to set as the custom entity's authors.
    - `customFields` CustomFields
    - `folderId` string: ID of the folder that the entity is moved into

## Response `202`

This endpoint launches a [long-running task](https://docs.benchling.com/docs/api/v2/benchling-api/tasks/get-task) and returns the Task ID of the launched task.
When successful, the task returns the resources of the objects that were upserted.

- AsyncTaskLink
  - `taskId` string

## Other responses

- `400`: Bad Request

---

[API](https://skmtc.dev/benchling/apis/benchling-api-2.md) - [All operations](https://skmtc.dev/benchling/apis/benchling-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/benchling/apis/benchling-api-2/revisions/01d2fa8523cd?raw)