Formify Files API

openapi: 3.2.0
info:
  title: Formify Files API
  description: '## Overview


    The Formify API lets you send documents for electronic signature, prepare drafts, track signing status, and retrieve signed documents. It is designed for integrating signing workflows into your application.


    ### Getting Access


    OAuth 2.0 is the recommended way to access the API. Before you can use the API, you need an OAuth 2.0 client. Formify creates this for you based on information about your company, contacts, and redirect URIs. See the **Getting Access** guide for setup instructions.


    Once your OAuth client has been created, you can use the OAuth 2.0 Authorization Code flow to obtain access tokens for API requests.


    For MCP clients and third-party platforms that cannot complete OAuth/PKCE and only accept a pasted token, a Formify API key can be exchanged for a short-lived access token with `POST /auth/token`. This is a compatibility option; use OAuth where the client supports it.


    ### Authentication


    Protected API requests use a Bearer access token. The recommended flow is OAuth 2.0: your application redirects the user to Formify for authorization, receives an authorization code, and exchanges it for an access token. See the OAuth 2.0 section for the complete flow.


    ### Environments


    **API base URL**: `https://docs-api.formify.eu/v1`

    All document operations, file uploads, and token exchange endpoints (OAuth and API key fallback) happen here.


    **Authorization Server**: `https://app.formify.eu`

    This is where users authorize your application and approve access (the OAuth consent).


    ### Rate Limiting


    The API uses token-based rate limiting to ensure fair usage:


    - **Headers**: Every response includes rate limit headers:

    - `X-RateLimit-Limit`: Maximum requests allowed

    - `X-RateLimit-Remaining`: Requests remaining in current window

    - `X-RateLimit-Reset`: The number of seconds until the rate limit resets


    - **Not every request costs the same.** Endpoints that build or copy a document consume several tokens

    rather than one, because they render a PDF and make multiple calls to the document service. Creating,

    editing or duplicating a document or a public link is the most expensive; creating or editing a template

    costs less; deleting and duplicating a draft less again. Plain reads cost one.


    If you exceed the limit, the API returns `429 Too Many Requests`. Wait until the reset time before making additional requests.


    ---


    ## Quick Start: Send a PDF for Signing


    Once you have a valid `access_token`, you can send your first document for signing in three steps:


    ### 1. Upload a PDF

    Upload a PDF file using the Upload File endpoint:


    ```bash

    POST /files

    Content-Type: multipart/form-data

    ```


    You will receive a `fileId` in the response.


    ### 2. Create a Signature Request

    Send the document for signing using the Create Document endpoint:


    ```bash

    POST /docs

    {

    "fileId": "your-file-id",

    "signeeDetails": [

    {

    "fullName": "John Doe",

    "emailAddress": "john@example.com",

    "signaturePlacement": "new_page"

    }

    ]

    }

    ```


    The response returns a documentId. The signee then receives an email with a link to sign the document.


    ### 3. Get Notified and Download

    Register a webhook to receive a notification when the document is signed:


    ```bash

    POST /webhooks

    {

    "webhookUrl": "https://your-app.com/webhook",

    "eventTypes": ["document.completed"]

    }

    ```


    Then download the signed PDF using Get Signed Document File:


    ```bash

    GET /docs/{documentId}/signed-file

    ```


    For more detailed walkthroughs, see the **Integration Flows** guide.


    ---


    ### Help


    - **Getting Access** - How to set up OAuth 2.0 credentials

    - **Integration Flows** - Step-by-step guides for common integration scenarios

    - **PDF Form Attributes** - How to add `tink-*` attributes to PDF form field names

    - **MCP Server** - Connect AI assistants with OAuth or an API key fallback for token-only clients

    - **Production Checklist** - Essential steps before going live


    ### Links


    - Formify API Changelog - Track API updates and changes

    - Formify App - Register OAuth applications and manage settings


    ---'
  contact:
    email: api@formify.eu
  version: 1.5.2
  termsOfService: https://formify.eu/privacy/terms
servers:
- url: https://docs-api.formify.eu/v1
  description: Main API server for all document related endpoints and token exchange.
security:
- OAuth2: []
tags:
- name: Files
  description: Upload files to use for signature requests
