Create an entity

Creates a new entity, sending entity data in the request body.

Two objects are required: general_data and EITHER user_data OR business_data but the objects can be empty. The user_data is required if general_data.entity_type is set to user, otherwise this field will be ignored. The business_data is required if general_data.entity_type is set to business, otherwise this field will be ignored.

NOTICE: Entity Type is will be optional soon.

If the /entities/create API is called for an entity that already exists in our system, it is treated it as an upsert and an update on the existing entity is performed. The response to the request will then contain the entry previously_existed: true.

Unit21 selectively ignores upserts if the request is identical to a previous request. The response to any ignored upsert will contain the field ignored: true.

If you want to perform strict validation and not perform an upsert on conflict, specifying options.upsert_on_conflict: false will result in the API responding with a 409 error code indicating that this entity cannot be overwritten.

Updates to an entity's general_data.entity_id are not allowed.

Instruments can be associated with entities by providing the IDs of these instruments within the instrument_ids section of the request. If the instrument doesn't already exist, Unit21 creates a placeholder instrument.

Whitelisted entities cannot be updated through the /entities/create endpoint.

We recommend that you create entities prior to running verification. In the event you wish to run a verification on an entity immediately, Unit21 recommends that you wait at-least 2 minutes for your entity data to be securely stored. You will receive a 423 error code if an entity is busy.

Follow the links for more information:

The response will consist of the following fields:

FieldTypeDescription
entity_idStringUnique identifier of the entity on your platform
unit21_idStringInternal ID of the entity within Unit21's system
previously_existedBooleanIf entity (with the same entity_id) already exists
Language
Authentication
Header
URL
Click Try It! to start a request and see the response here!