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

# Registering Entities

## Overview

Registering an entity moves the entity into the organization's Registry. Entities in the Registry are validated and shared among the other members of the organization.

There are three ways to register an entity with the API:

1. Create and register in one call, with the [V3](/docs/v3-api-overview) create endpoints for each entity type, such as `POST /api/v3/dna-oligo`, `POST /api/v3/custom-entity`, and their `:batch-create` and `:bulk-create` variants.
2. Register existing entities with the V3 update endpoints, such as `PATCH /api/v3/dna-oligo/{id}`, `PATCH /api/v3/custom-entity/{id}`, and their `:batch-update` and `:bulk-update` variants.
3. Register existing entities of mixed types in a specific registry with the V2 [Bulk register entities](#bulk-register-endpoint) endpoint.

The first two approaches use the [V3 Python SDK](/docs/getting-started-with-the-v3-sdk). The same `registryId`, `namingStrategy`, and `entityRegistryId` fields exist on DNA sequences, AA sequences, RNA sequences, oligos, molecules, and proteins. The third approach has no V3 equivalent: V3 has no registry-scoped bulk registration endpoint, and `/api/v3/registry` is read-only. That section stays on V2.

> **Info**
>
> The V3 custom entity endpoints are stable. The V3 DNA oligo, DNA sequence, AA sequence, and registry endpoints are beta. Set `early_access="true"` on the client, as in the examples below, or send the `EARLY-ACCESS: true` header on raw HTTP requests. See the [V3 Stability Guidelines](/docs/stability-guidelines).

> **Info**
>
> **Enable Higher Registry Performance**
>
> If you are having issues with registry locks and / or performance when registering items in Benchling, please reach out to [Benchling support](https://help.benchling.com/hc/en-us/requests/new) and ask about granular locking for the Registry.
>
> Your Benchling representative can change the configuration of your Registry to allow for more parallel registration attempts which will also increase total throughput.

Every example below uses this client. Pass your tenant's root URL; the SDK adds `/api/v3` itself.

```python
from benchling_v3_sdk import Benchling

benchling = Benchling(
    base_url="https://example.benchling.com",
    api_key="<your-api-key>",
    early_access="true",
)
```

To register, you need the ID of the registry. The `registryId` must match the registry of the entity's schema. Copy it from the UI, or look it up by name:

```python
registry = next(iter(benchling.registry.list(name_any_of="Registry")))
print(registry.id)
```

Our registry ID is `src_JK1ktG3S`.

## Create endpoints

Entities can be created directly in the registry. To do this, pass `registry_id` (`registryId` in the request body). When an item is added to the registry, it receives a new ID called the `entityRegistryId`. The `entityRegistryId` can be provided directly with the entity or it can be generated automatically based on a naming strategy. To use the automatically generated names, provide a [`namingStrategy`](#naming-strategies) instead of the `entityRegistryId`; the two cannot be set together.

A `:batch-create` request creates up to 25 entities in a single transaction: if any entity fails validation, none are created and the errors describing the invalid entities are returned. For larger sets, use `:bulk-create`; see [Bulk Import](/docs/bulk-import). As in V2, every entity in one `:batch-create` or `:bulk-create` request must use the same `registryId` and `namingStrategy`; split entities that need different ones into separate requests.

**Example** To create a DNA oligo and have an `entityRegistryId` generated for us:

```python
from benchling_v3_sdk import FieldValueInput

oligo = benchling.dna_oligo.create(
    name="Example Oligo",
    folder_id="lib_55UxcIps",
    bases="tcaagaaggaccatgtggtcacgcttttcgttgggatctt",
    schema_id="ts_VeU9vV3v",
    author_ids=["ent_cbRGbWMt"],
    custom_fields={"Legacy ID": FieldValueInput(value="STR100")},
    registry_id="src_JK1ktG3S",
    naming_strategy="NEW_IDS",
)
print(oligo.entity_registry_id)  # for example, JOLIGO037
```

The SDK sends this request body to `POST /api/v3/dna-oligo`:

```json
{
  "name": "Example Oligo",
  "folderId": "lib_55UxcIps",
  "bases": "tcaagaaggaccatgtggtcacgcttttcgttgggatctt",
  "schemaId": "ts_VeU9vV3v",
  "authorIds": ["ent_cbRGbWMt"],
  "customFields": {
    "Legacy ID": {"value": "STR100"}
  },
  "registryId": "src_JK1ktG3S",
  "namingStrategy": "NEW_IDS"
}
```

The response is the created oligo. Its `entityRegistryId` holds the generated registry ID, and its `registry` names the registry it now belongs to.

## Update endpoints

Existing entities can be registered by calling the update endpoint for their entity type with a `registryId`, plus either a `namingStrategy` or an `entityRegistryId`. On an entity that is already registered, setting `entityRegistryId` changes its registry ID, and setting `registryId` to `null` unregisters it.

```python
benchling.custom_entity.update(
    "bfi_ELstHqON",
    registry_id="src_JK1ktG3S",
    naming_strategy="NEW_IDS",
)
```

To register up to 25 entities of one type in a single transaction, use `:batch-update`. This example registers two DNA sequences with the `IDS_FROM_NAMES` naming strategy:

```python
from benchling_v3_sdk import UpdateDnaSequenceInputWithPathParams

response = benchling.dna_sequence.batch_update(
    items=[
        UpdateDnaSequenceInputWithPathParams(
            id=sequence_id,
            registry_id="src_JK1ktG3S",
            naming_strategy="IDS_FROM_NAMES",
        )
        for sequence_id in ["seq_t87iJOGT", "seq_hFdEBat5"]
    ]
)
print([sequence.entity_registry_id for sequence in response.items])
```

For more than 25, write one `{"request_id": ..., "input_object": {"id": ..., "registryId": ..., "namingStrategy": ...}}` line per entity to a JSONL scratch file and call `:bulk-update`, as described in [Bulk Import](/docs/bulk-import).

## Bulk register endpoint

This endpoint is V2 only, and V3 won't get a direct replacement. It registers existing entities of any type in one call, by specifying the IDs of the entities as the value for param `entityIds` and a value for param [`namingStrategy`](#naming-strategies). In V3, the intended path is to group the entities by type and register each group by setting `registryId` with that type's `:batch-update` or `:bulk-update`, as shown above.

This endpoint will first check that the entities are all valid to be moved into the registry given the `namingStrategy`. If any entities fail validation, no files will be moved and errors describing the invalid entities are returned. Only if all entities pass validation are the entities moved into the registry.

**Example** Moving two entities to a registry identified by `src_JK1ktG3S`, using the `IDS_FROM_NAMES` naming strategy:

**`cURL`**

```bash title="cURL"
curl -X POST "https://example.benchling.com/api/v2/registries/src_JK1ktG3S:bulk-register-entities" -H  "accept: application/json" -H  "Content-Type: application/json" -H  "Authorization: Basic <KEY>" -d '{"entityIds":["seq_t87iJOGT","seq_hFdEBat5"],"namingStrategy":"IDS_FROM_NAMES"}'
```

**`Request body`**

```json title="Request body"
{
  "entityIds": [
    "seq_t87iJOGT",
    "seq_hFdEBat5"
  ],
  "namingStrategy": "IDS_FROM_NAMES"
}
```

**`Response`**

```json title="Response"
{
  "taskId": "6fa5d107-2a7a-4e4b-b850-dd03a47c3d5e"
}
```

The returned value in this example is a task ID that will complete in the background. If you need to check on its status, call the V2 tasks endpoint for it:

**`cURL`**

```bash title="cURL"
curl -X GET "https://example.benchling.com/api/v2/tasks/6fa5d107-2a7a-4e4b-b850-dd03a47c3d5e" -H  "accept: application/json" -H  "Authorization: Basic <KEY>"
```

**`Response`**

```json title="Response"
{
  "status": "RUNNING"
}
```

The `status` field in the response will be `SUCCEEDED` if the task completes successfully.

## Naming Strategies

The naming strategy specifies the behavior for how to name an entity and how to generate its registry ID when registering it.

| Naming strategy                  | Description                                                                                                                                                                                                                                                    |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEW_IDS`                        | Generates new registry IDs, and leaves entity name as-is                                                                                                                                                                                                       |
| `IDS_FROM_NAMES`                 | Converts entity name into registry ID. Conversion has the following rules: • If the name ends in a number, use the schema's prefix, followed by that number, as the registry ID • If the name does not end in a number, use the name as-is for the registry ID |
| `DELETE_NAMES`                   | Generates new registry IDs and sets entity name to new registry ID, and does not keep old names as aliases                                                                                                                                                     |
| `SET_FROM_NAME_PARTS`            | Generates new registry IDs and generates new entity name based on the entity schema's naming template, if one has been set. Old name is converted into an alias.                                                                                               |
| `REPLACE_NAMES_FROM_PARTS`       | Generates new registry IDs and generates new entity name based on the entity schema's naming template, if one has been set. Old name is deleted.                                                                                                               |
| `KEEP_NAMES`                     | Use entity name as registry ID                                                                                                                                                                                                                                 |
| `REPLACE_ID_AND_NAME_FROM_PARTS` | Generates new registry IDs and entity names based on the entity schema's naming template, if one has been set. Old name is deleted.                                                                                                                            |

## Registration Attempt Error

Benchling cannot always process two registration attempts within the same registry at the same time, so it's possible for the task to return an error response that indicates another attempt is already in progress and currently blocking this one. Benchling will automatically retry the task up to 3 times, and in the unlikely event that it is still failing, the task status will be `FAILED` and the error message will read:

> Another registration attempt is in progress. Please try again in a few moments. If this problem persists, please wait 1-2 minutes before trying again.

## Using Registration Events

Once an entity is registered, you can listen to the [`entity.registered` event](/docs/events-reference#v2-events-reference) over our [events system](/docs/events-getting-started) and add your own automation or logic to the registration of an entity. Some examples:

* Fill in extra schema fields
* Add metadata from external systems
* Link other entities

## Merging Duplicates

In some cases, Benchling will merge entities that are considered duplicates of existing registered entities. For information on when this will occur, [check out our help article](https://help.benchling.com/hc/en-us/articles/9684256435597).

When this case is encountered in the API, it will prompt that it needs a folder for the duplicate to live in:

```json
{
  "error": {
    "message": "Entity \"Example Oligo 3\" is a duplicate and will be merged. To proceed, please specify a folder for the duplicate to live in",
    "type": "invalid_request_error",
    "userMessage": "Entity \"Example Oligo 3\" is a duplicate and will be merged. To proceed, please specify a folder for the duplicate to live in"
  }
}
```