docs: clarify v3 survey logic fallback usage

# Conflicts:
#	apps/web/app/api/v3/lib/response.ts
#	docs/api-v3-reference/openapi.yml

apps/web/app/api/v3/lib/api-wrapper.test.ts

@@ -135,7 +135,7 @@ describe("withV3ApiWrapper", () => {
       apiKeyId: "key_1",
       organizationId: "org_1",
       organizationAccess: { accessControl: { read: true, write: true } },
-      environmentPermissions: [],
+      workspacePermissions: [],
     });
 
     const wrapped = withV3ApiWrapper({
@@ -440,6 +440,46 @@ describe("withV3ApiWrapper", () => {
     );
   });
 
+  test("preserves machine-readable validation metadata from Zod issues", async () => {
+    const handler = vi.fn(async () => Response.json({ ok: true }));
+    const wrapped = withV3ApiWrapper({
+      auth: "none",
+      schemas: {
+        body: z.unknown().superRefine((_value, ctx) => {
+          ctx.addIssue({
+            code: "custom",
+            message: "Unsupported field 'extra'",
+            path: ["extra"],
+            params: { code: "unsupported_field" },
+          });
+        }),
+      },
+      handler,
+    });
+
+    const response = await wrapped(
+      new NextRequest("http://localhost/api/v3/surveys", {
+        method: "POST",
+        body: JSON.stringify({ extra: true }),
+        headers: {
+          "Content-Type": "application/json",
+        },
+      }),
+      {} as never
+    );
+
+    expect(response.status).toBe(400);
+    expect(handler).not.toHaveBeenCalled();
+    const body = await response.json();
+    expect(body.invalid_params).toEqual([
+      {
+        name: "extra",
+        reason: "Unsupported field 'extra'",
+        code: "unsupported_field",
+      },
+    ]);
+  });
+
   test("returns 429 problem response when rate limited", async () => {
     const { applyRateLimit } = await import("@/modules/core/rate-limit/helpers");
     mockGetServerSession.mockResolvedValue({

apps/web/app/api/v3/lib/api-wrapper.ts

@@ -14,6 +14,7 @@ import { queueAuditEvent } from "@/modules/ee/audit-logs/lib/handler";
 import { TAuditAction, TAuditTarget } from "@/modules/ee/audit-logs/types/audit-log";
 import {
   type InvalidParam,
+  isInvalidParamCode,
   problemBadRequest,
   problemInternalError,
   problemTooManyRequests,
@@ -70,11 +71,21 @@ function getUnauthenticatedDetail(authMode: TV3AuthMode): string {
   return "Not authenticated";
 }
 
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 function formatZodIssues(error: z.ZodError, fallbackName: "body" | "query" | "params"): InvalidParam[] {
-  return error.issues.map((issue) => ({
-    name: issue.path.length > 0 ? issue.path.join(".") : fallbackName,
-    reason: issue.message,
-  }));
+  return error.issues.map((issue) => {
+    const params = "params" in issue && isPlainObject(issue.params) ? issue.params : {};
+    const code = isInvalidParamCode(params.code) ? params.code : undefined;
+
+    return {
+      name: issue.path.length > 0 ? issue.path.join(".") : fallbackName,
+      reason: issue.message,
+      ...(code ? { code } : {}),
+    };
+  });
 }
 
 function searchParamsToObject(searchParams: URLSearchParams): Record<string, string | string[]> {

apps/web/app/api/v3/lib/response.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "vitest";
 import {
+  createdResponse,
   noContentResponse,
   problemBadRequest,
   problemForbidden,
@@ -120,6 +121,27 @@ describe("successResponse", () => {
   });
 });
 
+describe("createdResponse", () => {
+  test("returns 201 with Location, request id, and data envelope", async () => {
+    const res = createdResponse(
+      { id: "survey_1" },
+      {
+        location: "/api/v3/surveys/survey_1",
+        requestId: "req-created",
+      }
+    );
+
+    expect(res.status).toBe(201);
+    expect(res.headers.get("Location")).toBe("/api/v3/surveys/survey_1");
+    expect(res.headers.get("X-Request-Id")).toBe("req-created");
+    expect(res.headers.get("Content-Type")).toBe("application/json");
+    expect(res.headers.get("Cache-Control")).toContain("no-store");
+    expect(await res.json()).toEqual({
+      data: { id: "survey_1" },
+    });
+  });
+});
+
 describe("noContentResponse", () => {
   test("returns 204 without a body", async () => {
     const res = noContentResponse({ requestId: "req-empty" });

apps/web/app/api/v3/lib/response.ts

@@ -6,7 +6,45 @@
 const PROBLEM_JSON = "application/problem+json" as const;
 const CACHE_NO_STORE = "private, no-store" as const;
 
-export type InvalidParam = { name: string; reason: string; identifier?: string };
+export const INVALID_PARAM_CODES = [
+  "dangling_reference",
+  "duplicate_identifier",
+  "duplicate_locale",
+  "forbidden_identifier",
+  "immutable_identifier",
+  "invalid_locale",
+  "invalid_reference",
+  "missing_required_field",
+  "missing_translation",
+  "unsupported_field",
+] as const;
+
+export type InvalidParamCode = (typeof INVALID_PARAM_CODES)[number];
+
+const INVALID_PARAM_CODE_SET = new Set<InvalidParamCode>(INVALID_PARAM_CODES);
+
+export function isInvalidParamCode(value: unknown): value is InvalidParamCode {
+  return typeof value === "string" && INVALID_PARAM_CODE_SET.has(value as InvalidParamCode);
+}
+
+export type InvalidParam = {
+  name: string;
+  reason: string;
+  code?: InvalidParamCode;
+  identifier?: string;
+  referenceType?:
+    | "block"
+    | "element"
+    | "ending"
+    | "hiddenField"
+    | "language"
+    | "variable"
+    | "variableName"
+    | "recall";
+  missingId?: string;
+  firstUsedAt?: string;
+  conflictsWith?: string;
+};
 
 export type ProblemExtension = {
   code?: string;
@@ -172,6 +210,31 @@ export function successResponse<T>(
   );
 }
 
+export function createdResponse<T>(
+  data: T,
+  options: { location: string; requestId?: string; cache?: string }
+): Response {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "Cache-Control": options.cache ?? CACHE_NO_STORE,
+    Location: options.location,
+  };
+
+  if (options.requestId) {
+    headers["X-Request-Id"] = options.requestId;
+  }
+
+  return Response.json(
+    {
+      data,
+    },
+    {
+      status: 201,
+      headers,
+    }
+  );
+}
+
 export function noContentResponse(options?: { requestId?: string; cache?: string }): Response {
   const headers: Record<string, string> = {
     "Cache-Control": options?.cache ?? CACHE_NO_STORE,

apps/web/app/api/v3/surveys/create.test.ts

@@ -0,0 +1,255 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { prisma } from "@formbricks/database";
+import type { TSurvey } from "@formbricks/types/surveys/types";
+import { getOrganizationByWorkspaceId } from "@/lib/organization/service";
+import { createSurvey } from "@/lib/survey/service";
+import { getExternalUrlsPermission } from "@/modules/survey/lib/permission";
+import { V3SurveyCreatePermissionError, createV3Survey } from "./create";
+import { ZV3CreateSurveyBody } from "./schemas";
+
+vi.mock("server-only", () => ({}));
+
+vi.mock("@formbricks/database", () => ({
+  prisma: {
+    language: {
+      upsert: vi.fn(),
+    },
+  },
+}));
+
+vi.mock("@/lib/survey/service", () => ({
+  createSurvey: vi.fn(),
+}));
+
+vi.mock("@/lib/organization/service", () => ({
+  getOrganizationByWorkspaceId: vi.fn(),
+}));
+
+vi.mock("@/modules/survey/lib/permission", () => ({
+  getExternalUrlsPermission: vi.fn(),
+}));
+
+vi.mock("@formbricks/logger", () => ({
+  logger: {
+    withContext: vi.fn(() => ({
+      error: vi.fn(),
+      warn: vi.fn(),
+    })),
+  },
+}));
+
+const workspaceId = "clxx1234567890123456789012";
+
+const rawCreateBody = {
+  workspaceId,
+  name: "Product Feedback",
+  defaultLanguage: "en-US",
+  metadata: {
+    cx_operation: "enterprise_onboarding",
+    title: { "en-US": "Product Feedback", "de-DE": "Produktfeedback" },
+  },
+  blocks: [
+    {
+      id: "clbk1234567890123456789012",
+      name: "Main Block",
+      elements: [
+        {
+          id: "satisfaction",
+          type: "openText",
+          headline: {
+            "en-US": "What should we improve?",
+            "de-DE": "Was sollen wir verbessern?",
+          },
+          required: true,
+        },
+      ],
+    },
+  ],
+};
+
+const createBody = ZV3CreateSurveyBody.parse(rawCreateBody);
+
+const createdSurvey = {
+  id: "clsv1234567890123456789012",
+  workspaceId,
+  createdAt: new Date("2026-04-21T10:00:00.000Z"),
+  updatedAt: new Date("2026-04-21T10:00:00.000Z"),
+  name: "Product Feedback",
+  type: "link",
+  status: "draft",
+  metadata: {},
+  languages: [],
+  questions: [],
+  welcomeCard: { enabled: false },
+  blocks: createBody.blocks,
+  endings: [],
+  hiddenFields: { enabled: false },
+  variables: [],
+} as unknown as TSurvey;
+
+type TLanguageUpsertArgs = Parameters<typeof prisma.language.upsert>[0];
+type TLanguageUpsertReturn = ReturnType<typeof prisma.language.upsert>;
+
+describe("createV3Survey", () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    vi.mocked(prisma.language.upsert).mockImplementation(
+      (args: TLanguageUpsertArgs): TLanguageUpsertReturn => {
+        const workspaceIdCode = args.where.workspaceId_code;
+        if (!workspaceIdCode) {
+          throw new Error("Expected workspaceId_code upsert selector");
+        }
+
+        return Promise.resolve({
+          id: `cllang${workspaceIdCode.code.toLowerCase().replaceAll("-", "")}`,
+          code: workspaceIdCode.code,
+          alias: null,
+          workspaceId: workspaceIdCode.workspaceId,
+          createdAt: new Date("2026-04-21T10:00:00.000Z"),
+          updatedAt: new Date("2026-04-21T10:00:00.000Z"),
+        }) as TLanguageUpsertReturn;
+      }
+    );
+    vi.mocked(createSurvey).mockResolvedValue(createdSurvey);
+    vi.mocked(getOrganizationByWorkspaceId).mockResolvedValue({
+      id: "org_1",
+      name: "Organization",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      billing: {
+        limits: { monthly: { responses: 1000 }, workspaces: 1 },
+        stripeCustomerId: null,
+        usageCycleAnchor: null,
+      },
+      isAISmartToolsEnabled: false,
+      isAIDataAnalysisEnabled: false,
+      whitelabel: undefined,
+    });
+    vi.mocked(getExternalUrlsPermission).mockResolvedValue(true);
+  });
+
+  test("maps the public v3 body to the internal create payload", async () => {
+    await createV3Survey(
+      createBody,
+      {
+        user: { id: "user_1", email: "user@example.com", name: "User" },
+        expires: "2026-05-01",
+      },
+      "req_1"
+    );
+
+    expect(prisma.language.upsert).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { workspaceId_code: { workspaceId, code: "en-US" } },
+        create: { workspaceId, code: "en-US", alias: null },
+      })
+    );
+    expect(prisma.language.upsert).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { workspaceId_code: { workspaceId, code: "de-DE" } },
+        create: { workspaceId, code: "de-DE", alias: null },
+      })
+    );
+    expect(createSurvey).toHaveBeenCalledWith(
+      workspaceId,
+      expect.objectContaining({
+        name: "Product Feedback",
+        type: "link",
+        status: "draft",
+        createdBy: "user_1",
+        questions: [],
+        metadata: expect.objectContaining({
+          cx_operation: "enterprise_onboarding",
+          title: { default: "Product Feedback", "de-DE": "Produktfeedback" },
+        }),
+        blocks: [
+          expect.objectContaining({
+            elements: [
+              expect.objectContaining({
+                headline: {
+                  default: "What should we improve?",
+                  "de-DE": "Was sollen wir verbessern?",
+                },
+              }),
+            ],
+          }),
+        ],
+        languages: [
+          expect.objectContaining({ default: true, enabled: true }),
+          expect.objectContaining({ default: false, enabled: true }),
+        ],
+      })
+    );
+    expect(getOrganizationByWorkspaceId).not.toHaveBeenCalled();
+    expect(getExternalUrlsPermission).not.toHaveBeenCalled();
+  });
+
+  test("keeps createdBy null for API key calls and honors explicit disabled languages", async () => {
+    const body = ZV3CreateSurveyBody.parse({
+      ...rawCreateBody,
+      languages: [{ code: "fr-FR", enabled: false }],
+      blocks: [
+        {
+          ...rawCreateBody.blocks[0],
+          elements: [
+            {
+              ...rawCreateBody.blocks[0].elements[0],
+              headline: {
+                ...rawCreateBody.blocks[0].elements[0].headline,
+                "fr-FR": "Que devons-nous améliorer ?",
+              },
+            },
+          ],
+        },
+      ],
+    });
+
+    await createV3Survey(
+      body,
+      {
+        type: "apiKey",
+        apiKeyId: "key_1",
+        organizationId: "org_1",
+        organizationAccess: { accessControl: { read: true, write: true } },
+        workspacePermissions: [],
+      },
+      "req_2"
+    );
+
+    expect(createSurvey).toHaveBeenCalledWith(
+      workspaceId,
+      expect.objectContaining({
+        createdBy: null,
+        languages: expect.arrayContaining([
+          expect.objectContaining({ language: expect.objectContaining({ code: "fr-FR" }), enabled: false }),
+        ]),
+      })
+    );
+  });
+
+  test("rejects external CTA buttons when the organization does not have external URL permission", async () => {
+    vi.mocked(getExternalUrlsPermission).mockResolvedValue(false);
+    const body = ZV3CreateSurveyBody.parse({
+      ...rawCreateBody,
+      blocks: [
+        {
+          ...rawCreateBody.blocks[0],
+          elements: [
+            {
+              id: "external_cta",
+              type: "cta",
+              headline: { "en-US": "Continue" },
+              required: false,
+              buttonExternal: true,
+              buttonUrl: "https://example.com",
+              ctaButtonLabel: { "en-US": "Open" },
+            },
+          ],
+        },
+      ],
+    });
+
+    await expect(createV3Survey(body, null, "req_3")).rejects.toThrow(V3SurveyCreatePermissionError);
+    expect(createSurvey).not.toHaveBeenCalled();
+  });
+});

apps/web/app/api/v3/surveys/create.ts

@@ -0,0 +1,106 @@
+import "server-only";
+import type { TSurveyCreateInput } from "@formbricks/types/surveys/types";
+import type { TV3Authentication } from "@/app/api/v3/lib/types";
+import { getOrganizationByWorkspaceId } from "@/lib/organization/service";
+import { createSurvey } from "@/lib/survey/service";
+import { getElementsFromBlocks } from "@/lib/survey/utils";
+import { getExternalUrlsPermission } from "@/modules/survey/lib/permission";
+import { type TV3SurveyLanguageRequest, ensureV3WorkspaceLanguages } from "./languages";
+import { prepareV3SurveyCreate } from "./prepare";
+import { V3SurveyReferenceValidationError } from "./reference-validation";
+import type { TV3CreateSurveyBody } from "./schemas";
+
+export class V3SurveyCreatePermissionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "V3SurveyCreatePermissionError";
+  }
+}
+
+function getCreatedBy(authentication: TV3Authentication): string | null {
+  if (authentication && "user" in authentication && authentication.user?.id) {
+    return authentication.user.id;
+  }
+
+  return null;
+}
+
+function hasExternalUrlReferences(input: TV3CreateSurveyBody): boolean {
+  const hasExternalEndingLink = input.endings.some(
+    (ending) => ending.type === "endScreen" && Boolean(ending.buttonLink)
+  );
+  const hasExternalCtaButton = getElementsFromBlocks(input.blocks).some(
+    (element) => element.type === "cta" && element.buttonExternal
+  );
+
+  return hasExternalEndingLink || hasExternalCtaButton;
+}
+
+async function assertV3SurveyCreatePermissions(
+  input: TV3CreateSurveyBody,
+  organizationId?: string
+): Promise<void> {
+  if (!hasExternalUrlReferences(input)) {
+    return;
+  }
+
+  const resolvedOrganizationId =
+    organizationId ?? (await getOrganizationByWorkspaceId(input.workspaceId))?.id ?? null;
+  if (!resolvedOrganizationId) {
+    return;
+  }
+
+  const isExternalUrlsAllowed = await getExternalUrlsPermission(resolvedOrganizationId);
+  if (!isExternalUrlsAllowed) {
+    throw new V3SurveyCreatePermissionError(
+      "External URLs are not enabled for this organization. Upgrade to use external survey links."
+    );
+  }
+}
+
+export async function executeV3SurveyCreate(params: {
+  input: TV3CreateSurveyBody;
+  authentication: TV3Authentication;
+  languageRequests: TV3SurveyLanguageRequest[];
+  requestId?: string;
+}) {
+  const { input, authentication, languageRequests, requestId } = params;
+  const languages = await ensureV3WorkspaceLanguages(input.workspaceId, languageRequests, requestId);
+  const surveyCreateInput: TSurveyCreateInput = {
+    name: input.name,
+    type: "link",
+    status: input.status,
+    metadata: input.metadata,
+    welcomeCard: input.welcomeCard,
+    blocks: input.blocks,
+    endings: input.endings,
+    hiddenFields: input.hiddenFields,
+    variables: input.variables,
+    languages,
+    questions: [],
+    createdBy: getCreatedBy(authentication),
+  };
+
+  return await createSurvey(input.workspaceId, surveyCreateInput);
+}
+
+export async function createV3Survey(
+  input: TV3CreateSurveyBody,
+  authentication: TV3Authentication,
+  requestId?: string,
+  organizationId?: string
+) {
+  const preparation = prepareV3SurveyCreate(input);
+  if (!preparation.ok) {
+    throw new V3SurveyReferenceValidationError(preparation.validation.invalidParams);
+  }
+
+  await assertV3SurveyCreatePermissions(input, organizationId);
+
+  return await executeV3SurveyCreate({
+    input: preparation.document,
+    authentication,
+    languageRequests: preparation.languageRequests,
+    requestId,
+  });
+}

