teamtailor_list_candidates
Retrieve and filter candidate data from the Teamtailor recruitment platform, enabling users to manage and organize hiring processes efficiently.
Instructions
List and filter candidates.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | ||
| page | No | ||
| pageSize | No |
Implementation Reference
- src/server.ts:32-43 (handler)The MCP tool handler that executes the tool logic: fetches candidates using TeamtailorClient and returns them as JSON text.async ({ pageSize, page, filter}) => { const candidates = await client.listCandidates({ page, perPage: pageSize, filter }); return { content: [ { type: "text", text: JSON.stringify(candidates), } ] } }
- src/server.ts:22-31 (schema)Zod schema for tool input validation: pagination (pageSize, page) and optional date filters.{ pageSize: z.number().default(10), page: z.number().default(1), filter: z.object({ createdAfter: z.string().optional(), createdBefore: z.string().optional(), updatedAfter: z.string().optional(), updatedBefore: z.string().optional(), }).optional(), },
- src/server.ts:19-44 (registration)Registration of the 'teamtailor_list_candidates' tool on the MCP server, specifying name, description, input schema, and handler.server.tool( "teamtailor_list_candidates", "List and filter candidates.", { pageSize: z.number().default(10), page: z.number().default(1), filter: z.object({ createdAfter: z.string().optional(), createdBefore: z.string().optional(), updatedAfter: z.string().optional(), updatedBefore: z.string().optional(), }).optional(), }, async ({ pageSize, page, filter}) => { const candidates = await client.listCandidates({ page, perPage: pageSize, filter }); return { content: [ { type: "text", text: JSON.stringify(candidates), } ] } } );
- src/teamtailor.ts:69-92 (helper)Supporting method in TeamtailorClient that performs the HTTP GET request to list candidates with pagination and filter query parameters.async listCandidates(params: ListCandidatesParams = {}): Promise<Candidate[]> { const url = new URL(`${this.baseUrl}/candidates`); this.addPaginationQueryParams(url, params); if (params?.filter?.createdAfter) { url.searchParams.append('filter[created-at][from]', params.filter.createdAfter); } if (params?.filter?.createdBefore) { url.searchParams.append('filter[created-at][to]', params.filter.createdBefore); } if (params?.filter?.updatedAfter) { url.searchParams.append('filter[updated-at][from]', params.filter.updatedAfter); } if (params?.filter?.updatedBefore) { url.searchParams.append('filter[updated-at][to]', params.filter.updatedBefore); } const body = await this.request<{ data: Candidate[] }>(url); return body.data; }
- src/teamtailor.ts:39-48 (schema)TypeScript interface defining the parameter structure for the listCandidates helper method.export interface ListCandidatesParams { page?: number; perPage?: number; filter?: { createdAfter?: string; createdBefore?: string; updatedAfter?: string; updatedBefore?: string; } }