Skip to main content

REST API reference

Sebastian Nedoma avatar
Written by Sebastian Nedoma
Updated over 2 months ago

Overview

The fynk API exposes REST-style, resource-based endpoints to work with Documents, Templates, Parties, Signatories, Metadata, and more. You can explore the live API documentation at https://app.fynk.com/v1/docs.

Quickstart

  1. Create an account: Sign up at https://app.fynk.com/register or log in at https://app.fynk.com/login

  2. Create a party: Ensure at least one party exists in Account Settings → Parties.

  3. Create a template: Have at least one template in Templates (create or use from the gallery).

  4. Create an API token: In Account Settings → Integrations → API, click Create Token and save the value securely.

  5. Test your token: Call Current API token details and verify you get a 200 OK JSON response.

curl "https://app.fynk.com/v1/api/me" \

-H 'Authorization: Bearer <your-api-token>' \

-H 'Accept: application/json'

  1. Fetch data: Try List templates and then Show template with one of the returned UUIDs.

# List templates

curl "https://app.fynk.com/v1/api/templates" \

-H 'Authorization: Bearer <your-api-token>' \

-H 'Accept: application/json'

Authentication

Use a Bearer token in every request:

Authorization: Bearer <token>

Tokens created during free trial work during the trial; upgrade to continue afterwards.

Versioning

  • Backwards-compatible changes do not create a new version (e.g., adding fields/endpoints).

  • Backwards-incompatible changes create a new API version.

  • Override your account’s default version per request using the Fynk-Api-Version header:

Fynk-Api-Version: 2025-07-14

Pagination

List endpoints return data plus links and meta for pagination. Control size via per_page and page via page.

Rate Limits

Requests are limited per rolling one-minute window. When rate limited, you’ll receive 429 Too Many Requests with a Retry-After header.

How-to Guides

Create a document from a template

  1. Find the template UUID:

curl "https://app.fynk.com/v1/api/templates?filter%5Bquery%5D=Contract%20Layout%20A" \

-H 'Authorization: Bearer <your-api-token>' \

-H 'Accept: application/json'

  1. Create the document:

curl -X POST "https://app.fynk.com/v1/api/documents/create-from-template" \

-H 'Authorization: Bearer <your-api-token>' \

-H 'Accept: application/json' \

-H 'Content-Type: application/json; charset=utf-8' \

-d '{

"name": "Employment Contract",

"template_uuid": "4df1e60a-0114-4dce-89e7-8c5ad397fcf2"

}'

Optional: include owner_emails to assign ownership on creation.

Create a document from a PDF

  1. Generate presigned upload URL:

curl -X POST "https://app.fynk.com/v1/api/file-uploads/document-pdf" \

-H 'Authorization: Bearer <your-api-token>' \

-H 'Accept: application/json' \

-H 'Content-Type: application/json; charset=utf-8'

  1. Upload the PDF to the returned URL:

curl -X PUT "https://example-bucket.s3.amazonaws.com/uploads/..." \

-H 'Content-Type: application/pdf' \

--data-binary @/path/to/your/document.pdf

  1. Create the document:

curl -X POST "https://app.fynk.com/v1/api/documents/create-from-pdf" \

-H 'Authorization: Bearer <your-api-token>' \

-H 'Accept: application/json' \

-H 'Content-Type: application/json; charset=utf-8' \

-d '{

"file_upload_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",

"file_name": "my-contract.pdf",

"initial_stage": "draft",

"name": "My Contract from PDF",

"document_type": "contract"

}'

initial_stage can be draft or signed. Use template_uuid or document_type (mutually exclusive).

Store a file in a document’s file storage

  1. Generate presigned upload URL:

curl -X POST "https://app.fynk.com/v1/api/file-uploads/document-file-storage" \

-H 'Accept: application/json' \

-H 'Authorization: Bearer <your-api-token>' \

-H 'Content-Type: application/json' \

-d '{"content_type": "application/pdf"}'

  1. Upload the file:

curl -X PUT "https://example-bucket.s3.amazonaws.com/uploads/..." \

