## Link a document to a record (tenant:dms:write)

`POST /api/dms/v1/documents/{id}/links`

Module: DMS · operationId: `addDocumentLink` · Tag: Links · Auth: access token (`Authorization: Bearer <accessToken>`)

Idempotent – an existing identical link is returned again. `STANDALONE` is not a link target (`400`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `targetType` (TargetType, required): Type of the linked record (case-insensitive); `STANDALONE` = no link (one of `CUSTOMER`, `SUPPLIER`, `DISTRIBUTOR`, `ADDRESS`, `ARTICLE`, `TRANSACTION`, `INVOICE`, `CONTRACT`, `EMPLOYEE`, `TRAVEL_REPORT`, `TICKET`, `WORK_ITEM`, `FORGE_ITEM`, `LEAD`, `OPPORTUNITY`, `CAMPAIGN`, `PROJECT`, `ASSET`, `STANDALONE`)
- `relationType` (string): Upper-cased by the server (default `"ATTACHMENT"`)
- `targetId` (string): Id of the record; required unless `STANDALONE` (max length 128)
- `targetModule` (string): Defaults to the module of the target type

Example:

```json
{
  "relationType": "CONTRACT",
  "targetId": "10042",
  "targetType": "CUSTOMER"
}
```

### Responses

- **201** The link (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 201 answer:

- `createdAt` (string (date-time), required): Creation time
- `createdBy` (string, required): Who created the link
- `customerNo` (string, required): Customer number of the tenant
- `documentId` (string (uuid), required): The linked document
- `id` (string (uuid), required): Link id
- `relationType` (string, required): Kind of relation, a free code (default ATTACHMENT)
- `targetId` (string, required): Id of the linked record
- `targetModule` (string, required): Module of the linked record
- `targetType` (string, required): Type of the linked record (see TargetType)
- `tenantName` (string, required): Tenant name

Example 201 answer:

```json
{
  "createdAt": "2026-09-30T08:40:12Z",
  "createdBy": "christina.adler@muster-it.example",
  "customerNo": "99999",
  "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
  "id": "6e8a0c2e-4f6a-4b8c-9d0e-2f4a6c8e0a2c",
  "relationType": "ATTACHMENT",
  "targetId": "70001",
  "targetModule": "masterdata",
  "targetType": "SUPPLIER",
  "tenantName": "DEMO"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/links' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"relationType":"CONTRACT","targetId":"10042","targetType":"CUSTOMER"}'
```
