---
title: "Create a custom entity"
method: POST
path: "/custom-entities"
tags: ["customEntities"]
---

# Create a custom entity

`POST /custom-entities`

## Request

- Base URL: `https://{tenant_name}.benchling.com/api/v2`
- URL: `https://{tenant_name}.benchling.com/api/v2/custom-entities`
- Auth: HTTP bearer

Create a custom entity

## Request body

- CustomEntityCreate
  - `aliases` string[]: Aliases to add to the custom entity
  - `authorIds` string[]: IDs of users to set as the custom entity's authors.
  - `customFields` CustomFields
  - `fields` Fields
  - `folderId` string: ID of the folder containing the entity. Can be left empty when registryId is present.
  - `name` string, required
  - `schemaId` string, required
  - `entityRegistryId` string: Entity registry ID to set for the registered entity. Cannot specify both entityRegistryId and namingStrategy at the same time.
  - `namingStrategy` 'NEW_IDS' | 'IDS_FROM_NAMES' | 'DELETE_NAMES' | 'SET_FROM_NAME_PARTS' | 'REPLACE_NAMES_FROM_PARTS' | 'KEEP_NAMES' | 'REPLACE_ID_AND_NAME_FROM_PARTS': 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
  - `registryId` string: Registry ID into which entity should be registered. this is the ID of the registry which was configured for a particular organization To get available registryIds, use the [/registries endpoint](https://docs.benchling.com/docs/api/v2/benchling-api/registry/list-registries) Required in order for entities to be created directly in the registry.

## Response `201`

Created

- CustomEntity
  - `aliases` string[]
  - `apiURL` string, uri: The canonical url of the Custom Entity in the API.
  - `archiveRecord` ArchiveRecord
    - `reason` string
  - `authors` UserSummary[]
    - `handle` string
    - `id` string
    - `name` string
  - `createdAt` string, date-time
  - `creator` CustomEntityCreator
    - `handle` string
    - `id` string
    - `name` string
  - `customFields` CustomFields
  - `entityRegistryId` string, nullable
  - `fields` Fields
  - `folderId` string, nullable
  - `id` string
  - `modifiedAt` string, date-time
  - `name` string
  - `registrationOrigin` RegistrationOrigin
    - `originEntryId` string, nullable
    - `registeredAt` string, date-time
  - `registryId` string, nullable
  - `schema` SchemaSummary
    - `id` string
    - `name` string
  - `url` string: The path of the web URL, omitting the tenant domain
  - `webURL` string

## Other responses

- `400`: Bad Request
- `503`: Deprecated, a 429 is returned for too many requests

---

[API](https://skmtc.dev/benchling/apis/benchling-api-2.md) - [All operations](https://skmtc.dev/benchling/apis/benchling-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/benchling/apis/benchling-api-2/revisions/01d2fa8523cd?raw)