JavaScript / TypeScript

@onlyform/sdk is the official ESM package for Node.js 18+ and server runtimes with a standards-compatible Fetch API. It includes TypeScript declarations and has no runtime dependencies. The current release targets API contract 2026-08-01.

Install

npm install @onlyform/sdk

Configure the client

import { Onlyform } from '@onlyform/sdk'

const onlyform = new Onlyform({
  apiKey: process.env.ONLYFORM_API_KEY!,
})

The client uses https://api.onlyform.com by default. Use the optional baseUrl constructor property only for private development environments.

Create a complete form

The create call accepts blocks, settings, theme tokens, variables, and hidden fields inside definition.

const created = await onlyform.forms.create({
  name: 'Product feedback',
  workspace_id: '507f1f77bcf86cd799439012',
  type: 'MULTI',
  definition: {
    blocks: [
      {
        id: 'rating',
        type: 'rating',
        label: 'How would you rate the product?',
        description: '',
        required: true,
        properties: { max: 5, icon: 'star' },
      },
    ],
    settings: { progressBar: true },
    theme: {
      font: 'Inter',
      colors: { primary: '#3969D9' },
    },
    variables: { score: 0, price: 0, segment: 'new-customer' },
    hidden_fields: ['campaign_id', 'account_id'],
  },
})

console.log(created.id)

See Form definitions, Block types, and Theme tokens for the complete accepted schema.

Add and remove blocks

Form and block reads return { data, etag }. Pass the latest ETag as ifMatch when editing blocks to prevent overwriting a concurrent change.

const current = await onlyform.forms.retrieve('form_id')

const added = await onlyform.forms.blocks.create(
  'form_id',
  {
    block: {
      id: 'email',
      type: 'email',
      label: 'Email address',
      description: 'Where should we reply?',
      required: true,
      properties: {},
    },
  },
  { ifMatch: current.etag },
)

await onlyform.forms.blocks.delete(
  'form_id',
  'email',
  { ifMatch: added.etag },
)

Use replaceAll(formId, blocks, { ifMatch }) to atomically replace the complete ordered block collection.

Update a form

const current = await onlyform.forms.retrieve('form_id')

const updated = await onlyform.forms.update(
  'form_id',
  {
    name: 'Customer feedback',
    definition: {
      settings: { progressBar: false },
      theme: { font: 'Georgia', colors: { primary: '#3969D9' } },
    },
  },
  { ifMatch: current.etag },
)

Cursor pagination

let cursor: string | undefined

do {
  const page = await onlyform.forms.list({ limit: 100, cursor })

  for (const form of page.items) {
    console.log(form.id)
  }

  cursor = page.page.next_cursor ?? undefined
} while (cursor)

Other resources

const workspaces = await onlyform.workspaces.list({ limit: 50 })
const submissions = await onlyform.forms.submissions.list('form_id', { limit: 100 })
const metrics = await onlyform.forms.analytics.metrics('form_id', { period: '30d' })
const webhooks = await onlyform.webhooks.list()

Handle errors

import { OnlyformApiError, OnlyformNetworkError } from '@onlyform/sdk'

try {
  await onlyform.forms.retrieve('form_id')
} catch (error) {
  if (error instanceof OnlyformApiError) {
    console.error(error.status, error.code, error.requestId, error.details)
  } else if (error instanceof OnlyformNetworkError) {
    console.error(error.message)
  }
}

The client accepts AbortSignal on request options and uses a 30-second timeout by default. Set timeoutMs in the constructor to change it.

​Install

​Configure the client

​Create a complete form

​Add and remove blocks

​Update a form

​Cursor pagination

​Other resources

​Handle errors