Registering Entities

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 via the various Create and Bulk Create endpoints under DNA Sequences, AA Sequences, DNA Oligos, and Custom Entities.
2. Register existing entities via the various PATCH or Bulk Update endpoints under DNA Sequences, AA Sequences, DNA Oligos, and Custom Entities.
3. Register existing entities in a specific registry via the Bulk register entities endpoint.

📘

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 ([email protected]) 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.

Create endpoints

Entities can be created directly in the registry. To do this, specify the registryId param in the 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. In order to use the automatically generated names, provide a namingStrategy instead of providing the entityRegistryId.

In bulk create endpoints, the registryId and namingStrategy for all of the entities must be the same within the same request.

These endpoints will first check that the entities are all valid to be moved into the registry given the namingStrategy param value. If any entities fail validation, no files will be moved and errors describing invalid entities is returned. Only If all entities pass validation, the entities are moved into the registry.

Example
To create a DNA oligo via the API, and have an entityRegistryId specified for us:

curl -X POST "https://example.benchling.com/api/v2/dna-oligos" -H  "accept: application/json" -H  "Content-Type: application/json" -H  "Authorization: Basic <KEY>" --data-binary "@./request.txt"

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

{
  "aliases": [],
  "apiURL": "https://example.benchling.com/api/v2/dna-oligos/seq_Ytzc9F9w",
  "archiveRecord": null,
  "authors": [
    {
      "handle": "tom",
      "id": "ent_cbRGbWMt",
      "name": "Tom Benchling"
    }
  ],
  "bases": "tcaagaaggaccatgtggtcacgcttttcgttgggatctt",
  "createdAt": "2021-07-14T20:45:41.459328+00:00",
  "creator": {
    "handle": "geoff",
    "id": "ent_xJ3xGwm8",
    "name": "Geoffrey Benchling"
  },
  "customFields": {
    "Legacy ID": {
      "value": "STR100"
    }
  },
  "entityRegistryId": "JOLIGO037",
  "fields": {
    "Description": {
      "displayValue": null,
      "isMulti": false,
      "textValue": null,
      "type": "text",
      "value": null
    },
  },
  "folderId": null,
  "id": "seq_Ytzc9F9w",
  "length": 40,
  "modifiedAt": "2021-07-14T20:45:42.068701+00:00",
  "name": "Example Oligo",
  "nucleotideType": "DNA",
  "registrationOrigin": {
    "originEntryId": null,
    "registeredAt": "2021-07-14T20:45:41.459328+00:00"
  },
  "registryId": "src_JK1ktG3S",
  "schema": {
    "id": "ts_VeU9vV3v",
    "name": "Oligo"
  },
  "webURL": "https://example.benchling.com/example/f/lib_55UxcIps-registry/seq_Ytzc9F9w-example-oligo/edit"
}

From the interactive documentation:

Update endpoints

Existing entities can be registered by calling the appropriate PATCH endpoint for the respective schema type with the entityRegistryId field.

Bulk register endpoint

Existing entities can be registered by specifying the IDs of the existing entities you wish to register as value for param entityIds and a value for param namingStrategy.

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. Only if all entities pass validation, the entities are moved into the registry.

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

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\"}"

{
  "entityIds": [
    "seq_t87iJOGT,seq_hFdEBat5"
  ],
  "namingStrategy": "IDS_FROM_NAMES"
}

{
  "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 tasks endpoint for it:

curl -X GET "https://example.benchling.com/api/v2/tasks/45edd1c5-1e87-4f26-9e9a-fb55f7bf3f27" -H  "accept: application/json" -H  "Authorization: Basic <KEY>"

{
  "status": "RUNNING"
}

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

Using the interactive documentation:

Naming Strategies

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

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 over our events system 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.

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

{
  "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"
  }
}