Formify Account API

openapi: 3.2.0
info:
  title: Formify Account 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: Account
  description: Account info and operations
paths:
  /account/users:
    get:
      tags:
      - Account
      summary: Retrieve list of users on the account
      description: Retrieve a list of users on the account. Invited users with pending invitations are also included in the list (`invited`).
      operationId: getAccountUsers
      parameters:
      - in: query
        name: errorLanguage
        schema:
          type: string
          enum:
          - en
          - sv
          - es
        description: Language for the error message
      responses:
        '200':
          description: List of account users retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      type: object
                      properties:
                        userId:
                          type: string
                          format: uuid
                          description: Unique identifier for the user.
                        email:
                          type: string
                          format: email
                          description: Email address of the user.
                        firstName:
                          type: string
                          description: User's first name.
                        lastName:
                          type: string
                          description: User's last name.
                        fullName:
                          type: string
                          description: User's full name, if available.
                        roles:
                          type: array
                          items:
                            type: string
                            enum:
                            - admin
                            - user
                          description: Roles assigned to the user within the account.
                        status:
                          type: string
                          enum:
                          - active
                          - invited
                          description: Status of the user on the account.
        '401':
          description: Unauthorized - Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
        '404':
          description: Not Found - Account or users resource 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/account/users\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\""
      - lang: JavaScript
        source: "const response = await fetch(\"https://docs-api.formify.eu/v1/account/users\", {\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/account/users\"\nheaders = {\n    \"Authorization\": \"Bearer YOUR_ACCESS_TOKEN\"\n}\n\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
  /account/capabilities:
    get:
      tags:
      - Account
      summary: Get account capabilities
      description: 'Returns which features and add-ons are enabled for the account.


        Use this endpoint to check what is available before calling endpoints that require specific capabilities. Attempting to use a capability that is not enabled returns `403 Forbidden`.


        ### Capabilities


        | Capability | Description |

        |---|---|

        | `deliverySms` | `phoneNumberDeliveryMethod: sms` on signee |

        | `deliveryWhatsapp` | `phoneNumberDeliveryMethod: whatsapp` on signee |

        | `templates` | `GET /templates`, using `templateId` on document |

        | `templatesCreate` | `POST /templates` |

        | `signingOrder` | `enableSigningOrder: true` on document |

        | `signAndPay` | Sign & Pay feature |

        | `signAndPayCreate` | Create Sign & Pay links |

        | `signatureBankId` | `bankid_identification` signature type |

        | `signatureIdScan` | `digital_ink_id_scan` signature type |

        | `signatureFaceLiveness` | `face_liveness` signature type |

        | `verificationToOpen` | Verification-to-open setting on documents |

        | `disableSubmit` | Disable submit/sign setting on documents |

        | `searchableFormFields` | Searchable form fields |

        | `apiAccess` | API integration settings |

        | `companyLogo` | Custom company logo |

        | `sharedDocuments` | Shared document settings within account |

        | `verificationEmail` | Email address verification add-on |

        | `verificationPhone` | Mobile number verification add-on |

        | `initials` | Initials add-on |

        | `aiAssistant` | `aiAssistant.enabled: true` on document |

        | `aiAssistantCustomProfile` | Custom AI assistant profile |

        | `aiFeaturesEnabled` | False when AI features are switched off in Data controls (AI assistant settings refused) |

        | `aiEuOnlyProcessing` | AI processed on EU-hosted models only (AI assistant for signers unavailable) |'
      operationId: getAccountCapabilities
      parameters:
      - in: query
        name: errorLanguage
        schema:
          type: string
          enum:
          - en
          - sv
          - es
        description: Language for the error message
      responses:
        '200':
          description: Account capabilities retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountCapabilities'
        '401':
          description: Unauthorized - Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
        '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/account/capabilities\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\""
      - lang: JavaScript
        source: "const response = await fetch(\"https://docs-api.formify.eu/v1/account/capabilities\", {\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/account/capabilities\"\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
    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
    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
    AccountCapabilities:
      type: object
      description: 'Describes which features and add-ons are enabled for the account.


        Use this endpoint to discover what capabilities are available before attempting to use them. Features that are not enabled will result in a `403 Forbidden` response if used.'
      properties:
        deliverySms:
          type: boolean
          description: Whether SMS delivery is enabled for signee invitations and reminders.
          example: true
        deliveryWhatsapp:
          type: boolean
          description: Whether WhatsApp delivery is enabled for signee invitations and reminders.
          example: false
        templates:
          type: boolean
          description: Whether templates can be used (e.g. listed and applied to documents).
          example: true
        templatesCreate:
          type: boolean
          description: Whether new templates can be created.
          example: true
        signingOrder:
          type: boolean
          description: Whether sequential signing order is enabled for multi-party documents.
          example: true
        signAndPay:
          type: boolean
          description: Whether the Sign & Pay feature is enabled.
          example: false
        signAndPayCreate:
          type: boolean
          description: Whether Sign & Pay links can be created.
          example: false
        signatureBankId:
          type: boolean
          description: Whether the `bankid_identification` signature type is enabled.
          example: false
        signatureIdScan:
          type: boolean
          description: Whether the `digital_ink_id_scan` signature type is enabled.
          example: true
        signatureFaceLiveness:
          type: boolean
          description: Whether the `face_liveness` signature type is enabled.
          example: false
        verificationToOpen:
          type: boolean
          description: Whether the verification-to-open setting can be enabled on documents.
          example: false
        disableSubmit:
          type: boolean
          description: Whether the disable submit/sign setting can be enabled on documents.
          example: false
        searchableFormFields:
          type: boolean
          description: Whether searchable form fields are enabled.
          example: false
        apiAccess:
          type: boolean
          description: Whether API integration settings are accessible.
          example: true
        companyLogo:
          type: boolean
          description: Whether a custom company logo can be configured.
          example: true
        sharedDocuments:
          type: boolean
          description: Whether shared document settings within the account are enabled.
          example: false
        verificationEmail:
          type: boolean
          description: Whether the Email Address Verification add-on is enabled.
          example: false
        verificationPhone:
          type: boolean
          description: Whether the Mobile Number Verification add-on is enabled.
          example: false
        initials:
          type: boolean
          description: Whether the Initials add-on is enabled.
          example: false
        aiAssistant:
          type: boolean
          description: Whether the AI Assistant feature is enabled for the account.
          example: false
        aiAssistantCustomProfile:
          type: boolean
          description: Whether a custom AI assistant profile can be configured.
          example: false
        aiFeaturesEnabled:
          type: boolean
          description: False when an account admin has switched AI features off in Data controls. AI assistant settings are then refused.
          example: true
        aiEuOnlyProcessing:
          type: boolean
          description: True when the account processes AI on EU-hosted models only (Data controls). The AI assistant for signers is then unavailable.
          example: false
      example:
        deliverySms: true
        deliveryWhatsapp: false
        templates: true
        templatesCreate: true
        signingOrder: true
        signAndPay: false
        signAndPayCreate: false
        signatureBankId: false
        signatureIdScan: true
        signatureFaceLiveness: false
        verificationToOpen: false
        disableSubmit: false
        searchableFormFields: false
        apiAccess: true
        companyLogo: true
        sharedDocuments: false
        verificationEmail: false
        verificationPhone: false
        initials: false
        aiAssistant: false
        aiAssistantCustomProfile: false
        aiFeaturesEnabled: true
        aiEuOnlyProcessing: false
  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