> ## Documentation Index > Fetch the complete documentation index at: https://docs.onlyform.com/llms.txt > Use this file to discover all available pages before exploring further. # List form blocks > Returns the complete ordered top-level block collection. Requires forms:read. ## OpenAPI ````yaml /openapi.json get /v1/forms/{formId}/blocks openapi: 3.1.0 info: title: Onlyform Public API version: '2026-08-01' summary: >- Programmatic access to Onlyform workspaces, forms, submissions, analytics, and webhooks. description: >- The Onlyform Public API uses stable resource IDs, cursor pagination, scoped API keys, and structured errors. API keys are created in the Onlyform profile and must be sent in the X-API-Key header. Keys are shown once and cannot be recovered. servers: - url: https://api.onlyform.com description: Production security: - ApiKey: [] tags: - name: Identity description: Inspect the API key owner and effective scopes. - name: Workspaces description: List and manage accessible workspaces. - name: Forms description: Create and manage forms and their block definitions. - name: Submissions description: Read and remove completed form submissions. - name: Analytics description: Read aggregate form funnel metrics. - name: Webhooks description: Manage response-completed webhooks and inspect deliveries. paths: /v1/forms/{formId}/blocks: parameters: - $ref: '#/components/parameters/FormId' get: tags: - Forms summary: List form blocks description: >- Returns the complete ordered top-level block collection. Requires forms:read. operationId: listFormBlocks responses: '200': description: Ordered block collection. headers: ETag: description: Current form revision token. schema: type: string content: application/json: schema: $ref: '#/components/schemas/BlockCollection' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' components: parameters: FormId: name: formId in: path required: true schema: $ref: '#/components/schemas/ObjectId' schemas: BlockCollection: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/Block' ObjectId: type: string pattern: ^[0-9a-fA-F]{24}$ examples: - 507f1f77bcf86cd799439011 Block: type: object required: - id - type - label - description - required - properties properties: id: type: string description: Stable caller-supplied block ID. type: $ref: '#/components/schemas/BlockType' label: type: string description: type: string required: type: boolean part_of: type: string row_id: type: string choices: type: array items: $ref: '#/components/schemas/Choice' children: type: array items: $ref: '#/components/schemas/Block' properties: $ref: '#/components/schemas/BlockProperties' matrix_columns: type: array items: $ref: '#/components/schemas/Choice' matrix_rows: type: array items: $ref: '#/components/schemas/Choice' Error: type: object required: - type - code - message - status - request_id properties: type: type: string code: type: string message: type: string status: type: integer request_id: type: string details: type: array items: $ref: '#/components/schemas/ErrorDetail' BlockType: type: string enum: - welcome - ending - date - file-upload - phone-number - email - website - payment - statement - group - short-text - long-text - ranking - opinion-scale - rating - matrix - number - multiple-choice - picture-choice - yes-no - dropdown - legal - address - contact-info - time - color - currency - slider - gate - signature - coordinates - captcha - video - pdf - text - divider - label - heading-1 - heading-2 - heading-3 - page-break - logic - hidden-field - image - audio - checkboxes Choice: type: object required: - id - label properties: id: type: string label: type: string image: {} color: type: string description: Optional CSS color associated with the choice. row_id: type: string description: Optional row grouping identifier. alt: type: string description: Alternative text for a picture choice. BlockProperties: type: object additionalProperties: true description: >- Type-specific block settings. Unsupported combinations are ignored by the renderer. properties: buttonText: type: string description: Welcome or ending button label. buttonLink: type: string format: uri description: Ending button destination. shareButtons: type: boolean description: Show social sharing actions on a welcome or ending block. maxChars: type: integer minimum: -1 description: Maximum text length; -1 disables the limit. min: type: number description: Minimum numeric value. max: type: number description: Maximum numeric value. minVal: type: boolean description: Enable the minimum numeric bound. maxVal: type: boolean description: Enable the maximum numeric bound. dateFormat: type: string enum: - DDMMYYYY - MMDDYYYY - YYYYMMDD dateSeparator: type: string description: Date separator such as /, -, or . disabledDays: type: integer minimum: 1 maximum: 9 beforeDate: type: string format: date-time afterDate: type: string format: date-time specificDates: type: array items: type: string format: date-time weekStartsOn: type: integer minimum: 1 maximum: 7 quotationMarks: type: boolean description: Wrap a statement in quotation marks. multiSelection: type: boolean description: Allow more than one choice. randomize: type: boolean description: Shuffle choices for each respondent. alphaOrder: type: boolean description: Sort choices alphabetically. defaultCountry: type: string description: ISO 3166-1 alpha-2 default country code. from: type: number description: Start of an opinion scale. to: type: number description: End of an opinion scale. scaleStep: type: number description: Step interval for a scale or slider. limit: type: integer minimum: 1 description: Maximum number of uploaded files. currency: type: string description: ISO 4217 currency code. amount: type: string description: Payment amount represented as a decimal string. paymentGateway: type: string description: Configured payment gateway key, for example stripe. showFields: type: boolean description: Show split date fields. showDatePicker: type: boolean description: Show a date picker. showLabels: type: boolean description: Show picture-choice labels. superSize: type: boolean description: Use the large picture-choice layout. otherOption: type: boolean description: Add an Other choice. otherText: type: string description: Custom label for the Other choice. horizontalAlign: type: boolean description: Lay choices out horizontally. verticalAlign: type: boolean description: Stack choices vertically. perRow: type: integer minimum: 1 imageAlign: type: string enum: - left - center - right altText: type: boolean description: Enable custom alternative text. imageAlt: type: string description: Alternative text for an image block. imageWidth: type: number description: Rendered image width. icon: type: string enum: - star - heart firstLabel: type: string description: Start label for an opinion scale. secondLabel: type: string description: Middle label for an opinion scale. thirdLabel: type: string description: End label for an opinion scale. leftLabel: type: boolean description: Show the left scale label. centerLabel: type: boolean description: Show the center scale label. rightLabel: type: boolean description: Show the right scale label. addressOrContact: type: object additionalProperties: false description: >- Per-part visibility and required state for address and contact-info blocks. properties: firstName: type: object additionalProperties: false properties: hide: type: boolean required: type: boolean lastName: type: object additionalProperties: false properties: hide: type: boolean required: type: boolean email: type: object additionalProperties: false properties: hide: type: boolean required: type: boolean phone: type: object additionalProperties: false properties: hide: type: boolean required: type: boolean company: type: object additionalProperties: false properties: hide: type: boolean required: type: boolean address: type: object additionalProperties: false properties: hide: type: boolean required: type: boolean address2: type: object additionalProperties: false properties: hide: type: boolean required: type: boolean city: type: object additionalProperties: false properties: hide: type: boolean required: type: boolean state: type: object additionalProperties: false properties: hide: type: boolean required: type: boolean zip: type: object additionalProperties: false properties: hide: type: boolean required: type: boolean country: type: object additionalProperties: false properties: hide: type: boolean required: type: boolean legalText: type: string description: Legal copy or linked terms. legalType: type: integer enum: - 1 - 2 description: 1 = URL, 2 = inline text. legalStopFurther: type: boolean description: Prevent submission when consent is rejected. showSeconds: type: boolean description: Include seconds in a time input. showTimePicker: type: boolean description: Show the time picker UI. videoLink: type: string format: uri pdfLink: type: string format: uri embedLink: type: string format: uri captchaType: type: string enum: - turnstile - reCaptcha - hCaptcha placeholderText: type: string description: Placeholder shown by compatible input blocks. numberFormat: type: string description: Number formatting preset. allowedFiles: type: array items: type: string description: Allowed file extensions or MIME types. multipleFiles: type: boolean description: Allow multiple file uploads. maxFileSize: type: boolean description: Enable the configured maximum file-size restriction. hide: type: boolean description: Hide a hidden-field block from the visible form. showActions: type: boolean description: Show logic actions in the editor. badgeType: type: string enum: - 'off' - number - letter colorOption: type: boolean description: Enable per-choice colors. rule: type: object additionalProperties: true description: Logic rule definition for a logic block. image: type: object additionalProperties: true description: Optional block image and layout data. ErrorDetail: type: object additionalProperties: true responses: Unauthorized: description: Missing, invalid, expired, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The key lacks the required scope. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The resource does not exist or is not accessible. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: The key exceeded 100 requests in one minute. headers: Retry-After: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: ApiKey: type: apiKey in: header name: X-API-Key description: >- A scoped key with the of_live_ prefix, generated from Profile > API keys. ````