Teams API (v1) - Documenso

API v1 is deprecated. For new integrations, please use API v2.

Overview

In Documenso, teams (also called organizations) allow multiple users to collaborate on documents, share templates, and manage API tokens together. All API operations in v1 are performed within a team context.

API v1 does not provide endpoints for creating or managing teams directly. Team management must be done through the Documenso web interface.

Team Context

How Team Context Works

When you create an API token, it is associated with a specific team. All API requests made with that token operate within that team’s context:

// Your API token determines the team context
const client = initClient(ApiContractV1, {
  baseUrl: 'https://app.documenso.com/api/v1',
  baseHeaders: {
    authorization: 'Bearer api_xxxxxxxxxxxxxxxx', // Token tied to Team A
  },
});

// All operations happen in Team A's context
const { body } = await client.createDocument({
  body: {
    title: 'Document',
    recipients: [...],
  },
});

// This document belongs to Team A
console.log(body.teamId); // Team A's ID

Team Isolation

Resources are isolated by team:

Documents: You can only access documents created by your team
Templates: Templates are scoped to the team that created them
Recipients: Only visible within document context
Fields: Only visible within document context
Folders: Team-specific organization

Creating API Tokens for Teams

Step 1: Access Team Settings

Log in to Documenso
Switch to the desired team using the team selector
Navigate to Settings > API Tokens

Step 2: Create Token

Click Create API Token
Give it a descriptive name (e.g., “Production API”, “Dev Integration”)
Set an expiration date (optional but recommended)
Click Create
Copy the token immediately (shown only once)

Step 3: Verify Team Context

// The token is now tied to the selected team
const client = initClient(ApiContractV1, {
  baseUrl: 'https://app.documenso.com/api/v1',
  baseHeaders: {
    authorization: `Bearer ${YOUR_TOKEN}`,
  },
});

// Create a document
const { body } = await client.createDocument({
  body: {
    title: 'Test Document',
    recipients: [{ name: 'Test', email: 'test@example.com', role: 'SIGNER' }],
  },
});

// Check which team owns this document
console.log(`Team ID: ${body.teamId}`);

Team Resource Access

Documents

All documents created via API are owned by the team associated with your API token:

// Create document
const { body: createBody } = await client.createDocument({
  body: {
    title: 'Team Document',
    recipients: [...],
  },
});

console.log(`Document ${createBody.documentId} belongs to team ${createBody.teamId}`);

// List documents - only returns documents from this team
const { body: listBody } = await client.getDocuments({
  query: { page: 1, perPage: 10 },
});

listBody.documents.forEach((doc) => {
  console.log(`Document ${doc.id}: Team ${doc.teamId}`);
});

Templates

Templates are team-scoped resources:

// Create template (tied to team)
const { body } = await client.createTemplate({
  body: {
    title: 'Team Template',
  },
});

// List templates - only shows this team's templates
const { body: templates } = await client.getTemplates({
  query: { page: 1, perPage: 10 },
});

templates.templates.forEach((template) => {
  console.log(`Template ${template.id}: Team ${template.teamId}`);
});

Multi-Team Access

If you need to access multiple teams, create separate API tokens for each team:

// Team A client
const teamAClient = initClient(ApiContractV1, {
  baseUrl: 'https://app.documenso.com/api/v1',
  baseHeaders: {
    authorization: `Bearer ${TEAM_A_TOKEN}`,
  },
});

// Team B client
const teamBClient = initClient(ApiContractV1, {
  baseUrl: 'https://app.documenso.com/api/v1',
  baseHeaders: {
    authorization: `Bearer ${TEAM_B_TOKEN}`,
  },
});

// Create document in Team A
const teamADoc = await teamAClient.createDocument({
  body: { title: 'Team A Document', recipients: [...] },
});

// Create document in Team B
const teamBDoc = await teamBClient.createDocument({
  body: { title: 'Team B Document', recipients: [...] },
});

Team-Level Settings

Certain settings are inherited from team configuration:

Document Settings

