Quickstart

This guide verifies your key, lists your workspaces, and shows how to handle an API error.

Prerequisites

An Onlyform account.
A server, terminal, or API client that can keep secrets private.

Create an API key

Open Profile → API keys in the Onlyform dashboard, then select Create API key.Give the key a descriptive name, choose the minimum required scopes, and optionally set an expiration date.

Copy the secret immediately. Onlyform displays the complete key once and cannot recover it later.

Store the key

Store the secret in an environment variable. Keys begin with of_live_.

export ONLYFORM_API_KEY="of_live_your_key"

Do not commit the value to source control.

Verify the key

Call GET /v1/me to inspect the key owner and its effective scopes.

curl https://api.onlyform.com/v1/me \
  --header "X-API-Key: $ONLYFORM_API_KEY"

A successful response looks like this:

{
  "id": "507f1f77bcf86cd799439011",
  "name": "Alex Morgan",
  "email": "[email protected]",
  "scopes": [
    "forms:read",
    "submissions:read",
    "workspaces:read"
  ]
}

List your workspaces

Use the same header for every authenticated request.

curl "https://api.onlyform.com/v1/workspaces?limit=20" \
  --header "X-API-Key: $ONLYFORM_API_KEY"

Collections return an items array and a page object:

{
  "items": [
    {
      "id": "507f1f77bcf86cd799439012",
      "public_id": "workspace_public_id",
      "name": "Production",
      "created_at": "2026-07-31T09:00:00.000Z",
      "updated_at": "2026-07-31T09:00:00.000Z"
    }
  ],
  "page": {
    "has_more": false,
    "next_cursor": null
  }
}

Create a complete form

POST /v1/forms accepts the form type, ordered blocks, settings, theme, variables, and hidden fields in one request. Use MULTI for a page-per-question form or SINGLE for a single-page form.

curl --request POST https://api.onlyform.com/v1/forms \
  --header "X-API-Key: $ONLYFORM_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Contact us",
    "workspace_id": "507f1f77bcf86cd799439012",
    "type": "MULTI",
    "definition": {
      "blocks": [
        {
          "id": "name",
          "type": "short-text",
          "label": "Full name",
          "description": "Enter your full name.",
          "required": true,
          "properties": { "maxChars": 100 }
        },
        {
          "id": "email",
          "type": "email",
          "label": "Email address",
          "description": "We will use this address to reply.",
          "required": true,
          "properties": {}
        },
        {
          "id": "ending",
          "type": "ending",
          "label": "Thank you",
          "description": "We will be in touch soon.",
          "required": false,
          "properties": { "buttonText": "Submit" }
        }
      ],
      "settings": {
        "branding": true,
        "navigation": true,
        "progressBar": true,
        "closed": false
      },
      "theme": {
        "font": "Inter",
        "corners": 0,
        "colors": {
          "primary": "#3969D9",
          "primaryForeground": "#FFFFFF",
          "background": "#FFFFFF",
          "text": "#0A0A0A"
        }
      },
      "variables": {
        "score": 0,
        "price": 0,
        "lead_source": "public-api"
      },
      "hidden_fields": ["campaign_id", "account_id"]
    }
  }'

CONVERSATIONAL is reserved for the upcoming conversational renderer. Creation currently returns 422 UNSUPPORTED_FORM_TYPE instead of silently falling back to another layout.

Handle errors

Check the HTTP status and log the returned request_id. It lets Onlyform support trace a specific request.

{
  "type": "authorization_error",
  "code": "INSUFFICIENT_SCOPE",
  "message": "This operation requires the forms:write scope.",
  "status": 403,
  "request_id": "req_01example"
}

Authentication and scopes

Choose scopes and rotate keys safely.

API reference

Explore every endpoint in the interactive reference.

Get started

Core concepts

API reference

Prerequisites

Create a complete form

Handle errors

Authentication and scopes

API reference

​Prerequisites

​Create a complete form

​Handle errors

Authentication and scopes

API reference

Prerequisites

Create a complete form

Handle errors