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

# Create and finalize a bulk assembly

POST https://{tenant_name}.benchling.com/api/v2-alpha/assemblies:create-and-finalize
Content-Type: application/json

Create and finalize a new bulk assembly in a single step.

Reference: https://docs.benchling.com/docs/api/v2-alpha/benchling-api-alpha/assemblies/create-and-finalize-assembly

## 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 an object.

- `assemblyParameters` (AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaAssemblyParameters, required) — Assembly-wide parameters to describe requirements and procedures for the assembly.
- `bins` (list of AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaBinsItems, required) — Bins are used to group fragments according to their position in the output construct or add a spacer (i.e. constant) region.
- `constructs` (list of AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaConstructsItems, required) — Output constructs that should be created.
- `fragments` (list of AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaFragmentsItems, required) — Fragments to be used in the assembly.
- `topology` (enum, required) — Whether the created constructs should be circular or linear.
  - Allowed values: `CIRCULAR`, `LINEAR`
- `folderId` (string, required) — API identifier of the folder in which the assembly should be created.
- `name` (string, required) — Name of the bulk assembly.
- `outputLocation` (AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaOutputLocation, required)

## 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. The task response contains a [finalized bulk assembly](#components/schemas/Assembly).

- `taskId` (string, optional)

## Errors

### 400 Bad Request Error

Bad Request

- `error` (BadRequestErrorError, optional)

## Types

### AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaAssemblyParameters

Assembly-wide parameters to describe requirements and procedures for the assembly.

- `type`: `CONCATENATION` (CONCATENATION)
  - `parameters` (AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaAssemblyParametersDiscriminatorMappingConcatenationParameters, required)
- `type`: `GIBSON` (GIBSON)
  - `parameters` (AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaAssemblyParametersDiscriminatorMappingGibsonParameters, required)
- `type`: `GOLDEN_GATE` (GOLDEN_GATE)
  - `parameters` (AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaAssemblyParametersDiscriminatorMappingGoldenGateParameters, required)
- `type`: `HOMOLOGY` (HOMOLOGY)
  - `parameters` (AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaAssemblyParametersDiscriminatorMappingHomologyParameters, required)

### AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaBinsItems

- `binType`: `CONSTANT` (CONSTANT)
  - `id` (string, required) — Unique identifier for the bin.
  - `name` (string, required)
  - `residues` (string, required) — Base pairs or amino acid residues for the spacer/constant.
- `binType`: `FRAGMENT` (FRAGMENT)
  - `id` (string, required) — Unique identifier for the bin.
  - `name` (string, required)
  - `fragmentProductionMethod` (enum, optional)
    - Allowed values: `EXISTING_CUT_SITES`, `EXISTING_HOMOLOGY_REGIONS`, `PRIMER_PAIR`

### AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaConstructsItems

- `fragments` (list of string, required) — Ordered list of fragment IDs to use in creating the construct, or a special option (SKIP) to indicate a bin should be skipped.
- `id` (string, required)

### AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaFragmentsItems

- `end` (double, required) — End position of the fragment in the provided input.
- `id` (string, required) — Unique identifier for the fragment.
- `orientation` (enum, required)
  - Allowed values: `FORWARD`, `REVERSE`
- `polymer` (AssemblyPolymerReference, required)
- `start` (double, required) — Start position of the fragment in the provided input.
- `binId` (string, required) — ID of the fragment's bin
- `preferredPrimer3Id` (string, optional) — API identifier of a Benchling oligo to be used as a primer at the 3' end of the fragment.
- `preferredPrimer5Id` (string, optional) — API identifier of a Benchling oligo to be used as a primer at the 5' end of the fragment.
- `restrictionEnzyme3Id` (string, optional) — ID of enzyme used to digest fragment at 3' end
- `restrictionEnzyme5Id` (string, optional) — ID of enzyme used to digest fragment at 5' end

### AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaOutputLocation

- `constructFolderId` (string, required) — API identifier of the folder in which to create the constructs
- `constructSchemaId` (string, optional) — API identifier of the schema to which the constructs should be assigned
- `fragmentFolderId` (string, optional) — API identifier of the folder in which to create the fragments, if any. If not specified, fragments will not be created.
- `fragmentSchemaId` (string, optional) — API identifier of the schema to which the constructs should be assigned. If specified, `fragmentFolderId` must also be specified.
- `primerFolderId` (string, optional) — API identifier of the folder in which to create the primers, if any. If not specified, primers will not be created as Benchling oligos, but will still be referencable in the context of the assembly, if they were designed.
- `primerSchemaId` (string, optional) — API identifier of the schema to which the primers should be assigned. If specified, `primerFolderId` must also be specified.

### BadRequestErrorError

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

### AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaAssemblyParametersDiscriminatorMappingConcatenationParameters

- `fragmentProductionMethod` (enum, required)
  - Allowed values: `SLICE`
- `polymerType` (enum, required)
  - Allowed values: `DNA`, `RNA`, `AA`

### AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaAssemblyParametersDiscriminatorMappingGibsonParameters

- `fragmentProductionMethod`: `EXISTING_CUT_SITES` (EXISTING_CUT_SITES)
  - `maximumHomologyAndBindingRegionLength` (double, required) — Maximum length, in base pairs, of the primer's binding/homology regions.
  - `minimumBindingRegionMeltingTemperature` (double, required) — Minimum melting temperature of the primer binding region.
  - `minimumHomologyAndBindingRegionLength` (double, required) — Minimum length, in base pairs, of the primer's binding/homology regions.
