Go SDK

The sdk-go module provides a type-safe client for the Formalingo API, generated with Microsoft Kiota.

Installation

go get github.com/Formalingo/sdk-go

Setup

import formalingo "github.com/Formalingo/sdk-go"

client, err := formalingo.NewClient("af_live_YOUR_KEY")

The NewClient helper wires up authentication and the HTTP adapter automatically. You can optionally pass a custom base URL:

client, err := formalingo.NewClient("af_live_YOUR_KEY", "http://localhost:3000")

Note: The Kiota-generated client includes the full API path: client.Api().V1().Forms(), client.Api().V1().Documents(), etc.

Forms

List forms

ctx := context.Background()
forms, err := client.Api().V1().Forms().Get(ctx, nil)

Create a form

body := &models.CreateFormBody{
    Title:       to.Ptr("Customer Satisfaction Survey"),
    Description: to.Ptr("Help us improve our service."),
}

form, err := client.Api().V1().Forms().Post(ctx, body, nil)

Get a form

form, err := client.Api().V1().Forms().ByFormId("FORM_ID").Get(ctx, nil)

Update a form

body := &models.UpdateFormBody{
    Status: to.Ptr("published"),
}

form, err := client.Api().V1().Forms().ByFormId("FORM_ID").Put(ctx, body, nil)

Delete a form

err := client.Api().V1().Forms().ByFormId("FORM_ID").Delete(ctx, nil)

Sections

// List sections
sections, err := client.Api().V1().Forms().ByFormId("FORM_ID").Sections().Get(ctx, nil)

// Create a section
body := &models.CreateSectionBody{
    Title: to.Ptr("Personal Information"),
}
section, err := client.Api().V1().Forms().ByFormId("FORM_ID").Sections().Post(ctx, body, nil)

Questions

// Create a question
body := &models.CreateQuestionBody{
    QuestionText: to.Ptr("What is your full name?"),
    Type:         to.Ptr("short_text"),
    IsRequired:   to.Ptr(true),
}
question, err := client.Api().V1().Forms().ByFormId("FORM_ID").Questions().Post(ctx, body, nil)

Recipients

// Create a recipient with pre-fill
body := &models.CreateRecipientBody{
    Label: to.Ptr("John Doe"),
    Email: to.Ptr("john@acme.com"),
    Prefill: map[string]string{
        "question-uuid-1": "John Doe",
        "question-uuid-2": "Acme Corp",
    },
}
recipient, err := client.Api().V1().Forms().ByFormId("FORM_ID").Recipients().Post(ctx, body, nil)
fmt.Println(recipient.GetLink())
// → https://www.formalingo.com/f/TOKEN

// Bulk create with one caller-owned retry key for the exact request
bulkRecipient := sdkapi.NewV1FormsItemRecipientsBulkPostRequestBody_recipients()
label, email := "Alice", "alice@example.com"
bulkRecipient.SetLabel(&label)
bulkRecipient.SetEmail(&email)
bulkBody := sdkapi.NewV1FormsItemRecipientsBulkPostRequestBody()
confirmBulk := true
bulkBody.SetConfirmBulk(&confirmBulk)
bulkBody.SetRecipients(
    []sdkapi.V1FormsItemRecipientsBulkPostRequestBody_recipientsable{
        bulkRecipient,
    },
)
recipients, err := formalingo.CreateBulkRecipients(
    ctx,
    client,
    uuid.MustParse("00000000-0000-0000-0000-000000000001"),
    bulkBody,
    "recipient-bulk-create-7f3f",
)

The idempotency key is required. Reuse it only when retrying the exact same serialized request body. 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

body := &models.BrandingUpdateRequest{
    PrimaryColor:    to.Ptr("#6366F1"),
    WelcomeHeading:  to.Ptr("Welcome!"),
    ThankYouHeading: to.Ptr("Thank you!"),
    ThankYouMessage: to.Ptr("We appreciate your feedback."),
}
err := client.Api().V1().Forms().ByFormId("FORM_ID").Branding().Put(ctx, body, nil)

Documents

import (
    formalingo "github.com/Formalingo/sdk-go"
    "github.com/Formalingo/sdk-go/client/models"
    "github.com/google/uuid"
)

// List documents
docs, err := client.Api().V1().Documents().Get(ctx, nil)

// Create a submission with signers
prefill := models.NewSignerInput_prefill()
prefill.SetAdditionalData(map[string]any{"field-uuid-1": "John Doe"})
signer := models.NewSignerInput()
role, name, email, readonly := "signer_1", "John Doe", "john@acme.com", true
signer.SetRole(&role)
signer.SetName(&name)
signer.SetEmail(&email)
signer.SetPrefill(prefill)
signer.SetPrefillReadonly(&readonly)
body := models.NewCreateSubmissionBody()
body.SetSigners([]models.SignerInputable{signer})

submission, err := formalingo.CreateDocumentSubmission(
    ctx,
    client,
    uuid.MustParse("00000000-0000-0000-0000-000000000001"),
    body,
    "document-create-7f3f",
)
fmt.Println(*submission.GetSigners()[0].GetLink())
// → https://www.formalingo.com/d/TOKEN

The required idempotency key makes retries safe. The helper unwraps the API envelope so submission.GetSigners() comes from response.GetData().GetSigners().

Error Handling

form, err := client.Api().V1().Forms().ByFormId("non-existent").Get(ctx, nil)
if err != nil {
    fmt.Fprintf(os.Stderr, "API error: %v\n", err)
}

Go SDK

On this page