@formalingo/sdk

Official TypeScript SDK for the Formalingo API — build and manage AI-powered forms and document signing programmatically.

Installation

npm install @formalingo/sdk
# or
yarn add @formalingo/sdk
# or
pnpm add @formalingo/sdk

Quick Start

import { createClient } from "@formalingo/sdk"

const client = createClient("af_live_YOUR_API_KEY")

// List all forms
const forms = await client.forms.get()

// Create a form
const form = await client.forms.post({
  body: {
    title: "Customer Feedback",
    description: "Help us improve our service",
  },
})

Setup

Get Your API Key

1. Log in to Formalingo
2. Go to Settings > API Keys
3. Create a new key

Initialize the Client

import { createClient } from "@formalingo/sdk"

// Production (default)
const client = createClient("af_live_YOUR_API_KEY")

// Custom base URL (e.g., local development)
const client = createClient("af_live_YOUR_API_KEY", "http://localhost:3000")

Usage Examples

Forms

// List forms
const forms = await client.forms.get()

// Get a specific form
const form = await client.forms.byFormId("form-id").get()

// Update a form
await client.forms.byFormId("form-id").put({
  body: { title: "Updated Title", status: "published" },
})

// Delete a form
await client.forms.byFormId("form-id").delete()

Sections & Questions

const formApi = client.forms.byFormId("form-id")

// Create a section
const section = await formApi.sections.post({
  body: { title: "Personal Info", order: 0 },
})

// Add a question
const question = await formApi.questions.post({
  body: {
    sectionId: section.id,
    type: "short_text",
    title: "What is your name?",
    required: true,
    order: 0,
  },
})

// Multiple choice question
await formApi.questions.post({
  body: {
    sectionId: section.id,
    type: "mcq",
    title: "How did you hear about us?",
    required: false,
    order: 1,
    options: {
      choices: ["Search engine", "Social media", "Friend", "Other"],
    },
  },
})

Recipients

// Create a recipient (generates a shareable link)
const recipient = await client.forms.byFormId("form-id").recipients.post({
  body: {
    label: "John Doe",
    prefill: { name: "John Doe", email: "[email protected]" },
  },
})

// The shareable form URL
const formUrl = `https://www.formalingo.com/f/${recipient.token}`

Branding

await client.forms.byFormId("form-id").branding.put({
  body: {
    primaryColor: "#4F46E5",
    backgroundColor: "#F9FAFB",
    welcomeHeading: "Welcome!",
    welcomeSubtitle: "This will only take a minute.",
    thankYouHeading: "Thank you!",
    thankYouMessage: "Your response has been recorded.",
  },
})

Documents

// List documents
const documents = await client.documents.get()

// Create a document with signers
const doc = await client.documents.post({
  body: {
    title: "NDA Agreement",
    content: "Full document text...",
    signers: [
      { name: "Alice", email: "[email protected]" },
      { name: "Bob", email: "[email protected]" },
    ],
  },
})

Error Handling

try {
  const form = await client.forms.byFormId("nonexistent").get()
} catch (error) {
  if (error instanceof Error) {
    console.error("API error:", error.message)
  }
}

Advanced Usage

For full control over the underlying Kiota client:

import { createFormalingoClient } from "@formalingo/sdk"
import {
  ApiKeyAuthenticationProvider,
  ApiKeyLocation,
} from "@microsoft/kiota-abstractions"
import { FetchRequestAdapter } from "@microsoft/kiota-http-fetchlibrary"

const auth = new ApiKeyAuthenticationProvider(
  "Bearer af_live_YOUR_API_KEY",
  "Authorization",
  ApiKeyLocation.Header
)
const adapter = new FetchRequestAdapter(auth)
adapter.baseUrl = "https://app.formalingo.com"

const rawClient = createFormalingoClient(adapter)
const v1 = rawClient.api.v1

Requirements

• Node.js 20+
• ESM (this package uses "type": "module")

Other SDKs

Formalingo also provides SDKs for:

• Python — formalingo-sdk
• .NET — Formalingo.Sdk
• Go — github.com/Formalingo/sdk-go

Documentation

Full API documentation and guides: formalingo.com/docs

License

MIT