Formify User API

openapi: 3.2.0
info:
  title: Formify User 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: User
  description: User info and operations
paths:
  /user:
    get:
      tags:
      - User
      summary: Get user info settings
      description: Get info about the authenticated user.
      operationId: getUserInfo
      parameters:
      - in: query
        name: errorLanguage
        schema:
          type: string
          enum:
          - en
          - sv
          - es
        description: Language for the error message
      responses:
        '200':
          description: User info retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  userId:
                    type: string
                    description: Unique identifier of the user
                  emailAddress:
                    type: string
                    description: Email address of the user on this account
                  fullName:
                    type: string
                    description: Full name of the user
                  firstName:
                    type: string
                    description: First name of the user
                  lastName:
                    type: string
                    description: Last name of the user
                  accountId:
                    type: string
                    description: Unique identifier of the user's account
                  accountName:
                    type: string
                    description: Name of the user's account
        '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/user\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\""
      - lang: JavaScript
        source: "const response = await fetch(\"https://docs-api.formify.eu/v1/user\", {\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/user\"\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
  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