External API

The Deformity External API lets you create, edit, fetch, and delete forms from your own app, scripts, or automation tools. It is completely free for all users.

If you want an AI assistant to work with Deformity through conversation, use the Deformity MCP server. MCP uses the same External API keys and form payloads.

Setup

1. Go to Account - API Keys and create a key in the Deformity External API section.
2. Copy the key immediately. It is only shown once.
3. Use Authorization: Bearer df_your_api_key on every form API request.
4. Find a workspace ID from this page, the dashboard URL, or the workspace endpoint.
5. Find a form ID from Settings - Integrations - Developer inside a form, or from the list forms endpoint.

Find your workspace ID

workspaceId is required when creating a form. If you are logged in, your active organization workspaces appear below. You can also callGET /api/v1/workspaces with your API key to list workspaces programmatically.

Endpoints

Status codes and responses

Successful requests return a data value. Errors return anerror object with a stable code and human-readable message. Delete requests return confirmation JSON instead of an empty response.

{
  "data": {
    "id": "form_123"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Request body is invalid"
  }
}

AI vs static forms

Send formType on create. Use ai for conversational forms andstatic for one-question-at-a-time static forms. You can also sendformType in PATCH to switch a form.

{
  "workspaceId": "workspace_123",
  "formType": "ai",
  "name": "Customer intake"
}

Create a form

curl -X POST https://deformity.ai/api/v1/forms \
  -H 'Authorization: Bearer df_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "workspaceId": "workspace_123",
    "formType": "ai",
    "name": "Customer intake",
    "purpose": "Collect onboarding details and ask helpful follow-ups.",
    "points": [
      {
        "pointType": "welcome_screen",
        "body": {
          "point": "Welcome to onboarding",
          "description": "We will ask a few quick questions.",
          "buttonText": "Start",
          "active": true
        }
      },
      {
        "pointType": "freeform",
        "required": true,
        "body": {
          "point": "What should we know before kickoff?",
          "sampleQuestion": "Tell us about your goals"
        }
      }
    ],
    "settings": {
      "saveResponses": true,
      "emailResponses": true
    }
  }'

Edit a form

PATCH accepts partial form updates. If you send points, the API replaces the form's ordered points with the array you provide.

curl -X PATCH https://deformity.ai/api/v1/forms/form_123 \
  -H 'Authorization: Bearer df_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Customer onboarding intake",
    "formType": "static",
    "settings": {
      "completionRedirect": "https://example.com/thanks"
    }
  }'

Form properties

Settings properties

Settings object shapes

{
  "submissionPeriod": {
    "startDate": "2026-06-01T00:00:00.000Z",
    "endDate": "2026-06-30T23:59:59.999Z",
    "customMessage": "This form is closed."
  },
  "limit": {
    "maxSubmissions": "100",
    "customMessage": "This form has reached its response limit."
  },
  "completionEmail": {
    "active": true,
    "email": "team@example.com"
  },
  "customBranding": {
    "logo": "https://example.com/logo.png",
    "position": "bottomRight"
  },
  "metadata": {
    "title": "Customer intake",
    "description": "Tell us about your project.",
    "favicon": "https://example.com/favicon.ico",
    "shareImage": "https://example.com/share.png"
  }
}

Point properties

Visual object shapes

Visual objects are intentionally flexible because the builder may add renderer-specific keys over time. These are the common shapes to start with.

{
  "buttons": {
    "backgroundColor": "#000000",
    "textColor": "#ffffff",
    "borderRadius": 8
  },
  "background": {
    "type": "image",
    "url": "https://example.com/background.jpg",
    "position": "center",
    "size": "cover"
  },
  "files": [
    {
      "id": "file_123",
      "name": "Brief.pdf",
      "url": "https://example.com/brief.pdf",
      "type": "application/pdf"
    }
  ]
}

Point body properties

Put question-specific values inside body. For convenience, unknown top-level fields on a point are folded into body, but using body directly is clearer for integrations.

Choice option shapes

For simple choices, send strings. For choices that need stable IDs or metadata, send objects.

{
  "options": ["Free", "Pro", "Enterprise"]
}

{
  "options": [
    { "id": "free", "label": "Free", "value": "free" },
    { "id": "pro", "label": "Pro", "value": "pro" }
  ]
}

Common body shapes by point type

{
  "freeform": {
    "point": "What should we know?",
    "description": "Share as much detail as you want.",
    "sampleQuestion": "Tell us about your goals"
  },
  "multiple_choice": {
    "point": "Pick one",
    "options": ["A", "B", "C"],
    "showOther": true
  },
  "dropdown": {
    "point": "Choose a department",
    "options": ["Sales", "Support", "Product"],
    "selectMultiple": false
  },
  "rating": {
    "point": "Rate your experience",
    "minRating": 1,
    "maxRating": 5,
    "ratingType": "stars"
  },
  "signature": {
    "point": "Sign here",
    "signatureType": "both"
  },
  "date_time": {
    "point": "Pick a time",
    "dateType": "date_time",
    "weekStart": 1
  },
  "matrix": {
    "point": "Rate each area",
    "matrixRows": ["Support", "Pricing"],
    "matrixColumns": ["Poor", "Okay", "Great"]
  },
  "payment": {
    "point": "Pay your deposit",
    "buttonText": "Pay now",
    "amount": 5000,
    "currency": "USD",
    "collectName": true,
    "collectEmail": true
  },
  "embed": {
    "point": "Watch this first",
    "embedLink": "https://www.youtube.com/watch?v=example",
    "buttonText": "Continue"
  }
}

Supported point types

Common point examples

[
  {
    "pointType": "multiple_choice",
    "required": true,
    "body": {
      "point": "Which plan are you interested in?",
      "options": ["Free", "Pro", "Enterprise"],
      "showOther": true
    }
  },
  {
    "pointType": "rating",
    "body": {
      "point": "How urgent is this?",
      "minRating": 1,
      "maxRating": 5,
      "ratingType": "stars"
    }
  },
  {
    "pointType": "date_time",
    "body": {
      "point": "When should we follow up?",
      "dateType": "date_time",
      "weekStart": 1
    }
  },
  {
    "pointType": "matrix",
    "body": {
      "point": "Rate each area",
      "matrixRows": ["Support", "Pricing", "Features"],
      "matrixColumns": ["Poor", "Okay", "Great"]
    }
  },
  {
    "pointType": "payment",
    "body": {
      "point": "Pay your deposit",
      "buttonText": "Pay now",
      "amount": 5000,
      "currency": "USD",
      "collectName": true,
      "collectEmail": true
    }
  }
]

Response shape

Successful create, fetch, and update responses return { "data": form }. Form objects include id, formType, form metadata,settings, ordered points, timestamps, andnumberOfSubmissions.

Errors

{
  "error": {
    "code": "invalid_request",
    "message": "Request body is invalid"
  }
}

API keys are rate limited to 120 requests per minute by default. A rate limited request returns HTTP 429 with Retry-After, X-RateLimit-Limit,X-RateLimit-Remaining, and X-RateLimit-Reset headers.