- `fragmentProductionMethod`: `EXISTING_HOMOLOGY_REGIONS` (EXISTING_HOMOLOGY_REGIONS)
  - `maximumHomologyAndBindingRegionLength` (double, required) — Maximum length, in base pairs, of the primer's binding/homology regions.
  - `minimumBindingRegionMeltingTemperature` (double, required) — Minimum melting temperature of the primer binding region.
  - `minimumHomologyAndBindingRegionLength` (double, required) — Minimum length, in base pairs, of the primer's binding/homology regions.
- `fragmentProductionMethod`: `PRIMER_PAIR` (PRIMER_PAIR)
  - `maximumHomologyAndBindingRegionLength` (double, required) — Maximum length, in base pairs, of the primer's binding/homology regions.
  - `maximumPrimerPairMeltingTemperatureDifference` (double, required) — Maximum difference of melting temperature between both primers in a pair.
  - `minimumBindingRegionMeltingTemperature` (double, required) — Minimum melting temperature of the primer binding region.
  - `minimumHomologyAndBindingRegionLength` (double, required) — Minimum length, in base pairs, of the primer's binding/homology regions.
  - `minimumPrimerMeltingTemperature` (double, required) — Minimum melting temperature of the whole primer.

### AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaAssemblyParametersDiscriminatorMappingGoldenGateParameters

- `fragmentProductionMethod`: `EXISTING_CUT_SITES` (EXISTING_CUT_SITES)
  - `type2SRestrictionEnzymeId` (string, required)
- `fragmentProductionMethod`: `PRIMER_PAIR` (PRIMER_PAIR)
  - `maximumPrimerPairMeltingTemperatureDifference` (double, required) — Maximum difference of melting temperature between both primers in a pair.
  - `minimumBindingRegionLength` (double, required) — Minimum length of the primer binding region.
  - `minimumBindingRegionMeltingTemperature` (double, required) — Minimum melting temperature of the primer binding region.
  - `preRecognitionSiteBases` (string, required) — Specific base pairs to insert before the type IIS enzyme recognition site.
  - `preRecognitionSiteLength` (double, required) — Number of base pairs to insert before the type IIS enzyme recognition site.
  - `type2SRestrictionEnzymeId` (string, required)

### AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaAssemblyParametersDiscriminatorMappingHomologyParameters

- `ambiguousConstructPreference` (enum, required)
  - Allowed values: `USE_LARGER_FRAGMENT_IN_FIRST_BIN`, `USE_SMALER_FRAGMENT_IN_FIRST_BIN`
- `fragmentProductionMethod` (enum, required)
  - Allowed values: `EXISTING_HOMOLOGY_REGIONS`

### AssemblyPolymerReference

- `polymerType`: `AA_SEQUENCE` (AA_SEQUENCE)
  - `proteinId` (string, required) — API identifier for the amino acid sequence.
- `polymerType`: `NUCLEOTIDE_SEQUENCE` (NUCLEOTIDE_SEQUENCE)
  - `sequenceId` (string, required) — API identifier for the nucleotide sequence.

## Examples

**Request**

```json
{
  "assemblyParameters": {
    "type": "GOLDEN_GATE",
    "parameters": {
      "fragmentProductionMethod": "EXISTING_CUT_SITES",
      "type2SRestrictionEnzymeId": "enz_Z1fxwlBi"
    }
  },
  "bins": [
    {
      "binType": "FRAGMENT",
      "id": "string",
      "name": "string"
    }
  ],
  "constructs": [
    {
      "fragments": [
        "string"
      ],
      "id": "string"
    }
  ],
  "fragments": [
    {
      "end": 1.1,
      "id": "string",
      "orientation": "FORWARD",
      "polymer": {
        "polymerType": "NUCLEOTIDE_SEQUENCE",
        "sequenceId": "seq_123"
      },
      "start": 1.1,
      "binId": "bin1"
    }
  ],
  "topology": "CIRCULAR",
  "folderId": "string",
  "name": "string",
  "outputLocation": {
    "constructFolderId": "string"
  }
}
```

**Response**

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

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v2-alpha/assemblies:create-and-finalize"

payload = {
    "assemblyParameters": {
        "type": "GOLDEN_GATE",
        "parameters": {
            "fragmentProductionMethod": "EXISTING_CUT_SITES",
            "type2SRestrictionEnzymeId": "enz_Z1fxwlBi"
        }
    },
    "bins": [
        {
            "binType": "FRAGMENT",
            "id": "string",
            "name": "string"
        }
    ],
    "constructs": [
        {
            "fragments": ["string"],
            "id": "string"
        }
    ],
    "fragments": [
        {
            "end": 1.1,
            "id": "string",
            "orientation": "FORWARD",
            "polymer": {
                "polymerType": "NUCLEOTIDE_SEQUENCE",
                "sequenceId": "seq_123"
            },
            "start": 1.1,
            "binId": "bin1"
        }
    ],
    "topology": "CIRCULAR",
    "folderId": "string",
    "name": "string",
    "outputLocation": { "constructFolderId": "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-alpha/assemblies:create-and-finalize';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"assemblyParameters":{"type":"GOLDEN_GATE","parameters":{"fragmentProductionMethod":"EXISTING_CUT_SITES","type2SRestrictionEnzymeId":"enz_Z1fxwlBi"}},"bins":[{"binType":"FRAGMENT","id":"string","name":"string"}],"constructs":[{"fragments":["string"],"id":"string"}],"fragments":[{"end":1.1,"id":"string","orientation":"FORWARD","polymer":{"polymerType":"NUCLEOTIDE_SEQUENCE","sequenceId":"seq_123"},"start":1.1,"binId":"bin1"}],"topology":"CIRCULAR","folderId":"string","name":"string","outputLocation":{"constructFolderId":"string"}}'
};

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