paths:
  /files:
    post:
      tags:
      - Files
      summary: Upload a PDF file for signing
      description: 'Uploads a PDF file to Formify, making it available for creating document signature requests via the `POST /docs` endpoint.


        ### Requirements

        - **File Format**: Only PDF files are supported.

        - **File Size**: Maximum allowed file size is **50 MB**.

        - **Unlocked PDFs Only**: The file must not be password-protected or locked in any way. Locked files cannot be processed.

        - **No Pre-Signed Documents**: The PDF must not contain digital signatures from other services, as these will be removed, invalidating the document''s signature integrity.

        - **Signature Field Handling**: If the uploaded document contains existing signature fields (interactive PDF form fields of type `signature`), these will be removed automatically. New signature fields, fully compatible with the Formify signing process, must be added to the document instead. This ensures that all signature fields function seamlessly within the Formify platform.

        By ensuring these requirements are met, you can use the uploaded file to create a document signature request seamlessly.'
      operationId: uploadFile
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: 'The PDF document to be uploaded. Max file size: 50 MB.'
                errorLanguage:
                  type: string
                  enum:
                  - en
                  - sv
                  - es
                  description: Language for the error message
        required: true
      responses:
        '201':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  fileId:
                    type: string
                    format: uuid
                    description: The unique identifier of the uploaded file
        '400':
          description: Invalid request parameters or issues with the file
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: File exceeds the maximum allowed size of 50 MB.
                  code:
                    type: integer
                    example: 400
        '401':
          description: Unauthorized - Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
        '403':
          description: Forbidden - Access to the file is denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Unauthorized access to the file.
                  code:
                    type: integer
                    example: 403
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
      x-codeSamples:
      - lang: curl
        source: "curl -X POST \"https://docs-api.formify.eu/v1/files\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\\n  -H \"Content-Type: multipart/form-data\" \\\n  -F \"file=@file.pdf\" \\\n  -F \"errorLanguage=en\""
      - lang: JavaScript
        source: "const formData = new FormData();\nformData.append(\"file\", fileBlob, \"file.pdf\");\nformData.append(\"errorLanguage\", \"en\");\n\nconst response = await fetch(\"https://docs-api.formify.eu/v1/files\", {\n  method: \"POST\",\n  headers: {\n    \"Authorization\": \"Bearer YOUR_ACCESS_TOKEN\"\n  },\n  body: formData\n});\n\nconst data = await response.json();\nconsole.log(data);"
      - lang: Python
        source: "import requests\n\nurl = \"https://docs-api.formify.eu/v1/files\"\nheaders = {\n    \"Authorization\": \"Bearer YOUR_ACCESS_TOKEN\"\n}\nfiles = {\n    \"file\": open(\"file.pdf\", \"rb\"),\n    \"errorLanguage\": (None, \"en\")\n}\n\nresponse = requests.post(url, headers=headers, files=files)\nprint(response.json())"
  /files/merge:
    post:
      tags:
      - Files
      summary: Merge multiple PDF files into a single document
      description: 'Merges two or more uploaded PDF files into a single file. The resulting file will be assigned a new `fileId`.


        ### Requirements

        - **File Format**: Only pre-uploaded PDF files are supported for merging.

        - **Order of Merge**: The files will be merged in the order of the provided `fileIds`.

        - **File Name**: A name for the resulting merged file must be provided.

        - **Max File Size**: Ensure the combined file size does not exceed system limits (**50 MB**).

        - **2-8 Files**: A minimum of 2 files and a maximum of 8 `fileIds` are required (duplicate `fileIds` are not allowed.).


        This endpoint is particularly useful for workflows where multiple PDF files need to be combined before sending them for signatures or further processing.'
      operationId: mergeFiles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fileIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                    description: Unique identifier of a file to be merged.
                  description: List of File IDs to merge. Must contain between 2 and 8 unique File IDs.
                  example:
                  - 123e4567-e89b-12d3-a456-426614174000
                  - 123e4567-e89b-12d3-a456-426614174001
                name:
                  type: string
                  description: Name for the resulting merged file.
                  example: Merged Document
      responses:
        '201':
          description: Files merged successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  fileId:
                    type: string
                    format: uuid
                    description: The unique identifier of the merged file.
                    example: 123e4567-e89b-12d3-a456-426614174002
        '400':
          description: Invalid request parameters or issues with the files.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: 'Invalid request: Must provide between 2 and 8 unique File IDs.'
                  code:
                    type: integer
                    example: 400
        '401':
          description: Unauthorized - Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
        '403':
          description: Forbidden - Access to one or more files is denied.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Unauthorized access to one or more files.
                  code:
                    type: integer
                    example: 403
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
      x-codeSamples:
      - lang: curl
        source: "curl -X POST \"https://docs-api.formify.eu/v1/files/merge\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"fileIds\": [\n    \"123e4567-e89b-12d3-a456-426614174000\",\n    \"123e4567-e89b-12d3-a456-426614174001\"\n  ],\n  \"name\": \"Merged Document\"\n}'"
      - lang: JavaScript
        source: "const response = await fetch(\"https://docs-api.formify.eu/v1/files/merge\", {\n  method: \"POST\",\n  headers: {\n    \"Authorization\": \"Bearer YOUR_ACCESS_TOKEN\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"fileIds\": [\n        \"123e4567-e89b-12d3-a456-426614174000\",\n        \"123e4567-e89b-12d3-a456-426614174001\"\n    ],\n    \"name\": \"Merged Document\"\n})\n});\n\nconst data = await response.json();\nconsole.log(data);"
      - lang: Python
        source: "import requests\n\nurl = \"https://docs-api.formify.eu/v1/files/merge\"\nheaders = {\n    \"Authorization\": \"Bearer YOUR_ACCESS_TOKEN\"\n}\npayload = {\n    \"fileIds\": [\n        \"123e4567-e89b-12d3-a456-426614174000\",\n        \"123e4567-e89b-12d3-a456-426614174001\"\n    ],\n    \"name\": \"Merged Document\"\n}\n\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
  /files/{fileId}:
    delete:
      tags:
      - Files
      summary: Delete an uploaded file
      operationId: deleteFileById
      parameters:
      - name: fileId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Unique identifier of the file to delete
      - in: query
        name: errorLanguage
        schema:
          type: string
          enum:
          - en
          - sv
          - es
        description: Language for the error message
      responses:
        '204':
          description: File successfully deleted
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
        '404':
          description: Not Found - File not found or already deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
      x-codeSamples:
      - lang: curl
        source: "curl -X DELETE \"https://docs-api.formify.eu/v1/files/{fileId}\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\""
      - lang: JavaScript
        source: "const response = await fetch(\"https://docs-api.formify.eu/v1/files/{fileId}\", {\n  method: \"DELETE\",\n  headers: {\n    \"Authorization\": \"Bearer YOUR_ACCESS_TOKEN\"\n  }\n});\n\nconsole.log(response.status); // 204"
      - lang: Python
        source: "import requests\n\nurl = \"https://docs-api.formify.eu/v1/files/{fileId}\"\nheaders = {\n    \"Authorization\": \"Bearer YOUR_ACCESS_TOKEN\"\n}\n\nresponse = requests.delete(url, headers=headers)\nprint(response.status_code)  # 204"
  /files/{fileId}/fields:
    get:
      tags:
      - Files
      summary: Retrieve all form fields for an uploaded file
      description: 'Retrieves all the form fields defined in a specific file before it is used to create a document. This is useful for pre-filling values or understanding the structure of the form.


        ### Notes:

        - Fields retrieved here may include metadata such as `readOnly` (not possible to modify by the signee) and `editable` to indicate whether they can be modified or pre-filled.

        - For getting actual values in a signed document, use the `/docs/{documentId}/field-values` endpoint.

        - Field names containing `tink-scan-id` (a scan trigger) or `tink-scanned-id-` (an image of part of the document) place an image of the signee''s identity document in the signed document — unless the trigger is combined with a `tink-scanned-id-mrz-` text attribute on the same field, which only fills in text. Reproducing a copy of an identity document requires your own legal basis (Terms 8.5); see PDF Form Attributes.'
      operationId: getFileFields
      parameters:
      - name: fileId
        in: path
        required: true
        description: The unique identifier of the uploaded file.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successfully retrieved form fields.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FormField'
        '401':
          description: Unauthorized - Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
        '404':
          description: File not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
      x-codeSamples:
      - lang: curl
        source: "curl -X GET \"https://docs-api.formify.eu/v1/files/{fileId}/fields\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\""
      - lang: JavaScript
        source: "const response = await fetch(\"https://docs-api.formify.eu/v1/files/{fileId}/fields\", {\n  method: \"GET\",\n  headers: {\n    \"Authorization\": \"Bearer YOUR_ACCESS_TOKEN\"\n  }\n});\n\nconst data = await response.json();\nconsole.log(data);"
      - lang: Python
        source: "import requests\n\nurl = \"https://docs-api.formify.eu/v1/files/{fileId}/fields\"\nheaders = {\n    \"Authorization\": \"Bearer YOUR_ACCESS_TOKEN\"\n}\n\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
