Public API

Authentication

Every public API request must include a service token in the Authorization header. Service tokens are created inside the authenticated Fill app and can expire after 30, 60, or 90 days, or be created without an expiration. A token is shown only once when it is created.

Authorization: Bearer fill_sk_live_...
Content-Type: application/json

Postman Collection

Import the collection, set baseUrl to your Fill backend URL, and set serviceToken to a Fill service token.

Common Fields

Settings Fields

• notifyOnSubmit boolean, optional, default false: send a monday.com notification when a form is submitted.
• allowEditingAfterSubmit boolean, optional, default false: allow the same link to submit updated answers.
• password string or null, optional: set or clear password protection. Non-empty passwords must be at least 6 characters. Passwords are never returned by the API.
• customMessage string or null, optional: message shown above the public form fields.
• expirationDate ISO 8601 UTC string or null, optional: date after which the form stops accepting submissions.

Column Input Fields

• id string, required: monday.com column ID.
• validations array, optional: rules with operator and value. Operators include required, numeric comparisons, text checks, list inclusion, and date comparisons.
• readonly boolean, optional: show the current monday value without allowing edits.
• allowedPeople array, optional: allowed People column choices, each with id and name.
• allowedLinkedItemIds array, optional: allowed item IDs for Connected Boards columns.
• description string, optional: helper text shown below the field label, up to 5,000 characters.

Response Shape

Successful public API responses wrap the payload in { "data": ... }. Form responses include:

• id: Fill form ID.
• target: item or board.
• config.mode: returned for board forms only.
• form.settings: public-safe settings. Password values are never returned.
• form.columns: stored form columns with monday title and type metadata.
• formUrl: public form URL, or null if the URL cannot be generated.
• acceptingSubmissions, createdAt, and optional updatedAt.

POST /api/v1/forms

Create Forms

Create one or more Fill forms. Item targets can create up to 50 forms in one request. Board targets create one board-backed link.

Example request

curl -X POST "{{baseUrl}}/api/v1/forms" \
  -H "Authorization: Bearer {{serviceToken}}" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "item",
    "config": {
      "itemIds": ["123456789"],
      "conflictStrategy": "skip"
    },
    "form": {
      "settings": {
        "notifyOnSubmit": true,
        "allowEditingAfterSubmit": false,
        "customMessage": "Please confirm the details below.",
        "expirationDate": "2026-06-01T00:00:00.000Z",
        "password": "client-intake"
      },
      "columns": [
        {
          "id": "email",
          "validations": [{ "operator": "required", "value": true }]
        },
        {
          "id": "status",
          "readonly": true,
          "description": "Current project status"
        }
      ]
    }
  }'

Board-backed example

curl -X POST "{{baseUrl}}/api/v1/forms" \
  -H "Authorization: Bearer {{serviceToken}}" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "board",
    "config": {
      "boardId": "987654321",
      "mode": "permanent"
    },
    "form": {
      "columns": [
        { "id": "name" },
        { "id": "email" },
        { "id": "status" }
      ]
    }
  }'

Example success response

{
  "data": {
    "forms": [
      {
        "id": "65f1a6f8c2d1e9a123456789",
        "target": "item",
        "form": {
          "settings": {
            "notifyOnSubmit": true,
            "allowEditingAfterSubmit": false,
            "customMessage": "Please confirm the details below.",
            "expirationDate": "2026-06-01T00:00:00.000Z"
          },
          "columns": [
            {
              "id": "email",
              "title": "Email",
              "type": "email",
              "validations": [{ "operator": "required", "value": true }]
            }
          ]
        },
        "formUrl": "https://...",
        "acceptingSubmissions": true,
        "createdAt": "2026-04-30T15:25:00.000Z",
        "updatedAt": "2026-04-30T15:25:00.000Z"
      }
    ]
  }
}

GET /api/v1/forms

List Forms

Return a paginated list of forms for the token account, newest first.

Example request

curl "{{baseUrl}}/api/v1/forms?page=1&limit=10&boardId=987654321" \
  -H "Authorization: Bearer {{serviceToken}}"

Example success response

