README

Boldsign Elixir Client

Unofficial Elixir client for BoldSign built on top of Req.

Use it to send documents for signature, generate embedded signing links, manage templates and users, work with contacts and custom fields, verify webhooks, and plug BoldSign into Phoenix apps without dragging in a huge SDK.

Why This Library

Supports both X-API-KEY and OAuth bearer token auth.
Covers the most useful BoldSign API areas in a lightweight, idiomatic Elixir wrapper.
Automatically switches between JSON and multipart requests when file uploads are present.
Includes Phoenix-friendly webhook verification helpers.
Ships with broad Bypass-backed test coverage so wrappers stay honest.

Quick Start with LiveBook

The fastest way to try the client is the interactive LiveBook example:

Installation

Add boldsign to your dependencies:

def deps do
  [
    {:boldsign, "~> 0.6.1"}
  ]
end

The docs are available at hexdocs.pm/boldsign.

Authentication

Boldsign supports either API keys or OAuth access tokens:

# API key
client = Boldsign.new(api_key: "your_api_key")

# OAuth bearer token
oauth_client = Boldsign.new(access_token: "your_oauth_access_token")

# Dual credential setup if your app may use either path
hybrid_client = Boldsign.new(
  api_key: "your_api_key",
  access_token: "your_oauth_access_token"
)

Regional base URLs are built in:

Boldsign.new(api_key: "your_api_key", region: :us)
Boldsign.new(api_key: "your_api_key", region: :eu)
Boldsign.new(api_key: "your_api_key", region: :ca)
Boldsign.new(api_key: "your_api_key", region: :au)

If you need a custom endpoint, pass base_url: ... directly.

Quick Examples

Send a document

params = %{
  title: "Agreement",
  message: "Please review and sign.",
  fileUrls: ["https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"],
  signers: [
    %{
      name: "John Doe",
      emailAddress: "john@example.com",
      signerOrder: 1
    }
  ]
}

Boldsign.Document.send(client, params)

Generate an embedded signing link

response = Boldsign.Document.get_embedded_sign_link(client, "document_id", %{
  "SignerEmail" => "john@example.com",
  "RedirectUrl" => "https://example.com/complete"
})

response["signLink"]

Send from a template

Boldsign.Template.send(client, "template_id", %{
  roles: [
    %{
      roleIndex: 1,
      name: "John Doe",
      emailAddress: "john@example.com"
    }
  ]
})

Update user metadata

Boldsign.User.update_metadata(client, %{
  userId: "user_id",
  metaData: %{department: "Legal", cost_center: "A-14"}
})

Verify webhooks

payload = conn.assigns[:raw_body]
signature = get_req_header(conn, "x-boldsign-signature") |> List.first()
secret = System.fetch_env!("BOLDSIGN_WEBHOOK_SECRET")

Boldsign.Webhook.verify_signature(payload, signature, secret)

API Coverage

Core APIs

Directory and admin APIs

Support modules

Notes on Params

This client intentionally stays thin. Most list and filter options are forwarded directly to BoldSign, so use the official request parameter names when a given endpoint expects a specific casing such as Page, TeamId, SignerEmail, or RedirectUrl.

For endpoints that support file uploads, pass files: [...] using Boldsign.File.from_path/1 or Boldsign.File.from_binary/3 and the client will transparently switch to multipart form data.

Boldsign.Document.send(client, %{
  title: "NDA",
  files: [Boldsign.File.from_path("/tmp/nda.pdf")],
  signers: [%{name: "Jane", emailAddress: "jane@example.com"}]
})

Phoenix Integration

Use the included plug if you want webhook verification and dispatch in one place:

plug Boldsign.WebhookPlug,
  at: "/webhook/boldsign",
  handler: MyApp.BoldsignHandler,
  secret: fn -> System.fetch_env!("BOLDSIGN_WEBHOOK_SECRET") end

Your handler just needs to implement Boldsign.Webhook.Handler.

Development

mix format
mix test

The test suite uses Bypass and exercises the request shapes for auth, multipart uploads, documents, templates, contacts, contact groups, custom fields, users, teams, identity verification, and plan APIs.

Credits

This project is inspired by the Dashbit blog post on building SDKs with Req.

Formatting and CI structure were adapted from docusign_elixir.

Next Page → Changelog