BeeSign API

The electronic signature REST API for developers — send documents for signature, manage reusable templates and forms, and administer your team, all from your own code.

BeeSign is an electronic signature platform. The BeeSign API puts the whole platform behind simple, predictable REST endpoints — so signatures become a feature of your product instead of a tab someone has to remember to check.

This repository contains the public documentation, an OpenAPI specification, and copy‑paste examples (curl, Node.js, and Python) for the BeeSign REST API. It is the fastest way to make your first call.

• 🌐 Hosted reference: https://beesign.net/api-docs
• 🔑 Get an API key: https://beesign.net/api-keys
• 📄 OpenAPI spec: openapi.yaml

---

Table of contents

• Why BeeSign
• Quickstart
• Authentication
• Resources & endpoints
• Examples
• Errors
• Working with organizations
• OpenAPI specification
• FAQ
• Support

---

Why BeeSign

API‑key authentication	Create and revoke keys from your dashboard. Authenticate with a single Authorization: Bearer header — no OAuth dance.
Predictable REST	Plain JSON over HTTPS, resource‑oriented URLs, standard status codes. If you've used a REST API, you already know this one.
Secure by default	Every call runs over TLS and is scoped to your workspace. Downloads are short‑lived signed URLs that expire automatically.
The whole platform	Everything you manage in the dashboard — documents, templates, forms, and team — is available over the API.

---

Quickstart

1. Get an API key. Sign up at beesign.net and create a key on the API Keys page. Keys look like bsk_live_… and are shown once, so copy it somewhere safe.

2. Make your first call.

curl https://api.beesign.net/v1/documents \
  -H "Authorization: Bearer $BEESIGN_API_KEY"

{
  "documents": [
    {
      "id": "BSD-1718049600000",
      "name": "BSD-1718049600000",
      "size": 254013,
      "contentType": "application/pdf",
      "createdAt": "2025-06-10T18:40:00.000Z",
      "updatedAt": "2025-06-10T18:40:00.000Z",
      "metadata": { "recipients": "[ ... ]" }
    }
  ],
  "count": 1
}

That's the whole setup. The examples/ directory has ready‑to‑run scripts for curl, Node.js, and Python.

---

Authentication

All requests are authenticated with an API key passed as a Bearer token:

Authorization: Bearer bsk_live_xxxxxxxxxxxxxxxxxxxxxxxx

• Keys are created and rotated from the API Keys dashboard page.
• A key grants full access on your behalf — treat it like a password and never commit it to source control. Use an environment variable (see .env.example).
• Rotating a key immediately invalidates the old one and issues a new one.

There are two kinds of keys:

Scope	Created by	Acts on
Personal	Any user	Your own workspace
Organization	Org admins	The organization, or a specific member via the X-User-Id header

See Working with organizations for details.

Full details: docs/authentication.md.

---

Resources & endpoints

Base URL: https://api.beesign.net · Version: v1 · All responses are JSON over HTTPS.

Documents — docs/documents.md

Documents are the PDFs sent out for signature. Each is identified by an id like BSD-1718049600000.

Method	Path	Description
GET	/v1/documents	List every non‑archived document
GET	/v1/documents/{documentId}	Retrieve a document's metadata
GET	/v1/documents/{documentId}/download	Get a short‑lived signed download URL
DELETE	/v1/documents/{documentId}	Archive a document (soft delete)
DELETE	/v1/documents	Archive every document in the workspace

Forms — docs/forms.md

Forms are reusable, fillable PDFs grouped by category. Identified by an id like BSF-1718049600000.

Method	Path	Description
POST	/v1/forms	Upload a form (multipart/form-data)
GET	/v1/forms	List every form
GET	/v1/forms/{formId}	Retrieve a form's metadata
GET	/v1/forms/{formId}/download	Get a signed download URL
DELETE	/v1/forms/{formId}	Delete a form
DELETE	/v1/forms	Delete every form

