list_documents
Retrieve and filter documents from your My Documents section with pagination, search, and filtering by status, sender, recipient, date range, and labels.
Instructions
Retrieve a paginated list of documents available in your My Documents section. This API fetches document details such as status, sender, recipient, labels, transmission type, creation date, and modification date, with options for filtering and paginated navigation.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| brandIds | No | Optional. Filters documents based on associated brand IDs. Only documents linked to the specified brands will be retrieved. | |
| dateFilterType | No | Optional. Type of date filter applied to documents. Available options: 'SentBetween' and 'Expiring'. | |
| endDate | No | Optional. End transmit date range of the document. The date should be in a valid date-time format. | |
| labels | Yes | Optional. Labels associated with documents. Used to filter the list by specific document tags. | |
| nextCursor | No | Optional. Cursor value for pagination beyond 10,000 records. Set to the cursor of the last retrieved document. | |
| page | Yes | ||
| pageSize | Yes | ||
| recipients | No | Optional. Filter documents by signer email addresses. One or more signer email IDs can be specified. | |
| searchKey | No | Optional. A search term used to filter the document list. The API will return documents matching details like document title, document ID, sender name, or recipient name. | |
| sentBy | No | Optional. Filter documents by sender email addresses. One or more sender email IDs can be specified. | |
| startDate | No | Optional. Start transmit date range of the document. The date should be in a valid date-time format. | |
| status | Yes | Optional. Filter documents based on their current status. | |
| transmitType | Yes | Optional. Type of transmission to filter documents if the user is both sender, recipient or both. | Both |
Implementation Reference
- Executes the tool logic by instantiating BoldSign DocumentApi, calling listDocuments with input parameters, and handling the response or error.async function listDocumentsHandler(payload: ListDocumentsSchemaType): Promise<McpResponse> { try { const documentApi = new DocumentApi(); documentApi.basePath = configuration.getBasePath(); documentApi.setApiKey(configuration.getApiKey()); const documentRecords: DocumentRecords = await documentApi.listDocuments( payload.page, payload.sentBy ?? undefined, payload.recipients ?? undefined, (payload.transmitType as any) ?? undefined, payload.dateFilterType ?? undefined, payload.pageSize ?? undefined, payload.startDate ?? undefined, payload.status ?? undefined, payload.endDate ?? undefined, payload.searchKey ?? undefined, payload.labels ?? undefined, payload.nextCursor ?? undefined, payload.brandIds ?? undefined, ); return handleMcpResponse({ data: documentRecords, }); } catch (error: any) { return handleMcpError(error); } }
- Zod schema defining the input parameters for the list_documents tool, including pagination, filters, and sorting options.const ListDocumentsSchema = z.object({ pageSize: z.number().int().min(1).max(100), page: z.number().int().min(1).default(1), searchKey: commonSchema.OptionalStringSchema.describe( 'Optional. A search term used to filter the document list. The API will return documents matching details like document title, document ID, sender name, or recipient name.', ), sentBy: z .array(commonSchema.EmailSchema.describe('Email address of the sender.')) .optional() .describe( 'Optional. Filter documents by sender email addresses. One or more sender email IDs can be specified.', ), recipients: z .array(commonSchema.EmailSchema.describe('Email address of the signer.')) .optional() .describe( 'Optional. Filter documents by signer email addresses. One or more signer email IDs can be specified.', ), startDate: commonSchema.OptionalDateSchema.describe( 'Optional. Start transmit date range of the document. The date should be in a valid date-time format.', ), endDate: commonSchema.OptionalDateSchema.describe( 'Optional. End transmit date range of the document. The date should be in a valid date-time format.', ), labels: z .array(z.string().describe('Label of the document.')) .optional() .default([]) .describe( 'Optional. Labels associated with documents. Used to filter the list by specific document tags.', ), transmitType: z .enum(['Sent', 'Received', 'Both']) .optional() .default('Both') .describe( 'Optional. Type of transmission to filter documents if the user is both sender, recipient or both.', ), status: z .array( z .enum([ 'None', 'WaitingForMe', 'WaitingForOthers', 'NeedAttention', 'Completed', 'Declined', 'Revoked', 'Expired', 'Scheduled', 'Draft', ]) .default('None'), ) .optional() .default([]) .describe('Optional. Filter documents based on their current status.'), nextCursor: z .number() .optional() .describe( 'Optional. Cursor value for pagination beyond 10,000 records. Set to the cursor of the last retrieved document.', ), brandIds: z .array(commonSchema.InputIdSchema.describe('Unique identifier (ID) of the brand.')) .optional() .describe( 'Optional. Filters documents based on associated brand IDs. Only documents linked to the specified brands will be retrieved.', ), dateFilterType: z .enum(['SentBetween', 'Expiring']) .optional() .describe( "Optional. Type of date filter applied to documents. Available options: 'SentBetween' and 'Expiring'.", ), });
- src/tools/documentsTools/listDocuments.ts:89-98 (registration)Defines and exports the tool definition for 'list_documents', including name, description, schema, and handler reference. This is imported and registered in higher-level tool collections.export const listDocumentsToolDefinition: BoldSignTool = { method: ToolNames.ListDocuments.toString(), name: 'List documents', description: 'Retrieve a paginated list of documents available in your My Documents section. This API fetches document details such as status, sender, recipient, labels, transmission type, creation date, and modification date, with options for filtering and paginated navigation.', inputSchema: ListDocumentsSchema, async handler(args: unknown): Promise<McpResponse> { return await listDocumentsHandler(args as ListDocumentsSchemaType); }, };
- src/tools/documentsTools/index.ts:8-14 (registration)Registers listDocumentsToolDefinition as part of the documents API tools array, which is further aggregated.export const documentsApiToolsDefinitions: BoldSignTool[] = [ getDocumentPropertiesToolDefinition, listDocumentsToolDefinition, listTeamDocumentsToolDefinition, sendReminderForDocumentToolDefinition, revokeDocumentToolDefinition, ];
- src/tools/index.ts:8-14 (registration)Aggregates all API tool definitions including documentsApiToolsDefinitions into the main tools export for MCP registration.export const definitions: BoldSignTool[] = [ ...contactsApiToolsDefinitions, ...documentsApiToolsDefinitions, ...templatesApiToolsDefinitions, ...usersApiToolsDefinitions, ...teamsApiToolsDefinitions, ];