Teams API

This guide may not reflect the latest endpoints or parameters. For an always up-to-date reference, see the OpenAPI Reference.

Team Object

A team object contains the following properties:

Property	Type	Description
`id`	number	Unique team identifier
`name`	string	Team display name
`url`	string	Unique team URL slug
`createdAt`	string	ISO 8601 timestamp
`avatarImageId`	string \| null	ID of the team's avatar image
`organisationId`	string	ID of the parent organisation
`currentTeamRole`	string	Your role in the team: `ADMIN`, `MANAGER`, `MEMBER`

Example Team Object

{
  "id": 123,
  "name": "Engineering",
  "url": "engineering",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "avatarImageId": null,
  "organisationId": "org_abc123",
  "currentTeamRole": "ADMIN"
}

Team-Scoped API Tokens

API tokens in Documenso are always scoped to a specific team. When you create an API token, it is associated with the team you're currently working in.

How Team Scoping Works

Each API token belongs to exactly one team
All API operations using that token automatically access that team's resources
Documents, templates, and other resources created via the API belong to the token's team
You cannot access resources from other teams with a single token

Creating Team-Scoped Tokens

Navigate to your team's settings

Go to API Tokens

Click Create Token

The token will be scoped to the current team

To work with multiple teams via API, create separate tokens for each team.

Token Permissions

Your API token inherits permissions based on your role in the team:

Role	Permissions
`ADMIN`	Full access to all team resources and settings
`MANAGER`	Create, edit, and delete documents and templates
`MEMBER`	Create and manage own documents

Working with Team Documents

When you use a team-scoped API token, all document operations are automatically scoped to that team.

Create a Team Document

Documents created with a team token belong to that team:

curl -X POST "https://app.documenso.com/api/v2/envelope/create" \
  -H "Authorization: api_team_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: multipart/form-data" \
  -F 'payload={
    "type": "DOCUMENT",
    "title": "Team Contract",
    "recipients": [
      {
        "email": "signer@example.com",
        "name": "John Smith",
        "role": "SIGNER"
      }
    ]
  }' \
  -F "files=@./contract.pdf;type=application/pdf"

const TEAM_API_TOKEN = process.env.DOCUMENSO_TEAM_API_TOKEN;

const form = new FormData();

const payload = {
  type: 'DOCUMENT',
  title: 'Team Contract',
  recipients: [
    {
      email: 'signer@example.com',
      name: 'John Smith',
      role: 'SIGNER',
    },
  ],
};

form.append('payload', JSON.stringify(payload));
form.append('files', fs.createReadStream('./contract.pdf'), {
  contentType: 'application/pdf',
});

const response = await fetch('https://app.documenso.com/api/v2/envelope/create', {
  method: 'POST',
  headers: {
    Authorization: TEAM_API_TOKEN,
  },
  body: form,
});

const { id } = await response.json();
console.log('Created team document:', id);

List Team Documents

Retrieve all documents belonging to the team:

# List all team documents
curl -X GET "https://app.documenso.com/api/v2/envelope" \
  -H "Authorization: api_team_xxxxxxxxxxxxxxxx"

# Filter by status
curl -X GET "https://app.documenso.com/api/v2/envelope?status=PENDING" \
  -H "Authorization: api_team_xxxxxxxxxxxxxxxx"

const response = await fetch('https://app.documenso.com/api/v2/envelope', {
  method: 'GET',
  headers: {
    Authorization: TEAM_API_TOKEN,
  },
});

const { data, pagination } = await response.json();
console.log(`Found ${pagination.totalItems} team documents`);

Working with Team Templates

Templates created with a team token are shared across the team.

Create a Team Template

curl -X POST "https://app.documenso.com/api/v2/template/create" \
  -H "Authorization: api_team_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: multipart/form-data" \
  -F 'payload={
    "title": "NDA Template",
    "recipients": [
      {
        "email": "placeholder@example.com",
        "name": "Signer",
        "role": "SIGNER",
        "fields": [
          {
            "identifier": 0,
            "type": "SIGNATURE",
            "page": 1,
            "positionX": 10,
            "positionY": 80,
            "width": 30,
            "height": 5
          }
        ]
      }
    ]
  }' \
  -F "files=@./nda-template.pdf;type=application/pdf"

const form = new FormData();

const payload = {
  title: 'NDA Template',
  recipients: [
    {
      email: 'placeholder@example.com',
      name: 'Signer',
      role: 'SIGNER',
      fields: [
        {
          identifier: 0,
          type: 'SIGNATURE',
          page: 1,
          positionX: 10,
          positionY: 80,
          width: 30,
          height: 5,
        },
      ],
    },
  ],
};

form.append('payload', JSON.stringify(payload));
form.append('files', fs.createReadStream('./nda-template.pdf'), {
  contentType: 'application/pdf',
});

const response = await fetch('https://app.documenso.com/api/v2/template/create', {
  method: 'POST',
  headers: {
    Authorization: TEAM_API_TOKEN,
  },
  body: form,
});

const template = await response.json();
console.log('Created team template:', template.id);

List Team Templates

curl -X GET "https://app.documenso.com/api/v2/template" \
  -H "Authorization: api_team_xxxxxxxxxxxxxxxx"

const response = await fetch('https://app.documenso.com/api/v2/template', {
  method: 'GET',
  headers: {
    Authorization: TEAM_API_TOKEN,
  },
});

const { data } = await response.json();
console.log('Team templates:', data);

Team Member Roles

Role	Description
`ADMIN`	Full control over team settings, members, and all resources
`MANAGER`	Can manage documents, templates, and view team resources
`MEMBER`	Can create and manage their own documents within the team

Document Visibility

Team documents have visibility settings that control who can access them:

Visibility	Description
`EVERYONE`	All team members can view the document
`MANAGER_AND_ABOVE`	Only managers and admins can view
`ADMIN`	Only admins can view

Set visibility when creating a document:

const payload = {
  type: 'DOCUMENT',
  title: 'Confidential Agreement',
  visibility: 'ADMIN', // Only team admins can view
  recipients: [...],
};

Multi-Team Workflow

To work with multiple teams, create and manage separate API tokens for each team.

Example: Sync Documents Across Teams

// Tokens for different teams
const SALES_TEAM_TOKEN = process.env.SALES_TEAM_API_TOKEN;
const LEGAL_TEAM_TOKEN = process.env.LEGAL_TEAM_API_TOKEN;

// Get pending documents from sales team
const salesResponse = await fetch('https://app.documenso.com/api/v2/envelope?status=PENDING', {
  headers: { Authorization: SALES_TEAM_TOKEN },
});
const salesDocs = await salesResponse.json();

// Get completed documents from legal team
const legalResponse = await fetch('https://app.documenso.com/api/v2/envelope?status=COMPLETED', {
  headers: { Authorization: LEGAL_TEAM_TOKEN },
});
const legalDocs = await legalResponse.json();

console.log(`Sales team: ${salesDocs.pagination.totalItems} pending`);
console.log(`Legal team: ${legalDocs.pagination.totalItems} completed`);

Error Responses

Status	Description
`401`	Invalid or expired API token
`403`	Token doesn't have permission for this operation
`404`	Resource not found or not accessible by this team

Example Error Response

{
  "message": "You do not have permission to access this resource"
}

API tokens can only access resources belonging to their associated team. Attempting to access resources from another team returns a 403 or 404 error.