apps/web/app/api/v3/surveys/language.ts

@@ -1,8 +1,16 @@
+import type { TSurvey as TInternalSurvey } from "@formbricks/types/surveys/types";
+
 type TV3SurveyLanguageInput = {
   code: string;
   enabled: boolean;
 };
 
+export type TV3SurveyLanguage = {
+  code: string;
+  default: boolean;
+  enabled: boolean;
+};
+
 type TV3SurveyLanguageQueryInput = string | string[];
 
 type TResolveV3SurveyLanguageCodeResult =
@@ -95,3 +103,32 @@ export function resolveV3SurveyLanguageCode(
     message: `Language '${normalizedRequestedLanguage}' is not configured for this survey`,
   };
 }
+
+export function getV3SurveyLanguages(
+  survey: Pick<TInternalSurvey, "languages">,
+  fallbackLanguage: string
+): TV3SurveyLanguage[] {
+  const languages = (survey.languages ?? []).map((surveyLanguage) => ({
+    code: normalizeV3SurveyLanguageTag(surveyLanguage.language.code) ?? surveyLanguage.language.code,
+    default: surveyLanguage.default,
+    enabled: surveyLanguage.enabled,
+  }));
+
+  if (languages.length === 0) {
+    return [{ code: fallbackLanguage, default: true, enabled: true }];
+  }
+
+  return languages;
+}
+
+export function getV3SurveyDefaultLanguage(
+  survey: Pick<TInternalSurvey, "languages">,
+  fallbackLanguage: string
+): string {
+  const defaultLanguageCode = survey.languages?.find((surveyLanguage) => surveyLanguage.default)?.language
+    .code;
+
+  return defaultLanguageCode
+    ? (normalizeV3SurveyLanguageTag(defaultLanguageCode) ?? defaultLanguageCode)
+    : fallbackLanguage;
+}

