BeeSign API Reference

The BeeSign REST API lets you manage documents, forms, templates, and organization members programmatically. All endpoints return JSON and are served over HTTPS.

Base URL

https://api.beesign.net

Authentication

Authenticate every request with an API key passed as a Bearer token in the Authorization header. Create and rotate keys from the API keys page. Keys grant full access on your behalf, so keep them secret.

Authorization header

Authorization: Bearer YOUR_API_KEY

Organization keys

Organization API keys can act on behalf of a specific member by adding an X-User-Id header. The request is then scoped to that member's workspace. Without it, the key operates on the organization's shared scope.

Errors

Errors return a non-2xx status with a JSON body of the shape { "error": "..." }. Common codes: 401 (missing or invalid key), 403 (key lacks access), 404 (resource not found), 400 (bad request).

Documents

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

List documents

GET/v1/documents

Returns every non-archived document in the authenticated workspace.

Request

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

Response · 200 OK

{
  "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
}

Retrieve a document

GET/v1/documents/{documentId}

Fetches a single document's metadata. Archived documents return 404 as if they no longer exist.

Parameters

Parameter	Type	In	Description
`documentId`required	string	path	The document identifier, e.g. BSD-1718049600000.

Request

curl https://api.beesign.net/v1/documents/BSD-1718049600000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200 OK

{
  "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": "[ ... ]" }
}

Get a download URL

GET/v1/documents/{documentId}/download

Generates a short-lived, signed URL you can use to download the PDF directly. The URL expires after 15 minutes (900 seconds).

Parameters

Parameter	Type	In	Description
`documentId`required	string	path	The document identifier.

Request

curl https://api.beesign.net/v1/documents/BSD-1718049600000/download \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200 OK

{
  "downloadUrl": "https://storage.googleapis.com/beesign/...&X-Goog-Signature=...",
  "expiresIn": 900
}

Archive a document

DELETE/v1/documents/{documentId}

Soft-deletes a document by moving it to ARCHIVE storage. It stops appearing in listings but is not permanently destroyed.

Parameters

Parameter	Type	In	Description
`documentId`required	string	path	The document identifier.

Request

curl -X DELETE https://api.beesign.net/v1/documents/BSD-1718049600000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200 OK

{
  "message": "Document deleted successfully",
  "id": "BSD-1718049600000"
}

Archive all documents

DELETE/v1/documents

Archives every document in the workspace in one call. Returns the number of documents that were archived.

Request

curl -X DELETE https://api.beesign.net/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200 OK

{
  "message": "All documents archived successfully",
  "archivedCount": 12,
  "storageClass": "ARCHIVE"
}

Forms

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

Upload a form

POST/v1/forms

Uploads a new form. Send the request as multipart/form-data. If you omit formId, one is generated for you.

Parameters

Parameter	Type	In	Description
`file`required	file	form	The PDF file to upload.
`category`required	string	form	The category the form belongs to.
`formName`required	string	form	A human-readable name for the form.
`formId`optional	string	form	Optional custom id. Defaults to BSF-{timestamp}.

Request

curl -X POST https://api.beesign.net/v1/forms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./onboarding.pdf" \
  -F "category=HR" \
  -F "formName=Onboarding Agreement"

Response · 201 Created

{
  "id": "BSF-1718049600000",
  "name": "Onboarding Agreement",
  "category": "HR",
  "size": 84213,
  "contentType": "application/pdf",
  "path": "user_2ab.../forms/BSF-1718049600000"
}

List forms

GET/v1/forms

Returns every form in the authenticated workspace.

Request

curl https://api.beesign.net/v1/forms \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200 OK

{
  "forms": [
    {
      "id": "BSF-1718049600000",
      "name": "BSF-1718049600000",
      "size": 84213,
      "contentType": "application/pdf",
      "createdAt": "2025-06-10T18:40:00.000Z",
      "updatedAt": "2025-06-10T18:40:00.000Z",
      "metadata": { "category": "HR", "formName": "Onboarding Agreement" }
    }
  ],
  "count": 1
}

Retrieve a form

GET/v1/forms/{formId}

Fetches a single form's metadata.

Parameters

Parameter	Type	In	Description
`formId`required	string	path	The form identifier.

Request

curl https://api.beesign.net/v1/forms/BSF-1718049600000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200 OK

{
  "id": "BSF-1718049600000",
  "name": "BSF-1718049600000",
  "size": 84213,
  "contentType": "application/pdf",
  "createdAt": "2025-06-10T18:40:00.000Z",
  "updatedAt": "2025-06-10T18:40:00.000Z",
  "metadata": { "category": "HR", "formName": "Onboarding Agreement" }
}

Get a download URL

GET/v1/forms/{formId}/download

Generates a signed download URL valid for 15 minutes.

Parameters

Parameter	Type	In	Description
`formId`required	string	path	The form identifier.

Request

curl https://api.beesign.net/v1/forms/BSF-1718049600000/download \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200 OK

{
  "downloadUrl": "https://storage.googleapis.com/beesign/...&X-Goog-Signature=...",
  "expiresIn": 900
}