components:
  schemas:
    ErrorResponse401:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Unauthorized
        code:
          type: integer
          example: 401
        language:
          type: string
          example: en
    ErrorResponse500:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Internal Server Error
        code:
          type: integer
          example: 500
        language:
          type: string
          example: en
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Invalid request parameters
        code:
          type: integer
          example: 400
        language:
          type: string
          example: en
    FormField:
      type: object
      description: 'Represents an interactive form field embedded in a PDF document. FormFields are extracted from PDF forms and can be read or updated via the API.


        **Usage:**

        - Retrieve form fields from uploaded files: `GET /files/{fileId}/fields`

        - Retrieve form fields from documents: `GET /docs/{documentId}/fields`

        - Get field values from completed documents: `GET /docs/{documentId}/field-values`

        - Update field values: `POST /docs/{documentId}/field-values`


        **Field Types:**

        - **textField**: Single-line or multi-line text input

        - **checkbox**: Boolean selection (checked/unchecked)

        - **radioButton**: Single selection from a group of options

        - **combobox**: Dropdown with editable text input

        - **listbox**: List selection (single or multiple)


        **Common Use Cases:**

        - Pre-fill contract templates with customer data

        - Collect structured information from signees

        - Create dynamic forms with conditional logic

        - Extract data from completed forms for processing


        **Key Properties:**

        - `name`: Unique identifier for the field (use this when updating values)

        - `required`: Whether the field must be filled before signing

        - `editable`: Whether the field can be updated via API

        - `readOnly`: Whether signees can modify the field

        - `value` / `defaultValues`: The field''s predefined starting values, not what anyone has entered


        **Definitions, not entered values.** These endpoints describe the fields a document contains: their names,

        types, positions and predefined values. What a recipient has actually filled in is a separate thing, read

        with `GET /docs/{documentId}/field-values` once the document is completed.'
      example:
        fieldId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        name: customer_email
        label: Email Address
        type: textField
        value: null
        required: true
        readOnly: false
        editable: true
        page: 0
      properties:
        fieldId:
          type: string
          format: uuid
          description: Unique identifier for the field.
        name:
          type: string
          description: The name of the form field, used as the key for API interactions.
        label:
          type: string
          description: The display label of the form field.
        type:
          type: string
          enum:
          - checkbox
          - combobox
          - listbox
          - radioButton
          - textField
          description: The type of the form field.
        value:
          type: string
          nullable: true
          description: 'The field''s predefined starting value — what it was built with, not what anyone has since filled in.

            It is the first entry of `defaultValues`, and is `null` when the field has no predefined value.


            To read what has actually been entered, use `GET /docs/{documentId}/field-values` on a completed

            document. Entered values are stored per recipient and are never returned by this endpoint.'
        defaultValues:
          type: array
          items:
            type: string
          nullable: true
          description: List of default values for the form field.
        options:
          type: array
          items:
            type: object
            properties:
              label:
                type: string
                description: The display label of the option.
              value:
                type: string
                description: The value associated with the option.
          nullable: true
          description: List of available options for dropdown or choice fields.
        required:
          type: boolean
          description: Indicates if the field is mandatory for submission.
        readOnly:
          type: boolean
          description: Indicates if the field is read-only and cannot be modified.
        editable:
          type: boolean
          description: Indicates if the field is editable through the `POST /docs/{documentId}/field-values` endpoint.
        multiLine:
          type: boolean
          nullable: true
          description: Indicates if the field supports multi-line text.
        comb:
          type: boolean
          nullable: true
          description: Indicates if the field uses comb formatting for text input.
        page:
          type: integer
          description: The page index (zero-based) where the field is located.
        boundingBox:
          type: object
          nullable: true
          properties:
            x:
              type: number
              description: The X coordinate of the field's top-left corner.
            y:
              type: number
              description: The Y coordinate of the field's top-left corner.
            width:
              type: number
              description: The width of the field in points.
            height:
              type: number
              description: The height of the field in points.
          description: The bounding box of the field on the page.
    ErrorResponse404:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Not Found
        code:
          type: integer
          example: 404
        language:
          type: string
          example: en
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'HTTP Basic Authentication for traditional OAuth clients. Send `Authorization: Basic base64(client_id:client_secret)`.'
    ApiKeyAuth:
      type: http
      scheme: ApiKey
      description: 'Formify API key authentication for `POST /auth/token` only. Send the API key using the HTTP authorization scheme format `Authorization: ApiKey sk_live_YOUR_API_KEY` to exchange it for a short-lived Bearer access token. Test keys use the same format with the `sk_test_` prefix.'
    OAuth2:
      type: oauth2
      description: OAuth2 Authentication. Allows third-party systems to access the API on behalf of the user and their account after authorization.
      flows:
        authorizationCode:
          authorizationUrl: https://docs-api.formify.eu/v1/oauth/authorize
          tokenUrl: https://docs-api.formify.eu/v1/oauth/token
          scopes:
            read: Allows reading documents and their metadata
            write: Allows modifying documents and sending signature requests
externalDocs:
  description: Formify website
  url: https://formify.eu
x-tagGroups:
- name: Authentication
  tags:
  - oauth
  - auth
- name: Documents
  tags:
  - files
  - docs
  - drafts
  - templates
  - links
- name: Account & User
  tags:
  - user
  - account
- name: Webhooks
  tags:
  - webhooks