---
title: "Link documents"
method: POST
path: "/documents/{document}/linked-documents"
tags: ["Document Operations"]
---

# Link documents

`POST /documents/{document}/linked-documents`

<small>Requires an API token with the **Document Manager** role.</small>

Creates a relationship between the [document](/#documents) referred to by the URL and another document. Allows
representing relationships such as parent-child, amendment, renewal, etc. between documents.

The values that are sent in the request body will be normalised to create a "document relationship" where one
of the documents is the "controller document" and the other is the "peripheral document". The resulting
normalised relationship type will be one of the values defined in the
[DocumentRelationshipType](/schemas/DocumentRelationshipType) enum. The normalised form of the relationship is
what is returned in the response.

The following table shows how the different relationship types will be normalised and which role each of the
documents will end up playing in the resulting relationship:

| Request `relationship_type` | Normalised type | URL document's role | Other document's role |
|---------------------|-----------------|-------------------|---------------------|
| `parent_of` | `parent` | controller_document | peripheral_document |
| `child_of` | `parent` | peripheral_document | controller_document |
| `amendment_to` | `amendment` | controller_document | peripheral_document |
| `amended_by` | `amendment` | peripheral_document | controller_document |
| `renewal_of` | `renewal` | controller_document | peripheral_document |
| `renewed_by` | `renewal` | peripheral_document | controller_document |
| `addition_to` | `addition` | controller_document | peripheral_document |
| `added_to_by` | `addition` | peripheral_document | controller_document |
| `replacement_of` | `replacement` | controller_document | peripheral_document |
| `replaced_by` | `replacement` | peripheral_document | controller_document |
| `termination_of` | `termination` | controller_document | peripheral_document |
| `terminated_by` | `termination` | peripheral_document | controller_document |

## Path parameters

- `document` string, required

## Request body

- StoreDocumentRelationshipRequest
  - `other_document_uuid` string, uuid, required — UUID of the document to link to
  - `relationship_type` 'parent_of' | 'child_of' | 'amendment_to' | 'amended_by' | 'renewal_of' | 'renewed_by' | 'addition_to' | 'added_to_by' | 'replacement_of' | 'replaced_by' | 'termination_of' | 'terminated_by', required

## Response `201`

`DocumentRelationshipResource`

- object
  - `data` DocumentRelationshipResource, required
    - `uuid` string, required
    - `controller_document` DocumentMinimalResource, required
      - `uuid` string, required
      - `name` string, required
      - `origin` 'signed_pdf' | 'signed_pdf_external_account' | 'template' | 'scratch' | 'onboarding' | 'pdf', required
      - `stage` 'draft' | 'approved_draft' | 'review' | 'approved_review' | 'signing' | 'done', required
      - `locale` string, nullable, required
      - `template_uuid` string, required — UUID of the [template](/#templates) the document was created from, if any
      - `created_at` string, date-time, nullable, required
      - `updated_at` string, date-time, nullable, required
      - `archived_at` string, date-time, nullable, required
      - `parties` DocumentPartySnippetResource[], required — The people and/or organizations that will be involved in signing the document
        - `uuid` string, required
        - `ref_uuid` string, required — If the document containing this party was created from a template, this identifier will be the same as the `ref_uuid` of the corresponding party in the source template.
        - `reference` string, nullable, required — A generic reference for the party
        - `entity_name` string, nullable, required — The actual name of the party. May be null if the party was created via a Template's "set later" option
        - `address` string, nullable, required
        - `scope` 'internal' | 'internal_and_external', required
        - `is_internal_party` boolean, required — Indicates whether this party is linked to an account party (internal) or is standalone (external)
        - `is_ready_for_signing` boolean, required — `true` indicates that an external party has indicated they are ready to sign
        - `ready_for_signing_at` string, date-time, nullable, required
        - `created_at` string, date-time, nullable, required
        - `updated_at` string, date-time, nullable, required
      - `links` object, required
        - `show` string, required — Link to [Show document](/operations/v1.documents.show)
        - `latest_revision_pdf` string, required — Link to [show latest revision PDF details](/operations/v1.documents.revisions.latest.pdf.show)
        - `latest_revision_pdf_download` string, required — Link to [download latest revision PDF](/operations/v1.documents.revisions.latest.pdf.download)
    - `peripheral_document` DocumentMinimalResource, required
      - `uuid` string, required
      - `name` string, required
      - `origin` 'signed_pdf' | 'signed_pdf_external_account' | 'template' | 'scratch' | 'onboarding' | 'pdf', required
      - `stage` 'draft' | 'approved_draft' | 'review' | 'approved_review' | 'signing' | 'done', required
      - `locale` string, nullable, required
      - `template_uuid` string, required — UUID of the [template](/#templates) the document was created from, if any
      - `created_at` string, date-time, nullable, required
      - `updated_at` string, date-time, nullable, required
      - `archived_at` string, date-time, nullable, required
      - `parties` DocumentPartySnippetResource[], required — The people and/or organizations that will be involved in signing the document
        - `uuid` string, required
        - `ref_uuid` string, required — If the document containing this party was created from a template, this identifier will be the same as the `ref_uuid` of the corresponding party in the source template.
        - `reference` string, nullable, required — A generic reference for the party
        - `entity_name` string, nullable, required — The actual name of the party. May be null if the party was created via a Template's "set later" option
        - `address` string, nullable, required
        - `scope` 'internal' | 'internal_and_external', required
        - `is_internal_party` boolean, required — Indicates whether this party is linked to an account party (internal) or is standalone (external)
        - `is_ready_for_signing` boolean, required — `true` indicates that an external party has indicated they are ready to sign
        - `ready_for_signing_at` string, date-time, nullable, required
        - `created_at` string, date-time, nullable, required
        - `updated_at` string, date-time, nullable, required
      - `links` object, required
        - `show` string, required — Link to [Show document](/operations/v1.documents.show)
        - `latest_revision_pdf` string, required — Link to [show latest revision PDF details](/operations/v1.documents.revisions.latest.pdf.show)
        - `latest_revision_pdf_download` string, required — Link to [download latest revision PDF](/operations/v1.documents.revisions.latest.pdf.download)
    - `relationship_type` 'parent' | 'amendment' | 'renewal' | 'addition' | 'replacement' | 'termination', required
    - `created_at` string, date-time, nullable, required

## Other responses

- `401` — Unauthenticated
- `403` — Authorization error
- `404` — Not found
- `422` — Validation error

---

[API](https://skmtc.dev/fynk/apis/fynk-api-reference.md) · [All operations](https://skmtc.dev/fynk/apis/fynk-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fynk/fynk-api-reference/revisions/9657a6757f59/schema)