When creating documents, these settings may be inherited from team defaults:

const { body } = await client.createDocument({
  body: {
    title: 'Document',
    recipients: [...],
    meta: {
      // These override team defaults
      subject: 'Custom subject',
      message: 'Custom message',
      timezone: 'America/New_York',
      dateFormat: 'yyyy-MM-dd',
      
      // Signature settings (from team if not specified)
      typedSignatureEnabled: true,
      uploadSignatureEnabled: true,
      drawSignatureEnabled: true,
    },
  },
});

Email Branding

Team branding settings apply to all documents:

Company logo
Brand colors
Email footer
Reply-to email address

These are configured in the team settings and automatically applied to API-created documents.

Folders

Folders are team-specific. Documents can be organized into folders for better organization.

Creating Documents in Folders

// Create document in a specific folder
const { body } = await client.createDocument({
  body: {
    title: 'Organized Document',
    folderId: 'folder_abc123', // Team's folder ID
    recipients: [...],
  },
});

// List documents in a folder
const { body: docs } = await client.getDocuments({
  query: {
    page: 1,
    perPage: 10,
    folderId: 'folder_abc123',
  },
});

Getting Folder ID

Folder IDs must be obtained from the web interface:

Navigate to the desired folder in Documenso
Check the URL: https://app.documenso.com/documents?folderId=folder_abc123
Copy the folderId parameter

Team Members

User vs Team Context

API tokens are created by individual users within a team context:

// Document created via API
const { body } = await client.createDocument({
  body: { title: 'Document', recipients: [...] },
});

// userId = the user who created the API token
// teamId = the team associated with the token
console.log(`Created by user ${body.userId} in team ${body.teamId}`);

Audit Trail

All API actions are logged with both user and team information:

User who created the API token
Team context
IP address
Timestamp
Action performed

Permissions

Team-Level Permissions

API tokens inherit permissions from the team member who created them:

Permission Level	Can Do
Admin	Full API access including deleting documents and templates
Manager	Create, update, and send documents; manage templates
Member	Create and send documents assigned to them

If a user’s permissions are downgraded, their existing API tokens retain the old permission level until regenerated.

Team Webhooks

Webhooks are also team-scoped. Configure them in team settings to receive events for all team documents:

// Webhook events are fired for all documents in the team
// Configure webhooks in: Settings > Webhooks
// Events include:
// - DOCUMENT_CREATED
// - DOCUMENT_SENT
// - DOCUMENT_SIGNED
// - DOCUMENT_COMPLETED

Best Practices

1. Use Descriptive Token Names

When creating tokens, use names that indicate their purpose and team:

✅ Good:
- "Production API - Sales Team"
- "Development - Engineering Team"
- "Zapier Integration - Marketing Team"

❌ Avoid:
- "Token 1"
- "API Key"
- "Test"

2. Token Rotation

Rotate API tokens periodically for security:

// Old token
const oldClient = initClient(ApiContractV1, {
  baseUrl: 'https://app.documenso.com/api/v1',
  baseHeaders: { authorization: `Bearer ${OLD_TOKEN}` },
});

// Create new token in Documenso UI, then update your code
const newClient = initClient(ApiContractV1, {
  baseUrl: 'https://app.documenso.com/api/v1',
  baseHeaders: { authorization: `Bearer ${NEW_TOKEN}` },
});

// Revoke old token in Documenso UI after migration

3. Separate Tokens for Different Environments

Use different API tokens for different environments:

const client = initClient(ApiContractV1, {
  baseUrl: 'https://app.documenso.com/api/v1',
  baseHeaders: {
    authorization: `Bearer ${
      process.env.NODE_ENV === 'production'
        ? process.env.PROD_API_TOKEN
        : process.env.DEV_API_TOKEN
    }`,
  },
});

4. Monitor Token Usage

Regularly review API token usage in team settings:

Check last used timestamp
Remove unused tokens
Verify token ownership
Review permissions

Rate Limits

Rate limits are applied per team:

100 requests per minute per team
10 requests per second burst limit

