TypeScript SDK

The @formalingo/sdk package provides a type-safe client for the Formalingo API, generated with Microsoft Kiota.

Installation

npm install @formalingo/sdk @microsoft/kiota-abstractions

Or with yarn:

yarn add @formalingo/sdk @microsoft/kiota-abstractions

Setup

import {
  createBulkRecipients,
  createClient,
  createDocumentSubmission,
} from "@formalingo/sdk"

const client = createClient("af_live_YOUR_KEY")

To use a custom base URL (e.g. for local development):

const client = createClient("af_live_YOUR_KEY", "http://localhost:3000")

Forms

List forms

const forms = await client.forms.get()

Create a form

const form = await client.forms.post({
  title: "Customer Satisfaction Survey",
  description: "Help us improve our service.",
})

Get a form

const form = await client.forms.byFormId("FORM_ID").get()

Update a form

const form = await client.forms.byFormId("FORM_ID").put({
  status: "published",
})

Delete a form

await client.forms.byFormId("FORM_ID").delete()

Sections

// List sections
const sections = await client.forms.byFormId("FORM_ID").sections.get()

// Create a section
const section = await client.forms.byFormId("FORM_ID").sections.post({
  title: "Personal Information",
})

Questions

// Create a question
const question = await client.forms.byFormId("FORM_ID").questions.post({
  questionText: "What is your full name?",
  type: "short_text",
  isRequired: true,
})

// Create a multiple choice question
const mcq = await client.forms.byFormId("FORM_ID").questions.post({
  questionText: "How did you hear about us?",
  type: "mcq",
  options: {
    choices: ["Social media", "Friend", "Search engine", "Other"],
  },
})

Recipients

// Create a recipient with pre-fill
const recipient = await client.forms.byFormId("FORM_ID").recipients.post({
  label: "John Doe",
  email: "john@acme.com",
  prefill: {
    "question-uuid-1": "John Doe",
    "question-uuid-2": "Acme Corp",
  },
})

console.log(recipient.link)
// → https://www.formalingo.com/f/TOKEN

// Bulk create with one retry-safe key for the whole request
const recipients = await createBulkRecipients(
  client,
  "00000000-0000-0000-0000-000000000001",
  {
    confirmBulk: true,
    recipients: [
      { label: "Alice", email: "alice@example.com" },
      { label: "Bob", phone: "+1 202-555-0100" },
    ],
  },
  "recipient-bulk-create-7f3f",
)

On idempotency_request_in_progress, retry the exact body with the same key. A different body returns idempotency_key_conflict; recipient erasure returns idempotency_replay_unavailable.

Branding

await client.forms.byFormId("FORM_ID").branding.put({
  primaryColor: "#6366F1",
  welcomeHeading: "Welcome!",
  thankYouHeading: "Thank you!",
  thankYouMessage: "We appreciate your feedback.",
})

Documents

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

// Create a submission with signers
const submission = await createDocumentSubmission(
  client,
  "00000000-0000-0000-0000-000000000001",
  {
    signers: [
      {
        role: "signer_1",
        name: "John Doe",
        email: "john@acme.com",
        prefill: { "field-uuid-1": "John Doe" },
        prefillReadonly: true,
      },
    ],
  },
  "document-create-7f3f",
)

console.log(submission.signers?.[0]?.link)
// → https://www.formalingo.com/d/TOKEN

Import createDocumentSubmission alongside createClient. The required idempotency key makes retries safe, and the helper unwraps the API envelope so submission.signers comes from response.data.signers.

Error Handling

try {
  const form = await client.forms.byFormId("non-existent").get()
} catch (error) {
  // Kiota throws typed errors with status code and message
  console.error("API error:", error)
}

TypeScript SDK

On this page