-H 'Content-Type: application/pdf' \

--data-binary @/path/to/your/document.pdf

  1. Associate with document:

curl -X POST "https://app.fynk.com/v1/api/documents/{document}/file-storage" \

-H 'Accept: application/json' \

-H 'Authorization: Bearer <your-api-token>' \

-H 'Content-Type: application/json' \

-d '{

"file_upload_uuid": "e1413d6e-d516-4f67-84be-6dd98446aebb",

"file_name": "your-filename.pdf"

}'

Populate dynamic fields

  • Get dynamic fields via the Create/Show document response, or list them:

curl "https://app.fynk.com/v1/api/documents/{document}/dynamic-fields" \

-H 'Authorization: Bearer <your-api-token>' \

-H 'Accept: application/json'

  • Update a field value:

curl -X PUT "https://app.fynk.com/v1/api/documents/{document}/dynamic-fields/{dynamicField}" \

-H 'Authorization: Bearer <your-api-token>' \

-H 'Accept: application/json' \

-H 'Content-Type: application/json; charset=utf-8' \

-d '{"value": "Software Engineer"}'

Value formats depend on the field type (see table in the dynamic fields endpoint docs).

Assign metadata

  1. Find metadata UUID:

curl "https://app.fynk.com/v1/api/metadata" \

-H 'Authorization: Bearer <your-api-token>' \

-H 'Accept: application/json'

  1. Add metadata value to a document:

curl -X POST "https://app.fynk.com/v1/api/documents/{document}/metadata-values" \

-H 'Authorization: Bearer <your-api-token>' \

-H 'Accept: application/json' \

-H 'Content-Type: application/json; charset=utf-8' \

-d '{"value": 100, "metadata_uuid": "205a379c-c4d5-469d-9f67-a025bc630cbf"}'

Manage parties

  • List parties for a document:

curl "https://app.fynk.com/v1/api/documents/{document}/parties" \

-H 'Authorization: Bearer <your-api-token>' \

-H 'Accept: application/json'

  • Update party (external parties):

curl -X PUT "https://app.fynk.com/v1/api/documents/{document}/parties/{party}" \

-H 'Authorization: Bearer <your-api-token>' \

-H 'Accept: application/json' \

-H 'Content-Type: application/json; charset=utf-8' \

-d '{"entity_name": "BigCo Inc.", "entity_type": "business", "address":"BigCo Plaza, New York"}'

Editable stages: draft, approved_draft, review, approved_review.

Assign and manage signatories

  • Add signatory:

curl -X POST "https://app.fynk.com/v1/api/documents/{document}/signatories" \

-H 'Authorization: Bearer <your-api-token>' \

-H 'Accept: application/json' \

-H 'Content-Type: application/json; charset=utf-8' \

-d '{

"party_uuid": "ad899fc9-3130-45d5-9d...",

"email": "[email protected]",

"first_name": "Alex",

"last_name": "Smith",

"title": "Software Engineer"

}'

  • Update signatory:

curl -X PUT "https://app.fynk.com/v1/api/documents/{document}/signatories/{signatory}" \

-H 'Authorization: Bearer <your-api-token>' \

-H 'Accept: application/json' \

-H 'Content-Type: application/json; charset=utf-8' \

-d '{"mobile_phone": "+431234567"}'

  • Remove signatory:

curl -X DELETE "https://app.fynk.com/v1/api/documents/{document}/signatories/{signatory}" \

-H 'Authorization: Bearer <your-api-token>'

Editable stages: draft, approved_draft, review, approved_review.

Move document to review / signing

  • To review:

curl -X POST "https://app.fynk.com/v1/api/documents/{document}/stage-transitions/review" \

-H 'Authorization: Bearer <your-api-token>' \

-H 'Accept: application/json'

  • To signing:

curl -X POST "https://app.fynk.com/v1/api/documents/{document}/stage-transitions/signing" \

-H 'Authorization: Bearer <your-api-token>' \

-H 'Accept: application/json'