Templates — docs/templates.md

Templates are reusable signature setups, each bundling one or more documents under a manifest. Identified by an id like BST-1718049600000.

Method	Path	Description
GET	/v1/templates	List every template
GET	/v1/templates/{templateId}	Retrieve a template and its documents
POST	/v1/templates/{templateId}/use_template	Send a template out for signature
GET	/v1/templates/{templateId}/download/{documentId}	Download a document inside a template
DELETE	/v1/templates/{templateId}	Delete a template and its documents
DELETE	/v1/templates	Delete every template

Users — docs/users.md

List the members of an organization. Organization keys only — personal keys receive a 403.

Method	Path	Description
GET	/v1/users	List the members of the organization that owns the key

---

Examples

Runnable examples live in examples/:

Language	Folder	What's inside
curl	examples/curl	One shell script per common task
Node.js	examples/node	A tiny beesign.js client + task scripts
Python	examples/python	A tiny beesign.py client + task scripts

Each folder has its own README and an .env.example. The common shape:

Node.js

import { BeeSign } from "./beesign.js";

const bee = new BeeSign(process.env.BEESIGN_API_KEY);

const { documents, count } = await bee.listDocuments();
console.log(`You have ${count} document(s).`);

Python

from beesign import BeeSign

bee = BeeSign(os.environ["BEESIGN_API_KEY"])

result = bee.list_documents()
print(f"You have {result['count']} document(s).")

---

Errors

Errors return a non‑2xx status with a JSON body of the shape:

{ "error": "Document not found" }

Status	Meaning
400	Bad request — a required parameter is missing or malformed
401	Missing or invalid API key
403	The key is valid but lacks access to this resource
404	The resource does not exist (archived documents also return 404)

See docs/errors.md for handling patterns.

---

Working with organizations

An organization API key can act on behalf of a specific member by adding an X-User-Id header. The request is then scoped to that member's private workspace:

curl -X POST https://api.beesign.net/v1/templates/BST-1718049600000/use_template \
  -H "Authorization: Bearer $BEESIGN_ORG_API_KEY" \
  -H "X-User-Id: user_2abc..." \
  -H "Content-Type: application/json" \
  -d '{ "assignments": { "Signer 1": { "name": "Jordan Lee", "email": "jordan@acme.com" } } }'

• Without X-User-Id, an org key operates on the organization's shared scope.
• POST /v1/templates/{id}/use_template requires X-User-Id when called with an org key, so the created documents land in a real member's workspace.
• GET /v1/users is the one endpoint exclusive to org keys.

Get the list of member ids from GET /v1/users.

---

OpenAPI specification

A machine‑readable OpenAPI 3.1 specification is included. Use it to:

• Generate a typed client in your language (openapi-generator, Speakeasy, etc.)
• Explore the API in Swagger UI, Postman, or Insomnia
• Drive contract tests

# Example: generate a TypeScript client
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml -g typescript-fetch -o ./generated

---

FAQ

Is there a sandbox? No separate sandbox application is required — every account, including the trial, has API access. Create a key and start calling.

What file types are supported? Documents and forms are PDFs (application/pdf).

How long do download URLs last? Download endpoints return a signed URL that expires after 15 minutes (900 seconds). Generate a fresh one whenever you need to download.

What happens when I archive a document? It is soft‑deleted — moved to archive storage. It stops appearing in listings and returns 404, but it is not permanently destroyed.

Are these official client libraries? The scripts in examples/ are lightweight, dependency‑light reference clients meant to be copied and adapted — not a versioned SDK. For a fully‑typed client, generate one from openapi.yaml.

---

Support

• 📖 Docs: https://beesign.net/api-docs
• 💬 Contact support: https://beesign.net/contact-support
• 🐛 Issues with these docs/examples: open an issue in this repository

---

_{BeeSign — electronic signatures from your own code. This repository documents the public REST API; the API itself is operated at api.beesign.net.}