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

# Transfers into containers

POST https://{tenant_name}.benchling.com/api/v2/transfers
Content-Type: application/json

Transfers a volume of an entity or container into a destination container. Limit of 5000 transfers per request. Concentration of all contents in the destination container will be automatically updated based on the previous volume & concentrations of the contents in that container, the concentration of the contents being transferred in, the volume of the contents being transferred in, and the final volume of the container. If no concentration is specified, the concentration will not be tracked.


Reference: https://docs.benchling.com/docs/api/v2/benchling-api/containers/transfer-into-containers

## Authentication

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

## Request

### Body (application/json)

This endpoint expects a MultipleContainersTransfersList.

- `transfers` (list of MultipleContainersTransfer, required)

## Response

### 202

This endpoint launches a [long-running task](#/Tasks/getTask) and returns the Task ID of the launched task. The task response contains the full list of destination [containers](#/Containers/getContainer).

- `taskId` (string, optional)

## Errors

### 400 Bad Request Error

Bad Request

- `error` (BadRequestErrorError, optional)

## Types

### MultipleContainersTransfer

- `destinationContainerId` (string, required) — ID of container that will be transferred into.
- `restrictedSamplePartyIds` (list of string, optional) — IDs of users or teams to be set as restricted sample parties for the destination container. If not specified, restricted sample parties from the source container, if present, will be added to those of the destination container. This only applies to stand-alone containers.
- `restrictionStatus` (enum, optional) — Restriction status of the destination container, either RESTRICTED or UNRESTRICTED. If not specified, the restriction status of the destination container will be the more restrictive of the source container, if present, and destination container restriction statuses. This only applies to stand-alone containers (Plate wells are always set to NOT_APPLICABLE).
  - Allowed values: `RESTRICTED`, `UNRESTRICTED`, `NOT_APPLICABLE`
- `sampleOwnerIds` (list of string, optional) — IDs of users or teams to be set as sample owners for the destination container. If not specified, restricted sample parties from the source container, if present, will be added to those of the destination container. This only applies to stand-alone containers.
- `sourceBatchId` (string, optional) — ID of the batch that will be transferred in. Must specify one of sourceEntityId, sourceBatchId, or sourceContainerId.
- `sourceContainerId` (string, optional) — ID of the container that will be transferred in. Must specify one of sourceEntityId, sourceBatchId, or sourceContainerId.
- `sourceEntityId` (string, optional) — ID of the entity that will be transferred in. Must specify one of sourceEntityId, sourceBatchId, or sourceContainerId.
- `transferQuantity` (ContainerQuantity, optional) — This represents the quantity of the source to be transferred into the destination container. Supports mass, volume, and other quantities. Required in place of transferVolume.
- `transferVolume` (DeprecatedContainerVolumeForInput, optional) — Deprecated - use transferQuantity instead.
- `finalQuantity` (ContainerQuantity, optional) — Quantity of a container, well, or transfer. Supports mass, volume, and other quantities.
- `finalVolume` (DeprecatedContainerVolumeForInput, optional) — Desired volume for a container, well, or transfer. "volume" type keys are deprecated in API requests; use the more permissive "quantity" type key instead.
- `sourceConcentration` (Measurement, optional) — Concentration at which to transfer entities. Not applicable for container-to-container transfers (the concentration of the source container’s contents will be used).

### BadRequestErrorError

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

### ContainerQuantity

Quantity of a container, well, or transfer. Supports mass, volume, and other quantities.

- `units` (enum, optional, nullable)
  - Allowed values: `L`, `mL`, `uL`, `nL`, `pL`, `gal (US)`, `qt (US)`, `pt (US)`, `kg`, `g`, `mg`, `ug`, `ng`, `pg`, `lb`, `oz`, `mol`, `mmol`, `umol`, `nmol`, `pmol`, `cells`, `(x10^3) cells`, `(x10^4) cells`, `(x10^5) cells`, `(x10^6) cells`, `(x10^7) cells`, `(x10^8) cells`, `(x10^9) cells`, `items`, `units`
- `value` (double, optional, nullable)

### DeprecatedContainerVolumeForInput

Desired volume for a container, well, or transfer. "volume" type keys are deprecated in API requests; use the more permissive "quantity" type key instead.

- `units` (enum, optional, nullable)
  - Allowed values: `pL`, `nL`, `uL`, `mL`, `L`
- `value` (double, optional, nullable)

### Measurement

- `units` (string, required, nullable) — Can only be null if value is also null
- `value` (double, required, nullable) — Can only be null if units is also null

## Examples

**Request**

```json
{
  "transfers": [
    {
      "destinationContainerId": "string"
    }
  ]
}
```

**Response**

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

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v2/transfers"

payload = { "transfers": [{ "destinationContainerId": "string" }] }
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/transfers';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"transfers":[{"destinationContainerId":"string"}]}'
};

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