apps/web/app/api/v3/surveys/languages.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test, vi } from "vitest";
+import { deriveV3SurveyLanguageRequests } from "./languages";
+import { ZV3CreateSurveyBody } from "./schemas";
+
+vi.mock("server-only", () => ({}));
+
+vi.mock("@formbricks/database", () => ({
+  prisma: {
+    language: {
+      upsert: vi.fn(),
+    },
+  },
+}));
+
+describe("deriveV3SurveyLanguageRequests", () => {
+  test("derives languages from survey content and known translatable metadata fields only", () => {
+    const document = ZV3CreateSurveyBody.parse({
+      workspaceId: "clxx1234567890123456789012",
+      name: "Product Feedback",
+      defaultLanguage: "en-US",
+      metadata: {
+        title: {
+          "en-US": "Feedback",
+          "de-DE": "Feedback",
+        },
+        cx_context: {
+          "fr-FR": "Arbitrary customer metadata, not translatable survey text",
+        },
+      },
+      blocks: [
+        {
+          id: "clbk1234567890123456789012",
+          name: "Main Block",
+          elements: [
+            {
+              id: "satisfaction",
+              type: "openText",
+              headline: {
+                "en-US": "What should we improve?",
+                "pt-BR": "O que devemos melhorar?",
+              },
+              required: true,
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(deriveV3SurveyLanguageRequests(document)).toEqual([
+      { code: "en-US", default: true, enabled: true },
+      { code: "de-DE", default: false, enabled: true },
+      { code: "pt-BR", default: false, enabled: true },
+    ]);
+  });
+});

apps/web/app/api/v3/surveys/languages.ts

@@ -0,0 +1,159 @@
+import "server-only";
+import { Prisma } from "@prisma/client";
+import { prisma } from "@formbricks/database";
+import { logger } from "@formbricks/logger";
+import { DatabaseError } from "@formbricks/types/errors";
+import type { TI18nString } from "@formbricks/types/i18n";
+import type { TSurveyLanguage } from "@formbricks/types/surveys/types";
+import { normalizeV3SurveyLanguageTag } from "./language";
+import type { TV3SurveyDocument } from "./schemas";
+
+export type TV3SurveyLanguageRequest = {
+  code: string;
+  default: boolean;
+  enabled: boolean;
+};
+
+const languageSelect = {
+  id: true,
+  code: true,
+  alias: true,
+  workspaceId: true,
+  createdAt: true,
+  updatedAt: true,
+} satisfies Prisma.LanguageSelect;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isInternalI18nString(value: unknown): value is TI18nString {
+  return (
+    isPlainObject(value) &&
+    typeof value.default === "string" &&
+    Object.values(value).every((entry) => typeof entry === "string")
+  );
+}
+
+function collectI18nLanguageCodes(value: unknown, languageCodes: Set<string>): void {
+  if (Array.isArray(value)) {
+    value.forEach((entry) => collectI18nLanguageCodes(entry, languageCodes));
+    return;
+  }
+
+  if (!isPlainObject(value)) {
+    return;
+  }
+
+  if (isInternalI18nString(value)) {
+    Object.keys(value).forEach((languageCode) => {
+      if (languageCode !== "default") {
+        const normalizedLanguageCode = normalizeV3SurveyLanguageTag(languageCode);
+        if (normalizedLanguageCode) {
+          languageCodes.add(normalizedLanguageCode);
+        }
+      }
+    });
+    return;
+  }
+
+  Object.values(value).forEach((entry) => collectI18nLanguageCodes(entry, languageCodes));
+}
+
+function collectMetadataI18nLanguageCodes(
+  metadata: TV3SurveyDocument["metadata"],
+  languageCodes: Set<string>
+): void {
+  if (!isPlainObject(metadata)) {
+    return;
+  }
+
+  collectI18nLanguageCodes(metadata.title, languageCodes);
+  collectI18nLanguageCodes(metadata.description, languageCodes);
+}
+
+export function deriveV3SurveyLanguageRequests(input: TV3SurveyDocument): TV3SurveyLanguageRequest[] {
+  const requestedLanguages = new Map<string, TV3SurveyLanguageRequest>();
+  const addLanguage = (code: string, enabled = true): void => {
+    requestedLanguages.set(code, {
+      code,
+      default: code.toLowerCase() === input.defaultLanguage.toLowerCase(),
+      enabled: code.toLowerCase() === input.defaultLanguage.toLowerCase() ? true : enabled,
+    });
+  };
+
+  addLanguage(input.defaultLanguage);
+
+  input.languages.forEach((language) => {
+    addLanguage(language.code, language.enabled);
+  });
+
+  const contentLanguageCodes = new Set<string>();
+  collectI18nLanguageCodes(input.welcomeCard, contentLanguageCodes);
+  collectI18nLanguageCodes(input.blocks, contentLanguageCodes);
+  collectI18nLanguageCodes(input.endings, contentLanguageCodes);
+  collectMetadataI18nLanguageCodes(input.metadata, contentLanguageCodes);
+  contentLanguageCodes.forEach((languageCode) => {
+    if (!requestedLanguages.has(languageCode)) {
+      addLanguage(languageCode);
+    }
+  });
+
+  return Array.from(requestedLanguages.values()).sort((left, right) => {
+    if (left.default) return -1;
+    if (right.default) return 1;
+    return left.code.localeCompare(right.code);
+  });
+}
+
+export async function ensureV3WorkspaceLanguages(
+  workspaceId: string,
+  languageRequests: TV3SurveyLanguageRequest[],
+  requestId?: string
+): Promise<TSurveyLanguage[]> {
+  const log = logger.withContext({ requestId, workspaceId });
+
+  try {
+    const languages = await Promise.all(
+      languageRequests.map((languageRequest) =>
+        prisma.language.upsert({
+          where: {
+            workspaceId_code: {
+              workspaceId,
+              code: languageRequest.code,
+            },
+          },
+          update: {},
+          create: {
+            workspaceId,
+            code: languageRequest.code,
+            alias: null,
+          },
+          select: languageSelect,
+        })
+      )
+    );
+    const languageByCode = new Map(languages.map((language) => [language.code.toLowerCase(), language]));
+
+    return languageRequests.map((languageRequest) => {
+      const language = languageByCode.get(languageRequest.code.toLowerCase());
+
+      if (!language) {
+        throw new DatabaseError(`Failed to resolve language '${languageRequest.code}'`);
+      }
+
+      return {
+        language,
+        default: languageRequest.default,
+        enabled: languageRequest.enabled,
+      };
+    });
+  } catch (error) {
+    if (error instanceof Prisma.PrismaClientKnownRequestError) {
+      log.error({ error }, "Error creating workspace languages for v3 survey write");
+      throw new DatabaseError(error.message);
+    }
+
+    throw error;
+  }
+}

apps/web/app/api/v3/surveys/prepare.test.ts

@@ -0,0 +1,259 @@
+import { describe, expect, test, vi } from "vitest";
+import type { TSurvey } from "@formbricks/types/surveys/types";
+import { prepareV3SurveyCreate, prepareV3SurveyCreateInput, prepareV3SurveyPatchInput } from "./prepare";
+import { ZV3CreateSurveyBody } from "./schemas";
+
+vi.mock("server-only", () => ({}));
+
+const workspaceId = "clxx1234567890123456789012";
+
+const rawCreateBody = {
+  workspaceId,
+  name: "Product Feedback",
+  defaultLanguage: "en-US",
+  blocks: [
+    {
+      id: "clbk1234567890123456789012",
+      name: "Main Block",
+      elements: [
+        {
+          id: "satisfaction",
+          type: "openText",
+          headline: { "en-US": "What should we improve?", "de-DE": "Was sollen wir verbessern?" },
+          required: true,
+        },
+      ],
+    },
+  ],
+};
+
+const createBody = ZV3CreateSurveyBody.parse(rawCreateBody);
+
+const survey = {
+  id: "clsv1234567890123456789012",
+  workspaceId,
+  createdAt: new Date("2026-04-21T10:00:00.000Z"),
+  updatedAt: new Date("2026-04-21T10:00:00.000Z"),
+  name: "Product Feedback",
+  type: "link",
+  status: "draft",
+  metadata: {},
+  languages: [
+    {
+      language: {
+        id: "cllangenus000000000000000",
+        code: "en-US",
+        alias: null,
+        workspaceId,
+        createdAt: new Date("2026-04-21T10:00:00.000Z"),
+        updatedAt: new Date("2026-04-21T10:00:00.000Z"),
+      },
+      default: true,
+      enabled: true,
+    },
+  ],
+  questions: [],
+  welcomeCard: { enabled: false },
+  blocks: createBody.blocks,
+  endings: [],
+  hiddenFields: { enabled: false },
+  variables: [],
+} as unknown as TSurvey;
+
+describe("v3 survey preparation", () => {
+  test("prepares a valid create document and derives language side effects", () => {
+    const preparation = prepareV3SurveyCreate(createBody);
+
+    expect(preparation.ok).toBe(true);
+    if (!preparation.ok) {
+      throw new Error("Expected create preparation to succeed");
+    }
+    expect(preparation.languageRequests).toEqual([
+      { code: "en-US", default: true, enabled: true },
+      { code: "de-DE", default: false, enabled: true },
+    ]);
+  });
+
+  test("returns validation results instead of throwing for invalid create input", () => {
+    const preparation = prepareV3SurveyCreateInput({
+      ...rawCreateBody,
+      blocks: [
+        {
+          ...rawCreateBody.blocks[0],
+          elements: [
+            {
+              ...rawCreateBody.blocks[0].elements[0],
+              buttonUrl: "https://example.com",
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(preparation.ok).toBe(false);
+    if (!preparation.ok) {
+      expect(preparation.validation.invalidParams).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "blocks.0.elements.0.buttonUrl",
+            code: "unsupported_field",
+          }),
+        ])
+      );
+    }
+  });
+
+  test("rejects configured languages that are missing from translatable survey content", () => {
+    const preparation = prepareV3SurveyCreateInput({
+      ...rawCreateBody,
+      languages: [{ code: "pt-PT", enabled: true }],
+    });
+
+    expect(preparation.ok).toBe(false);
+    if (!preparation.ok) {
+      expect(preparation.validation.invalidParams).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "blocks.0.elements.0.headline",
+            code: "missing_translation",
+            identifier: "pt-PT",
+            referenceType: "language",
+          }),
+        ])
+      );
+    }
+  });
+
+  test("rejects partial derived translations before internal survey validation", () => {
+    const preparation = prepareV3SurveyCreateInput({
+      ...rawCreateBody,
+      blocks: [
+        {
+          ...rawCreateBody.blocks[0],
+          elements: [
+            {
+              ...rawCreateBody.blocks[0].elements[0],
+              subheader: { "en-US": "Tell us more" },
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(preparation.ok).toBe(false);
+    if (!preparation.ok) {
+      expect(preparation.validation.invalidParams).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "blocks.0.elements.0.subheader",
+            code: "missing_translation",
+            identifier: "de-DE",
+            referenceType: "language",
+          }),
+        ])
+      );
+    }
+  });
+
+  test("returns language and reference validation issues together", () => {
+    const preparation = prepareV3SurveyCreateInput({
+      ...rawCreateBody,
+      languages: [{ code: "pt-PT", enabled: true }],
+      blocks: [
+        {
+          ...rawCreateBody.blocks[0],
+          logicFallback: "clmiss12345678901234567890",
+        },
+      ],
+    });
+
+    expect(preparation.ok).toBe(false);
+    if (!preparation.ok) {
+      expect(preparation.validation.invalidParams).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "blocks.0.elements.0.headline",
+            code: "missing_translation",
+          }),
+          expect.objectContaining({
+            name: "blocks.0.logicFallback",
+            code: "dangling_reference",
+          }),
+        ])
+      );
+    }
+  });
+
+  test("applies a patch over the current document before validating references", () => {
+    const preparation = prepareV3SurveyPatchInput(survey, {
+      blocks: [
+        {
+          ...rawCreateBody.blocks[0],
+          logicFallback: "clmiss12345678901234567890",
+        },
+      ],
+    });
+
+    expect(preparation.ok).toBe(false);
+    if (!preparation.ok) {
+      expect(preparation.validation.invalidParams).toEqual(
+        expect.arrayContaining([expect.objectContaining({ name: "blocks.0.logicFallback" })])
+      );
+    }
+  });
+
+  test("rejects patch input with immutable fields as validation results", () => {
+    const preparation = prepareV3SurveyPatchInput(survey, {
+      workspaceId,
+    });
+
+    expect(preparation.ok).toBe(false);
+    if (!preparation.ok) {
+      expect(preparation.validation.invalidParams).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "workspaceId",
+            code: "unsupported_field",
+          }),
+        ])
+      );
+    }
+  });
+
+  test("rejects non-draft element id changes on non-draft surveys", () => {
+    const preparation = prepareV3SurveyPatchInput(
+      {
+        ...survey,
+        status: "inProgress",
+      } as TSurvey,
+      {
+        blocks: [
+          {
+            ...rawCreateBody.blocks[0],
+            elements: [
+              {
+                ...rawCreateBody.blocks[0].elements[0],
+                id: "renamed_satisfaction",
+              },
+            ],
+          },
+        ],
+      }
+    );
+
+    expect(preparation.ok).toBe(false);
+    if (!preparation.ok) {
+      expect(preparation.validation.invalidParams).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "blocks.0.elements.0.id",
+            reason: expect.stringContaining("cannot be changed"),
+            code: "immutable_identifier",
+            identifier: "satisfaction",
+            referenceType: "element",
+          }),
+        ])
+      );
+    }
+  });
+});

apps/web/app/api/v3/surveys/prepare.ts

@@ -0,0 +1,181 @@
+import type { TSurvey as TInternalSurvey } from "@formbricks/types/surveys/types";
+import type { InvalidParam } from "@/app/api/v3/lib/response";
+import { getV3SurveyDefaultLanguage, getV3SurveyLanguages } from "./language";
+import { type TV3SurveyLanguageRequest, deriveV3SurveyLanguageRequests } from "./languages";
+import {
+  DEFAULT_V3_SURVEY_LANGUAGE,
+  type TV3CreateSurveyBody,
+  type TV3PatchSurveyBody,
+  type TV3SurveyDocument,
+  ZV3CreateSurveyBody,
+  ZV3SurveyDocumentBase,
+  createZV3PatchSurveyBodySchema,
+  formatV3ZodInvalidParams,
+} from "./schemas";
+import { type TV3SurveyDocumentValidationResult, validateV3SurveyDocument } from "./validation";
+
+type TV3SurveyPrepareSuccess<TDocument> = {
+  ok: true;
+  document: TDocument;
+  validation: Extract<TV3SurveyDocumentValidationResult, { valid: true }>;
+  languageRequests: TV3SurveyLanguageRequest[];
+};
+
+type TV3SurveyPrepareFailure = {
+  ok: false;
+  validation: Extract<TV3SurveyDocumentValidationResult, { valid: false }>;
+};
+
+export type TV3SurveyPrepareResult<TDocument> = TV3SurveyPrepareSuccess<TDocument> | TV3SurveyPrepareFailure;
+
+function invalidPreparation(invalidParams: InvalidParam[]): TV3SurveyPrepareFailure {
+  return {
+    ok: false,
+    validation: {
+      valid: false,
+      invalidParams,
+    },
+  };
+}
+
+function validPreparation<TDocument extends TV3SurveyDocument>(
+  document: TDocument
+): TV3SurveyPrepareResult<TDocument> {
+  const validation = validateV3SurveyDocument(document);
+
+  if (!validation.valid) {
+    return invalidPreparation(validation.invalidParams);
+  }
+
+  return {
+    ok: true,
+    document,
+    validation,
+    languageRequests: deriveV3SurveyLanguageRequests(document),
+  };
+}
+
+function buildDocumentFromSurvey(survey: TInternalSurvey): TV3SurveyPrepareResult<TV3SurveyDocument> {
+  if (Array.isArray(survey.questions) && survey.questions.length > 0) {
+    return invalidPreparation([
+      {
+        name: "survey",
+        reason: "Legacy question-based surveys are not supported by the v3 survey management API",
+      },
+    ]);
+  }
+
+  const documentResult = ZV3SurveyDocumentBase.safeParse({
+    name: survey.name,
+    status: survey.status,
+    metadata: survey.metadata ?? {},
+    defaultLanguage: getV3SurveyDefaultLanguage(survey, DEFAULT_V3_SURVEY_LANGUAGE),
+    languages: getV3SurveyLanguages(survey, DEFAULT_V3_SURVEY_LANGUAGE),
+    welcomeCard: survey.welcomeCard,
+    blocks: survey.blocks,
+    endings: survey.endings,
+    hiddenFields: survey.hiddenFields,
+    variables: survey.variables,
+  });
+
+  if (!documentResult.success) {
+    return invalidPreparation(formatV3ZodInvalidParams(documentResult.error, "survey"));
+  }
+
+  return validPreparation(documentResult.data);
+}
+
+function mergeV3SurveyPatch(document: TV3SurveyDocument, patch: TV3PatchSurveyBody): TV3SurveyDocument {
+  return {
+    ...document,
+    ...Object.fromEntries(Object.entries(patch).filter(([, value]) => value !== undefined)),
+  };
+}
+
+function getElementIds(document: TV3SurveyDocument): Set<string> {
+  return new Set(document.blocks.flatMap((block) => block.elements.map((element) => element.id)));
+}
+
+function getImmutableElementIdIssues(
+  currentDocument: TV3SurveyDocument,
+  patchedDocument: TV3SurveyDocument
+): InvalidParam[] {
+  if (currentDocument.status === "draft") {
+    return [];
+  }
+
+  const patchedElementIds = getElementIds(patchedDocument);
+  const issues: InvalidParam[] = [];
+
+  currentDocument.blocks.forEach((currentBlock) => {
+    const patchedBlockIndex = patchedDocument.blocks.findIndex((block) => block.id === currentBlock.id);
+    if (patchedBlockIndex === -1) {
+      return;
+    }
+
+    const patchedBlock = patchedDocument.blocks[patchedBlockIndex];
+    currentBlock.elements.forEach((currentElement, elementIndex) => {
+      if (currentElement.isDraft || patchedElementIds.has(currentElement.id)) {
+        return;
+      }
+
+      const patchedElement = patchedBlock.elements[elementIndex];
+      if (!patchedElement || patchedElement.id === currentElement.id) {
+        return;
+      }
+
+      issues.push({
+        name: `blocks.${patchedBlockIndex}.elements.${elementIndex}.id`,
+        reason: `Element id '${currentElement.id}' cannot be changed because the survey and element are no longer drafts`,
+        code: "immutable_identifier",
+        identifier: currentElement.id,
+        referenceType: "element",
+      });
+    });
+  });
+
+  return issues;
+}
+
+export function prepareV3SurveyCreate(
+  document: TV3CreateSurveyBody
+): TV3SurveyPrepareResult<TV3CreateSurveyBody> {
+  return validPreparation(document);
+}
+
+export function prepareV3SurveyCreateInput(input: unknown): TV3SurveyPrepareResult<TV3CreateSurveyBody> {
+  const parsed = ZV3CreateSurveyBody.safeParse(input);
+
+  if (!parsed.success) {
+    return invalidPreparation(formatV3ZodInvalidParams(parsed.error, "data"));
+  }
+
+  return prepareV3SurveyCreate(parsed.data);
+}
+
+export function prepareV3SurveyPatchInput(
+  survey: TInternalSurvey,
+  input: unknown
+): TV3SurveyPrepareResult<TV3SurveyDocument> {
+  const currentDocument = buildDocumentFromSurvey(survey);
+
+  if (!currentDocument.ok) {
+    return currentDocument;
+  }
+
+  const parsedPatch = createZV3PatchSurveyBodySchema(currentDocument.document.defaultLanguage).safeParse(
+    input
+  );
+
+  if (!parsedPatch.success) {
+    return invalidPreparation(formatV3ZodInvalidParams(parsedPatch.error, "data"));
+  }
+
+  const patchedDocument = mergeV3SurveyPatch(currentDocument.document, parsedPatch.data);
+  const immutableElementIdIssues = getImmutableElementIdIssues(currentDocument.document, patchedDocument);
+  if (immutableElementIdIssues.length > 0) {
+    return invalidPreparation(immutableElementIdIssues);
+  }
+
+  return validPreparation(patchedDocument);
+}