Delete a form

DELETE/v1/forms/{formId}

Permanently deletes a single form.

Parameters

Parameter	Type	In	Description
`formId`required	string	path	The form identifier.

Request

curl -X DELETE https://api.beesign.net/v1/forms/BSF-1718049600000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200 OK

{
  "message": "Form deleted successfully",
  "id": "BSF-1718049600000"
}

Delete all forms

DELETE/v1/forms

Permanently deletes every form in the workspace.

Request

curl -X DELETE https://api.beesign.net/v1/forms \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200 OK

{
  "message": "All forms deleted successfully",
  "deletedCount": 8
}

Templates

Templates are reusable signature setups, each bundling one or more documents under a manifest.

List templates

GET/v1/templates

Returns every template in the authenticated workspace.

Request

curl https://api.beesign.net/v1/templates \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200 OK

{
  "templates": [
    {
      "id": "BST-1718049600000",
      "name": "NDA Template",
      "createdAt": "2025-06-10T18:40:00.000Z",
      "updatedAt": "2025-06-10T18:40:00.000Z",
      "metadata": { "name": "NDA Template" }
    }
  ],
  "count": 1
}

Retrieve a template

GET/v1/templates/{templateId}

Fetches a template's metadata along with the list of documents it contains.

Parameters

Parameter	Type	In	Description
`templateId`required	string	path	The template identifier.

Request

curl https://api.beesign.net/v1/templates/BST-1718049600000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200 OK

{
  "id": "BST-1718049600000",
  "name": "NDA Template",
  "createdAt": "2025-06-10T18:40:00.000Z",
  "updatedAt": "2025-06-10T18:40:00.000Z",
  "metadata": { "name": "NDA Template" },
  "documents": [
    {
      "id": "doc-1.pdf",
      "name": "doc-1.pdf",
      "size": 120344,
      "contentType": "application/pdf",
      "createdAt": "2025-06-10T18:40:00.000Z",
      "updatedAt": "2025-06-10T18:40:00.000Z",
      "metadata": {}
    }
  ],
  "documentCount": 1
}

Send a template for signature

POST/v1/templates/{templateId}/use_template

Instantiates a template and sends its documents out for signature. Each document in the template is uploaded as a new document and emailed to the relevant recipients. Optionally remap the template's placeholder recipients to real people by name via the assignments body. If the template defines approvers, the documents are sent as an approval batch and a batchId is returned. When called with an organization key, the X-User-Id header is required so the documents are created under that member's workspace.

Parameters

Parameter	Type	In	Description
`templateId`required	string	path	The template identifier.
`X-User-Id`optional	string	header	Required for organization API keys — the member to send on behalf of. Ignored for personal keys.
`assignments`optional	object	body	Maps a template recipient's name to the real recipient's { name, email }. Recipients not listed keep the template's defaults.

Request

curl -X POST https://api.beesign.net/v1/templates/BST-1718049600000/use_template \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assignments": {
      "Signer 1": { "name": "Jordan Lee", "email": "[email protected]" }
    }
  }'

Response · 200 OK

{
  "success": true,
  "templateId": "BST-1718049600000",
  "documentsSent": 1,
  "batchId": null
}

Download a template document

GET/v1/templates/{templateId}/download/{documentId}

Generates a signed download URL for a specific document inside a template.

Parameters

Parameter	Type	In	Description
`templateId`required	string	path	The template identifier.
`documentId`required	string	path	The document identifier within the template.

Request

curl https://api.beesign.net/v1/templates/BST-1718049600000/download/doc-1.pdf \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200 OK

{
  "downloadUrl": "https://storage.googleapis.com/beesign/...&X-Goog-Signature=...",
  "expiresIn": 900,
  "templateId": "BST-1718049600000",
  "documentId": "doc-1.pdf"
}

Delete a template

DELETE/v1/templates/{templateId}

Permanently deletes a template and all of the documents it contains.

Parameters

Parameter	Type	In	Description
`templateId`required	string	path	The template identifier.

Request

curl -X DELETE https://api.beesign.net/v1/templates/BST-1718049600000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200 OK

{
  "message": "Template deleted successfully",
  "id": "BST-1718049600000",
  "deletedFiles": 3
}

Delete all templates

DELETE/v1/templates

Permanently deletes every template in the workspace.

Request

curl -X DELETE https://api.beesign.net/v1/templates \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200 OK

{
  "message": "All templates deleted successfully",
  "deletedTemplates": 4,
  "deletedFiles": 11
}

Users

List the members of an organization. Available only to organization API keys — personal keys receive a 403.

List organization users

GET/v1/users

Returns the members of the organization that owns the API key, including their role.

Request

curl https://api.beesign.net/v1/users \
  -H "Authorization: Bearer YOUR_ORG_API_KEY"

Response · 200 OK

{
  "users": [
    {
      "id": "user_2ab...",
      "name": "Jordan Lee",
      "email": "[email protected]",
      "role": "org:admin"
    }
  ],
  "count": 1
}