{
  "data": {
    "forms": [
      {
        "id": "65f1a6f8c2d1e9a123456789",
        "target": "board",
        "config": { "mode": "permanent" },
        "form": {
          "settings": {
            "notifyOnSubmit": false,
            "allowEditingAfterSubmit": false,
            "customMessage": null,
            "expirationDate": null
          },
          "columns": []
        },
        "formUrl": "https://...",
        "acceptingSubmissions": true,
        "createdAt": "2026-04-30T15:25:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 1,
      "totalPages": 1
    }
  }
}

GET /api/v1/forms/:formId

Get a Form

Fetch one form by Fill form ID.

Example request

curl "{{baseUrl}}/api/v1/forms/65f1a6f8c2d1e9a123456789" \
  -H "Authorization: Bearer {{serviceToken}}"

Example success response

{
  "data": {
    "form": 
      {
        "id": "65f1a6f8c2d1e9a123456789",
        "target": "item",
        "form": {
          "settings": {
            "notifyOnSubmit": true,
            "allowEditingAfterSubmit": false,
            "customMessage": "Please confirm the details below.",
            "expirationDate": "2026-06-01T00:00:00.000Z"
          },
          "columns": [
            {
              "id": "email",
              "title": "Email",
              "type": "email",
              "validations": [{ "operator": "required", "value": true }]
            }
          ]
        },
        "formUrl": "https://...",
        "acceptingSubmissions": true,
        "createdAt": "2026-04-30T15:25:00.000Z",
        "updatedAt": "2026-04-30T15:25:00.000Z"
      }
  }
}

PATCH /api/v1/forms/:formId

Update a Form

Update form settings, columns, or both. At least one of form.settings or form.columns is required.

Example request

curl -X PATCH "{{baseUrl}}/api/v1/forms/65f1a6f8c2d1e9a123456789" \
  -H "Authorization: Bearer {{serviceToken}}" \
  -H "Content-Type: application/json" \
  -d '{
    "form": {
      "settings": {
        "allowEditingAfterSubmit": true,
        "expirationDate": null
      },
      "columns": [
        {
          "id": "email",
          "validations": [{ "operator": "required", "value": true }]
        }
      ]
    }
  }'

Example success response

{
  "data": {
    "form": 
      {
        "id": "65f1a6f8c2d1e9a123456789",
        "target": "item",
        "form": {
          "settings": {
            "notifyOnSubmit": true,
            "allowEditingAfterSubmit": false,
            "customMessage": "Please confirm the details below.",
            "expirationDate": "2026-06-01T00:00:00.000Z"
          },
          "columns": [
            {
              "id": "email",
              "title": "Email",
              "type": "email",
              "validations": [{ "operator": "required", "value": true }]
            }
          ]
        },
        "formUrl": "https://...",
        "acceptingSubmissions": true,
        "createdAt": "2026-04-30T15:25:00.000Z",
        "updatedAt": "2026-04-30T15:25:00.000Z"
      }
  }
}

PATCH /api/v1/forms/:formId/active

Pause or Resume a Form

Toggle whether a form accepts new submissions. Used-up single-use links cannot be reactivated.

Example request

curl -X PATCH "{{baseUrl}}/api/v1/forms/65f1a6f8c2d1e9a123456789/active" \
  -H "Authorization: Bearer {{serviceToken}}" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

Example success response

{
  "data": {
    "form": 
      {
        "id": "65f1a6f8c2d1e9a123456789",
        "target": "item",
        "form": {
          "settings": {
            "notifyOnSubmit": true,
            "allowEditingAfterSubmit": false,
            "customMessage": "Please confirm the details below.",
            "expirationDate": "2026-06-01T00:00:00.000Z"
          },
          "columns": [
            {
              "id": "email",
              "title": "Email",
              "type": "email",
              "validations": [{ "operator": "required", "value": true }]
            }
          ]
        },
        "formUrl": "https://...",
        "acceptingSubmissions": true,
        "createdAt": "2026-04-30T15:25:00.000Z",
        "updatedAt": "2026-04-30T15:25:00.000Z"
      }
  }
}

DELETE /api/v1/forms/:formId

Delete a Form

Delete a Fill form by ID.

Example request

curl -X DELETE "{{baseUrl}}/api/v1/forms/65f1a6f8c2d1e9a123456789" \
  -H "Authorization: Bearer {{serviceToken}}"

Example success response

{
  "data": {
    "formId": "65f1a6f8c2d1e9a123456789",
    "deletedAt": "2026-04-30T15:30:00.000Z"
  }
}

Errors

Error responses use { "error": { "code", "message" } }and may include details. Implemented public API error codes include invalid_request, invalid_token, token_revoked, token_expired, oauth_required, rate_limited, quota_exceeded, form_not_found, target_not_accessible, conflict, and validation_failed.

{
  "error": {
    "code": "invalid_token",
    "message": "Missing service token"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "Validation failed",
    "details": [
      {
        "field": "form.columns",
        "message": "At least one column is required"
      }
    ]
  }
}

{
  "error": {
    "code": "conflict",
    "message": "Some items already have active forms",
    "details": {
      "conflicts": ["123456789"]
    }
  }
}