apps/web/app/api/v3/surveys/reference-validation.test.ts

@@ -0,0 +1,373 @@
+import { describe, expect, test } from "vitest";
+import { validateV3SurveyReferences } from "./reference-validation";
+import { ZV3CreateSurveyBody } from "./schemas";
+
+const validSurvey = ZV3CreateSurveyBody.parse({
+  workspaceId: "clxx1234567890123456789012",
+  name: "Product Feedback",
+  hiddenFields: {
+    enabled: true,
+    fieldIds: ["account_id"],
+  },
+  variables: [
+    {
+      id: "clvar123456789012345678901",
+      name: "score",
+      type: "number",
+      value: 0,
+    },
+  ],
+  endings: [
+    {
+      id: "clend123456789012345678901",
+      type: "endScreen",
+      headline: { "en-US": "Thanks" },
+    },
+  ],
+  blocks: [
+    {
+      id: "clbk1234567890123456789012",
+      name: "Main Block",
+      logicFallback: "clend123456789012345678901",
+      elements: [
+        {
+          id: "satisfaction",
+          type: "openText",
+          headline: { "en-US": "What should we improve?" },
+          required: true,
+        },
+      ],
+      logic: [
+        {
+          id: "cllog123456789012345678901",
+          conditions: {
+            id: "clgrp123456789012345678901",
+            connector: "and",
+            conditions: [
+              {
+                id: "clcon123456789012345678901",
+                leftOperand: { type: "element", value: "satisfaction" },
+                operator: "isSubmitted",
+              },
+            ],
+          },
+          actions: [
+            {
+              id: "clact123456789012345678901",
+              objective: "calculate",
+              variableId: "clvar123456789012345678901",
+              operator: "add",
+              value: { type: "static", value: 1 },
+            },
+          ],
+        },
+      ],
+    },
+  ],
+});
+
+describe("validateV3SurveyReferences", () => {
+  test("accepts a survey with consistent stable identifiers", () => {
+    expect(
+      validateV3SurveyReferences({
+        blocks: validSurvey.blocks,
+        endings: validSurvey.endings,
+        hiddenFields: validSurvey.hiddenFields,
+        variables: validSurvey.variables,
+      })
+    ).toEqual({ ok: true, invalidParams: [] });
+  });
+
+  test("rejects duplicate block, element, variable, and hidden field identifiers", () => {
+    const survey = {
+      ...validSurvey,
+      hiddenFields: { enabled: true, fieldIds: ["account_id", "account_id"] },
+      variables: [
+        ...validSurvey.variables,
+        {
+          id: "clvar123456789012345678901",
+          name: "score",
+          type: "number" as const,
+          value: 0,
+        },
+      ],
+      blocks: [
+        ...validSurvey.blocks,
+        {
+          ...validSurvey.blocks[0],
+          elements: [{ ...validSurvey.blocks[0].elements[0] }],
+        },
+      ],
+    };
+
+    const result = validateV3SurveyReferences({
+      blocks: survey.blocks,
+      endings: survey.endings,
+      hiddenFields: survey.hiddenFields,
+      variables: survey.variables,
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.invalidParams).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ name: "blocks.1.id" }),
+          expect.objectContaining({ name: "blocks.1.elements.0.id" }),
+          expect.objectContaining({ name: "variables.1.id" }),
+          expect.objectContaining({ name: "hiddenFields.fieldIds.1" }),
+          expect.objectContaining({
+            name: "blocks.1.id",
+            code: "duplicate_identifier",
+            identifier: "clbk1234567890123456789012",
+            referenceType: "block",
+            firstUsedAt: "blocks.0.id",
+          }),
+        ])
+      );
+    }
+  });
+
+  test("rejects cross-namespace identifier collisions", () => {
+    const result = validateV3SurveyReferences({
+      blocks: validSurvey.blocks,
+      endings: validSurvey.endings,
+      hiddenFields: { enabled: true, fieldIds: ["account_id", "satisfaction"] },
+      variables: [
+        {
+          id: "satisfaction",
+          name: "account_id",
+          type: "number",
+          value: 0,
+        },
+      ],
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.invalidParams).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ name: "hiddenFields.fieldIds.1" }),
+          expect.objectContaining({ name: "variables.0.id" }),
+          expect.objectContaining({ name: "variables.0.name" }),
+          expect.objectContaining({
+            name: "hiddenFields.fieldIds.1",
+            code: "duplicate_identifier",
+            identifier: "satisfaction",
+            referenceType: "hiddenField",
+            conflictsWith: "blocks.0.elements.0.id",
+          }),
+        ])
+      );
+    }
+  });
+
+  test("reports dangling logic references with actionable paths", () => {
+    const survey = {
+      ...validSurvey,
+      blocks: [
+        {
+          ...validSurvey.blocks[0],
+          logicFallback: "clmiss12345678901234567890",
+          logic: [
+            {
+              ...validSurvey.blocks[0].logic![0],
+              actions: [
+                {
+                  ...validSurvey.blocks[0].logic![0].actions[0],
+                  variableId: "clmiss12345678901234567890",
+                },
+                {
+                  id: "cljmp123456789012345678901",
+                  objective: "jumpToBlock" as const,
+                  target: "clmiss12345678901234567890",
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = validateV3SurveyReferences({
+      blocks: survey.blocks,
+      endings: survey.endings,
+      hiddenFields: survey.hiddenFields,
+      variables: survey.variables,
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.invalidParams).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ name: "blocks.0.logicFallback" }),
+          expect.objectContaining({ name: "blocks.0.logic.0.actions.0.variableId" }),
+          expect.objectContaining({ name: "blocks.0.logic.0.actions.1.target" }),
+          expect.objectContaining({
+            name: "blocks.0.logic.0.actions.0.variableId",
+            code: "dangling_reference",
+            missingId: "clmiss12345678901234567890",
+            referenceType: "variable",
+          }),
+        ])
+      );
+    }
+  });
+
+  test("rejects logicFallback without logic before persistence", () => {
+    const survey = {
+      ...validSurvey,
+      blocks: [
+        {
+          ...validSurvey.blocks[0],
+          logic: undefined,
+          logicFallback: validSurvey.endings[0].id,
+        },
+      ],
+    };
+
+    const result = validateV3SurveyReferences({
+      blocks: survey.blocks,
+      endings: survey.endings,
+      hiddenFields: survey.hiddenFields,
+      variables: survey.variables,
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.invalidParams).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "blocks.0.logicFallback",
+            code: "invalid_reference",
+            reason:
+              "logicFallback requires at least one logic rule on the same block; omit logicFallback for normal sequential flow or add blocks[].logic",
+            referenceType: "ending",
+          }),
+        ])
+      );
+    }
+  });
+
+  test("rejects logicFallback targeting the same block", () => {
+    const survey = {
+      ...validSurvey,
+      blocks: [
+        {
+          ...validSurvey.blocks[0],
+          logicFallback: validSurvey.blocks[0].id,
+        },
+      ],
+    };
+
+    const result = validateV3SurveyReferences({
+      blocks: survey.blocks,
+      endings: survey.endings,
+      hiddenFields: survey.hiddenFields,
+      variables: survey.variables,
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.invalidParams).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "blocks.0.logicFallback",
+            code: "invalid_reference",
+            reason: "logicFallback cannot target the same block",
+          }),
+        ])
+      );
+    }
+  });
+
+  test("reports dangling recall references with actionable paths", () => {
+    const survey = {
+      ...validSurvey,
+      blocks: [
+        {
+          ...validSurvey.blocks[0],
+          elements: [
+            {
+              ...validSurvey.blocks[0].elements[0],
+              headline: {
+                default: "Please explain #recall:missing_id/fallback:your answer#",
+              },
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = validateV3SurveyReferences({
+      blocks: survey.blocks,
+      endings: survey.endings,
+      hiddenFields: survey.hiddenFields,
+      variables: survey.variables,
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.invalidParams).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "blocks.0.elements.0.headline.default",
+            reason: expect.stringContaining("missing_id"),
+            code: "dangling_reference",
+            missingId: "missing_id",
+            referenceType: "recall",
+          }),
+        ])
+      );
+    }
+  });
+
+  test("reports dangling recall references in survey-level translatable fields", () => {
+    const result = validateV3SurveyReferences({
+      blocks: validSurvey.blocks,
+      endings: validSurvey.endings,
+      hiddenFields: validSurvey.hiddenFields,
+      metadata: {
+        title: {
+          default: "Metadata #recall:missing_metadata_reference/fallback:value#",
+        },
+      },
+      variables: validSurvey.variables,
+      welcomeCard: {
+        enabled: true,
+        headline: {
+          default: "Welcome #recall:missing_welcome_reference/fallback:there#",
+        },
+      },
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.invalidParams).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "welcomeCard.headline.default",
+            reason: expect.stringContaining("missing_welcome_reference"),
+          }),
+          expect.objectContaining({
+            name: "metadata.title.default",
+            reason: expect.stringContaining("missing_metadata_reference"),
+          }),
+        ])
+      );
+    }
+  });
+
+  test("ignores recall-like strings in arbitrary metadata values", () => {
+    const result = validateV3SurveyReferences({
+      blocks: validSurvey.blocks,
+      endings: validSurvey.endings,
+      hiddenFields: validSurvey.hiddenFields,
+      metadata: {
+        cx_operation: "Enterprise #recall:external_context/fallback:context#",
+      },
+      variables: validSurvey.variables,
+    });
+
+    expect(result).toEqual({ ok: true, invalidParams: [] });
+  });
+});

apps/web/app/api/v3/surveys/reference-validation.ts

