ToFF Form: API Reference & Integration

Powered by Formbricks

Managed by CultureOS

This reference manual documents programmatic interfaces for interacting with ToFF Form, including REST API endpoints (v1/v2), Webhook pipelines, and Model Context Protocol (MCP) tool bindings.

System Operations & Engineering

This operational system is configured, deployed, and managed by CultureOS. CultureOS is an AI-native practice helping cultural institutions modernize digital infrastructure, archives, and research workflows responsibly.

Authentication

All administrative API requests require an HTTP Bearer token generated within the dashboard (Settings → API Keys):

curl -X GET "https://form.tomoffinland.org/api/v1/management/surveys" \
  -H "x-api-key: fbk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Core Management Endpoints

1. List Active Surveys

• Method: GET
• Endpoint: /api/v1/management/surveys
• Description: Returns all published and drafted surveys within the authenticated workspace.

Response Example

{
  "data": [
    {
      "id": "cmv1rw9zt000801q0b1knm0dq",
      "name": "Tom of Finland Emerging Artist Fellowship 2026",
      "status": "inProgress",
      "type": "link",
      "createdAt": "2026-10-09T22:30:00.000Z",
      "responseCount": 42
    }
  ]
}

2. Fetch Survey Responses

• Method: GET
• Endpoint: /api/v1/management/surveys/{surveyId}/responses
• Parameters: limit (default 50), offset (integer)

3. Retrieve Individual Submission

• Method: GET
• Endpoint: /api/v1/management/responses/{responseId}

Webhook Event Pipelines

ToFF Form dispatches real-time HTTPS webhooks to notify external Foundation platforms (e.g., triggering contract execution in ToFF Sign when a grant application is approved):

 [ ToFF Form Submission ] ──> [ Hub Worker Dispatch ] ──> [ POST https://sign.tomoffinland.org/api/... ]

Supported Webhook Events

• responseCreated: Emitted upon initiation of a new questionnaire attempt.
• responseUpdated: Emitted upon intermediate progress saves.
• responseFinished: Emitted when all mandatory questions are answered and submitted.

Webhook Payload Schema

{
  "event": "responseFinished",
  "surveyId": "cmv1rw9zt000801q0b1knm0dq",
  "responseId": "rsp_98a7sd6f5g4",
  "createdAt": "2026-10-10T03:30:00Z",
  "data": {
    "applicant_name": "Artist Name",
    "portfolio_url": "https://form.tomoffinland.org/storage/portfolio.pdf",
    "residency_session": "Fall 2026"
  }
}

Model Context Protocol (MCP) Agentic Integration

AI agents (such as Noddie or Dots) can programmatically inspect survey metrics and query applicant rosters via the Noema MCP bridge:

{
  "server": "toff-form-mcp",
  "tools": [
    "list_surveys",
    "get_survey_metrics",
    "export_applicant_records"
  ]
}

Agents access ToFF Form over authenticated TLS, parsing structured JSON answers without exposing personal identifiable information (PII) to public LLM contexts.