{
  "aid": "fynk.com:main-2025-12-05",
  "name": "fynk API Reference",
  "type": "Index",
  "description": "The fynk API offers a range of endpoints that allow you to build custom integrations against your fynk\naccount.\n\nAs far as possible, it uses REST-style, resource-based URLs to allow your applications to interact with the\n[Documents](/#documents) and [other entities](/#core-concepts) that make up your fynk account.\n\n## Quickstart\n\nFollow these steps to get up and running using the API to work with your fynk account.\n\n### 1. Create an account\n\n[Click here](https://app.fynk.com/register) to create a fynk account, or [login here](https://app.fynk.com/login) if you already have an\naccount.\n\n### 2. Create a party\n\nMake sure your account contains at least one [party](https://app.fynk.com/account-settings/parties). You'll need a party to use in your\n[documents](/#documents) and [templates](/#templates).\n\n### 3. Create a template\n\nMake sure your account has at least one [template](/#templates) available in its [template\nlist](https://app.fynk.com/templates) . You can create a template from scratch or use one from the\n[gallery](https://app.fynk.com/templates#gallery).\n\n### 4. Create an API token\n\n> Only fynk users with the \"Owner\" role can perform this step.\n\nGo to [the fynk API settings page](https://app.fynk.com/account-settings/integrations/api) and click the **Create Token** button. Give your token\na name and give it at least the \"Template Reader\" role. Feel free to also set an expiry date if you would\nlike to be sure that the token cannot be used later. Then click **Create Token** and you'll be shown your\nnew API token. Copy the token to your clipboard, and then paste it somewhere safe such a password manager.\n\n> For security reasons, we can't show you the API token again after you move past this step, so it's\n> important to note it down somewhere safe that you can refer to later.\n\n### 5. Try using your API token\n\nYou can try out your new API token right from this documentation. Open the page for the [Current API token\ndetails](/operations/v1.api-tokens.show-me) API endpoint and paste your API token into the **Token**\ninput in the **Auth** box, then click **Send API Request**.\n\nYou should then see a JSON response appear, with a `data` array at the top level containing information\nabout your API token. It should look something like the example below.\n\n```js\n{\n  \"data\": {\n    \"uuid\": \"efc24626-9724-43cd-9247-e9769fe08844\",\n    \"name\": \"fynk API token\",\n    \"expires_at\": null,\n    \"account\": {\n      \"uuid\": \"08fd4c01-7327-42d4-9442-a09dd57f55b8\",\n      \"name\": \"Demo Inc.\"\n    },\n    \"settings\": {\n      \"account_default_api_version\": \"2025-05-22\",\n      \"request_api_version\": \"2025-05-22\",\n      \"latest_api_version\": \"2025-06-06\",\n      \"changelog\": {}\n    },\n    \"created_at\": \"2025-07-01T06:19:03Z\",\n    \"updated_at\": \"2025-07-01T06:19:03Z\"\n  },\n  \"links\": {\n    \"documentation\": \"https://app.fynk.com/v1/docs\",\n    \"document_list\": \"https://app.fynk.com/v1/api/documents\",\n    \"template_list\": \"https://app.fynk.com/v1/api/templates\"\n  }\n}\n```\n\n> If you instead see a `401 Unauthorized` response, make sure you copied the whole of the generated API\n> token, if you think you might be missing part of it, you can revoke the token you created in step 4 and\n> try generating a new token.\n\n### 6. Try fetching data\n\nNow that you know your API token works, open the page for the [List templates](/operations/v1.templates.index) API\nendpoint and try sending that request. You should receive a response like the one below, containing details\nof the template you created in step three.\n\nAt this point, if you would like, you can try altering some of the request parameters like `sort_by` or\n`sort_direction` and re-send the request to see how this affects the response.\n\nYou could also copy one of the returned template `uuid` values and use it to fetch additional information\nabout the template by pasting it into the **template** input on the\n[Show template](/operations/v1.templates.show) page and sending that request.\n\n```js\n{\n  \"data\": [\n    {\n      \"uuid\": \"00ac949f-4871-496f-904c-8703a33fe163\",\n      \"name\": \"Contract Layout A\",\n      \"locale\": \"en-US\",\n      \"published\": true,\n      \"signature_type\": null,\n      \"sequential_signing\": false,\n      \"created_at\": \"2025-05-28T07:11:14Z\",\n      \"updated_at\": \"2025-05-28T07:11:15Z\",\n      \"archived_at\": null,\n      \"parties\": [\n        {\n          \"uuid\": \"e137ca22-c69d-43ec-bb6b-4b5ebd10417f\",\n          \"reference\": \"Demo Inc.\",\n          \"entity_type\": \"business\",\n          \"entity_name\": \"Demo Inc.\",\n          \"address\": \"Am Tabor 36\\n1020 Wien\",\n          \"scope\": \"internal\",\n          \"is_internal_party\": true,\n          \"created_at\": \"2025-05-28T07:11:14Z\",\n          \"updated_at\": \"2025-05-28T07:11:14Z\"\n        },\n        {\n          \"uuid\": \"9781632f-12b0-4528-bde9-346377f79fe9\",\n          \"reference\": \"Counterparty\",\n          \"entity_type\": null,\n          \"entity_name\": null,\n          \"address\": null,\n          \"scope\": \"internal_and_external\",\n          \"is_internal_party\": false,\n          \"created_at\": \"2025-05-28T07:11:14Z\",\n          \"updated_at\": \"2025-05-28T07:11:14Z\"\n        }\n      ]\n      \"links\": {\n        \"show\": \"https://app.fynk.com/v1/api/templates/00ac949f-4871-496f-904c-8703a33fe163\"\n      }\n    },\n    // ...\n```\n\n### 7. Integrate with your systems\n\nYou now have a working API token and have seen what an API response looks like. To help you start\nintegrating the API into your systems, take a look at the **Request Sample** section of any endpoint\ndocumentation page. There you can use the menu to select your preferred programming language and see an\nexample of how you could send that endpoint's request using the selected language.\n\n## How to create a document from a template\n\n### Create a template\n\nCreating a [document](/#documents) through the API first requires that your account contains a\n[template](/#template) to use as the basis of the new document. If you don't have a template available\nalready, you can either create one from scratch or choose one from the [gallery](https://app.fynk.com/templates#gallery) and\nmodify it to fit your needs.\n\n### Create a document from the template\n\nTo create a document from a template, you will need to send a `POST` request to the [Create document from\ntemplate](/operations/v1.documents.create-from-template) endpoint. Before you can do this, you will first need to find the UUID of\nthe template you would like to base your new document on.\n\nYou can use a filtered request to the [List templates](/operations/v1.templates.index) endpoint to find the UUID of\nthe template you would like to use. For example, if your template is called \"Contract Layout A\", a request\nlike this using `curl` would return a list of the templates matching that name, and you can then take the\n`uuid` from the appropriate template in the response:\n\n```shell\ncurl \"https://app.fynk.com/v1/api/templates?filter%5Bquery%5D=Contract%20Layout%20A\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json'\n```\n\nThe template UUID can then be used as the `template_uuid` parameter in the [Create document from\ntemplate](/operations/v1.documents.create-from-template) request. You can optionally provide a `name` parameter to set the name\nof the new document - if you don't provide a name, then the new document will be given the same name as the\ntemplate it is based on.\n\nThe request parameters should be sent in a JSON object in the request body. The following example shows how\nthis would look if you wanted to create a document called \"Employment Contract\" from the template with the\nUUID \"4df1e60a-0114-4dce-89e7-8c5ad397fcf2\":\n\n```shell\ncurl -X \"POST\" \"https://app.fynk.com/v1/api/documents/create-from-template\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json' \\\n    -H 'Content-Type: application/json; charset=utf-8' \\\n    -d '{\"name\": \"Employment Contract\", \"template_uuid\": \"4df1e60a-0114-4dce-89e7-8c5ad397fcf2\"}'\n```\n\n> **Assigning document ownership**: you can optionally specify which users from your account should be given\n> ownership of the new document by including the `owner_emails` parameter in your request. This parameter\n> should contain an array of email addresses belonging to users in your fynk account.\n\nSending this request will return a JSON response containing the details of the newly created document, which\nwill look something like this:\n\n```js\n{\n  \"data\": {\n    \"uuid\": \"14e82085-6e94-48c7-9b9b-15bc5c4656d4\",\n    \"name\": \"Employment Contract\",\n    \"origin\": \"template\",\n    // ...\n}\n```\n\nThe `data.uuid` returned in the response is the UUID of the newly created document. This would be the value\nyou would need to use in subsequent requests when the endpoint documentation specifies that it accepts a\n`document` parameter in the URL (as in the [Show document](/operations/v1.documents.show) endpoint, for example).\n\nAt this point the document has been created and would be visible in the [documents](https://app.fynk.com/documents) list to\nusers with the appropriate permissions.\n\n### Populate dynamic fields\n\nIf your template contains [dynamic fields](/#dynamic-fields), your new document will also contain those same\ndynamic fields, and you can now use the API to customise the content of your document by updating its\ndynamic field values. The response returned after creating the document will contain a `data.dynamic_fields`\nlist, which will contain all of the document's dynamic fields and their initial values. This example shows\nhow this could look for a variety of different field types:\n\n```js\n{\n  \"data\": {\n    \"uuid\": \"14e82085-6e94-48c7-9b9b-15bc5c4656d4\",\n    // ...\n    \"dynamic_fields\": [\n      {\n        \"uuid\": \"f4522967-c04f-4113-8762-6d5642c9d863\",\n        \"type\": \"date\",\n        \"name\": \"Start of employment\",\n        \"scope\": \"internal\",\n        \"settings\": null,\n        \"autofill_type\": null,\n        \"format\": null,\n        \"select_values\": null,\n        \"is_mandatory\": true,\n        \"question\": \"When does the employee start?\",\n        \"question_external\": null,\n        \"value\": \"2025-10-01\",\n        \"order\": null\n      },\n      {\n        \"uuid\": \"4000293a-773b-4efa-ae4b-96bc511d8ad7\",\n        \"type\": \"text\",\n        \"name\": \"Job Title\",\n        \"scope\": \"internal\",\n        \"settings\": null,\n        \"autofill_type\": null,\n        \"format\": null,\n        \"select_values\": null,\n        \"is_mandatory\": true,\n        \"question\": \"What is the role's job title?\",\n        \"question_external\": null,\n        \"value\": \"Full-stack Developer\",\n        \"order\": null\n      },\n      {\n        \"uuid\": \"c6c0b0bb-87af-44e9-bc8d-0e543b217429\",\n        \"type\": \"currency\",\n        \"name\": \"Yearly Gross Salary\",\n        \"scope\": \"internal\",\n        \"settings\": {\n          \"currencies\": [\n            \"EUR\"\n          ]\n        },\n        \"autofill_type\": null,\n        \"format\": null,\n        \"select_values\": null,\n        \"is_mandatory\": true,\n        \"question\": \"What is the role's yearly gross salary?\",\n        \"question_external\": null,\n        \"value\": \"EUR;75000\",\n        \"order\": null\n      },\n      {\n        \"uuid\": \"6778cfe0-1509-47fc-a333-c80c794c0443\",\n        \"type\": \"select\",\n        \"name\": \"Location\",\n        \"scope\": \"internal\",\n        \"settings\": null,\n        \"autofill_type\": null,\n        \"format\": null,\n        \"select_values\": [\n          \"Cork\",\n          \"Dublin\"\n        ],\n        \"is_mandatory\": true,\n        \"question\": \"In which location will the employee be based?\",\n        \"question_external\": null,\n        \"value\": \"Dublin\",\n        \"order\": null\n      },\n      {\n        \"uuid\": \"30e5296d-08fe-4fc8-abd4-df2670583115\",\n        \"type\": \"bool\",\n        \"name\": \"Remote work\",\n        \"scope\": \"internal\",\n        \"settings\": null,\n        \"autofill_type\": null,\n        \"format\": null,\n        \"select_values\": null,\n        \"is_mandatory\": true,\n        \"question\": \"Does the role allow a remote work component?\",\n        \"question_external\": null,\n        \"value\": false,\n        \"order\": null\n      }\n    ],\n    // ...\n  }\n}\n```\n\nThis list of current dynamic field values for a document is also included in the [Show\ndocument](/operations/v1.documents.show) response or can be fetched (without the rest of the document's data) using\nthe [List document's dynamic fields](/operations/v1.documents.dynamic-fields.index) endpoint.\n\nTo change the value of a dynamic field, you can use the [Update dynamic field](/operations/v1.documents.dynamic-fields.update)\nendpoint. Looking at the documentation for this, you can see that URL for this request requires a `document`\nparameter and a `dynamicField` parameter. `document` is the UUID of the document, which you received in\n`data.uuid` when creating the document. `dynamicField` is the UUID of the dynamic field you would like to\nupdate, which you can take from the appropriate entry in the document's `data.dynamic_fields` list.\n\nUsing the values from the previous example response, if you wanted to change the value of the \"Job Title\"\nfield to \"Software Engineer\", you would take the UUIDs \"14e82085-6e94-48c7-9b9b-15bc5c4656d4\" for `document`\nand \"4000293a-773b-4efa-ae4b-96bc511d8ad7\" for `dynamicField` and send a request like this:\n\n```shell\ncurl -X \"PUT\" \"https://app.fynk.com/v1/api/documents/14e82085-6e94-48c7-9b9b-15bc5c4656d4/dynamic-fields/4000293a-773b-4efa-ae4b-96bc511d8ad7\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json' \\\n    -H 'Content-Type: application/json; charset=utf-8' \\\n    -d '{\"value\": \"Software Engineer\"}'\n```\n\nThe format of the `value` parameter sent in the request body will depend on the `type` of the dynamic field,\nthe possible types and their corresponding formats are detailed in the [Update dynamic\nfield](/operations/v1.documents.dynamic-fields.update#value-format) documentation.\n\n### Assign metadata\n\nAt this point it is also possible to enrich your document with [metadata](/#metadata). Your fynk account\ncomes with a selection of [reference metadata fields](https://app.fynk.com/account-settings/metadata#reference) as well as allowing\nyou to create custom [account metadata fields](https://app.fynk.com/account-settings/metadata#account). You can assign values for any\nof these metadata fields to your documents using the API.\n\nAssigning a new metadata value to a document is a two step process:\n\n1. Use the [List metadata](/operations/v1.metadata.index) endpoint to find the metadata field's UUID.\n2. Send an [Add metadata value to document](/operations/v1.documents.metadata-values.store) request to create a \"metadata value\" for that field.\n\nThe [List metadata](/operations/v1.metadata.index) endpoint will return a list of all of the metadata fields that are\navailable in your account. Its response will look something like this:\n\n```js\n{\n  \"data\": [\n    {\n      \"uuid\": \"ddfc1bd7-05c9-456e-9dab-dacfcf44fbb2\",\n      \"type\": \"system_reference\",\n      \"value_type\": \"select\",\n      \"name\": \"end_user_license_type\",\n      \"display_name\": \"End User License Type\",\n      \"settings\": null,\n      \"select_values\": [\n        \"Freeware\",\n        \"Shareware\",\n        \"Proprietary\",\n        \"Subscription\",\n        \"Open Source\",\n        \"Public Domain\",\n        \"Other\"\n      ],\n      \"always_exists\": false,\n      \"description\": \"The type of license governing the use of the software product.\"\n    },\n    {\n      \"uuid\": \"7c997428-de84-483b-a072-f2c9da93d924\",\n      \"type\": \"system_reference\",\n      \"value_type\": \"currency\",\n      \"name\": \"freelance_rate\",\n      \"display_name\": \"Freelance Rate\",\n      \"settings\": null,\n      \"select_values\": null,\n      \"always_exists\": false,\n      \"description\": \"The hourly rate charged for freelance services.\"\n    },\n    {\n      \"uuid\": \"205a379c-c4d5-469d-9f67-a025bc630cbf\",\n      \"type\": \"system_reference\",\n      \"value_type\": \"number\",\n      \"name\": \"freelance_hours\",\n      \"display_name\": \"Freelance Hours\",\n      \"settings\": null,\n      \"select_values\": null,\n      \"always_exists\": false,\n      \"description\": \"The number of hours to be provided as part of the freelance services.\"\n    },\n    // ...\n  ]\n}\n```\n\nLets assume that you would like to set the `freelance_hours` metadata field to `100` for your document. The\n[Add metadata value to document](/operations/v1.documents.metadata-values.store) endpoint requires three parameters:\n\n- `document` in the URL: The UUID of the document to add the metadata value to.\n- `metadata_uuid` in the request body: The UUID of the metadata field to add the value to.\n- `value` in the request body: The value to assign to the metadata field.\n\nUsing the values from the previous example responses, this means you would send a request like this:\n\n```shell\ncurl -X \"POST\" \"https://app.fynk.com/v1/api/documents/14e82085-6e94-48c7-9b9b-15bc5c4656d4/metadata-values\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json' \\\n    -H 'Content-Type: application/json; charset=utf-8' \\\n    -d '{\"value\": 100, \"metadata_uuid\": \"205a379c-c4d5-469d-9f67-a025bc630cbf\"}'\n```\n\nYou would then be able to see the newly set metadata value in `data.metadata_values` field of the [Show\ndocument](/operations/v1.documents.show) response.\n\n### Managing parties\n\nAt this point, your document may need to have the details of at least one of its [parties](/#parties)\ncompleted, since your template likely only contains a generic `reference` to the external party, rather than\ntheir concrete details.\n\n#### List document parties\n\nTo see all parties associated with a document, use the [List document parties](/operations/v1.documents.parties.index)\nendpoint:\n\n```shell\ncurl \"https://app.fynk.com/v1/api/documents/14e82085-6e94-48c7-9b9b-15bc5c4656d4/parties\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json'\n```\n\n> `is_internal_party` in the response tells you whether the party will be editable via the API. Only parties\n> where this field is false can be updated via API. Internal parties can be edited in the [settings of your\n> fynk account](https://app.fynk.com/account-settings/parties).\n\n#### Update party details\n\nYou can edit party information using the [Update document party](/operations/v1.documents.parties.update) endpoint.\n\nFor example, to update a party's name and address and set that they are business:\n\n```shell\ncurl -X \"PUT\" \"https://app.fynk.com/v1/api/documents/14e82085-6e94-48c7-9b9b-15bc5c4656d4/parties/ad899fc9-3130-45d5-9cd5-d7a0737f0ffd\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json' \\\n    -H 'Content-Type: application/json; charset=utf-8' \\\n    -d '{\"entity_name\": \"BigCo Inc.\", \"entity_type\": \"business\", \"address\":\"BigCo Plaza, New York\"}'\n```\n\n> Party management is only allowed while the document is in `draft`, `approved_draft`, `review`, or\n> `approved_review` stages. Once a document reaches the `signing` or `done` stage, parties cannot be\n> updated.\n\n### Assign a signatory\n\nBefore your document can be signed, you need to assign [signatories](/#signatories) to it. Signatories are\nindividuals who will sign the document and must belong to one of the document's [parties](/#parties).\n\nTo add a signatory to your document, use the [Add signatory](/operations/v1.documents.signatories.store)\nendpoint. This endpoint requires:\n\n- `document` in the URL: The UUID of the document to add the signatory to\n- `party_uuid` in the request body: The UUID of the party this signatory belongs to\n- `email` in the request body: The email address of the signatory\n\nYou can also optionally provide additional information like `first_name`, `last_name`, `mobile_phone`, and\n`title`.\n\nUsing the document UUID from our previous examples and assuming you want to add a signatory named \"Alex\nSmith\" with email \"alex.smith@example.com\" to the party with UUID \"ad899fc9-3130-45d5-9cd5-d7a0737f0ffd\",\nyou would send a request like this:\n\n```shell\ncurl -X \"POST\" \"https://app.fynk.com/v1/api/documents/14e82085-6e94-48c7-9b9b-15bc5c4656d4/signatories\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json' \\\n    -H 'Content-Type: application/json; charset=utf-8' \\\n    -d '{\n      \"party_uuid\": \"ad899fc9-3130-45d5-9cd5-d7a0737f0ffd\",\n      \"email\": \"alex.smith@example.com\",\n      \"first_name\": \"Alex\",\n      \"last_name\": \"Smith\",\n      \"title\": \"Software Engineer\"\n    }'\n```\n\nThe response will include the details of the newly created signatory:\n\n```js\n{\n  \"data\": {\n    \"uuid\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n    \"party_uuid\": \"ad899fc9-3130-45d5-9cd5-d7a0737f0ffd\",\n    \"first_name\": \"Alex\",\n    \"last_name\": \"Smith\",\n    \"email\": \"alex.smith@example.com\",\n    \"mobile_phone\": null,\n    \"title\": \"Software Engineer\",\n    \"profile_photo_url\": \"https://ui-avatars.com/api/?name=AS\",\n    \"signing_order\": 1,\n    \"has_account_user\": false\n  }\n}\n```\n\n#### Managing signatories\n\nYou can also update signatory information using the [Update signatory](/operations/v1.documents.signatories.update)\nendpoint, or remove a signatory using the [Remove signatory](/operations/v1.documents.signatories.destroy)\nendpoint.\n\nTo list all signatories for a document, use the [List signatories](/operations/v1.documents.signatories.index)\nendpoint.\n\n> Some changes to signatories may be prevented while a document is in the `signing` stage. For example, it\n> is not allowed to remove the only remaining signatory from a party while a document is being signed. If\n> you try to make a modification that is not allowed in the document's current stage, your request will\n> receive a response with a `409 Conflict` status.\n\n### Move the document to review\n\nAt this point, assuming you haven't made any changes to your document outside of the API, it will be in the\n`draft` stage. You can use the\n[Move document to review stage](/operations/v1.documents.stage-transitions.review) endpoint to move the\ndocument into the `review` stage, where you can share it with collaborators:\n\n```shell\ncurl -X \"POST\" \"https://app.fynk.com/v1/api/documents/14e82085-6e94-48c7-9b9b-15bc5c4656d4/stage-transitions/review\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json' \\\n```\n\n### Move the document to signing\n\nOnce you are happy with your document's content, have configured its [parties](/#parties) and their\n[signatories](/#signatories), and have added signature blocks to the document for each signatory, you can\ncan use the [Move document to signing stage](/operations/v1.documents.stage-transitions.signing) endpoint to\nmove the document into the `signing` stage:\n\n```shell\ncurl -X \"POST\" \"https://app.fynk.com/v1/api/documents/14e82085-6e94-48c7-9b9b-15bc5c4656d4/stage-transitions/signing\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json' \\\n```\n\nThis request sends invitations to all document signatories. If sequential signing is enabled, invitations\nare sent one at a time in the order specified by each signatory's `signing_order` property. Otherwise, all\nsignatories receive their invitations simultaneously.\n\n### Access the document\n\nOnce you have created a document, you can access it in the fynk web application by visiting it from the\n[documents list](https://app.fynk.com/documents), assuming your fynk user has the appropriate role and/or team membership.\nYou can also download the document as a PDF via the API, using the `data.pdf_url` returned by the [Show\nlatest revision PDF details](/operations/v1.documents.revisions.latest.pdf.show) endpoint, or directly via\nthe [Download latest revision PDF](/operations/v1.documents.revisions.latest.pdf.download) endpoint.\n\nThe latter option would look like this using `curl` to download to a file named `my-document.pdf`. Note that\nbecause the API endpoint returns a HTTP 302 redirect to the actual PDF data, we have to tell `curl` to\nfollow redirects using the `--location` flag:\n\n```shell\ncurl \"https://app.fynk.com/v1/api/documents/14e82085-6e94-48c7-9b9b-15bc5c4656d4/revisions/latest/pdf/download\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    --location > my-document.pdf\n```\n\n## How to create a document from a PDF file\n\nCreating a [document](/#documents) from a PDF file requires a multi-step upload process to ensure your PDF\nis safely transferred and processed.\n\n### Generate a presigned upload URL\n\nFirst, you need to obtain an upload URL by making a request to the [Create document PDF upload\nURL](/operations/v1.file-uploads.document-pdf.create) endpoint:\n\n```shell\ncurl -X \"POST\" \"https://app.fynk.com/v1/api/file-uploads/document-pdf\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json' \\\n    -H 'Content-Type: application/json; charset=utf-8'\n```\n\nThis will return a response containing the upload details:\n\n```json\n{\n  \"data\": {\n    \"uuid\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n    \"url\": \"https://example-bucket.s3.amazonaws.com/uploads/...\",\n    \"headers\": {\n      \"Content-Type\": \"application/pdf\"\n    },\n    \"expires_at\": \"2025-07-29T15:30:00Z\"\n  }\n}\n```\n\n> Hold on to the `uuid` value - you'll need it when you reach the \"Create the document\" step. The upload URL\n> expires at the time specified in `expires_at`, so complete the upload promptly.\n\n### Upload your PDF file\n\nUsing the URL and headers from the previous response, upload your PDF file with a PUT request. Send the raw\nPDF file data (not base64-encoded) in the request body:\n\n```shell\ncurl -X \"PUT\" \"https://example-bucket.s3.amazonaws.com/uploads/...\" \\ # use the URL from data.url in the previous response\n    -H 'Content-Type: application/pdf' \\ # this comes from data.headers in the previous response\n    --data-binary @/path/to/your/document.pdf\n```\n\n> This is a direct upload to an S3-compatible storage bucket using a presigned URL. You do not need to\n> include your fynk API token in the request. Include all headers from the previous response exactly as\n> provided.\n\nA successful upload returns a `200 OK` response with no body content.\n\n### Create the document\n\nFinally, create your fynk document from the uploaded PDF using the [Create document from\nPDF](/operations/v1.documents.create-from-pdf) endpoint, providing the `uuid` from step 1:\n\n```shell\ncurl -X \"POST\" \"https://app.fynk.com/v1/api/documents/create-from-pdf\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json' \\\n    -H 'Content-Type: application/json; charset=utf-8' \\\n    -d '{\n      \"file_upload_uuid\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n      \"file_name\": \"my-contract.pdf\",\n      \"initial_stage\": \"draft\",\n      \"name\": \"My Contract from PDF\",\n    }'\n```\nThis returns the newly created document:\n\n```js\n{\n  \"data\": {\n    \"uuid\": \"b71a0628-529f-4ae1-a891-e1c6e9339507\",\n    \"name\": \"My Contract from PDF\",\n    \"origin\": \"pdf\",\n    \"stage\": \"draft\",\n    // ...\n  }\n}\n```\n\n#### Initial stage\n\nThe `initial_stage` may be either `draft` or `done`. Here we've used `draft`, indicating that the document\nstill needs to be signed through fynk. If we'd instead used `done` this would be the same as the \"Import\nwithout signing\" option in the fynk web interface - the document would be created already in the \"Done\"\nstage.\n\n#### Using a Template\n\nYou can specify a `template_uuid` to copy settings from an existing template. When using `template_uuid`,\nvarious settings (parties, metadata, etc.) will be copied from the template to the new document.\n\n#### Additional Options\n\nSeveral optional parameters are available for customizing the document, including team assignment, tags,\nand AI analysis settings. See the [Create document from PDF](/operations/v1.documents.create-from-pdf)\nendpoint documentation for the complete list of available parameters.\n\n### What happens next\n\nYour PDF will be processed and converted into a fynk document. If your account has access to AI Analyses,\nan analysis will be automatically started for the newly created document.\n\nThe new document will appear in your [documents list](https://app.fynk.com/documents) and can be managed like any other fynk\ndocument through both the web interface and API.\n\n## How to store a file in a document's file storage\n\nStoring a file in a [document](/#documents) file storage requires a multi-step upload process to ensure your\nfile is safely transferred and processed.\n\n### Generate a presigned upload URL\n\nFirst, you need to obtain an upload URL by making a request to the [Create document file storage upload\nURL](/operations/v1.file-uploads.document-file-storage.create) endpoint:\n\n```shell\ncurl -X \"POST\" \"https://app.fynk.com/v1/api/file-uploads/document-file-storage\" \\\n  -H 'Accept: application/json' \\\n  -H 'Authorization: Bearer <your-api-token>' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"content_type\": \"application/pdf\"}'\n```\n\nThis will return a response containing the upload details:\n\n```json\n{\n  \"data\": {\n    \"uuid\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n    \"url\": \"https://example-bucket.s3.amazonaws.com/uploads/...\",\n    \"headers\": {\n      \"Content-Type\": \"application/pdf\"\n    },\n    \"expires_at\": \"2025-07-29T15:30:00Z\"\n  }\n}\n```\n\n> Hold on to the `uuid` value - you'll need it when you reach the \"Store the file in a document's file\n> storage\" step. The upload URL expires at the time specified in `expires_at`, so complete the upload\n> promptly.\n\n### Upload your file\n\nUsing the URL and headers from the previous response, upload your file with a PUT request. Send the raw\nfile data (not base64-encoded) in the request body:\n\n```shell\ncurl -X \"PUT\" \"https://example-bucket.s3.amazonaws.com/uploads/...\" \\ # use the URL from data.url in the previous response\n    -H 'Content-Type: application/pdf' \\ # this comes from data.headers in the previous response\n    --data-binary @/path/to/your/document.pdf\n```\n\n> This is a direct upload to an S3-compatible storage bucket using a presigned URL. You do not need to\n> include your fynk API token in the request. Include all headers from the previous response exactly as\n> provided.\n\nA successful upload returns a `200 OK` response with no body content.\n\n### Store the file in the document's file storage\n\nFinally, link your newly uploaded file to the file storage of the document in question using the [Store a file in a document's file storage\nPDF](/operations/v1.documents.document-file-storage.store) endpoint, providing the `uuid` from step 1:\n\n```shell\ncurl -X \"POST\" \"https://app.fynk.com/v1/api/documents/{document}/file-storage\" \\\n  -H 'Accept: application/json' \\\n  -H 'Authorization: Bearer <your-api-token>' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"file_upload_uuid\": \"e1413d6e-d516-4f67-84be-6dd98446aebb\",\n    \"file_name\": \"your-filename.pdf\"\n  }'\n```\nThis returns the details of the newly stored file:\n\n```js\n{\n  \"data\": {\n    \"uuid\": \"09d358a7-4268-413f-a79b-7fed013f8768\",\n    \"sha256\": \"697651f6ceea8a931289ff64cb62f78ceea5d36f7e84590fe9d5920b2dce52cf\",\n    \"file_name\": \"your-filename.pdf\",\n    \"file_size\": 349059,\n    \"mime_type\": \"application/pdf\",\n  }\n}\n```\n\n## Core concepts\n\n### UUIDs\n\nAll resources returned by the fynk API are identified by a UUID. The UUID that identifies a particular\nresource will always be returned in the `uuid` field of the resource's JSON representation.\n\n```js\n{\n  \"data\" {\n    \"uuid\": \"88a774d2-904a-4b1a-9c49-338cdc203041\",\n    // ...\n  }\n}\n```\n\n### Documents\n\nDocuments are the individual contracts, quotes, forms, etc that you are managing through fynk.\n\nAmong other things, the API allows you to:\n\n- [Create new documents](/operations/v1.documents.create-from-template)\n- [List and search for existing documents](/operations/v1.documents.index)\n- [View details of a document](/operations/v1.documents.show)\n- [Rename a document or update its general settings](/operations/v1.documents.update)\n- [Download a PDF copy of a document](/operations/v1.documents.revisions.latest.pdf.download)\n- Manage a document's [dynamic field](/#dynamic-fields) and [metadata](/#metadata) values\n\n### Templates\n\nTemplates in fynk allow you to create standardized [documents](/#documents) efficiently while maintaining\nflexibility for customization. You can read more about using templates in fynk in our [article\nhere](https://help.fynk.com/en/articles/270538-templates-in-fynk).\n\nUsing the API you can:\n\n- [List and search the templates](/operations/v1.templates.index) available in your account\n- [View details of a template](/operations/v1.templates.show)\n- [Use a template to create a new document](/operations/v1.documents.create-from-template)\n\n### Parties\n\nA party represents a business or natural person who will be involved in a [document](/#documents). Your fynk\naccount will have at least one internal party representing the internal entities relevant to your\norganization - such as company locations, legal subsidiaries, or departments. Your documents may involve\nthose internal parties, as well as external parties - like suppliers, customers, or partners.\n\nYou can read more about managing your account's parties in [our article\nhere](https://help.fynk.com/en/articles/125635-managing-account-settings-in-fynk?#h_1689d3ae54).\n\nA given party may have one or more [signatories](/#signatories) in a document.\n\nUsing the API you can:\n\n- [List document parties](/operations/v1.documents.parties.index)\n- [Update document party](/operations/v1.documents.parties.update)\n\nYou will also find party information in both [documents](/#documents) and [templates](/#templates) in\ntheir `parties` fields, which will look something like this:\n\n```json\n{\n  \"data\": {\n    \"parties\": [\n      {\n        \"uuid\": \"e85ce001-529d-4ed3-a320-cf374a2eec7a\",\n        \"reference\": \"Employer\",\n        \"entity_type\": \"business\",\n        \"entity_name\": \"Demo Inc.\",\n        \"address\": \"2 Example Street\\nLondon\\nW1 7PQ\",\n        \"scope\": \"internal\",\n        \"is_internal_party\": true,\n        \"is_ready_for_signing\": false,\n        \"ready_for_signing_at\": null,\n        \"created_at\": \"2025-06-03T06:28:54Z\",\n        \"updated_at\": \"2025-06-03T06:28:54Z\"\n      },\n      {\n        \"uuid\": \"ad899fc9-3130-45d5-9cd5-d7a0737f0ffd\",\n        \"reference\": \"Employee\",\n        \"entity_type\": \"person\",\n        \"entity_name\": \"Jane Marshall\",\n        \"address\": \"1 Main Street\\nBirmingham\\nB2 8QR\",\n        \"scope\": \"internal_and_external\",\n        \"is_internal_party\": false,\n        \"is_ready_for_signing\": false,\n        \"ready_for_signing_at\": null,\n        \"created_at\": \"2025-06-03T06:28:54Z\",\n        \"updated_at\": \"2025-06-03T13:05:56Z\"\n      }\n    ]\n  }\n}\n```\n\n### Signature types\n\nThe signing process for a fynk [document](/#documents) may use one of three different signature types:\n\n- Simple electronic signature (SES)\n- Advanced electronic signature (AES)\n- Qualified electronic signature (QES)\n\nSee our article [here](https://help.fynk.com/en/articles/126836-signature-types) for details of the\ndifferences between these.\n\nDocuments returned by the API have a `signature_type` field indicating their currently assigned type. If a\ndocument does not have a signature type assigned, a type may be specified when [moving the document to the\nsigning stage](/operations/v1.documents.stage-transitions.signing).\n\n### Signatories\n\nA signatory represents an individual person who will sign a [document](/#documents). All signatories must\nbelong to a [party](/#party).\n\nA signatory may be either an internal user, who has an [account\nuser](https://help.fynk.com/en/articles/125635-managing-account-settings-in-fynk#h_b6fd630e81) in your fynk\naccount, or they may be any other person, who does not have access to your fynk account - e.g. employees of\nyour suppliers, customers, or partners.\n\nNote that signatories for `internal` parties do not necessarily have to have a fynk account user in your\naccount.\n\nYou can find signatory information in both the [Show document](/operations/v1.documents.show) and [Show\ntemplate](/operations/v1.templates.show) API responses:\n\n```json\n{\n  \"data\": {\n    \"signatories\": [\n      {\n        \"uuid\": \"7f356fd9-5144-4a75-8378-d223bf13011d\",\n        \"party_uuid\": \"e85ce001-529d-4ed3-a320-cf374a2eec7a\",\n        \"first_name\": \"Jane\",\n        \"last_name\": \"Marshall\",\n        \"email\": \"jane@example.org\",\n        \"mobile_phone\": \"+447951123456\",\n        \"title\": \"HR Manager\",\n        \"profile_photo_url\": \"https:\\/\\/ui-avatars.com\\/api\\/?name=JM\",\n        \"signing_order\": 2,\n        \"has_account_user\": true,\n      },\n      {\n        \"uuid\": \"5cb21e44-3002-4af6-91d4-fe8127cb13d2\",\n        \"party_uuid\": \"ad899fc9-3130-45d5-9cd5-d7a0737f0ffd\",\n        \"first_name\": \"Liam\",\n        \"last_name\": \"Roberts\",\n        \"email\": \"roberts@example.com\",\n        \"mobile_phone\": null,\n        \"title\": null,\n        \"profile_photo_url\": \"https:\\/\\/ui-avatars.com\\/api\\/?name=LR\",\n        \"signing_order\": 1,\n        \"has_account_user\": false,\n      }\n    ]\n  }\n}\n```\n\n### Dynamic fields\n\nDynamic fields allow your [templates](/#templates) and [documents](/#documents) to contain dynamically\ncustomisable placeholders. To find out how to add dynamic fields to your documents, see our article on\n[using the fynk editor](https://help.fynk.com/en/articles/147803-using-fynk-s-editor#h_6c4eafc77e).\n\nDynamic fields are included in the the [Show document](/operations/v1.documents.show) and [Show\ntemplate](/operations/v1.templates.show) API responses in their `dynamic_fields` fields.\n\nSee [this section](/#populate-dynamic-fields) of the API's [How to create a\ndocument](/#how-to-create-a-document-from-a-template) guide for an introduction to working with dynamic\nfields via the API.\n\n### Metadata\n\nIn fynk, metadata are details such as dates, financial figures, or contract clauses related to your\n[documents](/#documents). You can find an overview of how metadata can help in your document management\nprocesses in our [using metadata](https://help.fynk.com/en/articles/126993-using-metadata) article.\n\nThe API allows you to retrieve a list of the metadata fields available in your account via the [List\nmetadata](/operations/v1.metadata.index) endpoint, and the [Show document](/operations/v1.documents.show) and [Show\ntemplate](/operations/v1.templates.show) responses each include a `metadata_values` list, which contain the\ncurrent metadata values assigned to the respective document or [template](/#templates).\n\nSee [this section](/#assign-metadata) of the API's [How to create a\ndocument](/#how-to-create-a-document-from-a-template) guide for an introduction to working with metadata via\nthe API.\n\n## Authentication\n\n### API tokens\n\nTo access the API you will need an API token. You can generate new API tokens in your\n[Account Settings](https://app.fynk.com/account-settings/integrations/api), or by asking your account's owner to do this for you if you do not have\nsufficient permissions.\n\n> You will only be able to see a new API token's value one time, immediately after you create it, so make\n> sure to save it.\n\nAn API token needs to be sent in the `Authorization` header of each request. The value of the header should\nbe in the format `Bearer <token>`, where `<token>` is the API token itself. For example, if your API token\nwas \"WAnMlf6725\", your request's `Authorization` header would look like this:\n\n```\nAuthorization: Bearer WAnMlf6725\n```\n\n### Tokens created during free trial\n\nIf your account is on a Trial plan, you will be able to generate API tokens and use them to make requests\nto the API for the duration of your trial period. Once your trial ends, you will need to move to a paid plan\nto continue using the API.\n\n## Versioning\n\nThe API may change over time. Wherever possible, backwards incompatible changes will only be included in a\nnew \"version\" of the API, and we will attempt to keep old versions working for a reasonable period after\nthe release of a new version.\n\n### Backwards compatibility\n\nNew API versions are only released for backwards-incompatible changes. The following changes are considered\nbackwards compatible and will not trigger the release of a new version:\n\n- Adding new API endpoints\n- Adding new optional request parameters to existing API endpoints\n- Adding new properties to existing responses\n- Changing the order of properties in existing responses\n- Adding new variants to enumerated types returned in existing responses, e.g. adding a new [DocumentType](/schemas/DocumentType)\n\nBackwards incompatible changes like the following will result in the release of a new version:\n\n- Removing existing API endpoints\n- Adding new mandatory request parameters to existing API endpoints\n- Removing, renaming or changing the type of properties in existing responses\n\n### Setting your Default API Version\n\nWhen you first visit the [API settings page](https://app.fynk.com/account-settings/integrations/api) to generate an API token, your account's\nDefault API Version will automatically be set to the current API version. All API tokens you create will use\nthis version by default for API requests.\n\n### Updating to new versions\n\nYou can update your account's default API version when new versions are released by visiting your [Account\nSettings](https://app.fynk.com/account-settings/integrations/api), where available newer versions will be listed.\n\n> Version downgrades are not supported. Once you upgrade to a newer version, you cannot revert to an older\n> version.\n>\n> To test your integrations against a newer version of the API, without changing your account's default\n> setting, refer to the \"Overriding the Default API Version\" section on this page.\n\n### Overriding the Default API Version\n\nYou can override your account's default API version for individual requests by including the\n`Fynk-Api-Version` request header. This is useful when testing integrations against newer API versions.\n\n**Example:** If your account has its default version set to 2025-07-07 and you want to test against version\n2025-07-14, include this header:\n\n```\nFynk-Api-Version: 2025-07-14\n```\n\n**Verification:** To confirm the version used, check the `Fynk-Api-Version` header in the API response. This\nheader is included in every response and shows which version processed your request.\n\n#### Fynk-Api-Version requirements\n\n- The version must be valid and available for your account\n- The version must be the same as or newer than your account's default API version\n- Requesting an older version will be ignored, and your account's default version will be used instead\n\n**Finding available versions:** View all available API versions for your account in your [Account\nSettings](https://app.fynk.com/account-settings/integrations/api).\n\n## Pagination\n\nCertain endpoints that return a list of resources support pagination. By default, these endpoints will\nreturn the first page of their result set with the resources for that page in the `data` key of the\nresponse. The response will include both a `links` object containing the URLs of other pages and a `meta`\nobject containing information about the total size of the list.\n\n```js\n{\n  \"data\": [\n    { /* ... */ },\n    { /* ... */ },\n  ],\n  \"links\": {\n    \"first\": \"https://app.fynk.com/v1/api/documents?page=1\",\n    \"last\": \"https://app.fynk.com/v1/api/documents?page=2\",\n    \"prev\": null,\n    \"next\": \"https://app.fynk.com/v1/api/documents?page=2\"\n  },\n  \"meta\": {\n    \"per_page\": 10,    // maximum number of resources returned in a single page\n    \"current_page\": 1, // the page that was returned in this response\n    \"last_page\": 2,    // the last available page\n    \"from\": 1,         // index of the first item in the current page, starting from 1\n    \"to\": 10,          // index of the last item in the current page, starting from 1\n    \"total\": 17,       // total number of resources available\n    \"path\": \"https://app.fynk.com/v1/api/documents\"\n  }\n}\n```\n\nTo request the next pages from the result set, you can either use the `next` link from the returned `links`\nobject or add a `page` parameter to the query string of your next request.\n\nYou may also control the size of the returned pages by including a `page_size` parameter in the query\nstring. When an endpoint supports pagination, the `page` and `page_size` parameters will be documented in\nthe _Query Parameters_ section of the endpoint's documentation.\n\n## Rate Limits\n\nRequests to the API are rate limited based on a rolling one-minute window. If an API token exceeds its rate\nlimit, requests will be rejected with a `429 Too Many Requests` response. If this happens, the response will\ninclude a `Retry-After` header indicating how many seconds you should wait before sending any more requests.\n\nThe rate limit for the current API token is returned on every response in the `X-RateLimit-Limit` HTTP\nheader. The number of remaining requests in the current window is returned in the `X-RateLimit-Remaining`\nheader.\n\n> - Some endpoints may be subject to stricter limits than the general per-minute limit.\n> - Requests made by Trial accounts may be subject to additional limits.\n\n## Webhooks\n\nWebhooks allow you to configure fynk so that it will notify your systems about events that happen in fynk.\n\n### Getting started\n\nTo setup fynk to send webhooks you'll first need a URL to receive the webhook requests. This will usually be\neither a dedicated URL on your own systems, or a URL provided by a third party system (e.g. Zapier,\nMicrosoft Teams, Slack, etc). For testing during development, you may wish to use a tool like\n[webhook.site](https://webhook.site/) to allow you to inspect various webhook payloads.\n\nThe only requirement for the URL handler is that it returns a 20X HTTP status code when it has successfully\nprocessed a request. If it returns any other status code, fynk will consider the request failed and attempt\nto retry it later.\n\nOnce you have a URL that you would like to receive the webhook requests, go to the\n[Webhooks](https://app.fynk.com/account-settings/webhook-targets) page in your account settings and add a new webhook using that URL. If you\nare integrating with your own systems, you will probably want to leave the \"delivery format\" and \"signature\nlocation\" options on their default settings.\n\n> Only fynk users with the \"Owner\" role can access the Webhooks settings page.\n\nNow you will need to choose which notification types your webhook should receive. You can do this from your\naccount's [Notifications settings](https://app.fynk.com/account-settings/document-notifications) page, via the \"Edit\" option on the relevant\nnotification types.\n\nIf you would like different webhooks to be notified based on which template a document was created from, you\ncan override the global notification settings for a particular template by opening the template and editing\nthe settings found in its \"Template notifications\" tab.\n\nOnce you have created a webhook, and configured at least one type of notification to use it, then whenever\nan event of that type occurs, fynk will send a HTTP POST request to the webhook's URL. See the following\nsections for details of what the request payload will contain, and how you can verify it was sent\nby fynk.\n\n### Webhook delivery formats\n\n#### Default delivery format\n\nWebhooks using the \"Default\" delivery format will receive requests containing a JSON object like this:\n\n```json\n{\n  \"events\": [\n    {\n      \"uuid\": \"05113346-425d-48df-8bf2-a20037fc6fa4\",\n      \"type\": \"document.moved_to_stage.signing\",\n      \"timestamp\": \"2026-01-08T14:32:50Z\",\n      \"data\": {\n        \"document\": {\n          \"name\": \"Employment Contract\",\n          \"uuid\": \"0a4b6e64-3c4a-4973-af2c-0ec1072b2e1e\"\n        }\n      }\n    }\n  ],\n  \"timestamp\": \"2026-01-08T14:32:59Z\"\n}\n```\n\nThe top-level `events` field will contain one or more event objects. Each event in the array will have\nthese fields:\n\n| Field name | Description |\n|------------|-------------|\n| `uuid`       | Unique ID for the event |\n| `type`       | What kind of event in fynk you are being notified about. The `events` array may contain events of multiple different types |\n| `timestamp`  | When the event occurred |\n| `data`       | An object containing type-specific data about the event |\n\nThese are the possible values for the `type` field:\n\n- `document.checkpoint.approved`\n- `document.checkpoint.canceled`\n- `document.checkpoint.rejected`\n- `document.comment.created`\n- `document.signed_by_all_parties`\n- `document.moved_to_stage.signing`\n- `document.party.ready_for_signing`\n- `document.reminder.cancellation_notice_period`\n- `document.reminder.effective`\n- `document.reminder.expiring`\n- `document.reminder.renewal`\n\nWhich types of event your webhook actually receives will depend on which [Notifications](https://app.fynk.com/account-settings/document-notifications)\nyou configure to send to the webhook.\n\nBelow you'll find a JSON example showing the structure of each event type. Your webhook handler should parse\nthese from the `events` array in the payload.\n\n> Each example shows a single event object. The actual `events` array in a webhook delivery may contain\n> multiple events.\n\n##### document.checkpoint.approved\n\n```json\n{\n  \"uuid\": \"d445a7e7-d2b7-44c0-87ae-7be2fb2438cd\",\n  \"type\": \"document.checkpoint.approved\",\n  \"timestamp\": \"2026-01-13T12:33:53Z\",\n  \"data\": {\n    \"document\": {\n      \"name\": \"Employment Contract\",\n      \"uuid\": \"0a4b6e64-3c4a-4973-af2c-0ec1072b2e1e\"\n    },\n    \"checkpoint\": {\n      \"uuid\": \"a833571d-fffe-4b4f-b427-ac04036b56f8\",\n      \"document_stage\": \"review\"\n    }\n  }\n}\n```\n\n##### document.checkpoint.canceled\n\n```json\n{\n  \"uuid\": \"2d17653c-6bda-47e3-b51b-2664eb6c8392\",\n  \"type\": \"document.checkpoint.canceled\",\n  \"timestamp\": \"2026-01-13T12:32:44Z\",\n  \"data\": {\n    \"document\": {\n      \"name\": \"Employment Contract\",\n      \"uuid\": \"0a4b6e64-3c4a-4973-af2c-0ec1072b2e1e\"\n    },\n    \"checkpoint\": {\n      \"uuid\": \"a833571d-fffe-4b4f-b427-ac04036b56f8\",\n      \"document_stage\": \"review\"\n    }\n  }\n}\n```\n\n##### document.checkpoint.rejected\n\n```json\n{\n  \"uuid\": \"ccbbb212-d72a-4bb1-a214-db866f45baba\",\n  \"type\": \"document.checkpoint.rejected\",\n  \"timestamp\": \"2026-01-13T12:33:13Z\",\n  \"data\": {\n    \"document\": {\n      \"name\": \"Employment Contract\",\n      \"uuid\": \"0a4b6e64-3c4a-4973-af2c-0ec1072b2e1e\"\n    },\n    \"checkpoint\": {\n      \"uuid\": \"a833571d-fffe-4b4f-b427-ac04036b56f8\",\n      \"document_stage\": \"review\"\n    }\n  }\n}\n```\n\n##### document.comment.created\n\n```json\n{\n  \"uuid\": \"e8880462-bd62-4ff3-8495-6a084c059076\",\n  \"type\": \"document.comment.created\",\n  \"timestamp\": \"2026-01-13T10:30:56Z\",\n  \"data\": {\n    \"comment\": {\n      \"type\": \"comment\",\n      \"uuid\": \"089d1493-2157-4f73-8077-aa248205af79\"\n    },\n    \"document\": {\n      \"name\": \"Employement Contract\",\n      \"uuid\": \"0a4b6e64-3c4a-4973-af2c-0ec1072b2e1e\"\n    }\n  }\n}\n```\n\n##### document.signed_by_all_parties\n\n```json\n{\n  \"uuid\": \"f0c61a22-4deb-4706-8906-097c25e86ed6\",\n  \"type\": \"document.signed_by_all_parties\",\n  \"timestamp\": \"2026-01-13T11:48:33Z\",\n  \"data\": {\n    \"document\": {\n      \"name\": \"Employment Contract\",\n      \"uuid\": \"0a4b6e64-3c4a-4973-af2c-0ec1072b2e1e\"\n    }\n  }\n}\n```\n\n##### document.moved_to_stage.signing\n\n```json\n{\n  \"uuid\": \"7a425adc-4a0c-48a8-a5cb-5da162780a27\",\n  \"type\": \"document.moved_to_stage.signing\",\n  \"timestamp\": \"2026-01-12T11:46:31Z\",\n  \"data\": {\n    \"document\": {\n      \"name\": \"Employment Contract\",\n      \"uuid\": \"0a4b6e64-3c4a-4973-af2c-0ec1072b2e1e\"\n    }\n  }\n}\n```\n\n##### document.party.ready_for_signing\n\n```json\n{\n  \"uuid\": \"d2925089-ebae-4348-af1c-469760e19d54\",\n  \"type\": \"document.party.ready_for_signing\",\n  \"timestamp\": \"2026-01-13T11:52:53Z\",\n  \"data\": {\n    \"party\": {\n      \"uuid\": \"0ad899fc9-3130-45d5-9cd5-d7a0737f0ffd\",\n      \"reference\": \"Employee\",\n      \"entity_name\": \"Jane Marshall\"\n    },\n    \"document\": {\n      \"name\": \"Employment Contract\",\n      \"uuid\": \"0a4b6e64-3c4a-4973-af2c-0ec1072b2e1e\"\n    }\n  }\n}\n```\n\n##### document.reminder.cancellation_notice_period\n\n```json\n{\n  \"uuid\": \"75f4d704-8b10-4b68-8ff3-0deb4d46cfcb\",\n  \"type\": \"document.reminder.cancellation_notice_period\",\n  \"timestamp\": \"2026-01-13T06:25:15Z\",\n  \"data\": {\n    \"document\": {\n      \"name\": \"Lease - 1 Oxford Rd\",\n      \"uuid\": \"756b6deb-4c69-42d0-b416-369710dd24e9\"\n    },\n    \"reminder_about_date\": \"2026-02-13T00:00:00Z\"\n  }\n}\n```\n\n##### document.reminder.effective\n\n```json\n{\n  \"uuid\": \"90d9d243-8c5c-4995-9f1f-a3da6b8dde86\",\n  \"type\": \"document.reminder.effective\",\n  \"timestamp\": \"2026-01-13T06:36:40Z\",\n  \"data\": {\n    \"document\": {\n      \"name\": \"Lease - 1 Oxford Rd\",\n      \"uuid\": \"756b6deb-4c69-42d0-b416-369710dd24e9\"\n    },\n    \"reminder_about_date\": \"2026-02-13T00:00:00Z\"\n  }\n}\n```\n\n##### document.reminder.expiring\n\n```json\n{\n  \"uuid\": \"d1d4a218-83bb-46ab-ad8c-758043f0385f\",\n  \"type\": \"document.reminder.expiring\",\n  \"timestamp\": \"2026-01-13T06:16:29Z\",\n  \"data\": {\n    \"document\": {\n      \"name\": \"Lease - 1 Oxford Rd\",\n      \"uuid\": \"756b6deb-4c69-42d0-b416-369710dd24e9\"\n    },\n    \"reminder_about_date\": \"2026-04-13T00:00:00Z\"\n  }\n}\n```\n\n##### document.reminder.renewal\n\n```json\n{\n  \"uuid\": \"5d2e326a-e145-41e3-b23c-639ac4c58f70\",\n  \"type\": \"document.reminder.renewal\",\n  \"timestamp\": \"2026-01-13T05:45:00Z\",\n  \"data\": {\n    \"document\": {\n      \"name\": \"Lease - 1 Oxford Rd\",\n      \"uuid\": \"756b6deb-4c69-42d0-b416-369710dd24e9\"\n    },\n    \"reminder_about_date\": \"2026-02-13T00:00:00Z\"\n  }\n}\n```\n\n#### Microsoft Teams delivery format\n\nWebhooks using the \"Microsoft Teams\" delivery format are intended for use with webhooks created by following\n[these instructions for Workflows for Microsoft Teams](https://support.microsoft.com/en-us/office/create-incoming-webhooks-with-workflows-for-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498),\nusing either the \"Send webhook alerts to a channel\" or \"Send webhook alerts to a chat\" workflow template.\n\n1. Follow the instructions to setup a workflow for the channel or chat of your choice\n2. Take the URL that this gives you and create a new fynk Webhook Target using this URL. The webhook's delivery format must be set to \"Microsoft Teams\"\n3. Configure one or more [Notifications](https://app.fynk.com/account-settings/document-notifications) in fynk to use the new webhook\n\nWhenever your selected notifications are triggered, a message desribing the event will be posted to the\nTeams channel or chat that you selected when setting up your workflow.\n\n### Webhook request signatures\n\nWhen a webhook is created using the default settings, all requests sent to that webhook will include a\n([Standard Webhooks](https://www.standardwebhooks.com/) compatible) signature to allow you to verify that\nthe requests you receive are really sent by fynk.\n\nfynk uses the \"Symmetric\" signature scheme described [here](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md#verifying-webhook-authenticity)\nin the Standard Webhooks spec. The signing secret needed to verify received requests is unique per webhook\nand is available by visiting the Webhooks page in your account [settings](https://app.fynk.com/account-settings/webhook-targets).\n\nWhen a webhook uses the default signature location (\"Header\"), the request ID, signature and timestamp\nneeded for verifying the signature will be included in the headers described in the Standard Webhooks\nspecification (`webhook-id`, `webhook-signature`, `webhook-timestamp`).\n\nIf for some reason, you need to receive webhooks in an environment that does not have access to the request\nheaders - and you would still like to verify the requests' authenticity - you can instead set the webhook's\nsignature location to \"Query parameter\". When you do this, fynk will dynamically include three additional\nquery parameters in the webhook's URL: `wh_id` (the unique webhook identifier), `wh_sig` (the signature of\nthe webhook) & `wh_ts` (the webhook timestamp).\n",
  "url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/fynk.com/main/2025-12-05/apis.json",
  "tags": [
    "fynk.com",
    "main"
  ],
  "created": "2026-04-10",
  "modified": "2026-04-10",
  "specificationVersion": "0.19",
  "access": "3rd-Party",
  "maintainers": [
    {
      "FN": "Jentic",
      "X-github": "jentic",
      "url": "https://github.com/jentic"
    }
  ],
  "apis": [
    {
      "aid": "fynk.com:main-2025-12-05",
      "name": "fynk API Reference",
      "description": "The fynk API offers a range of endpoints that allow you to build custom integrations against your fynk\naccount.\n\nAs far as possible, it uses REST-style, resource-based URLs to allow your applications to interact with the\n[Documents](/#documents) and [other entities](/#core-concepts) that make up your fynk account.\n\n## Quickstart\n\nFollow these steps to get up and running using the API to work with your fynk account.\n\n### 1. Create an account\n\n[Click here](https://app.fynk.com/register) to create a fynk account, or [login here](https://app.fynk.com/login) if you already have an\naccount.\n\n### 2. Create a party\n\nMake sure your account contains at least one [party](https://app.fynk.com/account-settings/parties). You'll need a party to use in your\n[documents](/#documents) and [templates](/#templates).\n\n### 3. Create a template\n\nMake sure your account has at least one [template](/#templates) available in its [template\nlist](https://app.fynk.com/templates) . You can create a template from scratch or use one from the\n[gallery](https://app.fynk.com/templates#gallery).\n\n### 4. Create an API token\n\n> Only fynk users with the \"Owner\" role can perform this step.\n\nGo to [the fynk API settings page](https://app.fynk.com/account-settings/integrations/api) and click the **Create Token** button. Give your token\na name and give it at least the \"Template Reader\" role. Feel free to also set an expiry date if you would\nlike to be sure that the token cannot be used later. Then click **Create Token** and you'll be shown your\nnew API token. Copy the token to your clipboard, and then paste it somewhere safe such a password manager.\n\n> For security reasons, we can't show you the API token again after you move past this step, so it's\n> important to note it down somewhere safe that you can refer to later.\n\n### 5. Try using your API token\n\nYou can try out your new API token right from this documentation. Open the page for the [Current API token\ndetails](/operations/v1.api-tokens.show-me) API endpoint and paste your API token into the **Token**\ninput in the **Auth** box, then click **Send API Request**.\n\nYou should then see a JSON response appear, with a `data` array at the top level containing information\nabout your API token. It should look something like the example below.\n\n```js\n{\n  \"data\": {\n    \"uuid\": \"efc24626-9724-43cd-9247-e9769fe08844\",\n    \"name\": \"fynk API token\",\n    \"expires_at\": null,\n    \"account\": {\n      \"uuid\": \"08fd4c01-7327-42d4-9442-a09dd57f55b8\",\n      \"name\": \"Demo Inc.\"\n    },\n    \"settings\": {\n      \"account_default_api_version\": \"2025-05-22\",\n      \"request_api_version\": \"2025-05-22\",\n      \"latest_api_version\": \"2025-06-06\",\n      \"changelog\": {}\n    },\n    \"created_at\": \"2025-07-01T06:19:03Z\",\n    \"updated_at\": \"2025-07-01T06:19:03Z\"\n  },\n  \"links\": {\n    \"documentation\": \"https://app.fynk.com/v1/docs\",\n    \"document_list\": \"https://app.fynk.com/v1/api/documents\",\n    \"template_list\": \"https://app.fynk.com/v1/api/templates\"\n  }\n}\n```\n\n> If you instead see a `401 Unauthorized` response, make sure you copied the whole of the generated API\n> token, if you think you might be missing part of it, you can revoke the token you created in step 4 and\n> try generating a new token.\n\n### 6. Try fetching data\n\nNow that you know your API token works, open the page for the [List templates](/operations/v1.templates.index) API\nendpoint and try sending that request. You should receive a response like the one below, containing details\nof the template you created in step three.\n\nAt this point, if you would like, you can try altering some of the request parameters like `sort_by` or\n`sort_direction` and re-send the request to see how this affects the response.\n\nYou could also copy one of the returned template `uuid` values and use it to fetch additional information\nabout the template by pasting it into the **template** input on the\n[Show template](/operations/v1.templates.show) page and sending that request.\n\n```js\n{\n  \"data\": [\n    {\n      \"uuid\": \"00ac949f-4871-496f-904c-8703a33fe163\",\n      \"name\": \"Contract Layout A\",\n      \"locale\": \"en-US\",\n      \"published\": true,\n      \"signature_type\": null,\n      \"sequential_signing\": false,\n      \"created_at\": \"2025-05-28T07:11:14Z\",\n      \"updated_at\": \"2025-05-28T07:11:15Z\",\n      \"archived_at\": null,\n      \"parties\": [\n        {\n          \"uuid\": \"e137ca22-c69d-43ec-bb6b-4b5ebd10417f\",\n          \"reference\": \"Demo Inc.\",\n          \"entity_type\": \"business\",\n          \"entity_name\": \"Demo Inc.\",\n          \"address\": \"Am Tabor 36\\n1020 Wien\",\n          \"scope\": \"internal\",\n          \"is_internal_party\": true,\n          \"created_at\": \"2025-05-28T07:11:14Z\",\n          \"updated_at\": \"2025-05-28T07:11:14Z\"\n        },\n        {\n          \"uuid\": \"9781632f-12b0-4528-bde9-346377f79fe9\",\n          \"reference\": \"Counterparty\",\n          \"entity_type\": null,\n          \"entity_name\": null,\n          \"address\": null,\n          \"scope\": \"internal_and_external\",\n          \"is_internal_party\": false,\n          \"created_at\": \"2025-05-28T07:11:14Z\",\n          \"updated_at\": \"2025-05-28T07:11:14Z\"\n        }\n      ]\n      \"links\": {\n        \"show\": \"https://app.fynk.com/v1/api/templates/00ac949f-4871-496f-904c-8703a33fe163\"\n      }\n    },\n    // ...\n```\n\n### 7. Integrate with your systems\n\nYou now have a working API token and have seen what an API response looks like. To help you start\nintegrating the API into your systems, take a look at the **Request Sample** section of any endpoint\ndocumentation page. There you can use the menu to select your preferred programming language and see an\nexample of how you could send that endpoint's request using the selected language.\n\n## How to create a document from a template\n\n### Create a template\n\nCreating a [document](/#documents) through the API first requires that your account contains a\n[template](/#template) to use as the basis of the new document. If you don't have a template available\nalready, you can either create one from scratch or choose one from the [gallery](https://app.fynk.com/templates#gallery) and\nmodify it to fit your needs.\n\n### Create a document from the template\n\nTo create a document from a template, you will need to send a `POST` request to the [Create document from\ntemplate](/operations/v1.documents.create-from-template) endpoint. Before you can do this, you will first need to find the UUID of\nthe template you would like to base your new document on.\n\nYou can use a filtered request to the [List templates](/operations/v1.templates.index) endpoint to find the UUID of\nthe template you would like to use. For example, if your template is called \"Contract Layout A\", a request\nlike this using `curl` would return a list of the templates matching that name, and you can then take the\n`uuid` from the appropriate template in the response:\n\n```shell\ncurl \"https://app.fynk.com/v1/api/templates?filter%5Bquery%5D=Contract%20Layout%20A\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json'\n```\n\nThe template UUID can then be used as the `template_uuid` parameter in the [Create document from\ntemplate](/operations/v1.documents.create-from-template) request. You can optionally provide a `name` parameter to set the name\nof the new document - if you don't provide a name, then the new document will be given the same name as the\ntemplate it is based on.\n\nThe request parameters should be sent in a JSON object in the request body. The following example shows how\nthis would look if you wanted to create a document called \"Employment Contract\" from the template with the\nUUID \"4df1e60a-0114-4dce-89e7-8c5ad397fcf2\":\n\n```shell\ncurl -X \"POST\" \"https://app.fynk.com/v1/api/documents/create-from-template\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json' \\\n    -H 'Content-Type: application/json; charset=utf-8' \\\n    -d '{\"name\": \"Employment Contract\", \"template_uuid\": \"4df1e60a-0114-4dce-89e7-8c5ad397fcf2\"}'\n```\n\n> **Assigning document ownership**: you can optionally specify which users from your account should be given\n> ownership of the new document by including the `owner_emails` parameter in your request. This parameter\n> should contain an array of email addresses belonging to users in your fynk account.\n\nSending this request will return a JSON response containing the details of the newly created document, which\nwill look something like this:\n\n```js\n{\n  \"data\": {\n    \"uuid\": \"14e82085-6e94-48c7-9b9b-15bc5c4656d4\",\n    \"name\": \"Employment Contract\",\n    \"origin\": \"template\",\n    // ...\n}\n```\n\nThe `data.uuid` returned in the response is the UUID of the newly created document. This would be the value\nyou would need to use in subsequent requests when the endpoint documentation specifies that it accepts a\n`document` parameter in the URL (as in the [Show document](/operations/v1.documents.show) endpoint, for example).\n\nAt this point the document has been created and would be visible in the [documents](https://app.fynk.com/documents) list to\nusers with the appropriate permissions.\n\n### Populate dynamic fields\n\nIf your template contains [dynamic fields](/#dynamic-fields), your new document will also contain those same\ndynamic fields, and you can now use the API to customise the content of your document by updating its\ndynamic field values. The response returned after creating the document will contain a `data.dynamic_fields`\nlist, which will contain all of the document's dynamic fields and their initial values. This example shows\nhow this could look for a variety of different field types:\n\n```js\n{\n  \"data\": {\n    \"uuid\": \"14e82085-6e94-48c7-9b9b-15bc5c4656d4\",\n    // ...\n    \"dynamic_fields\": [\n      {\n        \"uuid\": \"f4522967-c04f-4113-8762-6d5642c9d863\",\n        \"type\": \"date\",\n        \"name\": \"Start of employment\",\n        \"scope\": \"internal\",\n        \"settings\": null,\n        \"autofill_type\": null,\n        \"format\": null,\n        \"select_values\": null,\n        \"is_mandatory\": true,\n        \"question\": \"When does the employee start?\",\n        \"question_external\": null,\n        \"value\": \"2025-10-01\",\n        \"order\": null\n      },\n      {\n        \"uuid\": \"4000293a-773b-4efa-ae4b-96bc511d8ad7\",\n        \"type\": \"text\",\n        \"name\": \"Job Title\",\n        \"scope\": \"internal\",\n        \"settings\": null,\n        \"autofill_type\": null,\n        \"format\": null,\n        \"select_values\": null,\n        \"is_mandatory\": true,\n        \"question\": \"What is the role's job title?\",\n        \"question_external\": null,\n        \"value\": \"Full-stack Developer\",\n        \"order\": null\n      },\n      {\n        \"uuid\": \"c6c0b0bb-87af-44e9-bc8d-0e543b217429\",\n        \"type\": \"currency\",\n        \"name\": \"Yearly Gross Salary\",\n        \"scope\": \"internal\",\n        \"settings\": {\n          \"currencies\": [\n            \"EUR\"\n          ]\n        },\n        \"autofill_type\": null,\n        \"format\": null,\n        \"select_values\": null,\n        \"is_mandatory\": true,\n        \"question\": \"What is the role's yearly gross salary?\",\n        \"question_external\": null,\n        \"value\": \"EUR;75000\",\n        \"order\": null\n      },\n      {\n        \"uuid\": \"6778cfe0-1509-47fc-a333-c80c794c0443\",\n        \"type\": \"select\",\n        \"name\": \"Location\",\n        \"scope\": \"internal\",\n        \"settings\": null,\n        \"autofill_type\": null,\n        \"format\": null,\n        \"select_values\": [\n          \"Cork\",\n          \"Dublin\"\n        ],\n        \"is_mandatory\": true,\n        \"question\": \"In which location will the employee be based?\",\n        \"question_external\": null,\n        \"value\": \"Dublin\",\n        \"order\": null\n      },\n      {\n        \"uuid\": \"30e5296d-08fe-4fc8-abd4-df2670583115\",\n        \"type\": \"bool\",\n        \"name\": \"Remote work\",\n        \"scope\": \"internal\",\n        \"settings\": null,\n        \"autofill_type\": null,\n        \"format\": null,\n        \"select_values\": null,\n        \"is_mandatory\": true,\n        \"question\": \"Does the role allow a remote work component?\",\n        \"question_external\": null,\n        \"value\": false,\n        \"order\": null\n      }\n    ],\n    // ...\n  }\n}\n```\n\nThis list of current dynamic field values for a document is also included in the [Show\ndocument](/operations/v1.documents.show) response or can be fetched (without the rest of the document's data) using\nthe [List document's dynamic fields](/operations/v1.documents.dynamic-fields.index) endpoint.\n\nTo change the value of a dynamic field, you can use the [Update dynamic field](/operations/v1.documents.dynamic-fields.update)\nendpoint. Looking at the documentation for this, you can see that URL for this request requires a `document`\nparameter and a `dynamicField` parameter. `document` is the UUID of the document, which you received in\n`data.uuid` when creating the document. `dynamicField` is the UUID of the dynamic field you would like to\nupdate, which you can take from the appropriate entry in the document's `data.dynamic_fields` list.\n\nUsing the values from the previous example response, if you wanted to change the value of the \"Job Title\"\nfield to \"Software Engineer\", you would take the UUIDs \"14e82085-6e94-48c7-9b9b-15bc5c4656d4\" for `document`\nand \"4000293a-773b-4efa-ae4b-96bc511d8ad7\" for `dynamicField` and send a request like this:\n\n```shell\ncurl -X \"PUT\" \"https://app.fynk.com/v1/api/documents/14e82085-6e94-48c7-9b9b-15bc5c4656d4/dynamic-fields/4000293a-773b-4efa-ae4b-96bc511d8ad7\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json' \\\n    -H 'Content-Type: application/json; charset=utf-8' \\\n    -d '{\"value\": \"Software Engineer\"}'\n```\n\nThe format of the `value` parameter sent in the request body will depend on the `type` of the dynamic field,\nthe possible types and their corresponding formats are detailed in the [Update dynamic\nfield](/operations/v1.documents.dynamic-fields.update#value-format) documentation.\n\n### Assign metadata\n\nAt this point it is also possible to enrich your document with [metadata](/#metadata). Your fynk account\ncomes with a selection of [reference metadata fields](https://app.fynk.com/account-settings/metadata#reference) as well as allowing\nyou to create custom [account metadata fields](https://app.fynk.com/account-settings/metadata#account). You can assign values for any\nof these metadata fields to your documents using the API.\n\nAssigning a new metadata value to a document is a two step process:\n\n1. Use the [List metadata](/operations/v1.metadata.index) endpoint to find the metadata field's UUID.\n2. Send an [Add metadata value to document](/operations/v1.documents.metadata-values.store) request to create a \"metadata value\" for that field.\n\nThe [List metadata](/operations/v1.metadata.index) endpoint will return a list of all of the metadata fields that are\navailable in your account. Its response will look something like this:\n\n```js\n{\n  \"data\": [\n    {\n      \"uuid\": \"ddfc1bd7-05c9-456e-9dab-dacfcf44fbb2\",\n      \"type\": \"system_reference\",\n      \"value_type\": \"select\",\n      \"name\": \"end_user_license_type\",\n      \"display_name\": \"End User License Type\",\n      \"settings\": null,\n      \"select_values\": [\n        \"Freeware\",\n        \"Shareware\",\n        \"Proprietary\",\n        \"Subscription\",\n        \"Open Source\",\n        \"Public Domain\",\n        \"Other\"\n      ],\n      \"always_exists\": false,\n      \"description\": \"The type of license governing the use of the software product.\"\n    },\n    {\n      \"uuid\": \"7c997428-de84-483b-a072-f2c9da93d924\",\n      \"type\": \"system_reference\",\n      \"value_type\": \"currency\",\n      \"name\": \"freelance_rate\",\n      \"display_name\": \"Freelance Rate\",\n      \"settings\": null,\n      \"select_values\": null,\n      \"always_exists\": false,\n      \"description\": \"The hourly rate charged for freelance services.\"\n    },\n    {\n      \"uuid\": \"205a379c-c4d5-469d-9f67-a025bc630cbf\",\n      \"type\": \"system_reference\",\n      \"value_type\": \"number\",\n      \"name\": \"freelance_hours\",\n      \"display_name\": \"Freelance Hours\",\n      \"settings\": null,\n      \"select_values\": null,\n      \"always_exists\": false,\n      \"description\": \"The number of hours to be provided as part of the freelance services.\"\n    },\n    // ...\n  ]\n}\n```\n\nLets assume that you would like to set the `freelance_hours` metadata field to `100` for your document. The\n[Add metadata value to document](/operations/v1.documents.metadata-values.store) endpoint requires three parameters:\n\n- `document` in the URL: The UUID of the document to add the metadata value to.\n- `metadata_uuid` in the request body: The UUID of the metadata field to add the value to.\n- `value` in the request body: The value to assign to the metadata field.\n\nUsing the values from the previous example responses, this means you would send a request like this:\n\n```shell\ncurl -X \"POST\" \"https://app.fynk.com/v1/api/documents/14e82085-6e94-48c7-9b9b-15bc5c4656d4/metadata-values\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json' \\\n    -H 'Content-Type: application/json; charset=utf-8' \\\n    -d '{\"value\": 100, \"metadata_uuid\": \"205a379c-c4d5-469d-9f67-a025bc630cbf\"}'\n```\n\nYou would then be able to see the newly set metadata value in `data.metadata_values` field of the [Show\ndocument](/operations/v1.documents.show) response.\n\n### Managing parties\n\nAt this point, your document may need to have the details of at least one of its [parties](/#parties)\ncompleted, since your template likely only contains a generic `reference` to the external party, rather than\ntheir concrete details.\n\n#### List document parties\n\nTo see all parties associated with a document, use the [List document parties](/operations/v1.documents.parties.index)\nendpoint:\n\n```shell\ncurl \"https://app.fynk.com/v1/api/documents/14e82085-6e94-48c7-9b9b-15bc5c4656d4/parties\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json'\n```\n\n> `is_internal_party` in the response tells you whether the party will be editable via the API. Only parties\n> where this field is false can be updated via API. Internal parties can be edited in the [settings of your\n> fynk account](https://app.fynk.com/account-settings/parties).\n\n#### Update party details\n\nYou can edit party information using the [Update document party](/operations/v1.documents.parties.update) endpoint.\n\nFor example, to update a party's name and address and set that they are business:\n\n```shell\ncurl -X \"PUT\" \"https://app.fynk.com/v1/api/documents/14e82085-6e94-48c7-9b9b-15bc5c4656d4/parties/ad899fc9-3130-45d5-9cd5-d7a0737f0ffd\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json' \\\n    -H 'Content-Type: application/json; charset=utf-8' \\\n    -d '{\"entity_name\": \"BigCo Inc.\", \"entity_type\": \"business\", \"address\":\"BigCo Plaza, New York\"}'\n```\n\n> Party management is only allowed while the document is in `draft`, `approved_draft`, `review`, or\n> `approved_review` stages. Once a document reaches the `signing` or `done` stage, parties cannot be\n> updated.\n\n### Assign a signatory\n\nBefore your document can be signed, you need to assign [signatories](/#signatories) to it. Signatories are\nindividuals who will sign the document and must belong to one of the document's [parties](/#parties).\n\nTo add a signatory to your document, use the [Add signatory](/operations/v1.documents.signatories.store)\nendpoint. This endpoint requires:\n\n- `document` in the URL: The UUID of the document to add the signatory to\n- `party_uuid` in the request body: The UUID of the party this signatory belongs to\n- `email` in the request body: The email address of the signatory\n\nYou can also optionally provide additional information like `first_name`, `last_name`, `mobile_phone`, and\n`title`.\n\nUsing the document UUID from our previous examples and assuming you want to add a signatory named \"Alex\nSmith\" with email \"alex.smith@example.com\" to the party with UUID \"ad899fc9-3130-45d5-9cd5-d7a0737f0ffd\",\nyou would send a request like this:\n\n```shell\ncurl -X \"POST\" \"https://app.fynk.com/v1/api/documents/14e82085-6e94-48c7-9b9b-15bc5c4656d4/signatories\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json' \\\n    -H 'Content-Type: application/json; charset=utf-8' \\\n    -d '{\n      \"party_uuid\": \"ad899fc9-3130-45d5-9cd5-d7a0737f0ffd\",\n      \"email\": \"alex.smith@example.com\",\n      \"first_name\": \"Alex\",\n      \"last_name\": \"Smith\",\n      \"title\": \"Software Engineer\"\n    }'\n```\n\nThe response will include the details of the newly created signatory:\n\n```js\n{\n  \"data\": {\n    \"uuid\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n    \"party_uuid\": \"ad899fc9-3130-45d5-9cd5-d7a0737f0ffd\",\n    \"first_name\": \"Alex\",\n    \"last_name\": \"Smith\",\n    \"email\": \"alex.smith@example.com\",\n    \"mobile_phone\": null,\n    \"title\": \"Software Engineer\",\n    \"profile_photo_url\": \"https://ui-avatars.com/api/?name=AS\",\n    \"signing_order\": 1,\n    \"has_account_user\": false\n  }\n}\n```\n\n#### Managing signatories\n\nYou can also update signatory information using the [Update signatory](/operations/v1.documents.signatories.update)\nendpoint, or remove a signatory using the [Remove signatory](/operations/v1.documents.signatories.destroy)\nendpoint.\n\nTo list all signatories for a document, use the [List signatories](/operations/v1.documents.signatories.index)\nendpoint.\n\n> Some changes to signatories may be prevented while a document is in the `signing` stage. For example, it\n> is not allowed to remove the only remaining signatory from a party while a document is being signed. If\n> you try to make a modification that is not allowed in the document's current stage, your request will\n> receive a response with a `409 Conflict` status.\n\n### Move the document to review\n\nAt this point, assuming you haven't made any changes to your document outside of the API, it will be in the\n`draft` stage. You can use the\n[Move document to review stage](/operations/v1.documents.stage-transitions.review) endpoint to move the\ndocument into the `review` stage, where you can share it with collaborators:\n\n```shell\ncurl -X \"POST\" \"https://app.fynk.com/v1/api/documents/14e82085-6e94-48c7-9b9b-15bc5c4656d4/stage-transitions/review\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json' \\\n```\n\n### Move the document to signing\n\nOnce you are happy with your document's content, have configured its [parties](/#parties) and their\n[signatories](/#signatories), and have added signature blocks to the document for each signatory, you can\ncan use the [Move document to signing stage](/operations/v1.documents.stage-transitions.signing) endpoint to\nmove the document into the `signing` stage:\n\n```shell\ncurl -X \"POST\" \"https://app.fynk.com/v1/api/documents/14e82085-6e94-48c7-9b9b-15bc5c4656d4/stage-transitions/signing\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json' \\\n```\n\nThis request sends invitations to all document signatories. If sequential signing is enabled, invitations\nare sent one at a time in the order specified by each signatory's `signing_order` property. Otherwise, all\nsignatories receive their invitations simultaneously.\n\n### Access the document\n\nOnce you have created a document, you can access it in the fynk web application by visiting it from the\n[documents list](https://app.fynk.com/documents), assuming your fynk user has the appropriate role and/or team membership.\nYou can also download the document as a PDF via the API, using the `data.pdf_url` returned by the [Show\nlatest revision PDF details](/operations/v1.documents.revisions.latest.pdf.show) endpoint, or directly via\nthe [Download latest revision PDF](/operations/v1.documents.revisions.latest.pdf.download) endpoint.\n\nThe latter option would look like this using `curl` to download to a file named `my-document.pdf`. Note that\nbecause the API endpoint returns a HTTP 302 redirect to the actual PDF data, we have to tell `curl` to\nfollow redirects using the `--location` flag:\n\n```shell\ncurl \"https://app.fynk.com/v1/api/documents/14e82085-6e94-48c7-9b9b-15bc5c4656d4/revisions/latest/pdf/download\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    --location > my-document.pdf\n```\n\n## How to create a document from a PDF file\n\nCreating a [document](/#documents) from a PDF file requires a multi-step upload process to ensure your PDF\nis safely transferred and processed.\n\n### Generate a presigned upload URL\n\nFirst, you need to obtain an upload URL by making a request to the [Create document PDF upload\nURL](/operations/v1.file-uploads.document-pdf.create) endpoint:\n\n```shell\ncurl -X \"POST\" \"https://app.fynk.com/v1/api/file-uploads/document-pdf\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json' \\\n    -H 'Content-Type: application/json; charset=utf-8'\n```\n\nThis will return a response containing the upload details:\n\n```json\n{\n  \"data\": {\n    \"uuid\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n    \"url\": \"https://example-bucket.s3.amazonaws.com/uploads/...\",\n    \"headers\": {\n      \"Content-Type\": \"application/pdf\"\n    },\n    \"expires_at\": \"2025-07-29T15:30:00Z\"\n  }\n}\n```\n\n> Hold on to the `uuid` value - you'll need it when you reach the \"Create the document\" step. The upload URL\n> expires at the time specified in `expires_at`, so complete the upload promptly.\n\n### Upload your PDF file\n\nUsing the URL and headers from the previous response, upload your PDF file with a PUT request. Send the raw\nPDF file data (not base64-encoded) in the request body:\n\n```shell\ncurl -X \"PUT\" \"https://example-bucket.s3.amazonaws.com/uploads/...\" \\ # use the URL from data.url in the previous response\n    -H 'Content-Type: application/pdf' \\ # this comes from data.headers in the previous response\n    --data-binary @/path/to/your/document.pdf\n```\n\n> This is a direct upload to an S3-compatible storage bucket using a presigned URL. You do not need to\n> include your fynk API token in the request. Include all headers from the previous response exactly as\n> provided.\n\nA successful upload returns a `200 OK` response with no body content.\n\n### Create the document\n\nFinally, create your fynk document from the uploaded PDF using the [Create document from\nPDF](/operations/v1.documents.create-from-pdf) endpoint, providing the `uuid` from step 1:\n\n```shell\ncurl -X \"POST\" \"https://app.fynk.com/v1/api/documents/create-from-pdf\" \\\n    -H 'Authorization: Bearer <your-api-token>' \\\n    -H 'Accept: application/json' \\\n    -H 'Content-Type: application/json; charset=utf-8' \\\n    -d '{\n      \"file_upload_uuid\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n      \"file_name\": \"my-contract.pdf\",\n      \"initial_stage\": \"draft\",\n      \"name\": \"My Contract from PDF\",\n    }'\n```\nThis returns the newly created document:\n\n```js\n{\n  \"data\": {\n    \"uuid\": \"b71a0628-529f-4ae1-a891-e1c6e9339507\",\n    \"name\": \"My Contract from PDF\",\n    \"origin\": \"pdf\",\n    \"stage\": \"draft\",\n    // ...\n  }\n}\n```\n\n#### Initial stage\n\nThe `initial_stage` may be either `draft` or `done`. Here we've used `draft`, indicating that the document\nstill needs to be signed through fynk. If we'd instead used `done` this would be the same as the \"Import\nwithout signing\" option in the fynk web interface - the document would be created already in the \"Done\"\nstage.\n\n#### Using a Template\n\nYou can specify a `template_uuid` to copy settings from an existing template. When using `template_uuid`,\nvarious settings (parties, metadata, etc.) will be copied from the template to the new document.\n\n#### Additional Options\n\nSeveral optional parameters are available for customizing the document, including team assignment, tags,\nand AI analysis settings. See the [Create document from PDF](/operations/v1.documents.create-from-pdf)\nendpoint documentation for the complete list of available parameters.\n\n### What happens next\n\nYour PDF will be processed and converted into a fynk document. If your account has access to AI Analyses,\nan analysis will be automatically started for the newly created document.\n\nThe new document will appear in your [documents list](https://app.fynk.com/documents) and can be managed like any other fynk\ndocument through both the web interface and API.\n\n## How to store a file in a document's file storage\n\nStoring a file in a [document](/#documents) file storage requires a multi-step upload process to ensure your\nfile is safely transferred and processed.\n\n### Generate a presigned upload URL\n\nFirst, you need to obtain an upload URL by making a request to the [Create document file storage upload\nURL](/operations/v1.file-uploads.document-file-storage.create) endpoint:\n\n```shell\ncurl -X \"POST\" \"https://app.fynk.com/v1/api/file-uploads/document-file-storage\" \\\n  -H 'Accept: application/json' \\\n  -H 'Authorization: Bearer <your-api-token>' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"content_type\": \"application/pdf\"}'\n```\n\nThis will return a response containing the upload details:\n\n```json\n{\n  \"data\": {\n    \"uuid\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n    \"url\": \"https://example-bucket.s3.amazonaws.com/uploads/...\",\n    \"headers\": {\n      \"Content-Type\": \"application/pdf\"\n    },\n    \"expires_at\": \"2025-07-29T15:30:00Z\"\n  }\n}\n```\n\n> Hold on to the `uuid` value - you'll need it when you reach the \"Store the file in a document's file\n> storage\" step. The upload URL expires at the time specified in `expires_at`, so complete the upload\n> promptly.\n\n### Upload your file\n\nUsing the URL and headers from the previous response, upload your file with a PUT request. Send the raw\nfile data (not base64-encoded) in the request body:\n\n```shell\ncurl -X \"PUT\" \"https://example-bucket.s3.amazonaws.com/uploads/...\" \\ # use the URL from data.url in the previous response\n    -H 'Content-Type: application/pdf' \\ # this comes from data.headers in the previous response\n    --data-binary @/path/to/your/document.pdf\n```\n\n> This is a direct upload to an S3-compatible storage bucket using a presigned URL. You do not need to\n> include your fynk API token in the request. Include all headers from the previous response exactly as\n> provided.\n\nA successful upload returns a `200 OK` response with no body content.\n\n### Store the file in the document's file storage\n\nFinally, link your newly uploaded file to the file storage of the document in question using the [Store a file in a document's file storage\nPDF](/operations/v1.documents.document-file-storage.store) endpoint, providing the `uuid` from step 1:\n\n```shell\ncurl -X \"POST\" \"https://app.fynk.com/v1/api/documents/{document}/file-storage\" \\\n  -H 'Accept: application/json' \\\n  -H 'Authorization: Bearer <your-api-token>' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"file_upload_uuid\": \"e1413d6e-d516-4f67-84be-6dd98446aebb\",\n    \"file_name\": \"your-filename.pdf\"\n  }'\n```\nThis returns the details of the newly stored file:\n\n```js\n{\n  \"data\": {\n    \"uuid\": \"09d358a7-4268-413f-a79b-7fed013f8768\",\n    \"sha256\": \"697651f6ceea8a931289ff64cb62f78ceea5d36f7e84590fe9d5920b2dce52cf\",\n    \"file_name\": \"your-filename.pdf\",\n    \"file_size\": 349059,\n    \"mime_type\": \"application/pdf\",\n  }\n}\n```\n\n## Core concepts\n\n### UUIDs\n\nAll resources returned by the fynk API are identified by a UUID. The UUID that identifies a particular\nresource will always be returned in the `uuid` field of the resource's JSON representation.\n\n```js\n{\n  \"data\" {\n    \"uuid\": \"88a774d2-904a-4b1a-9c49-338cdc203041\",\n    // ...\n  }\n}\n```\n\n### Documents\n\nDocuments are the individual contracts, quotes, forms, etc that you are managing through fynk.\n\nAmong other things, the API allows you to:\n\n- [Create new documents](/operations/v1.documents.create-from-template)\n- [List and search for existing documents](/operations/v1.documents.index)\n- [View details of a document](/operations/v1.documents.show)\n- [Rename a document or update its general settings](/operations/v1.documents.update)\n- [Download a PDF copy of a document](/operations/v1.documents.revisions.latest.pdf.download)\n- Manage a document's [dynamic field](/#dynamic-fields) and [metadata](/#metadata) values\n\n### Templates\n\nTemplates in fynk allow you to create standardized [documents](/#documents) efficiently while maintaining\nflexibility for customization. You can read more about using templates in fynk in our [article\nhere](https://help.fynk.com/en/articles/270538-templates-in-fynk).\n\nUsing the API you can:\n\n- [List and search the templates](/operations/v1.templates.index) available in your account\n- [View details of a template](/operations/v1.templates.show)\n- [Use a template to create a new document](/operations/v1.documents.create-from-template)\n\n### Parties\n\nA party represents a business or natural person who will be involved in a [document](/#documents). Your fynk\naccount will have at least one internal party representing the internal entities relevant to your\norganization - such as company locations, legal subsidiaries, or departments. Your documents may involve\nthose internal parties, as well as external parties - like suppliers, customers, or partners.\n\nYou can read more about managing your account's parties in [our article\nhere](https://help.fynk.com/en/articles/125635-managing-account-settings-in-fynk?#h_1689d3ae54).\n\nA given party may have one or more [signatories](/#signatories) in a document.\n\nUsing the API you can:\n\n- [List document parties](/operations/v1.documents.parties.index)\n- [Update document party](/operations/v1.documents.parties.update)\n\nYou will also find party information in both [documents](/#documents) and [templates](/#templates) in\ntheir `parties` fields, which will look something like this:\n\n```json\n{\n  \"data\": {\n    \"parties\": [\n      {\n        \"uuid\": \"e85ce001-529d-4ed3-a320-cf374a2eec7a\",\n        \"reference\": \"Employer\",\n        \"entity_type\": \"business\",\n        \"entity_name\": \"Demo Inc.\",\n        \"address\": \"2 Example Street\\nLondon\\nW1 7PQ\",\n        \"scope\": \"internal\",\n        \"is_internal_party\": true,\n        \"is_ready_for_signing\": false,\n        \"ready_for_signing_at\": null,\n        \"created_at\": \"2025-06-03T06:28:54Z\",\n        \"updated_at\": \"2025-06-03T06:28:54Z\"\n      },\n      {\n        \"uuid\": \"ad899fc9-3130-45d5-9cd5-d7a0737f0ffd\",\n        \"reference\": \"Employee\",\n        \"entity_type\": \"person\",\n        \"entity_name\": \"Jane Marshall\",\n        \"address\": \"1 Main Street\\nBirmingham\\nB2 8QR\",\n        \"scope\": \"internal_and_external\",\n        \"is_internal_party\": false,\n        \"is_ready_for_signing\": false,\n        \"ready_for_signing_at\": null,\n        \"created_at\": \"2025-06-03T06:28:54Z\",\n        \"updated_at\": \"2025-06-03T13:05:56Z\"\n      }\n    ]\n  }\n}\n```\n\n### Signature types\n\nThe signing process for a fynk [document](/#documents) may use one of three different signature types:\n\n- Simple electronic signature (SES)\n- Advanced electronic signature (AES)\n- Qualified electronic signature (QES)\n\nSee our article [here](https://help.fynk.com/en/articles/126836-signature-types) for details of the\ndifferences between these.\n\nDocuments returned by the API have a `signature_type` field indicating their currently assigned type. If a\ndocument does not have a signature type assigned, a type may be specified when [moving the document to the\nsigning stage](/operations/v1.documents.stage-transitions.signing).\n\n### Signatories\n\nA signatory represents an individual person who will sign a [document](/#documents). All signatories must\nbelong to a [party](/#party).\n\nA signatory may be either an internal user, who has an [account\nuser](https://help.fynk.com/en/articles/125635-managing-account-settings-in-fynk#h_b6fd630e81) in your fynk\naccount, or they may be any other person, who does not have access to your fynk account - e.g. employees of\nyour suppliers, customers, or partners.\n\nNote that signatories for `internal` parties do not necessarily have to have a fynk account user in your\naccount.\n\nYou can find signatory information in both the [Show document](/operations/v1.documents.show) and [Show\ntemplate](/operations/v1.templates.show) API responses:\n\n```json\n{\n  \"data\": {\n    \"signatories\": [\n      {\n        \"uuid\": \"7f356fd9-5144-4a75-8378-d223bf13011d\",\n        \"party_uuid\": \"e85ce001-529d-4ed3-a320-cf374a2eec7a\",\n        \"first_name\": \"Jane\",\n        \"last_name\": \"Marshall\",\n        \"email\": \"jane@example.org\",\n        \"mobile_phone\": \"+447951123456\",\n        \"title\": \"HR Manager\",\n        \"profile_photo_url\": \"https:\\/\\/ui-avatars.com\\/api\\/?name=JM\",\n        \"signing_order\": 2,\n        \"has_account_user\": true,\n      },\n      {\n        \"uuid\": \"5cb21e44-3002-4af6-91d4-fe8127cb13d2\",\n        \"party_uuid\": \"ad899fc9-3130-45d5-9cd5-d7a0737f0ffd\",\n        \"first_name\": \"Liam\",\n        \"last_name\": \"Roberts\",\n        \"email\": \"roberts@example.com\",\n        \"mobile_phone\": null,\n        \"title\": null,\n        \"profile_photo_url\": \"https:\\/\\/ui-avatars.com\\/api\\/?name=LR\",\n        \"signing_order\": 1,\n        \"has_account_user\": false,\n      }\n    ]\n  }\n}\n```\n\n### Dynamic fields\n\nDynamic fields allow your [templates](/#templates) and [documents](/#documents) to contain dynamically\ncustomisable placeholders. To find out how to add dynamic fields to your documents, see our article on\n[using the fynk editor](https://help.fynk.com/en/articles/147803-using-fynk-s-editor#h_6c4eafc77e).\n\nDynamic fields are included in the the [Show document](/operations/v1.documents.show) and [Show\ntemplate](/operations/v1.templates.show) API responses in their `dynamic_fields` fields.\n\nSee [this section](/#populate-dynamic-fields) of the API's [How to create a\ndocument](/#how-to-create-a-document-from-a-template) guide for an introduction to working with dynamic\nfields via the API.\n\n### Metadata\n\nIn fynk, metadata are details such as dates, financial figures, or contract clauses related to your\n[documents](/#documents). You can find an overview of how metadata can help in your document management\nprocesses in our [using metadata](https://help.fynk.com/en/articles/126993-using-metadata) article.\n\nThe API allows you to retrieve a list of the metadata fields available in your account via the [List\nmetadata](/operations/v1.metadata.index) endpoint, and the [Show document](/operations/v1.documents.show) and [Show\ntemplate](/operations/v1.templates.show) responses each include a `metadata_values` list, which contain the\ncurrent metadata values assigned to the respective document or [template](/#templates).\n\nSee [this section](/#assign-metadata) of the API's [How to create a\ndocument](/#how-to-create-a-document-from-a-template) guide for an introduction to working with metadata via\nthe API.\n\n## Authentication\n\n### API tokens\n\nTo access the API you will need an API token. You can generate new API tokens in your\n[Account Settings](https://app.fynk.com/account-settings/integrations/api), or by asking your account's owner to do this for you if you do not have\nsufficient permissions.\n\n> You will only be able to see a new API token's value one time, immediately after you create it, so make\n> sure to save it.\n\nAn API token needs to be sent in the `Authorization` header of each request. The value of the header should\nbe in the format `Bearer <token>`, where `<token>` is the API token itself. For example, if your API token\nwas \"WAnMlf6725\", your request's `Authorization` header would look like this:\n\n```\nAuthorization: Bearer WAnMlf6725\n```\n\n### Tokens created during free trial\n\nIf your account is on a Trial plan, you will be able to generate API tokens and use them to make requests\nto the API for the duration of your trial period. Once your trial ends, you will need to move to a paid plan\nto continue using the API.\n\n## Versioning\n\nThe API may change over time. Wherever possible, backwards incompatible changes will only be included in a\nnew \"version\" of the API, and we will attempt to keep old versions working for a reasonable period after\nthe release of a new version.\n\n### Backwards compatibility\n\nNew API versions are only released for backwards-incompatible changes. The following changes are considered\nbackwards compatible and will not trigger the release of a new version:\n\n- Adding new API endpoints\n- Adding new optional request parameters to existing API endpoints\n- Adding new properties to existing responses\n- Changing the order of properties in existing responses\n- Adding new variants to enumerated types returned in existing responses, e.g. adding a new [DocumentType](/schemas/DocumentType)\n\nBackwards incompatible changes like the following will result in the release of a new version:\n\n- Removing existing API endpoints\n- Adding new mandatory request parameters to existing API endpoints\n- Removing, renaming or changing the type of properties in existing responses\n\n### Setting your Default API Version\n\nWhen you first visit the [API settings page](https://app.fynk.com/account-settings/integrations/api) to generate an API token, your account's\nDefault API Version will automatically be set to the current API version. All API tokens you create will use\nthis version by default for API requests.\n\n### Updating to new versions\n\nYou can update your account's default API version when new versions are released by visiting your [Account\nSettings](https://app.fynk.com/account-settings/integrations/api), where available newer versions will be listed.\n\n> Version downgrades are not supported. Once you upgrade to a newer version, you cannot revert to an older\n> version.\n>\n> To test your integrations against a newer version of the API, without changing your account's default\n> setting, refer to the \"Overriding the Default API Version\" section on this page.\n\n### Overriding the Default API Version\n\nYou can override your account's default API version for individual requests by including the\n`Fynk-Api-Version` request header. This is useful when testing integrations against newer API versions.\n\n**Example:** If your account has its default version set to 2025-07-07 and you want to test against version\n2025-07-14, include this header:\n\n```\nFynk-Api-Version: 2025-07-14\n```\n\n**Verification:** To confirm the version used, check the `Fynk-Api-Version` header in the API response. This\nheader is included in every response and shows which version processed your request.\n\n#### Fynk-Api-Version requirements\n\n- The version must be valid and available for your account\n- The version must be the same as or newer than your account's default API version\n- Requesting an older version will be ignored, and your account's default version will be used instead\n\n**Finding available versions:** View all available API versions for your account in your [Account\nSettings](https://app.fynk.com/account-settings/integrations/api).\n\n## Pagination\n\nCertain endpoints that return a list of resources support pagination. By default, these endpoints will\nreturn the first page of their result set with the resources for that page in the `data` key of the\nresponse. The response will include both a `links` object containing the URLs of other pages and a `meta`\nobject containing information about the total size of the list.\n\n```js\n{\n  \"data\": [\n    { /* ... */ },\n    { /* ... */ },\n  ],\n  \"links\": {\n    \"first\": \"https://app.fynk.com/v1/api/documents?page=1\",\n    \"last\": \"https://app.fynk.com/v1/api/documents?page=2\",\n    \"prev\": null,\n    \"next\": \"https://app.fynk.com/v1/api/documents?page=2\"\n  },\n  \"meta\": {\n    \"per_page\": 10,    // maximum number of resources returned in a single page\n    \"current_page\": 1, // the page that was returned in this response\n    \"last_page\": 2,    // the last available page\n    \"from\": 1,         // index of the first item in the current page, starting from 1\n    \"to\": 10,          // index of the last item in the current page, starting from 1\n    \"total\": 17,       // total number of resources available\n    \"path\": \"https://app.fynk.com/v1/api/documents\"\n  }\n}\n```\n\nTo request the next pages from the result set, you can either use the `next` link from the returned `links`\nobject or add a `page` parameter to the query string of your next request.\n\nYou may also control the size of the returned pages by including a `page_size` parameter in the query\nstring. When an endpoint supports pagination, the `page` and `page_size` parameters will be documented in\nthe _Query Parameters_ section of the endpoint's documentation.\n\n## Rate Limits\n\nRequests to the API are rate limited based on a rolling one-minute window. If an API token exceeds its rate\nlimit, requests will be rejected with a `429 Too Many Requests` response. If this happens, the response will\ninclude a `Retry-After` header indicating how many seconds you should wait before sending any more requests.\n\nThe rate limit for the current API token is returned on every response in the `X-RateLimit-Limit` HTTP\nheader. The number of remaining requests in the current window is returned in the `X-RateLimit-Remaining`\nheader.\n\n> - Some endpoints may be subject to stricter limits than the general per-minute limit.\n> - Requests made by Trial accounts may be subject to additional limits.\n\n## Webhooks\n\nWebhooks allow you to configure fynk so that it will notify your systems about events that happen in fynk.\n\n### Getting started\n\nTo setup fynk to send webhooks you'll first need a URL to receive the webhook requests. This will usually be\neither a dedicated URL on your own systems, or a URL provided by a third party system (e.g. Zapier,\nMicrosoft Teams, Slack, etc). For testing during development, you may wish to use a tool like\n[webhook.site](https://webhook.site/) to allow you to inspect various webhook payloads.\n\nThe only requirement for the URL handler is that it returns a 20X HTTP status code when it has successfully\nprocessed a request. If it returns any other status code, fynk will consider the request failed and attempt\nto retry it later.\n\nOnce you have a URL that you would like to receive the webhook requests, go to the\n[Webhooks](https://app.fynk.com/account-settings/webhook-targets) page in your account settings and add a new webhook using that URL. If you\nare integrating with your own systems, you will probably want to leave the \"delivery format\" and \"signature\nlocation\" options on their default settings.\n\n> Only fynk users with the \"Owner\" role can access the Webhooks settings page.\n\nNow you will need to choose which notification types your webhook should receive. You can do this from your\naccount's [Notifications settings](https://app.fynk.com/account-settings/document-notifications) page, via the \"Edit\" option on the relevant\nnotification types.\n\nIf you would like different webhooks to be notified based on which template a document was created from, you\ncan override the global notification settings for a particular template by opening the template and editing\nthe settings found in its \"Template notifications\" tab.\n\nOnce you have created a webhook, and configured at least one type of notification to use it, then whenever\nan event of that type occurs, fynk will send a HTTP POST request to the webhook's URL. See the following\nsections for details of what the request payload will contain, and how you can verify it was sent\nby fynk.\n\n### Webhook delivery formats\n\n#### Default delivery format\n\nWebhooks using the \"Default\" delivery format will receive requests containing a JSON object like this:\n\n```json\n{\n  \"events\": [\n    {\n      \"uuid\": \"05113346-425d-48df-8bf2-a20037fc6fa4\",\n      \"type\": \"document.moved_to_stage.signing\",\n      \"timestamp\": \"2026-01-08T14:32:50Z\",\n      \"data\": {\n        \"document\": {\n          \"name\": \"Employment Contract\",\n          \"uuid\": \"0a4b6e64-3c4a-4973-af2c-0ec1072b2e1e\"\n        }\n      }\n    }\n  ],\n  \"timestamp\": \"2026-01-08T14:32:59Z\"\n}\n```\n\nThe top-level `events` field will contain one or more event objects. Each event in the array will have\nthese fields:\n\n| Field name | Description |\n|------------|-------------|\n| `uuid`       | Unique ID for the event |\n| `type`       | What kind of event in fynk you are being notified about. The `events` array may contain events of multiple different types |\n| `timestamp`  | When the event occurred |\n| `data`       | An object containing type-specific data about the event |\n\nThese are the possible values for the `type` field:\n\n- `document.checkpoint.approved`\n- `document.checkpoint.canceled`\n- `document.checkpoint.rejected`\n- `document.comment.created`\n- `document.signed_by_all_parties`\n- `document.moved_to_stage.signing`\n- `document.party.ready_for_signing`\n- `document.reminder.cancellation_notice_period`\n- `document.reminder.effective`\n- `document.reminder.expiring`\n- `document.reminder.renewal`\n\nWhich types of event your webhook actually receives will depend on which [Notifications](https://app.fynk.com/account-settings/document-notifications)\nyou configure to send to the webhook.\n\nBelow you'll find a JSON example showing the structure of each event type. Your webhook handler should parse\nthese from the `events` array in the payload.\n\n> Each example shows a single event object. The actual `events` array in a webhook delivery may contain\n> multiple events.\n\n##### document.checkpoint.approved\n\n```json\n{\n  \"uuid\": \"d445a7e7-d2b7-44c0-87ae-7be2fb2438cd\",\n  \"type\": \"document.checkpoint.approved\",\n  \"timestamp\": \"2026-01-13T12:33:53Z\",\n  \"data\": {\n    \"document\": {\n      \"name\": \"Employment Contract\",\n      \"uuid\": \"0a4b6e64-3c4a-4973-af2c-0ec1072b2e1e\"\n    },\n    \"checkpoint\": {\n      \"uuid\": \"a833571d-fffe-4b4f-b427-ac04036b56f8\",\n      \"document_stage\": \"review\"\n    }\n  }\n}\n```\n\n##### document.checkpoint.canceled\n\n```json\n{\n  \"uuid\": \"2d17653c-6bda-47e3-b51b-2664eb6c8392\",\n  \"type\": \"document.checkpoint.canceled\",\n  \"timestamp\": \"2026-01-13T12:32:44Z\",\n  \"data\": {\n    \"document\": {\n      \"name\": \"Employment Contract\",\n      \"uuid\": \"0a4b6e64-3c4a-4973-af2c-0ec1072b2e1e\"\n    },\n    \"checkpoint\": {\n      \"uuid\": \"a833571d-fffe-4b4f-b427-ac04036b56f8\",\n      \"document_stage\": \"review\"\n    }\n  }\n}\n```\n\n##### document.checkpoint.rejected\n\n```json\n{\n  \"uuid\": \"ccbbb212-d72a-4bb1-a214-db866f45baba\",\n  \"type\": \"document.checkpoint.rejected\",\n  \"timestamp\": \"2026-01-13T12:33:13Z\",\n  \"data\": {\n    \"document\": {\n      \"name\": \"Employment Contract\",\n      \"uuid\": \"0a4b6e64-3c4a-4973-af2c-0ec1072b2e1e\"\n    },\n    \"checkpoint\": {\n      \"uuid\": \"a833571d-fffe-4b4f-b427-ac04036b56f8\",\n      \"document_stage\": \"review\"\n    }\n  }\n}\n```\n\n##### document.comment.created\n\n```json\n{\n  \"uuid\": \"e8880462-bd62-4ff3-8495-6a084c059076\",\n  \"type\": \"document.comment.created\",\n  \"timestamp\": \"2026-01-13T10:30:56Z\",\n  \"data\": {\n    \"comment\": {\n      \"type\": \"comment\",\n      \"uuid\": \"089d1493-2157-4f73-8077-aa248205af79\"\n    },\n    \"document\": {\n      \"name\": \"Employement Contract\",\n      \"uuid\": \"0a4b6e64-3c4a-4973-af2c-0ec1072b2e1e\"\n    }\n  }\n}\n```\n\n##### document.signed_by_all_parties\n\n```json\n{\n  \"uuid\": \"f0c61a22-4deb-4706-8906-097c25e86ed6\",\n  \"type\": \"document.signed_by_all_parties\",\n  \"timestamp\": \"2026-01-13T11:48:33Z\",\n  \"data\": {\n    \"document\": {\n      \"name\": \"Employment Contract\",\n      \"uuid\": \"0a4b6e64-3c4a-4973-af2c-0ec1072b2e1e\"\n    }\n  }\n}\n```\n\n##### document.moved_to_stage.signing\n\n```json\n{\n  \"uuid\": \"7a425adc-4a0c-48a8-a5cb-5da162780a27\",\n  \"type\": \"document.moved_to_stage.signing\",\n  \"timestamp\": \"2026-01-12T11:46:31Z\",\n  \"data\": {\n    \"document\": {\n      \"name\": \"Employment Contract\",\n      \"uuid\": \"0a4b6e64-3c4a-4973-af2c-0ec1072b2e1e\"\n    }\n  }\n}\n```\n\n##### document.party.ready_for_signing\n\n```json\n{\n  \"uuid\": \"d2925089-ebae-4348-af1c-469760e19d54\",\n  \"type\": \"document.party.ready_for_signing\",\n  \"timestamp\": \"2026-01-13T11:52:53Z\",\n  \"data\": {\n    \"party\": {\n      \"uuid\": \"0ad899fc9-3130-45d5-9cd5-d7a0737f0ffd\",\n      \"reference\": \"Employee\",\n      \"entity_name\": \"Jane Marshall\"\n    },\n    \"document\": {\n      \"name\": \"Employment Contract\",\n      \"uuid\": \"0a4b6e64-3c4a-4973-af2c-0ec1072b2e1e\"\n    }\n  }\n}\n```\n\n##### document.reminder.cancellation_notice_period\n\n```json\n{\n  \"uuid\": \"75f4d704-8b10-4b68-8ff3-0deb4d46cfcb\",\n  \"type\": \"document.reminder.cancellation_notice_period\",\n  \"timestamp\": \"2026-01-13T06:25:15Z\",\n  \"data\": {\n    \"document\": {\n      \"name\": \"Lease - 1 Oxford Rd\",\n      \"uuid\": \"756b6deb-4c69-42d0-b416-369710dd24e9\"\n    },\n    \"reminder_about_date\": \"2026-02-13T00:00:00Z\"\n  }\n}\n```\n\n##### document.reminder.effective\n\n```json\n{\n  \"uuid\": \"90d9d243-8c5c-4995-9f1f-a3da6b8dde86\",\n  \"type\": \"document.reminder.effective\",\n  \"timestamp\": \"2026-01-13T06:36:40Z\",\n  \"data\": {\n    \"document\": {\n      \"name\": \"Lease - 1 Oxford Rd\",\n      \"uuid\": \"756b6deb-4c69-42d0-b416-369710dd24e9\"\n    },\n    \"reminder_about_date\": \"2026-02-13T00:00:00Z\"\n  }\n}\n```\n\n##### document.reminder.expiring\n\n```json\n{\n  \"uuid\": \"d1d4a218-83bb-46ab-ad8c-758043f0385f\",\n  \"type\": \"document.reminder.expiring\",\n  \"timestamp\": \"2026-01-13T06:16:29Z\",\n  \"data\": {\n    \"document\": {\n      \"name\": \"Lease - 1 Oxford Rd\",\n      \"uuid\": \"756b6deb-4c69-42d0-b416-369710dd24e9\"\n    },\n    \"reminder_about_date\": \"2026-04-13T00:00:00Z\"\n  }\n}\n```\n\n##### document.reminder.renewal\n\n```json\n{\n  \"uuid\": \"5d2e326a-e145-41e3-b23c-639ac4c58f70\",\n  \"type\": \"document.reminder.renewal\",\n  \"timestamp\": \"2026-01-13T05:45:00Z\",\n  \"data\": {\n    \"document\": {\n      \"name\": \"Lease - 1 Oxford Rd\",\n      \"uuid\": \"756b6deb-4c69-42d0-b416-369710dd24e9\"\n    },\n    \"reminder_about_date\": \"2026-02-13T00:00:00Z\"\n  }\n}\n```\n\n#### Microsoft Teams delivery format\n\nWebhooks using the \"Microsoft Teams\" delivery format are intended for use with webhooks created by following\n[these instructions for Workflows for Microsoft Teams](https://support.microsoft.com/en-us/office/create-incoming-webhooks-with-workflows-for-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498),\nusing either the \"Send webhook alerts to a channel\" or \"Send webhook alerts to a chat\" workflow template.\n\n1. Follow the instructions to setup a workflow for the channel or chat of your choice\n2. Take the URL that this gives you and create a new fynk Webhook Target using this URL. The webhook's delivery format must be set to \"Microsoft Teams\"\n3. Configure one or more [Notifications](https://app.fynk.com/account-settings/document-notifications) in fynk to use the new webhook\n\nWhenever your selected notifications are triggered, a message desribing the event will be posted to the\nTeams channel or chat that you selected when setting up your workflow.\n\n### Webhook request signatures\n\nWhen a webhook is created using the default settings, all requests sent to that webhook will include a\n([Standard Webhooks](https://www.standardwebhooks.com/) compatible) signature to allow you to verify that\nthe requests you receive are really sent by fynk.\n\nfynk uses the \"Symmetric\" signature scheme described [here](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md#verifying-webhook-authenticity)\nin the Standard Webhooks spec. The signing secret needed to verify received requests is unique per webhook\nand is available by visiting the Webhooks page in your account [settings](https://app.fynk.com/account-settings/webhook-targets).\n\nWhen a webhook uses the default signature location (\"Header\"), the request ID, signature and timestamp\nneeded for verifying the signature will be included in the headers described in the Standard Webhooks\nspecification (`webhook-id`, `webhook-signature`, `webhook-timestamp`).\n\nIf for some reason, you need to receive webhooks in an environment that does not have access to the request\nheaders - and you would still like to verify the requests' authenticity - you can instead set the webhook's\nsignature location to \"Query parameter\". When you do this, fynk will dynamically include three additional\nquery parameters in the webhook's URL: `wh_id` (the unique webhook identifier), `wh_sig` (the signature of\nthe webhook) & `wh_ts` (the webhook timestamp).\n",
      "image": "",
      "baseURL": "https://app.fynk.com/v1/api",
      "humanURL": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/fynk.com/main/2025-12-05",
      "version": "2025-12-05",
      "tags": [
        "fynk.com",
        "main"
      ],
      "properties": [
        {
          "type": "OpenAPI",
          "name": "OpenAPI definition",
          "url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/fynk.com/main/2025-12-05/openapi.json",
          "mediaType": "application/openapi+json"
        },
        {
          "type": "GitHubRepo",
          "url": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/fynk.com/main/2025-12-05"
        }
      ]
    }
  ]
}