@@ -0,0 +1,427 @@
+import type { TSurveyBlocks } from "@formbricks/types/surveys/blocks";
+import type { TConditionGroup, TDynamicLogicFieldValue } from "@formbricks/types/surveys/logic";
+import type { TSurveyEndings, TSurveyHiddenFields, TSurveyVariables } from "@formbricks/types/surveys/types";
+import type { InvalidParam } from "@/app/api/v3/lib/response";
+
+type TReferenceValidationInput = {
+  blocks: TSurveyBlocks;
+  endings: TSurveyEndings;
+  hiddenFields: TSurveyHiddenFields;
+  metadata?: unknown;
+  variables: TSurveyVariables;
+  welcomeCard?: unknown;
+};
+
+type TNamedReference = {
+  id: string;
+  path: string;
+  namespace: "block" | "element" | "ending" | "hiddenField" | "variable" | "variableName";
+};
+
+type TReferenceLookup = {
+  elementIds: Set<string>;
+  variableIds: Set<string>;
+  hiddenFieldIds: Set<string>;
+};
+
+export class V3SurveyReferenceValidationError extends Error {
+  invalidParams: InvalidParam[];
+
+  constructor(invalidParams: InvalidParam[]) {
+    super("Survey contains invalid references");
+    this.name = "V3SurveyReferenceValidationError";
+    this.invalidParams = invalidParams;
+  }
+}
+
+export type TV3SurveyReferenceValidationResult =
+  | { ok: true; invalidParams: [] }
+  | { ok: false; invalidParams: InvalidParam[] };
+
+function addDuplicateIdIssues(
+  entries: { id: string; path: string }[],
+  label: string,
+  referenceType: NonNullable<InvalidParam["referenceType"]>,
+  issues: InvalidParam[]
+): void {
+  const firstPathById = new Map<string, string>();
+
+  entries.forEach(({ id, path }) => {
+    const firstPath = firstPathById.get(id);
+    if (firstPath !== undefined) {
+      issues.push({
+        name: path,
+        reason: `${label} id '${id}' is duplicated; first used at ${firstPath}`,
+        code: "duplicate_identifier",
+        identifier: id,
+        referenceType,
+        firstUsedAt: firstPath,
+      });
+      return;
+    }
+
+    firstPathById.set(id, path);
+  });
+}
+
+function addDuplicateValueIssues(
+  values: string[],
+  pathForIndex: (index: number) => string,
+  label: string,
+  referenceType: NonNullable<InvalidParam["referenceType"]>,
+  issues: InvalidParam[]
+): void {
+  const firstIndexByValue = new Map<string, number>();
+
+  values.forEach((value, index) => {
+    const firstIndex = firstIndexByValue.get(value);
+    if (firstIndex !== undefined) {
+      issues.push({
+        name: pathForIndex(index),
+        reason: `${label} '${value}' is duplicated; first used at ${pathForIndex(firstIndex)}`,
+        code: "duplicate_identifier",
+        identifier: value,
+        referenceType,
+        firstUsedAt: pathForIndex(firstIndex),
+      });
+      return;
+    }
+
+    firstIndexByValue.set(value, index);
+  });
+}
+
+function addCrossNamespaceCollisionIssues(entries: TNamedReference[], issues: InvalidParam[]): void {
+  const firstEntryById = new Map<string, TNamedReference>();
+
+  entries.forEach((entry) => {
+    const lookupId = entry.id.toLowerCase();
+    const firstEntry = firstEntryById.get(lookupId);
+
+    if (!firstEntry) {
+      firstEntryById.set(lookupId, entry);
+      return;
+    }
+
+    if (firstEntry.namespace === entry.namespace) {
+      return;
+    }
+
+    issues.push({
+      name: entry.path,
+      reason: `${entry.namespace} identifier '${entry.id}' conflicts with ${firstEntry.namespace} identifier at ${firstEntry.path}`,
+      code: "duplicate_identifier",
+      identifier: entry.id,
+      referenceType: entry.namespace,
+      conflictsWith: firstEntry.path,
+    });
+  });
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function addRecallReferenceIssues(
+  value: unknown,
+  path: string,
+  references: TReferenceLookup,
+  issues: InvalidParam[]
+): void {
+  if (typeof value === "string") {
+    const recallPattern = /#recall:([A-Za-z0-9_-]+)/g;
+
+    for (const match of value.matchAll(recallPattern)) {
+      const recallId = match[1];
+      const isKnownReference =
+        references.elementIds.has(recallId) ||
+        references.variableIds.has(recallId) ||
+        references.hiddenFieldIds.has(recallId);
+
+      if (!isKnownReference) {
+        issues.push({
+          name: path,
+          reason: `Recall reference '${recallId}' is not defined in blocks, variables, or hiddenFields.fieldIds`,
+          code: "dangling_reference",
+          identifier: recallId,
+          referenceType: "recall",
+          missingId: recallId,
+        });
+      }
+    }
+
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => addRecallReferenceIssues(entry, `${path}.${index}`, references, issues));
+    return;
+  }
+
+  if (!isPlainObject(value)) {
+    return;
+  }
+
+  Object.entries(value).forEach(([key, entry]) => {
+    addRecallReferenceIssues(entry, path ? `${path}.${key}` : key, references, issues);
+  });
+}
+
+function addMetadataRecallReferenceIssues(
+  metadata: unknown,
+  references: TReferenceLookup,
+  issues: InvalidParam[]
+): void {
+  if (!isPlainObject(metadata)) {
+    return;
+  }
+
+  addRecallReferenceIssues(metadata.title, "metadata.title", references, issues);
+  addRecallReferenceIssues(metadata.description, "metadata.description", references, issues);
+}
+
+function validateDynamicOperand(
+  operand: TDynamicLogicFieldValue,
+  path: string,
+  references: TReferenceLookup,
+  issues: InvalidParam[]
+): void {
+  if (operand.type === "element" && !references.elementIds.has(operand.value)) {
+    issues.push({
+      name: `${path}.value`,
+      reason: `Element id '${operand.value}' is not defined in blocks`,
+      code: "dangling_reference",
+      identifier: operand.value,
+      referenceType: "element",
+      missingId: operand.value,
+    });
+  }
+
+  if (operand.type === "variable" && !references.variableIds.has(operand.value)) {
+    issues.push({
+      name: `${path}.value`,
+      reason: `Variable id '${operand.value}' is not defined in variables`,
+      code: "dangling_reference",
+      identifier: operand.value,
+      referenceType: "variable",
+      missingId: operand.value,
+    });
+  }
+
+  if (operand.type === "hiddenField" && !references.hiddenFieldIds.has(operand.value)) {
+    issues.push({
+      name: `${path}.value`,
+      reason: `Hidden field id '${operand.value}' is not defined in hiddenFields.fieldIds`,
+      code: "dangling_reference",
+      identifier: operand.value,
+      referenceType: "hiddenField",
+      missingId: operand.value,
+    });
+  }
+}
+
+function validateConditionGroup(
+  conditionGroup: TConditionGroup,
+  path: string,
+  references: TReferenceLookup,
+  issues: InvalidParam[]
+): void {
+  conditionGroup.conditions.forEach((condition, index) => {
+    const conditionPath = `${path}.conditions.${index}`;
+
+    if ("conditions" in condition) {
+      validateConditionGroup(condition, conditionPath, references, issues);
+      return;
+    }
+
+    validateDynamicOperand(condition.leftOperand, `${conditionPath}.leftOperand`, references, issues);
+
+    if (condition.rightOperand?.type && condition.rightOperand.type !== "static") {
+      validateDynamicOperand(condition.rightOperand, `${conditionPath}.rightOperand`, references, issues);
+    }
+  });
+}
+
+export function getV3SurveyReferenceInvalidParams(input: TReferenceValidationInput): InvalidParam[] {
+  const issues: InvalidParam[] = [];
+  const blockIds = input.blocks.map((block) => block.id);
+  const blockEntries = input.blocks.map((block, index) => ({
+    id: block.id,
+    path: `blocks.${index}.id`,
+  }));
+  const endingIds = input.endings.map((ending) => ending.id);
+  const endingEntries = input.endings.map((ending, index) => ({
+    id: ending.id,
+    path: `endings.${index}.id`,
+  }));
+  const elementEntries = input.blocks.flatMap((block, blockIndex) =>
+    block.elements.map((element, elementIndex) => ({
+      id: element.id,
+      path: `blocks.${blockIndex}.elements.${elementIndex}.id`,
+    }))
+  );
+  const elementIds = elementEntries.map((element) => element.id);
+  const hiddenFieldIds = input.hiddenFields.fieldIds ?? [];
+  const hiddenFieldEntries = hiddenFieldIds.map((id, index) => ({
+    id,
+    path: `hiddenFields.fieldIds.${index}`,
+  }));
+  const variableIds = input.variables.map((variable) => variable.id);
+  const variableIdEntries = variableIds.map((id, index) => ({
+    id,
+    path: `variables.${index}.id`,
+  }));
+  const variableNames = input.variables.map((variable) => variable.name);
+  const variableNameEntries = variableNames.map((id, index) => ({
+    id,
+    path: `variables.${index}.name`,
+  }));
+  const navigationTargetIds = new Set([...blockIds, ...endingIds]);
+  const navigationTargetReferenceTypes = new Map<string, "block" | "ending">([
+    ...blockIds.map((id) => [id, "block"] as const),
+    ...endingIds.map((id) => [id, "ending"] as const),
+  ]);
+  const references = {
+    elementIds: new Set(elementIds),
+    variableIds: new Set(variableIds),
+    hiddenFieldIds: new Set(hiddenFieldIds),
+  };
+
+  addDuplicateIdIssues(blockEntries, "Block", "block", issues);
+  addDuplicateIdIssues(elementEntries, "Element", "element", issues);
+  addDuplicateIdIssues(variableIdEntries, "Variable", "variable", issues);
+  addDuplicateValueIssues(
+    hiddenFieldIds,
+    (index) => `hiddenFields.fieldIds.${index}`,
+    "Hidden field id",
+    "hiddenField",
+    issues
+  );
+  addDuplicateValueIssues(
+    variableNames,
+    (index) => `variables.${index}.name`,
+    "Variable name",
+    "variableName",
+    issues
+  );
+  addCrossNamespaceCollisionIssues(
+    [
+      ...blockEntries.map((entry) => ({ ...entry, namespace: "block" as const })),
+      ...elementEntries.map((entry) => ({ ...entry, namespace: "element" as const })),
+      ...endingEntries.map((entry) => ({ ...entry, namespace: "ending" as const })),
+      ...hiddenFieldEntries.map((entry) => ({ ...entry, namespace: "hiddenField" as const })),
+      ...variableIdEntries.map((entry) => ({ ...entry, namespace: "variable" as const })),
+      ...variableNameEntries.map((entry) => ({ ...entry, namespace: "variableName" as const })),
+    ],
+    issues
+  );
+
+  input.blocks.forEach((block, blockIndex) => {
+    if (block.logicFallback && !block.logic?.length) {
+      issues.push({
+        name: `blocks.${blockIndex}.logicFallback`,
+        reason:
+          "logicFallback requires at least one logic rule on the same block; omit logicFallback for normal sequential flow or add blocks[].logic",
+        code: "invalid_reference",
+        identifier: block.logicFallback,
+        referenceType: navigationTargetReferenceTypes.get(block.logicFallback) ?? "block",
+      });
+    }
+
+    if (block.logicFallback && block.logicFallback === block.id) {
+      issues.push({
+        name: `blocks.${blockIndex}.logicFallback`,
+        reason: "logicFallback cannot target the same block",
+        code: "invalid_reference",
+        identifier: block.logicFallback,
+        referenceType: "block",
+      });
+    }
+
+    if (block.logicFallback && !navigationTargetIds.has(block.logicFallback)) {
+      issues.push({
+        name: `blocks.${blockIndex}.logicFallback`,
+        reason: `Logic fallback target '${block.logicFallback}' is not defined in blocks or endings`,
+        code: "dangling_reference",
+        identifier: block.logicFallback,
+        referenceType: "block",
+        missingId: block.logicFallback,
+      });
+    }
+
+    block.logic?.forEach((logic, logicIndex) => {
+      const logicPath = `blocks.${blockIndex}.logic.${logicIndex}`;
+      validateConditionGroup(logic.conditions, `${logicPath}.conditions`, references, issues);
+
+      logic.actions.forEach((action, actionIndex) => {
+        const actionPath = `${logicPath}.actions.${actionIndex}`;
+
+        if (action.objective === "calculate") {
+          if (!references.variableIds.has(action.variableId)) {
+            issues.push({
+              name: `${actionPath}.variableId`,
+              reason: `Variable id '${action.variableId}' is not defined in variables`,
+              code: "dangling_reference",
+              identifier: action.variableId,
+              referenceType: "variable",
+              missingId: action.variableId,
+            });
+          }
+
+          if (action.value.type !== "static") {
+            validateDynamicOperand(action.value, `${actionPath}.value`, references, issues);
+          }
+        }
+
+        if (action.objective === "requireAnswer" && !references.elementIds.has(action.target)) {
+          issues.push({
+            name: `${actionPath}.target`,
+            reason: `Element id '${action.target}' is not defined in blocks`,
+            code: "dangling_reference",
+            identifier: action.target,
+            referenceType: "element",
+            missingId: action.target,
+          });
+        }
+
+        if (action.objective === "jumpToBlock" && !navigationTargetIds.has(action.target)) {
+          issues.push({
+            name: `${actionPath}.target`,
+            reason: `Jump target '${action.target}' is not defined in blocks or endings`,
+            code: "dangling_reference",
+            identifier: action.target,
+            referenceType: "block",
+            missingId: action.target,
+          });
+        }
+      });
+    });
+  });
+
+  addRecallReferenceIssues(input.blocks, "blocks", references, issues);
+  addRecallReferenceIssues(input.endings, "endings", references, issues);
+  addRecallReferenceIssues(input.welcomeCard, "welcomeCard", references, issues);
+  addMetadataRecallReferenceIssues(input.metadata, references, issues);
+
+  return issues;
+}
+
+export function validateV3SurveyReferences(
+  input: TReferenceValidationInput
+): TV3SurveyReferenceValidationResult {
+  const invalidParams = getV3SurveyReferenceInvalidParams(input);
+
+  if (invalidParams.length > 0) {
+    return { ok: false, invalidParams };
+  }
+
+  return { ok: true, invalidParams: [] };
+}
+
+export function assertValidV3SurveyReferences(input: TReferenceValidationInput): void {
+  const result = validateV3SurveyReferences(input);
+
+  if (!result.ok) {
+    throw new V3SurveyReferenceValidationError(result.invalidParams);
+  }
+}

apps/web/app/api/v3/surveys/route.test.ts

@@ -50,6 +50,10 @@ vi.mock("@/modules/survey/list/lib/survey", async (importOriginal) => {
   };
 });
 
