list_contacts
Retrieve a paginated list of contacts from your BoldSign organization to access signer details for document signing workflows. Filter by search terms and contact type.
Instructions
This tool allows you to retrieve a paginated list of contacts from your BoldSign organization. You can specify the page number to navigate through the results, the number of contacts to display per page, an optional search term to filter contacts, and the type of contacts to retrieve (your personal contacts or all organizational contacts). Contacts are primarily used to store signer details, identified by their unique email address, for use when creating and sending documents for signature within the BoldSign application.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pageSize | Yes | ||
| page | Yes | ||
| searchKey | No | Optional. A string used to filter the contact list. The API will return contacts whose details contain this search term. | |
| contactType | Yes | Optional. Filters the list of contacts based on their type. 'MyContacts' retrieves contacts specifically associated with your account, while 'AllContacts' (default) retrieves all accessible contacts within your organization. | AllContacts |
Implementation Reference
- The primary handler function for the 'list_contacts' tool. It initializes the BoldSign ContactsApi client, calls the contactUserList API with provided pagination, search, and contact type parameters, processes the response, and handles any errors.async function listContactsHandler(payload: ListContactsSchemaType): Promise<McpResponse> { try { const contactsApi = new ContactsApi(); contactsApi.basePath = configuration.getBasePath(); contactsApi.setApiKey(configuration.getApiKey()); const contactsList: ContactsList = await contactsApi.contactUserList( payload.page, payload.pageSize ?? undefined, payload.searchKey ?? undefined, payload.contactType ?? undefined, ); return handleMcpResponse({ data: contactsList, }); } catch (error: any) { return handleMcpError(error); } }
- Zod input schema for validating parameters of the list_contacts tool: pageSize (1-100), page (default 1), optional searchKey, contactType (MyContacts or AllContacts, default AllContacts).const ListContactsSchema = z.object({ pageSize: z.number().int().min(1).max(100), page: z.number().int().min(1).default(1), searchKey: commonSchema.OptionalStringSchema.describe( 'Optional. A string used to filter the contact list. The API will return contacts whose details contain this search term.', ), contactType: z .enum(['MyContacts', 'AllContacts']) .optional() .nullable() .default('AllContacts') .describe( "Optional. Filters the list of contacts based on their type. 'MyContacts' retrieves contacts specifically associated with your account, while 'AllContacts' (default) retrieves all accessible contacts within your organization.", ), });
- src/tools/contactsTools/listContacts.ts:27-36 (registration)Tool registration definition for 'list_contacts'. Specifies the method name, human-readable name and description, references the input schema, and provides a wrapper handler that casts arguments and delegates to the main handler function.export const listContactsToolDefinition: BoldSignTool = { method: ToolNames.ListContacts.toString(), name: 'List contacts', description: 'This tool allows you to retrieve a paginated list of contacts from your BoldSign organization. You can specify the page number to navigate through the results, the number of contacts to display per page, an optional search term to filter contacts, and the type of contacts to retrieve (your personal contacts or all organizational contacts). Contacts are primarily used to store signer details, identified by their unique email address, for use when creating and sending documents for signature within the BoldSign application.', inputSchema: ListContactsSchema, async handler(args: unknown): Promise<McpResponse> { return await listContactsHandler(args as ListContactsSchemaType); }, };
- src/tools/contactsTools/index.ts:5-8 (registration)Local registration of list_contacts tool as part of the contacts API tools array, alongside getContact.export const contactsApiToolsDefinitions: BoldSignTool[] = [ getContactToolDefinition, listContactsToolDefinition, ];
- src/tools/index.ts:8-14 (registration)Global registration where contacts API tools (including list_contacts) are spread into the master list of all BoldSign tool definitions.export const definitions: BoldSignTool[] = [ ...contactsApiToolsDefinitions, ...documentsApiToolsDefinitions, ...templatesApiToolsDefinitions, ...usersApiToolsDefinitions, ...teamsApiToolsDefinitions, ];