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

# Register entities

POST https://{tenant_name}.benchling.com/api/v2/registries/{registry_id}:bulk-register-entities
Content-Type: application/json

Attempts to move entities into the registry. Limit of 2500 entities per request. 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 invalid entities is returned. If all entities pass validation, the entities are moved into the registry.


Reference: https://docs.benchling.com/docs/api/v2/benchling-api/registry/register-entities

## Authentication

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

## Request

### Path parameters

- `registry_id` (string, required) — ID for the registry

### Body (application/json)

This endpoint expects a RegisterEntities.

- `entityIds` (list of string, required) — Array of entity IDs
- `namingStrategy` (enum, required) — Specifies the behavior for automatically generated names when registering an entity. - NEW_IDS: Generate new registry IDs - IDS_FROM_NAMES: Generate registry IDs based on entity names - DELETE_NAMES: Generate new registry IDs and replace name with registry ID - SET_FROM_NAME_PARTS: Generate new registry IDs, rename according to name template, and keep old name as alias - REPLACE_NAMES_FROM_PARTS: Generate new registry IDs, and replace name according to name template - KEEP_NAMES: Keep existing entity names as registry IDs - REPLACE_ID_AND_NAME_FROM_PARTS: Generate registry IDs and names according to name template
  - Allowed values: `NEW_IDS`, `IDS_FROM_NAMES`, `DELETE_NAMES`, `SET_FROM_NAME_PARTS`, `REPLACE_NAMES_FROM_PARTS`, `KEEP_NAMES`, `REPLACE_ID_AND_NAME_FROM_PARTS`

## Response

### 202

This endpoint launches a [long-running task](#/Tasks/getTask) and returns the Task ID of the launched task. When successful, the task has an empty response. 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.

- `taskId` (string, optional)

## Errors

### 400 Bad Request Error

Bad Request

- `error` (BadRequestErrorError, optional)

## Types

### BadRequestErrorError

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

## Examples

**Request**

```json
{
  "entityIds": [
    "string"
  ],
  "namingStrategy": "NEW_IDS"
}
```

**Response**

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

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v2/registries/registry_id:bulk-register-entities"

payload = {
    "entityIds": ["string"],
    "namingStrategy": "NEW_IDS"
}
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/registries/registry_id:bulk-register-entities';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"entityIds":["string"],"namingStrategy":"NEW_IDS"}'
};

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