+vi.mock("./create", () => ({
+  createV3Survey: vi.fn(),
+}));
+
 vi.mock("@formbricks/logger", () => ({
   logger: {
     withContext: vi.fn(() => ({

apps/web/app/api/v3/surveys/route.ts

@@ -1,5 +1,5 @@
 /**
- * GET /api/v3/surveys — list surveys for a workspace.
+ * /api/v3/surveys — list and create block-based survey management resources.
  * Session cookie or x-api-key; scope by workspaceId only.
  */
 import { logger } from "@formbricks/logger";
@@ -7,6 +7,7 @@ import { DatabaseError, ResourceNotFoundError } from "@formbricks/types/errors";
 import { withV3ApiWrapper } from "@/app/api/v3/lib/api-wrapper";
 import { requireV3WorkspaceAccess } from "@/app/api/v3/lib/auth";
 import {
+  createdResponse,
   problemBadRequest,
   problemForbidden,
   problemInternalError,
@@ -14,8 +15,15 @@ import {
 } from "@/app/api/v3/lib/response";
 import { getSurveyCount } from "@/modules/survey/list/lib/survey";
 import { getSurveyListPage } from "@/modules/survey/list/lib/survey-page";
+import { V3SurveyCreatePermissionError, createV3Survey } from "./create";
 import { parseV3SurveysListQuery } from "./parse-v3-surveys-list-query";
-import { serializeV3SurveyListItem } from "./serializers";
+import { V3SurveyReferenceValidationError } from "./reference-validation";
+import { ZV3CreateSurveyBody } from "./schemas";
+import {
+  V3SurveyUnsupportedShapeError,
+  serializeV3SurveyListItem,
+  serializeV3SurveyResource,
+} from "./serializers";
 
 export const GET = withV3ApiWrapper({
   auth: "both",
@@ -80,3 +88,81 @@ export const GET = withV3ApiWrapper({
     }
   },
 });
+
+export const POST = withV3ApiWrapper({
+  auth: "both",
+  schemas: {
+    body: ZV3CreateSurveyBody,
+  },
+  action: "created",
+  targetType: "survey",
+  handler: async ({ authentication, auditLog, parsedInput, requestId, instance }) => {
+    const { body } = parsedInput;
+    const log = logger.withContext({ requestId, workspaceId: body.workspaceId });
+
+    try {
+      const authResult = await requireV3WorkspaceAccess(
+        authentication,
+        body.workspaceId,
+        "readWrite",
+        requestId,
+        instance
+      );
+      if (authResult instanceof Response) {
+        return authResult;
+      }
+
+      const survey = await createV3Survey(
+        {
+          ...body,
+          workspaceId: authResult.workspaceId,
+        },
+        authentication,
+        requestId,
+        authResult.organizationId
+      );
+      const resource = serializeV3SurveyResource(survey);
+
+      if (auditLog) {
+        auditLog.organizationId = authResult.organizationId;
+        auditLog.targetId = survey.id;
+        auditLog.newObject = resource;
+      }
+
+      return createdResponse(resource, {
+        requestId,
+        location: `/api/v3/surveys/${survey.id}`,
+      });
+    } catch (err) {
+      if (err instanceof V3SurveyReferenceValidationError) {
+        log.warn({ statusCode: 400, invalidParams: err.invalidParams }, "Survey document validation failed");
+        return problemBadRequest(requestId, "Invalid survey document", {
+          invalid_params: err.invalidParams,
+          instance,
+        });
+      }
+      if (err instanceof V3SurveyUnsupportedShapeError) {
+        log.warn({ statusCode: 400, errorCode: err.name }, "Unsupported survey shape");
+        return problemBadRequest(requestId, err.message, {
+          invalid_params: [{ name: "body", reason: err.message }],
+          instance,
+        });
+      }
+      if (err instanceof V3SurveyCreatePermissionError) {
+        log.warn({ statusCode: 403, errorCode: err.name }, "Survey create permission check failed");
+        return problemForbidden(requestId, err.message, instance);
+      }
+      if (err instanceof ResourceNotFoundError) {
+        log.warn({ statusCode: 403, errorCode: err.name }, "Resource not found");
+        return problemForbidden(requestId, "You are not authorized to access this resource", instance);
+      }
+      if (err instanceof DatabaseError) {
+        log.error({ error: err, statusCode: 500 }, "Database error");
+        return problemInternalError(requestId, "An unexpected error occurred.", instance);
+      }
+
+      log.error({ error: err, statusCode: 500 }, "V3 survey create unexpected error");
+      return problemInternalError(requestId, "An unexpected error occurred.", instance);
+    }
+  },
+});

apps/web/app/api/v3/surveys/schemas.test.ts

@@ -0,0 +1,597 @@
+import { describe, expect, test } from "vitest";
+import {
+  ZV3CreateSurveyBody,
+  ZV3PatchSurveyBody,
+  createZV3PatchSurveyBodySchema,
+  formatV3ZodInvalidParams,
+} from "./schemas";
+
+const validCreateBody = {
+  workspaceId: "clxx1234567890123456789012",
+  name: "Product Feedback",
+  blocks: [
+    {
+      id: "clbk1234567890123456789012",
+      name: "Main Block",
+      elements: [
+        {
+          id: "satisfaction",
+          type: "openText",
+          headline: { "en-US": "What should we improve?" },
+          required: true,
+        },
+      ],
+    },
+  ],
+};
+
+describe("ZV3CreateSurveyBody", () => {
+  test("accepts a valid block-based create body and applies public defaults", () => {
+    const parsed = ZV3CreateSurveyBody.parse(validCreateBody);
+
+    expect(parsed).toMatchObject({
+      workspaceId: validCreateBody.workspaceId,
+      name: "Product Feedback",
+      type: "link",
+      status: "draft",
+      metadata: {},
+      defaultLanguage: "en-US",
+      languages: [],
+      welcomeCard: { enabled: false },
+      endings: [],
+      hiddenFields: { enabled: false },
+      variables: [],
+    });
+    expect(parsed.blocks[0].elements[0]).toMatchObject({
+      headline: { default: "What should we improve?" },
+    });
+  });
+
+  test("generates server-managed block and variable ids on create when omitted", () => {
+    const parsed = ZV3CreateSurveyBody.parse({
+      ...validCreateBody,
+      blocks: [
+        {
+          name: "Generated ID Block",
+          elements: validCreateBody.blocks[0].elements,
+        },
+      ],
+      variables: [
+        {
+          name: "score",
+          type: "number",
+          value: 0,
+        },
+      ],
+    });
+
+    expect(parsed.blocks[0].id).toEqual(expect.any(String));
+    expect(parsed.blocks[0].id.length).toBeGreaterThan(0);
+    expect(parsed.variables[0].id).toEqual(expect.any(String));
+    expect(parsed.variables[0].id.length).toBeGreaterThan(0);
+  });
+
+  test("normalizes locale maps and language codes before shared survey validation", () => {
+    const parsed = ZV3CreateSurveyBody.parse({
+      ...validCreateBody,
+      defaultLanguage: "en_us",
+      languages: [{ code: "de_de" }],
+      welcomeCard: {
+        enabled: true,
+        headline: { en_us: "Welcome", de_de: "Willkommen" },
+      },
+      blocks: [
+        {
+          ...validCreateBody.blocks[0],
+          elements: [
+            {
+              ...validCreateBody.blocks[0].elements[0],
+              headline: { en_us: "Hello", de_de: "Hallo" },
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(parsed.defaultLanguage).toBe("en-US");
+    expect(parsed.languages).toEqual([{ code: "de-DE", enabled: true }]);
+    expect(parsed.welcomeCard).toMatchObject({
+      headline: { default: "Welcome", "de-DE": "Willkommen" },
+    });
+    expect(parsed.blocks[0].elements[0]).toMatchObject({
+      headline: { default: "Hello", "de-DE": "Hallo" },
+    });
+  });
+
+  test("rejects an invalid defaultLanguage instead of silently defaulting", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      defaultLanguage: "not a locale",
+    });
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(formatV3ZodInvalidParams(result.error, "body")).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "defaultLanguage",
+            reason: "Language 'not a locale' is not a valid locale code",
+            code: "invalid_locale",
+          }),
+        ])
+      );
+    }
+  });
+
+  test("rejects duplicate locale keys after normalization", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      blocks: [
+        {
+          ...validCreateBody.blocks[0],
+          elements: [
+            {
+              ...validCreateBody.blocks[0].elements[0],
+              headline: { "en-US": "Hello", en_us: "Duplicate" },
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(formatV3ZodInvalidParams(result.error, "body")).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "blocks.0.elements.0.headline.en_us",
+            reason: "Language key 'en_us' duplicates 'en-US' after locale normalization",
+            code: "duplicate_locale",
+          }),
+        ])
+      );
+    }
+  });
+
+  test("rejects unsupported top-level fields instead of silently ignoring them", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      questions: [],
+      styling: {},
+      createdBy: "user_1",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues.map((issue) => issue.path.join("."))).toEqual(
+      expect.arrayContaining(["questions", "styling", "createdBy"])
+    );
+  });
+
+  test("rejects unsupported nested fields instead of stripping them", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      blocks: [
+        {
+          ...validCreateBody.blocks[0],
+          targeting: {},
+          elements: [
+            {
+              ...validCreateBody.blocks[0].elements[0],
+              analytics: {},
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues.map((issue) => issue.path.join("."))).toEqual(
+      expect.arrayContaining(["blocks.0.targeting", "blocks.0.elements.0.analytics"])
+    );
+  });
+
+  test("rejects element fields that do not belong to the selected element type", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      blocks: [
+        {
+          ...validCreateBody.blocks[0],
+          elements: [
+            {
+              ...validCreateBody.blocks[0].elements[0],
+              buttonUrl: "https://example.com",
+              scale: "star",
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues.map((issue) => issue.path.join("."))).toContain(
+      "blocks.0.elements.0.buttonUrl"
+    );
+    expect(result.error?.issues.map((issue) => issue.path.join("."))).toContain("blocks.0.elements.0.scale");
+    expect(
+      result.error?.issues.find((issue) => issue.path.join(".") === "blocks.0.elements.0.buttonUrl")
+    ).toMatchObject({
+      message: expect.stringContaining("element type 'openText'"),
+    });
+  });
+
+  test("rejects choice fields that do not belong to the selected element type", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      blocks: [
+        {
+          ...validCreateBody.blocks[0],
+          elements: [
+            {
+              id: "choices",
+              type: "multipleChoiceSingle",
+              headline: { "en-US": "Pick one" },
+              required: true,
+              choices: [
+                { id: "choice_1", label: { "en-US": "A" }, imageUrl: "https://example.com/a.png" },
+                { id: "choice_2", label: { "en-US": "B" } },
+              ],
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues.map((issue) => issue.path.join("."))).toContain(
+      "blocks.0.elements.0.choices.0.imageUrl"
+    );
+    expect(
+      result.error?.issues.find((issue) => issue.path.join(".") === "blocks.0.elements.0.choices.0.imageUrl")
+    ).toMatchObject({
+      message: expect.stringContaining("Allowed fields: id, label"),
+    });
+  });
+
+  test("does not rewrite locale-shaped objects in logic metadata", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      blocks: [
+        {
+          ...validCreateBody.blocks[0],
+          elements: [
+            {
+              ...validCreateBody.blocks[0].elements[0],
+            },
+          ],
+          logic: [
+            {
+              id: "cllog123456789012345678901",
+              conditions: {
+                id: "clgrp123456789012345678901",
+                connector: "and",
+                conditions: [
+                  {
+                    id: "clcon123456789012345678901",
+                    leftOperand: {
+                      type: "element",
+                      value: "satisfaction",
+                      meta: { "en-US": "metadata" },
+                    },
+                    operator: "isSubmitted",
+                  },
+                ],
+              },
+              actions: [
+                {
+                  id: "clact123456789012345678901",
+                  objective: "requireAnswer",
+                  target: "satisfaction",
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(result.success).toBe(true);
+    if (!result.success) {
+      throw new Error("Expected schema validation to pass");
+    }
+    expect(result.data.blocks[0].logic?.[0].conditions.conditions[0]).toMatchObject({
+      leftOperand: {
+        meta: { "en-US": "metadata" },
+      },
+    });
+  });
+
+  test("rejects the internal default translation key in public v3 input", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      blocks: [
+        {
+          ...validCreateBody.blocks[0],
+          elements: [
+            {
+              ...validCreateBody.blocks[0].elements[0],
+              headline: { default: "Internal key should not be public" },
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues[0].path.join(".")).toBe("blocks.0.elements.0.headline.default");
+  });
+
+  test("preserves arbitrary metadata while normalizing known translatable metadata fields", () => {
+    const parsed = ZV3CreateSurveyBody.parse({
+      ...validCreateBody,
+      metadata: {
+        cx_context: {
+          "de-DE": "This is arbitrary customer metadata, not translation content",
+        },
+        title: {
+          "en-US": "Feedback Survey",
+          "de-DE": "Feedback-Umfrage",
+        },
+      },
+    });
+
+    expect(parsed.metadata).toMatchObject({
+      cx_context: {
+        "de-DE": "This is arbitrary customer metadata, not translation content",
+      },
+      title: {
+        default: "Feedback Survey",
+        "de-DE": "Feedback-Umfrage",
+      },
+    });
+  });
+
+  test("rejects non-link survey types for this survey-template endpoint", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      type: "app",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues[0].path).toEqual(["type"]);
+  });
+
+  test("rejects malformed locale maps that do not include the default language", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      blocks: [
+        {
+          ...validCreateBody.blocks[0],
+          elements: [
+            {
+              ...validCreateBody.blocks[0].elements[0],
+              headline: { "not a locale": "Hello" },
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(formatV3ZodInvalidParams(result.error, "body")).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "blocks.0.elements.0.headline.not a locale",
+            reason: "Language key 'not a locale' is not a valid locale code",
+            code: "invalid_locale",
+          }),
+        ])
+      );
+    }
+  });
+
+  test("reports missing required element fields before shared element union errors", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      blocks: [
+        {
+          ...validCreateBody.blocks[0],
+          elements: [
+            {
+              id: "feedback",
+              type: "openText",
+              headline: { "en-US": "Tell us more" },
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(formatV3ZodInvalidParams(result.error, "body")).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "blocks.0.elements.0.required",
+            reason: "Missing required field 'required' for element type 'openText'",
+            code: "missing_required_field",
+          }),
+        ])
+      );
+    }
+  });
+
+  test("reports missing required ending fields before shared ending union errors", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      endings: [
+        {
+          type: "endScreen",
+          headline: { "en-US": "Thanks!" },
+        },
+      ],
+    });
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(formatV3ZodInvalidParams(result.error, "body")).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "endings.0.id",
+            reason: "Missing required field 'id' for ending type 'endScreen'",
+            code: "missing_required_field",
+          }),
+        ])
+      );
+    }
+  });
+
+  test("reports missing ending type with a precise invalid param path", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      endings: [
+        {
+          id: "clend123456789012345678901",
+          headline: { "en-US": "Thanks!" },
+        },
+      ],
+    });
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(formatV3ZodInvalidParams(result.error, "body")).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "endings.0.type",
+            reason: "Missing required field 'type' for survey ending",
+            code: "missing_required_field",
+          }),
+        ])
+      );
+    }
+  });
+
+  test("rejects duplicate language entries and disabled default language", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      languages: [{ code: "en-US", enabled: false }, { code: "en_us" }],
+    });
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(formatV3ZodInvalidParams(result.error, "body")).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "languages.0.enabled",
+            reason: "The default language cannot be disabled",
+          }),
+          expect.objectContaining({
+            name: "languages.1.code",
+            reason: "Language 'en-US' is duplicated",
+            code: "duplicate_locale",
+          }),
+        ])
+      );
+    }
+  });
+
+  test("reports invalid language entries with machine-readable locale metadata", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      languages: [{ code: "de", enabled: true }],
+    });
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(formatV3ZodInvalidParams(result.error, "body")).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "languages.0.code",
+            reason: "Language 'de' is not a valid locale code",
+            code: "invalid_locale",
+          }),
+        ])
+      );
+    }
+  });
+});
+
+describe("ZV3PatchSurveyBody", () => {
+  test("accepts a strict top-level partial and preserves omitted defaults", () => {
+    const parsed = ZV3PatchSurveyBody.parse({
+      name: "Updated survey",
+    });
+
+    expect(parsed).toEqual({ name: "Updated survey" });
+  });
+
+  test("rejects an empty patch body", () => {
+    const result = ZV3PatchSurveyBody.safeParse({});
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues[0]).toMatchObject({
+      message: "Request body must include at least one updatable field",
+    });
+  });
+
+  test("rejects immutable and out-of-scope fields", () => {
+    const result = ZV3PatchSurveyBody.safeParse({
+      id: "clsv1234567890123456789012",
+      workspaceId: "clxx1234567890123456789012",
+      type: "link",
+      questions: [],
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues.map((issue) => issue.path.join("."))).toEqual(
+      expect.arrayContaining(["id", "workspaceId", "type", "questions"])
+    );
+  });
+
+  test("normalizes patch translation maps using the current default language", () => {
+    const parsed = createZV3PatchSurveyBodySchema("de-DE").parse({
+      blocks: [
+        {
+          id: "clbk1234567890123456789012",
+          name: "Main Block",
+          elements: [
+            {
+              id: "satisfaction",
+              type: "openText",
+              headline: { de_de: "Hallo", en_us: "Hello" },
+              required: true,
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(parsed.blocks?.[0].elements[0]).toMatchObject({
+      headline: { default: "Hallo", "en-US": "Hello" },
+    });
+    expect(parsed).not.toHaveProperty("defaultLanguage");
+  });
+
+  test("does not generate missing ids for canonical patch documents", () => {
+    const result = ZV3PatchSurveyBody.safeParse({
+      blocks: [
+        {
+          name: "Missing ID Block",
+          elements: validCreateBody.blocks[0].elements,
+        },
+      ],
+      variables: [
+        {
+          name: "score",
+          type: "number",
+          value: 0,
+        },
+      ],
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues.map((issue) => issue.path.join("."))).toEqual(
+      expect.arrayContaining(["blocks.0.id", "variables.0.id"])
+    );
+  });
+});

apps/web/app/api/v3/surveys/serializers.test.ts

@@ -14,7 +14,11 @@ const baseSurvey = {
   name: "Product Feedback",
   type: "link",
   status: "draft",
-  metadata: { cx: "enterprise" },
+  metadata: {
+    cx: "enterprise",
+    arbitraryConfig: { default: "preserve-me", mode: "strict" },
+    title: { default: "Product Feedback", "de-DE": "Produktfeedback" },
+  },
   languages: [
     {
       default: true,
@@ -68,6 +72,16 @@ describe("serializeV3SurveyResource", () => {
       { code: "de-DE", default: false, enabled: true },
       { code: "fr-FR", default: false, enabled: false },
     ]);
+    expect(resource).toMatchObject({
+      metadata: {
+        cx: "enterprise",
+        arbitraryConfig: { default: "preserve-me", mode: "strict" },
+        title: {
+          "en-US": "Product Feedback",
+          "de-DE": "Produktfeedback",
+        },
+      },
+    });
     expect(resource).toMatchObject({
       welcomeCard: {
         headline: {

apps/web/app/api/v3/surveys/serializers.ts

@@ -1,16 +1,16 @@
 import type { TSurvey as TInternalSurvey } from "@formbricks/types/surveys/types";
 import type { TSurvey as TSurveyListRecord } from "@/modules/survey/list/types/surveys";
-import { normalizeV3SurveyLanguageTag, resolveV3SurveyLanguageCode } from "./language";
+import {
+  type TV3SurveyLanguage,
+  getV3SurveyDefaultLanguage,
+  getV3SurveyLanguages,
+  normalizeV3SurveyLanguageTag,
+  resolveV3SurveyLanguageCode,
+} from "./language";
 
 export type TV3SurveyListItem = Omit<TSurveyListRecord, "singleUse">;
 const DEFAULT_V3_SURVEY_LANGUAGE = "en-US";
 
-type TV3SurveyLanguage = {
-  code: string;
-  default: boolean;
-  enabled: boolean;
-};
-
 type TSerializedValue =
   | string
   | number
@@ -50,28 +50,6 @@ function toIsoString(value: Date | string): string {
   return value instanceof Date ? value.toISOString() : new Date(value).toISOString();
 }
 
-function getSurveyLanguages(survey: TInternalSurvey): TV3SurveyLanguage[] {
-  const languages = (survey.languages ?? []).map((surveyLanguage) => ({
-    code: normalizeV3SurveyLanguageTag(surveyLanguage.language.code) ?? surveyLanguage.language.code,
-    default: surveyLanguage.default,
-    enabled: surveyLanguage.enabled,
-  }));
-
-  if (languages.length === 0) {
-    return [{ code: DEFAULT_V3_SURVEY_LANGUAGE, default: true, enabled: true }];
-  }
-
-  return languages;
-}
-
-function getDefaultLanguage(survey: TInternalSurvey): string {
-  const defaultLanguageCode = survey.languages?.find((surveyLanguage) => surveyLanguage.default)?.language
-    .code;
-  return defaultLanguageCode
-    ? (normalizeV3SurveyLanguageTag(defaultLanguageCode) ?? defaultLanguageCode)
-    : DEFAULT_V3_SURVEY_LANGUAGE;
-}
-
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -140,6 +118,34 @@ function serializeCanonicalValue(
   return value as TSerializedValue;
 }
 
+function serializeMetadata(
+  metadata: unknown,
+  defaultLanguage: string,
+  languageCodes: Set<string>,
+  options?: { fallbackMissingTranslations?: boolean }
+): TSerializedValue {
+  if (!isPlainObject(metadata)) {
+    return metadata as TSerializedValue;
+  }
+
+  const serializedMetadata: Record<string, TSerializedValue> = { ...metadata } as Record<
+    string,
+    TSerializedValue
+  >;
+  for (const key of ["title", "description"]) {
+    if (metadata[key] !== undefined) {
+      serializedMetadata[key] = serializeCanonicalValue(
+        metadata[key],
+        defaultLanguage,
+        languageCodes,
+        options
+      );
+    }
+  }
+
+  return serializedMetadata;
+}
+
 function resolveRequestedLanguage(languages: TV3SurveyLanguage[], language: string): string {
   const result = resolveV3SurveyLanguageCode(language, languages);
 
@@ -165,8 +171,8 @@ export function serializeV3SurveyResource(survey: TInternalSurvey, options?: { l
     );
   }
 
-  const defaultLanguage = getDefaultLanguage(survey);
-  const languages = getSurveyLanguages(survey);
+  const defaultLanguage = getV3SurveyDefaultLanguage(survey, DEFAULT_V3_SURVEY_LANGUAGE);
+  const languages = getV3SurveyLanguages(survey, DEFAULT_V3_SURVEY_LANGUAGE);
   const configuredLanguageCodes = new Set(languages.map((language) => language.code));
   const requestedLanguages = resolveRequestedLanguages(languages, options?.lang);
   const languageCodes = requestedLanguages.length > 0 ? new Set(requestedLanguages) : configuredLanguageCodes;
@@ -183,7 +189,9 @@ export function serializeV3SurveyResource(survey: TInternalSurvey, options?: { l
     name: survey.name,
     type: survey.type,
     status: survey.status,
-    metadata: survey.metadata,
+    metadata: serializeMetadata(survey.metadata, defaultLanguage, languageCodes, {
+      fallbackMissingTranslations: requestedLanguages.length > 0,
+    }),
     defaultLanguage,
     languages,
     welcomeCard: serializeValue(survey.welcomeCard),

apps/web/app/api/v3/surveys/validate/route.ts

@@ -0,0 +1,108 @@
+import { z } from "zod";
+import { logger } from "@formbricks/logger";
+import { DatabaseError } from "@formbricks/types/errors";
+import { withV3ApiWrapper } from "@/app/api/v3/lib/api-wrapper";
+import { requireV3WorkspaceAccess } from "@/app/api/v3/lib/auth";
+import { problemInternalError, successResponse } from "@/app/api/v3/lib/response";
+import { getAuthorizedV3Survey } from "../authorization";
+import {
+  type TV3SurveyPrepareResult,
+  prepareV3SurveyCreateInput,
+  prepareV3SurveyPatchInput,
+} from "../prepare";
+import { type TV3SurveyDocument, ZV3EmptyQuery, ZV3SurveyValidationRequestBody } from "../schemas";
+
+const createWorkspaceSchema = z.object({
+  workspaceId: z.cuid2(),
+});
+
+function serializeValidationResult<TDocument extends TV3SurveyDocument>(
+  operation: "create" | "patch",
+  preparation: TV3SurveyPrepareResult<TDocument>
+) {
+  if (!preparation.ok) {
+    return {
+      valid: false,
+      operation,
+      invalid_params: preparation.validation.invalidParams,
+    };
+  }
+
+  return {
+    valid: true,
+    operation,
+    invalid_params: [],
+    languages: preparation.languageRequests.map((languageRequest) => ({
+      ...languageRequest,
+      writeBehavior: "connect_or_create" as const,
+    })),
+  };
+}
+
+export const POST = withV3ApiWrapper({
+  auth: "both",
+  schemas: {
+    body: ZV3SurveyValidationRequestBody,
+    query: ZV3EmptyQuery,
+  },
+  handler: async ({ parsedInput, authentication, requestId, instance }) => {
+    const { body } = parsedInput;
+    const log = logger.withContext({ requestId, operation: body.operation });
+
+    try {
+      if (body.operation === "create") {
+        const workspaceResult = createWorkspaceSchema.safeParse(body.data);
+        if (workspaceResult.success) {
+          const authResult = await requireV3WorkspaceAccess(
+            authentication,
+            workspaceResult.data.workspaceId,
+            "readWrite",
+            requestId,
+            instance
+          );
+
+          if (authResult instanceof Response) {
+            return authResult;
+          }
+        }
+
+        return successResponse(serializeValidationResult("create", prepareV3SurveyCreateInput(body.data)), {
+          requestId,
+          cache: "private, no-store",
+        });
+      }
+
+      const { survey, response } = await getAuthorizedV3Survey({
+        surveyId: body.surveyId,
+        authentication,
+        access: "readWrite",
+        requestId,
+        instance,
+      });
+
+      if (response) {
+        log.warn(
+          { statusCode: response.status, surveyId: body.surveyId },
+          "Survey not found or not accessible"
+        );
+        return response;
+      }
+
+      return successResponse(
+        serializeValidationResult("patch", prepareV3SurveyPatchInput(survey, body.data)),
+        {
+          requestId,
+          cache: "private, no-store",
+        }
+      );
+    } catch (error) {
+      if (error instanceof DatabaseError) {
+        log.error({ error, statusCode: 500 }, "Database error");
+        return problemInternalError(requestId, "An unexpected error occurred.", instance);
+      }
+
+      log.error({ error, statusCode: 500 }, "V3 survey validation unexpected error");
+      return problemInternalError(requestId, "An unexpected error occurred.", instance);
+    }
+  },
+});

apps/web/app/api/v3/surveys/validation.ts

@@ -0,0 +1,145 @@
+import type { InvalidParam } from "@/app/api/v3/lib/response";
+import { validateV3SurveyReferences } from "./reference-validation";
+import type { TV3SurveyDocument } from "./schemas";
+
+export type TV3SurveyDocumentValidationResult =
+  | { valid: true; invalidParams: [] }
+  | { valid: false; invalidParams: InvalidParam[] };
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isInternalI18nString(value: unknown): value is Record<string, string> {
+  return (
+    isPlainObject(value) &&
+    typeof value.default === "string" &&
+    Object.values(value).every((entry) => typeof entry === "string")
+  );
+}
+
+function getConfiguredTranslationLanguageCodes(document: TV3SurveyDocument): string[] {
+  const defaultLanguage = document.defaultLanguage.toLowerCase();
+  const languageCodes = new Set<string>();
+
+  document.languages.forEach((language) => {
+    const code = language.code;
+    if (code.toLowerCase() !== defaultLanguage) {
+      languageCodes.add(code);
+    }
+  });
+
+  return Array.from(languageCodes.values());
+}
+
+function collectTranslationLanguageCodes(value: unknown, languageCodes: Set<string>): void {
+  if (Array.isArray(value)) {
+    value.forEach((entry) => collectTranslationLanguageCodes(entry, languageCodes));
+    return;
+  }
+
+  if (!isPlainObject(value)) {
+    return;
+  }
+
+  if (isInternalI18nString(value)) {
+    Object.keys(value).forEach((languageCode) => {
+      if (languageCode !== "default") {
+        languageCodes.add(languageCode);
+      }
+    });
+    return;
+  }
+
+  Object.values(value).forEach((entry) => collectTranslationLanguageCodes(entry, languageCodes));
+}
+
+function getRequiredTranslationLanguageCodes(document: TV3SurveyDocument): string[] {
+  const languageCodes = new Set(getConfiguredTranslationLanguageCodes(document));
+
+  collectTranslationLanguageCodes(document.welcomeCard, languageCodes);
+  collectTranslationLanguageCodes(document.blocks, languageCodes);
+  collectTranslationLanguageCodes(document.endings, languageCodes);
+
+  return Array.from(languageCodes.values());
+}
+
+function addMissingTranslationIssues(
+  value: unknown,
+  path: string,
+  languageCodes: string[],
+  issues: InvalidParam[]
+): void {
+  if (languageCodes.length === 0) {
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) =>
+      addMissingTranslationIssues(entry, path ? `${path}.${index}` : String(index), languageCodes, issues)
+    );
+    return;
+  }
+
+  if (!isPlainObject(value)) {
+    return;
+  }
+
+  if (isInternalI18nString(value)) {
+    languageCodes.forEach((languageCode) => {
+      if (value[languageCode] === undefined) {
+        issues.push({
+          name: path,
+          reason: `Translatable field is missing configured language '${languageCode}'`,
+          code: "missing_translation",
+          identifier: languageCode,
+          referenceType: "language",
+          missingId: languageCode,
+        });
+      }
+    });
+    return;
+  }
+
+  Object.entries(value).forEach(([key, entry]) =>
+    addMissingTranslationIssues(entry, path ? `${path}.${key}` : key, languageCodes, issues)
+  );
+}
+
+function getV3SurveyLanguageInvalidParams(document: TV3SurveyDocument): InvalidParam[] {
+  const languageCodes = getRequiredTranslationLanguageCodes(document);
+  const issues: InvalidParam[] = [];
+
+  addMissingTranslationIssues(document.welcomeCard, "welcomeCard", languageCodes, issues);
+  addMissingTranslationIssues(document.blocks, "blocks", languageCodes, issues);
+  addMissingTranslationIssues(document.endings, "endings", languageCodes, issues);
+
+  return issues;
+}
+
+export function validateV3SurveyDocument(document: TV3SurveyDocument): TV3SurveyDocumentValidationResult {
+  const languageInvalidParams = getV3SurveyLanguageInvalidParams(document);
+  const invalidParams = [...languageInvalidParams];
+
+  const referenceValidation = validateV3SurveyReferences({
+    blocks: document.blocks,
+    endings: document.endings,
+    hiddenFields: document.hiddenFields,
+    metadata: document.metadata,
+    variables: document.variables,
+    welcomeCard: document.welcomeCard,
+  });
+
+  if (!referenceValidation.ok) {
+    invalidParams.push(...referenceValidation.invalidParams);
+  }
+
+  if (invalidParams.length > 0) {
+    return {
+      valid: false,
+      invalidParams,
+    };
+  }
+
+  return { valid: true, invalidParams: [] };
+}

apps/web/lib/survey/service.test.ts

@@ -733,6 +733,85 @@ describe("Tests for createSurvey", () => {
         })
       );
     });
+
+    test("creates survey languages from validated language inputs", async () => {
+      vi.mocked(getOrganizationByWorkspaceId).mockResolvedValueOnce(mockOrganizationOutput);
+      prisma.survey.create.mockResolvedValueOnce({
+        ...mockSurveyOutput,
+      });
+
+      await createSurvey(mockWorkspaceId, {
+        ...mockCreateSurveyInput,
+        languages: [
+          {
+            default: true,
+            enabled: true,
+            language: {
+              id: "cllang12345678901234567890",
+              code: "en-US",
+              alias: null,
+              workspaceId: mockWorkspaceId,
+              createdAt: new Date(),
+              updatedAt: new Date(),
+            },
+          },
+        ],
+      });
+
+      expect(prisma.survey.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            languages: {
+              create: [
+                {
+                  language: {
+                    connect: {
+                      id: "cllang12345678901234567890",
+                    },
+                  },
+                  default: true,
+                  enabled: true,
+                },
+              ],
+            },
+          }),
+        })
+      );
+    });
+
+    test("preserves an explicitly provided segment relation for existing callers", async () => {
+      vi.mocked(getOrganizationByWorkspaceId).mockResolvedValueOnce(mockOrganizationOutput);
+      prisma.survey.create.mockResolvedValueOnce({
+        ...mockSurveyOutput,
+      });
+
+      await createSurvey(mockWorkspaceId, {
+        ...mockCreateSurveyInput,
+        segment: {
+          id: "clseg123456789012345678901",
+          title: "Segment",
+          description: null,
+          isPrivate: false,
+          filters: [],
+          workspaceId: mockWorkspaceId,
+          surveys: [],
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        },
+      });
+
+      expect(prisma.survey.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            segment: {
+              connect: {
+                id: "clseg123456789012345678901",
+              },
+            },
+          }),
+        })
+      );
+    });
   });
 
   describe("Sad Path", () => {
@@ -745,6 +824,30 @@ describe("Tests for createSurvey", () => {
       );
     });
 
+    test("rejects survey languages from a different workspace", async () => {
+      await expect(
+        createSurvey(mockWorkspaceId, {
+          ...mockCreateSurveyInput,
+          languages: [
+            {
+              default: true,
+              enabled: true,
+              language: {
+                id: "cllang12345678901234567890",
+                code: "en-US",
+                alias: null,
+                workspaceId: "clotherworkspace0000000000",
+                createdAt: new Date(),
+                updatedAt: new Date(),
+              },
+            },
+          ],
+        })
+      ).rejects.toThrow(ResourceNotFoundError);
+
+      expect(prisma.survey.create).not.toHaveBeenCalled();
+    });
+
     test("throws DatabaseError if there is a Prisma error", async () => {
       vi.mocked(getOrganizationByWorkspaceId).mockResolvedValueOnce(mockOrganizationOutput);
       const mockError = new Prisma.PrismaClientKnownRequestError("Database error", {

apps/web/lib/survey/service.ts

@@ -621,6 +621,17 @@ const validateSurveyCreateDataMedia = (
   return data;
 };
 
+const assertSurveyLanguagesBelongToWorkspace = (
+  workspaceId: string,
+  languages: TSurveyCreateInput["languages"]
+): void => {
+  for (const surveyLanguage of languages ?? []) {
+    if (surveyLanguage.language.workspaceId !== workspaceId) {
+      throw new ResourceNotFoundError("Language", surveyLanguage.language.id);
+    }
+  }
+};
+
 export const createSurvey = async (workspaceId: string, surveyBody: TSurveyCreateInput): Promise<TSurvey> => {
   const [parsedWorkspaceId, parsedSurveyBody] = validateInputs(
     [workspaceId, ZId],
@@ -628,9 +639,24 @@ export const createSurvey = async (workspaceId: string, surveyBody: TSurveyCreat
   );
 
   try {
-    const { createdBy, languages, ...restSurveyBody } = parsedSurveyBody;
+    const { createdBy, languages, segment, followUps, ...restSurveyBody } = parsedSurveyBody;
+    assertSurveyLanguagesBelongToWorkspace(parsedWorkspaceId, languages);
     const normalizedCloseOn = restSurveyBody.closeOn instanceof Date ? restSurveyBody.closeOn : null;
     const normalizedPublishOn = restSurveyBody.publishOn instanceof Date ? restSurveyBody.publishOn : null;
+    const surveyLanguagesCreateData: Prisma.SurveyLanguageCreateNestedManyWithoutSurveyInput | undefined =
+      languages?.length
+        ? {
+            create: languages.map((surveyLanguage) => ({
+              language: {
+                connect: {
+                  id: surveyLanguage.language.id,
+                },
+              },
+              default: surveyLanguage.default,
+              enabled: surveyLanguage.enabled,
+            })),
+          }
+        : undefined;
 
     const actionClasses = await getActionClasses(parsedWorkspaceId);
 
@@ -641,18 +667,15 @@ export const createSurvey = async (workspaceId: string, surveyBody: TSurveyCreat
         publishOn: normalizedPublishOn,
         status: restSurveyBody.status ?? "draft",
       }),
-      // @ts-expect-error - languages would be undefined in case of empty array
-      languages: languages?.length ? languages : undefined,
+      languages: surveyLanguagesCreateData,
+      segment: segment?.id ? { connect: { id: segment.id } } : undefined,
       triggers: restSurveyBody.triggers
         ? handleTriggerUpdates(restSurveyBody.triggers, [], actionClasses)
         : undefined,
       attributeFilters: undefined,
     };
     const data = validateSurveyCreateDataMedia(
-      attachSurveyFollowUpsToCreateData(
-        attachSurveyCreatorToCreateData(baseData, createdBy),
-        restSurveyBody.followUps
-      )
+      attachSurveyFollowUpsToCreateData(attachSurveyCreatorToCreateData(baseData, createdBy), followUps)
     );
 
     const organization = await getOrganizationByWorkspaceId(parsedWorkspaceId);

apps/web/lib/utils/validate.test.ts

@@ -27,8 +27,16 @@ describe("validateInputs", () => {
 
     expect(() => validateInputs([123, schema])).toThrow(ValidationError);
     expect(logger.error).toHaveBeenCalledWith(
-      expect.anything(),
-      expect.stringContaining("Validation failed")
+      expect.objectContaining({
+        error: expect.any(z.ZodError),
+        issues: expect.arrayContaining([
+          expect.objectContaining({
+            message: "Invalid input: expected string, received number",
+          }),
+        ]),
+        valuePreview: "123",
+      }),
+      "Input validation failed"
     );
   });
 
@@ -47,8 +55,16 @@ describe("validateInputs", () => {
 
     expect(() => validateInputs(["valid", stringSchema], ["invalid", numberSchema])).toThrow(ValidationError);
     expect(logger.error).toHaveBeenCalledWith(
-      expect.anything(),
-      expect.stringContaining("Validation failed")
+      expect.objectContaining({
+        error: expect.any(z.ZodError),
+        issues: expect.arrayContaining([
+          expect.objectContaining({
+            message: "Invalid input: expected number, received string",
+          }),
+        ]),
+        valuePreview: '"invalid"',
+      }),
+      "Input validation failed"
     );
   });
 });

apps/web/lib/utils/validate.ts

@@ -20,8 +20,12 @@ export function validateInputs<T extends ValidationPair<any>[]>(
         .join("; ");
 
       logger.error(
-        inputValidation.error,
-        `Validation failed for ${JSON.stringify(value).substring(0, 100)} and ${JSON.stringify(schema)}`
+        {
+          error: inputValidation.error,
+          issues: inputValidation.error.issues,
+          valuePreview: JSON.stringify(value).substring(0, 100),
+        },
+        "Input validation failed"
       );
       throw new ValidationError(`Validation failed: ${zodDetails}`);
     }

packages/types/surveys/types.ts

@@ -278,11 +278,13 @@ export const ZSurveyRecaptcha = z
 
 export type TSurveyRecaptcha = z.infer<typeof ZSurveyRecaptcha>;
 
-export const ZSurveyMetadata = z.object({
-  title: ZI18nString.optional(),
-  description: ZI18nString.optional(),
-  ogImage: ZStorageUrl.optional(),
-});
+export const ZSurveyMetadata = z
+  .object({
+    title: ZI18nString.optional(),
+    description: ZI18nString.optional(),
+    ogImage: ZStorageUrl.optional(),
+  })
+  .catchall(z.unknown());
 
 export type TSurveyMetadata = z.infer<typeof ZSurveyMetadata>;