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

# Transfer into container

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

Transfers a volume of an entity or container into a destination container.
Transfering a volume is cumulative with the existing destination container's contents. To transfer an entire container's contents, the sourceContainerId should be specified. To otherwise transfer multiple entities within a container, you can make multiple calls to this endpoint, specifying a single entity with each call.


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

## Authentication

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

## Request

### Path parameters

- `destination_container_id` (string, required)

### Body (application/json)

This endpoint expects a ContainerTransfer.

- `destinationContents` (list of ContainerTransferDestinationContentsItem, required) — This represents what the contents of the destination container should look like post-transfer.
- `destinationQuantity` (ContainerQuantity, optional) — This represents the desired final quantity of the destination container, post-dilution. If you don't want to dilute the destination container, you can omit this parameter. Supports mass, volume, and other quantities.
- `destinationVolume` (DeprecatedContainerVolumeForInput, optional) — Deprecated - use destinationQuantity instead.
- `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.

## Response

### 200

OK

## Errors

### 400 Bad Request Error

Bad Request

- `error` (BadRequestErrorError, optional)

### 403 Forbidden Error

Forbidden

- `error` (ForbiddenRestrictedSampleErrorError, optional)

## Types

### ContainerTransferDestinationContentsItem

- `entityId` (string, required)
- `concentration` (Measurement, 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)

### BadRequestErrorError

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

### ForbiddenRestrictedSampleErrorError

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

### 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
{
  "destinationContents": [
    {
      "entityId": "string"
    }
  ]
}
```

**Response**

```json
{}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v2/containers/destination_container_id:transfer"

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

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