All API tokens for a team share the same rate limit pool.

// All tokens for Team A share the rate limit
const token1Client = initClient(ApiContractV1, {
  baseHeaders: { authorization: `Bearer ${TEAM_A_TOKEN_1}` },
});

const token2Client = initClient(ApiContractV1, {
  baseHeaders: { authorization: `Bearer ${TEAM_A_TOKEN_2}` },
});

// Combined requests count toward Team A's rate limit
await token1Client.getDocuments({ query: { page: 1 } });
await token2Client.getDocuments({ query: { page: 1 } });

Example: Multi-Team Workflow

import { initClient } from '@ts-rest/core';
import { ApiContractV1 } from '@documenso/api/v1/contract';

// Sales team token
const salesClient = initClient(ApiContractV1, {
  baseUrl: 'https://app.documenso.com/api/v1',
  baseHeaders: {
    authorization: `Bearer ${process.env.SALES_TEAM_TOKEN}`,
  },
});

// Legal team token
const legalClient = initClient(ApiContractV1, {
  baseUrl: 'https://app.documenso.com/api/v1',
  baseHeaders: {
    authorization: `Bearer ${process.env.LEGAL_TEAM_TOKEN}`,
  },
});

async function processContract() {
  // 1. Sales team creates initial contract
  const { body: salesDoc } = await salesClient.createDocument({
    body: {
      title: 'Sales Contract - ACME Corp',
      externalId: 'sales-acme-2024',
      recipients: [
        {
          name: 'Client',
          email: 'client@acme.com',
          role: 'SIGNER',
        },
      ],
    },
  });

  console.log(`Sales contract created in team ${salesDoc.teamId}`);

  // Upload and send...

  // 2. Legal team creates separate NDA
  const { body: legalDoc } = await legalClient.createDocument({
    body: {
      title: 'NDA - ACME Corp',
      externalId: 'nda-acme-2024',
      recipients: [
        {
          name: 'Client',
          email: 'client@acme.com',
          role: 'SIGNER',
        },
      ],
    },
  });

  console.log(`NDA created in team ${legalDoc.teamId}`);

  // Each team manages their own documents independently
}

processContract().catch(console.error);

Limitations in v1

API v1 does not support:

Creating or deleting teams via API
Managing team members via API
Updating team settings via API
Transferring documents between teams via API
Querying team information via API

These operations must be performed through the Documenso web interface.

Migration to v2

API v2 provides improved team management capabilities. Consider migrating for better team-related functionality.

​Overview

​Team Context

​How Team Context Works

​Team Isolation

​Creating API Tokens for Teams

​Step 1: Access Team Settings

​Step 2: Create Token

​Step 3: Verify Team Context

​Team Resource Access

​Documents

​Templates

​Multi-Team Access

​Team-Level Settings

​Document Settings

​Email Branding

​Folders

​Creating Documents in Folders

​Getting Folder ID

​Team Members

​User vs Team Context

​Audit Trail

​Permissions

​Team-Level Permissions

​Team Webhooks

​Best Practices

​1. Use Descriptive Token Names

​2. Token Rotation

​3. Separate Tokens for Different Environments

​4. Monitor Token Usage

​Rate Limits

​Example: Multi-Team Workflow

​Limitations in v1

​Migration to v2

​See Also

Overview

Team Context

How Team Context Works

Team Isolation

Creating API Tokens for Teams

Step 1: Access Team Settings

Step 2: Create Token

Step 3: Verify Team Context

Team Resource Access

Documents

Templates

Multi-Team Access

Team-Level Settings

Document Settings

Email Branding

Folders

Creating Documents in Folders

Getting Folder ID

Team Members

User vs Team Context

Audit Trail

Permissions

Team-Level Permissions

Team Webhooks

Best Practices

1. Use Descriptive Token Names

2. Token Rotation

3. Separate Tokens for Different Environments

4. Monitor Token Usage

Rate Limits

Example: Multi-Team Workflow

Limitations in v1

Migration to v2

See Also