# Link Create or Update

**Link – Create or Update**

## Overview

Adds a new link in the given entity ID or updates an existing link.\
"Update link" will happen only for **mandatory links** or for **link types** where only one entity can be linked (for example, Parent).

***

## API URI

```bash
POST: /entities/{entityTypeId}/{entityId}/links?projectId=<projectId>
```

## URI Parameters

| Name         | In    | Required | Type   | Description                                        |
| ------------ | ----- | -------- | ------ | -------------------------------------------------- |
| entityTypeId | path  | True     | String | ‘id’ of the entity type for the given entity id    |
| entityId     | path  | True     | String | ‘id’ of the entity in which links need to be added |
| projectId    | query | True     | String | Project in which the given entity exists           |

***

## Request Payload

```json
{
  "linkType": "",
  "links": [
    {
      "<linkedEntityIdField>": "",
      "<linkedEntityTypeField>": "",
      "<linkCommentField>": "",
      "<externalLinkUrlField>": "",
      "<isExternalLinkField>": "true / false String",
      "<property1>": "value1",
      "<property2>": "value2"
    },
    {
      "<linkedEntityIdField>": "",
      "<linkedEntityTypeField>": "",
      "<linkCommentField>": "",
      "<externalLinkUrlField>": "",
      "<isExternalLinkField>": "true / false String",
      "<property1>": "value1",
      "<property2>": "value2"
    }
  ],
  "rankInfo": {
    "siblingEntity": {
      "internalId": "",
      "entityType": "",
      "scopeId": ""
    },
    "rankOperation": ""
  }
}
```

## Request Body

| Name         | Required | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------ | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **linkType** | True     | String | <p>The type of link for which links are to be added. E.g., <code>Parent</code>, <code>Child</code>, <code>Related</code>.<br><br><strong>Note:</strong> This is only applicable when connector supports rank feature:<br>- If connector supports rank and rank order type (given in <a href="entity-type-get">Entity Type – Get</a> API's <code>links.rank.orderType</code>) is either <code>HIERARCHY\_SINGLE</code> or <code>HIERARCHY\_MULTIPLE</code>, connector will need to handle additional link types <code>Hierarchy Parent</code> and <code>Hierarchy Child</code>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **links**    | True     | List   | <p>List of links to be added.<br>Each link in the list will have its properties as described below:<br>{<br><code>"\<linkedEntityIdField>"</code>: "The name will be the field name in which entity of the linked entity will come,and the value will be the entity id to which entityId coming in request URI need to be linked",<br><code>"\<linkedEntityTypeField>"</code>: "The name will be the field name in which entity type of linked entity will come,and the value will be the entity type of linked entity id",<br><code>"\<linkCommentField>"</code>: "Any comment that needs to be added in the link section.<br>Note: This is not a regular entity comment.Some connectors support having a separate note, i.e., a field with each link",<br><code>"\<externalLinkUrlField>"</code>: "The name will be the field name in which the external URL will come.<br>The value will be the URL of the external link that needs to be added",<br><code>"\<isExternalLinkField>"</code>: "The name will be a field name describing whether a link is internal or external.The value will be True if an external link needs to be added,<br>in which case, the connector only needs to add the link coming in the externalLinkUrlField field.If false, then a regular link to linkedEntityId needs to be added",<br><code>"\<property1>"</code>: "Any additional property that connector wants to set while adding or updating the link.<br>Such properties can be passed from the mapping interface in OpsHub",<br><code>"\<property2>"</code>: "Any additional property that connector wants to set while adding or updating the link.<br>Such properties can be passed from the mapping interface in OpsHub"<br>}</p> |
| **rankInfo** | False    | Object | <p>Only applicable when connector supports rank feature.<br>For move operations <code>MOVE\_BEFORE</code>, <code>MOVE\_AFTER</code>, and <code>MOVE\_BULK\_AFTER</code>, <code>siblingEntity</code> will also be provided.<br><br>Consider sibling entity as a reference entity to move the current entity before or after that.<br><code>{"siblingEntity": { "internalId: "", "entityType": "", "scopeId" : ""}, "rankOperation":"MOVE\_BEFORE/MOVE\_AFTER/LAST\_IN\_LIST/MOVE\_BULK\_AFTER" }</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

***

## Response Payload

Returns all the details of links added by the connector.

```json
[
  {
    "<linkTypeField>": "",
    "<linkedEntityIdField>": "",
    "<linkedEntityTypeField>": "",
    "<createdDateField>": "",
    "<createdByField>": "",
    "<linkCommentField>": "",
    "<externalLinkUrlField>": "",
    "<isExternalLinkField>": "true / false String",
    "<property1>": "value1",
    "<property2>": "value2"
  },
  {
    "<linkTypeField>": "",
    "<linkedEntityIdField>": "",
    "<linkedEntityTypeField>": "",
    "<createdDateField>": "",
    "<createdByField>": "",
    "<linkCommentField>": "",
    "<externalLinkUrlField>": "",
    "<isExternalLinkField>": "true / false String",
    "<property1>": "value1",
    "<property2>": "value2"
  }
]

```