> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

# Method name:

data.items.insert(dataCollectionId: string, item: any, options: WixDataInsertOptions)

# Method Link:

https://dev.wix.com/docs/sdk/data-items-sdk/data/items/insert.md

# Method Description:

Adds an item to a collection.

An item can only be inserted into an existing collection. You can create a new collection using the
Data Collections API.

The `insert()` method returns a Promise that resolves to the inserted item
after it has been added to the specified collection. The Promise is rejected
if the current user does not have "create" permissions for the collection or
the specified item includes an `_id` property whose value matches an
existing ID in the collection. Meaning, `insert()` cannot overwrite an
existing item in the collection.

Calling the `insert()` method triggers the [`beforeInsert()`](https://dev.wix.com/docs/velo/api-reference/wix-data/hooks/before-insert.md) and [`afterInsert()`](https://dev.wix.com/docs/velo/api-reference/wix-data/hooks/after-insert.md) hooks if they have been defined.

When inserting an item into a collection that has a reference field, set the
value of the reference field to the referenced item's `_id` value or the entire referenced item object.
When inserting an item into a collection that has a multi-reference field, set the
value of the multi-reference field to an array of the referenced items' `_id` values or an array of the
entire referenced item objects.
To save multi-reference values, specify `saveReferences: true` in the `options` object.

The `insert()` method adds the following properties and values to the item
when it adds it to the collection:
- `_id`: A unique identifier for an item in a collection, if the item
  doesn't have one or has one that is `undefined`. You can optionally provide
  your own ID. Once an ID is assigned to an item it cannot be changed.
- `_createdDate`: The date the item was added to the collection.
- `_updatedDate`: The date the item was modified. When the item is first
  added, the `_createdDate` and `_updatedDate` are the same.

Any valid JavaScript object can be added as a property value. The `insert()`
method maintains the structure of the specified object. For example, objects that contain nested objects, arrays, or arrays with nested objects are all added to the collection as defined.


> **Notes:**
> - The maximum size of an item that you can add to a collection is 500kb.
> - If an item's `_id` property value is set to `null` or an empty string, an error is thrown.
> - When creating a [single-item collection](https://support.wix.com/en/article/cms-adding-and-setting-up-a-single-item-collection), an item with the system field `_id` is pre-inserted into the collection. [Single-item collections](https://support.wix.com/en/article/cms-adding-and-setting-up-a-single-item-collection) may contain only one item.
> - If there is a pre-existing item in a [single-item collection](https://support.wix.com/en/article/cms-adding-and-setting-up-a-single-item-collection), the `insert()` method will not run. To update or change an item in a single-item collection see the `update()` and `save()` methods.
> - [Translatable collections](https://support.wix.com/en/article/wix-multilingual-translating-cms-collection-content) do not allow insertion and modification of items when working in a non-primary language. For example, if a collection's primary language is English, and the site visitor is viewing the site in French, calling `insert()` fails and issues an error.

# Method Permissions:

- Write Data Items

# Method Permissions Scopes IDs:

- SCOPE.DC-DATA.WRITE



# Method Code Examples:

## Insert an item into a collection

```javascript
import { items } from "@wix/data";

async function insertItem() {
  const toInsert = {
    "title":        "Mr.",
    "first_name":   "John",
    "last_name":    "Doe"
  };  
  const inserted = await items.insert("myCollection", toInsert);
  console.log(inserted); // See below
}

/*  item is:
 *
 *  {
 *    "_id":          "rifk4nrk-dj4o-djhe-oidk-fnoqw4oiglk4i",
 *    "_owner":       "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb",
 *    "_createdDate": "2017-05-24T12:33:18.938Z",
 *    "_updatedDate": "2017-05-24T12:33:18.938Z",
 *    "title":        "Mr.",
 *    "first_name":   "John",
 *    "last_name":    "Doe"
 *  }
 */
```



## Insert an item with a specified ID into a collection

```javascript
import { items } from "@wix/data";

async function insertItem() {
  const toInsert = {
    "_id":          "00001",
    "title":        "Mr.",
    "first_name":   "John",
    "last_name":    "Doe"
  };
  
  const inserted = await items.insert("myCollection", toInsert);
  console.log(inserted);
}
/*  item is:
 *
 *  {
 *    "_id":          "00001",
 *    "_owner":       "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb",
 *    "_createdDate": "2017-05-24T12:33:18.938Z",
 *    "_updatedDate": "2017-05-24T12:33:18.938Z",
 *    "title":        "Mr.",
 *    "first_name":   "John",
 *    "last_name":    "Doe"
 *  }
 */
```

## Insert an item including a reference to another item using the referenced item's ID

```javascript
import { items } from "@wix/data";

async function insertItem() {
  const countryId = "id-of-usa-item";
  
  const toInsert = {
    "title":        "Mr.",
    "first_name":   "John",
    "last_name":    "Doe",
    "country":      countryId
  };
  
  const inserted = await items.insert("myCollection", toInsert);
  console.log(inserted); // See below
}

/*  item is:
 *
 *  {
 *    "_id":          "rifk4nrk-dj4o-djhe-oidk-fnoqw4oiglk4i",
 *    "_owner":       "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb",
 *    "_createdDate": "2017-05-24T12:33:18.938Z",
 *    "_updatedDate": "2017-05-24T12:33:18.938Z",
 *    "title":        "Mr.",
 *    "first_name":   "John",
 *    "last_name":    "Doe",
 *    "country":      "id-of-usa-item"
 *  }
 */
```

## Insert an item including a reference to another item using the reference item

```javascript
import { items } from "@wix/data";

async function insertItem() {
  const countryItem = // Get country item
  
  const toInsert = {
    "title":        "Mr.",
    "first_name":   "John",
    "last_name":    "Doe",
    "country":      countryItem
  };
  
  const inserted = await items.insert("myCollection", toInsert);
  console.log(inserted); // See below
}

/*  item is:
 *
 *  {
 *    "_id":          "rifk4nrk-dj4o-djhe-oidk-fnoqw4oiglk4i",
 *    "_owner":       "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb",
 *    "_createdDate": "2017-05-24T12:33:18.938Z",
 *    "_updatedDate": "2017-05-24T12:33:18.938Z",
 *    "title":        "Mr.",
 *    "first_name":   "John",
 *    "last_name":    "Doe",
 *    "country":      "id-of-usa-item"
 *  }
 */
```

## Insert an item into a collection using a custom function

```javascript
import { items } from "@wix/data";

// Create an operation using insert() //

function createGreeting(language, greeting) {
  const toInsert = {
    language,
    greeting
  };

  return items.insert('Greetings', toInsert);
}

```

## default

```javascript
try {
      const result = await items.insert("collection-0.28758841360566656", {
          _id: "1ad20d72-f217-4663-b1c1-47fe7b9fcde5",
          name: "Sample Item",
          phone: "+972501234567",
          image: "https://static.wixstatic.com/media/503ea4_ed9a38760ae04aab86b47e82525fdcac~mv2.jpg",
          createdDate: Date.now(),
          updatedDate: Date.now()
      }, {
          suppressHooks: false
      });
      return result;
    } catch (error) {
      console.error(error);
      throw error;
   }
```