Access latest PDF revision

  • Get a pre-authenticated temporary URL:

curl "https://app.fynk.com/v1/api/documents/{document}/revisions/latest/pdf" \

-H 'Authorization: Bearer <your-api-token>' \

-H 'Accept: application/json'

  • Direct download (302 redirect; follow redirects):

curl "https://app.fynk.com/v1/api/documents/{document}/revisions/latest/pdf/download" \

-H 'Authorization: Bearer <your-api-token>' \

--location > my-document.pdf

Reference: Endpoints

API Tokens

  • GET /me — Current API token details

Documents

  • POST /documents/create-from-template — Create document from template

  • POST /documents/create-from-pdf — Create document from PDF

  • GET /documents — List documents (filtering, sorting, pagination)

  • GET /documents/{document} — Show document

  • PUT /documents/{document} — Update document

Document Parties

  • GET /documents/{document}/parties — List parties

  • POST /documents/{document}/parties — Add party

  • PUT /documents/{document}/parties/{party} — Update party

Document Signatories

  • GET /documents/{document}/signatories — List signatories

  • POST /documents/{document}/signatories — Add signatory

  • PUT /documents/{document}/signatories/{signatory} — Update signatory

  • DELETE /documents/{document}/signatories/{signatory} — Remove signatory

Document Stage Transitions

  • POST /documents/{document}/stage-transitions/review — Move to review

  • POST /documents/{document}/stage-transitions/signing — Move to signing

Document Dynamic Fields

  • GET /documents/{document}/dynamic-fields — List document dynamic fields

  • PUT /documents/{document}/dynamic-fields/{dynamicField} — Update dynamic field

Document Metadata Values

  • GET /documents/{document}/metadata-values — List metadata values

  • POST /documents/{document}/metadata-values — Add metadata value to document

  • PUT /documents/{document}/metadata-values/{metadataValue} — Update metadata value

  • DELETE /documents/{document}/metadata-values/{metadataValue} — Delete metadata value

Document Revisions

  • GET /documents/{document}/revisions/latest/pdf — Show latest revision PDF details

  • GET /documents/{document}/revisions/latest/pdf/download — Download latest revision PDF

Document File Storage

  • POST /documents/{document}/file-storage — Store a file in a document’s file storage

Linked Documents

  • GET /documents/{document}/linked-documents — List linked documents

  • POST /documents/{document}/linked-documents — Link documents

  • DELETE /documents/{document}/linked-documents/{documentRelationship} — Unlink documents

Templates

  • GET /templates — List templates

  • GET /templates/{template} — Show template

File Uploads

  • POST /file-uploads/document-pdf — Create document PDF upload URL

  • POST /file-uploads/document-file-storage — Create document file storage upload URL

Reference: Schemas

Commonly referenced schemas include:

  • MeResource, ApiTokenSettingsResource

  • DocumentDetailResource, DocumentMinimalResource, DocumentRevisionPdfResource

  • DynamicFieldResource, DynamicFieldFormatResource

  • MetadataResource, MetadataValueResource

  • TemplateDetailResource, TemplateMinimalResource

  • SignatoryResource, SignatorySnippetResource

  • DocumentPartyResource, DocumentPartySnippetResource

  • StoredFileResource, SignedUploadUrlResource

  • Enums: DocumentType, DocumentStage, DocumentOrigin, SignatureSecurityLevel, Scope, PartyEntityType, MultiFieldType, MetadataType, MetadataValueSource, MetadataValueComputedStatus, DocumentRelationshipType, BidirectionalDocumentRelationshipType

See the Original documentation links section for direct links to each schema page.

Original documentation links

Notes

  • For any 4xx/5xx responses, see the endpoint’s Responses table in the API docs for the exact error payload shape.

  • Ensure your HTTP client follows redirects where noted (e.g., PDF download endpoint).

  • Some actions are limited to specific document stages (e.g., editing parties/signatories).

Related Articles
Frequently asked Questions
Configuring SCIM with fynk
Notifications in fynk
Did this answer your question?