> 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

# BulkInsertDataItemReferences

# Package: cms

# Namespace: DataItemService

# Method link: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/bulk-insert-data-item-references.md

## Permission Scopes:
Write Data Items: SCOPE.DC-DATA.WRITE

## Introduction

Inserts one or more references in the specified fields of items in a collection.


This method adds one or more references to a collection.
Each new reference in the `dataItemReferences` field specifies a referring item's ID, the field in which to insert the reference, and the ID of the referenced item.

---

## REST API

### Schema

```
 Method: bulkInsertDataItemReferences
 Description: Inserts one or more references in the specified fields of items in a collection.   This method adds one or more references to a collection. Each new reference in the `dataItemReferences` field specifies a referring item's GUID, the field in which to insert the reference, and the GUID of the referenced item.
 URL: https://www.wixapis.com/wix-data/v2/bulk/items/insert-references
 Method: POST
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  dataCollectionId, dataItemReferences, dataItemReferences.referringItemFieldName, dataItemReferences.referringItemId, dataItemReferences.referencedItemId
 Method parameters: 
   param name: dataCollectionId | type: dataCollectionId | description: GUID of the collection containing the referring items. | required: true
   param name: dataItemReferences | type: array<dataItemReferences> | description: References to insert. | required: true
              - name: referringItemFieldName | type: string | description: Referring item field containing the references to the referenced items. | required: true
              - name: referringItemId | type: string | description: GUID of the referring item. | required: true
              - name: referencedItemId | type: string | description: GUID of the referenced item. | required: true
   param name: returnEntity | type: returnEntity | description: Whether to return the inserted data item references. When `true`, the `results` objects contain a `dataItemReference` field.  Default: `false` 
 Return type: BulkInsertDataItemReferencesResponse
  - name: results | type: array<BulkDataItemReferenceResult> | description: Information about the inserted references. 
     - name: action | type: BulkActionType | description: The action attempted for the reference. 
         - enum: UNKNOWN_ACTION_TYPE, INSERT, UPDATE, DELETE, PATCH
     - name: referenceMetadata | type: ItemMetadata | description: Metadata related to the reference for which the action was attempted. 
        - name: id | type: string | description: Item GUID. Does not appear if the item GUID is missing. For example, when item creation fails. 
        - name: originalIndex | type: integer | description: Original index of the item in the array specified in the request. Use this to match items in the request with those in the response. 
        - name: success | type: boolean | description: Whether the requested action was successful. When `false`, the `error` field is populated. 
        - name: error | type: ApplicationError | description: In case of failure, the error details. 
           - name: code | type: string | description: Error code. 
           - name: description | type: string | description: Description of the error. 
           - name: data | type: object | description: Data related to the error. 
     - name: dataItemReference | type: DataItemReference | description: The reference for which the action was attempted. Only returned if `returnEntity` is `true` in the request and the action is successful. 
        - name: referringItemFieldName | type: string | description: Referring item field containing the references to the referenced items. 
        - name: referringItemId | type: string | description: GUID of the referring item. 
        - name: referencedItemId | type: string | description: GUID of the referenced item. 
  - name: bulkActionMetadata | type: BulkActionMetadata | description: Bulk action metadata. 
     - name: totalSuccesses | type: integer | description: Number of items successfully processed. 
     - name: totalFailures | type: integer | description: Number of items that couldn't be processed. 


```

### Examples

### Bulk insert references and return inserted result
```curl
curl -X POST \
'https://www.wixapis.com/wix-data/v2/bulk/items/insert-references' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
    "dataCollectionId": "albums",
    "dataItemReferences": [
        {
            "referringItemFieldName": "songs",
            "referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105",
            "referencedItemId": "aafeaaf4-6192-4cc2-a79b-97ce0f1b3646"
        },
        {
            "referringItemFieldName": "songs",
            "referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105",
            "referencedItemId": "e7fe3827-5102-470a-a10a-b6221dd0b4a9"
        }
    ],
    "returnEntity": true
}'
```

### Bulk insert references
```curl
curl -X POST \
'https://www.wixapis.com/wix-data/v2/bulk/items/insert-references' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
    "dataCollectionId": "albums",
    "dataItemReferences": [
        {
            "referringItemFieldName": "songs",
            "referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105",
            "referencedItemId": "aafeaaf4-6192-4cc2-a79b-97ce0f1b3646"
        },
        {
            "referringItemFieldName": "songs",
            "referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105",
            "referencedItemId": "e7fe3827-5102-470a-a10a-b6221dd0b4a9"
        }
    ]
}'
```

---