# FeedbackPulse Developer Documentation --- ## Pages - [FeedbackPulse Developer Docs](https://feedbackpulse.com/help/developers.md) - [FeedbackPulse REST API](https://feedbackpulse.com/help/developers/api.md) - [Create an employee](https://feedbackpulse.com/help/developers/api/reference/create-employee.md) - [Get an employee](https://feedbackpulse.com/help/developers/api/reference/get-employee.md) - [List employees](https://feedbackpulse.com/help/developers/api/reference/list-employees.md) - [Sync employees](https://feedbackpulse.com/help/developers/api/reference/sync-employees.md) - [FeedbackPulse MCP](https://feedbackpulse.com/help/developers/mcp.md) - [FeedbackPulse for Zapier](https://feedbackpulse.com/help/developers/zapier.md) --- # FeedbackPulse Developer Docs > Integrate with FeedbackPulse using the REST API, connect an AI client over MCP, or use Zapier for employee workflows. Yes, FeedbackPulse has a REST API. A workspace Admin creates an API key in **Settings > Integrations > API Clients**. The published operations let you list, read, create, and sync employee records from an HR system. [Sync employees with the REST API](https://feedbackpulse.com/help/developers/api/reference/sync-employees.md)Send your first request, then check the result for each employee. [Create an API key and set up authentication](https://feedbackpulse.com/help/developers/api.md) ## Connect with MCP or Zapier [Section titled “Connect with MCP or Zapier”](#connect-with-mcp-or-zapier) [MCP](https://feedbackpulse.com/help/developers/mcp.md)Find server URLs, OAuth scopes, and tools for your AI client. [Zapier](https://feedbackpulse.com/help/developers/zapier.md)Create or update employees from your HR system with a Zap. For Slack or Claude setup, see the [Help Center integration guides](https://feedbackpulse.com/help/integrations.md). ## Documentation for AI agents [Section titled “Documentation for AI agents”](#documentation-for-ai-agents) Use the [developer documentation bundle](https://feedbackpulse.com/help/llms-developers.txt) to read this section as text. Append `.md` to a page path in place of the trailing slash, for example [the employee sync reference in Markdown](https://feedbackpulse.com/help/developers/api/reference/sync-employees.md). The [OpenAPI YAML](https://feedbackpulse.com/help/developers/api/openapi-v1.yaml) describes the published operations for API clients and code generation. --- # FeedbackPulse REST API > Create a workspace API key for the FeedbackPulse REST API, authenticate requests, interpret errors and rate limits, and understand versioning and pagination. Send API requests to `https://api.feedbackpulse.com` with a workspace API key. A workspace Admin creates the key in FeedbackPulse, as described in [Authentication](#authentication). * [List employees](https://feedbackpulse.com/help/developers/api/reference/list-employees.md) * [Get an employee](https://feedbackpulse.com/help/developers/api/reference/get-employee.md) * [Create an employee](https://feedbackpulse.com/help/developers/api/reference/create-employee.md) * [Sync employees](https://feedbackpulse.com/help/developers/api/reference/sync-employees.md) * [Download the OpenAPI 3.1 contract](https://feedbackpulse.com/help/developers/api/openapi-v1.yaml) ## Authentication [Section titled “Authentication”](#authentication) A workspace Admin opens **Settings > Integrations > API Clients**, chooses **Create API Client**, and selects the scopes the integration needs. Copy the key into your secret store. Select `employees:read` to list or read employees, `employees:write` to create them, and `employees:sync` to sync them. Send the key in the `Authorization: Bearer ` header over HTTPS. The REST API requires a workspace-owned API-client key. The [token management guide](https://feedbackpulse.com/help/integrations/token-management.md) covers personal tokens for MCP clients. ## Errors [Section titled “Errors”](#errors) Send `Accept: application/json`. A `401` response has a `message` field. Other API errors can include `error` and `error_description`. Validation failures can also include an `errors` object with field-level details. The employee sync response can include row-level failures in a successful HTTP response. | Status | What to check | | ------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | `401` | The bearer key is present and valid. | | `403` | The key belongs to an API client in an active workspace and has the required scope. | | `409` | The request with this idempotency key is in progress, or the key was used with a different payload. Check the error code before retrying. | | `422` | Correct invalid request fields or an invalid idempotency key. | | `429` | Wait for the `Retry-After` interval before sending the request again. | If an error continues after these checks, [contact support](https://feedbackpulse.com/help/troubleshooting/contact-support.md). ## Rate limits [Section titled “Rate limits”](#rate-limits) The default limit is 120 read requests and 30 write requests per minute, counted separately per API-client key. A rate-limited request returns `429`. For a sync request retried after a timeout, a `429`, or a server error, send the same payload and `Idempotency-Key`. The API stores every response for an idempotency key except a `429` or a server error, and replays a stored response, including a `422`, for a retry with the same key and payload. After you correct a rejected request, send it with a new `Idempotency-Key`. ## Versioning and pagination [Section titled “Versioning and pagination”](#versioning-and-pagination) The major version is part of the URL path, such as `/v1`. List operations use page numbers (`page`) and page size (`per_page`). To read the next page, send the same `per_page` and increase `page` by 1. `meta.last_page` is the number of the last page. Employee sync accepts a batch and returns a result per row in one response. --- # Create an employee > Create one employee with the FeedbackPulse REST API, optionally assign a manager, and choose whether to send an account invitation. POST `/v1/employees` Creates one employee in your workspace. If the email belongs to an employee who was deleted from the workspace, the API restores that employee with access disabled. Do not set `send_invitation` to `true` for such an email: the API then returns `422` and restores nothing. Requires a [workspace API-client key](https://feedbackpulse.com/help/developers/api.md#authentication) with the `employees:write` scope. ## Example request [Section titled “Example request”](#example-request) Run this example in a test workspace. Replace `alex@example.com` with an email address that no FeedbackPulse workspace uses. The example creates an employee and sends no invitation. Use a distinct idempotency key for each new employee and keep it the same when retrying that request. ```bash curl --request POST 'https://api.feedbackpulse.com/v1/employees' \ --header "Authorization: Bearer $FEEDBACKPULSE_API_KEY" \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: example-hr:hire-123' \ --data '{ "name": "Alex Example", "email": "alex@example.com", "type": "full-time", "job_title": "Product Designer" }' ``` ## Example response [Section titled “Example response”](#example-response) HTTP `201 Created` ```json { "data": { "id": "emp_01J9EXAMPLE", "name": "Alex Example", "email": "alex@example.com", "job_title": "Product Designer", "department": null, "employee_number": null, "type": "full-time", "employment_status": "active", "account_status": "not-invited", "access_status": "enabled", "is_manager": false, "hire_date": null, "termination_date": null, "created_at": "2026-11-02T09:00:00+00:00", "updated_at": "2026-11-02T09:00:00+00:00", "manager": null } } ``` ## Request [Section titled “Request”](#request) Send a JSON object. To assign a manager, set `manager_id` to an employee `id` from [List employees](https://feedbackpulse.com/help/developers/api/reference/list-employees.md). Set `send_invitation` to `true` to email an account invitation. Without it, FeedbackPulse sends no invitation. ### Headers [Section titled “Headers”](#headers) | Header | Required | Description | | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Authorization` | Yes | Bearer API-client key with `employees:write`. | | `Content-Type` | Yes | `application/json` | | `Idempotency-Key` | No | Replays the original response when the same API client sends the same key and same request fingerprint to the same POST route. Rate-limited (429) and server error (5xx) responses are not stored, so retry them with the same key. A key whose request never finished returns 409 `idempotency_key_in_progress` for 10 minutes; after that, the next request with the same key and payload runs again. | ### JSON body [Section titled “JSON body”](#json-body) | Field | Type | Required | Description | | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | | `name` | string | Yes | | | `email` | string | Yes | Format: `email`. | | `job_title` | string or null | No | | | `department` | string or null | No | | | `employee_number` | string or null | No | | | `type` | string | Yes | Values: `full-time`, `part-time`, `contractor`. | | `employment_status` | string | No | Rehire changes employment only. Access requires explicit admin reinstatement. Values: `active`, `terminated`. | | `hire_date` | string or null | No | Format: `date`. | | `termination_date` | string or null | No | Format: `date`. | | `is_manager` | boolean | No | | | `manager_id` | string or null | No | Canonical public employee identifier for the manager, for example `emp_01H...`. Internal numeric ids are rejected. | | `send_invitation` | boolean | No | | ## Response [Section titled “Response”](#response) A `201` response contains the new employee in `data`. If the invitation email fails, the employee is still created and `meta.warnings` contains `invitation_send_failed`. A `422` response can also mean that the email is already in use, in this or another FeedbackPulse workspace, or that the workspace is at the employee limit of its plan. | Field | Type | Required | Description | | ------------------------ | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `data` | object | Yes | | | `data.id` | string | Yes | Canonical public employee identifier, for example `emp_01H...`. | | `data.name` | string | Yes | | | `data.email` | string | Yes | Format: `email`. | | `data.job_title` | string or null | No | | | `data.department` | string or null | No | | | `data.employee_number` | string or null | No | | | `data.type` | string or null | No | | | `data.employment_status` | string | Yes | Values: `active`, `terminated`. | | `data.account_status` | string or null | Yes | Null means activation history is unknown for a legacy terminated employee. Values: `not-invited`, `invited`, `active`, `null`. | | `data.access_status` | string | Yes | Values: `enabled`, `disabled`. | | `data.is_manager` | boolean | Yes | | | `data.hire_date` | string or null | No | Format: `date`. | | `data.termination_date` | string or null | No | Format: `date`. | | `data.created_at` | string | Yes | Format: `date-time`. | | `data.updated_at` | string | Yes | Format: `date-time`. | | `data.manager` | object or null | No | | | `data.manager.id` | string | No | Canonical public employee identifier, for example `emp_01H...`. | | `data.manager.name` | string | No | | | `meta` | object | No | | | `meta.warnings` | array | No | | ## Status codes [Section titled “Status codes”](#status-codes) | HTTP status | Meaning | | ----------- | ---------------------------------------------------------------------------- | | `201` | Employee created | | `401` | Missing or invalid bearer token | | `403` | Authenticated but lacking the required API client scope | | `409` | Idempotency key reused with a different request payload or still in progress | | `422` | Validation failed or the idempotency key is invalid | | `429` | Rate limit exceeded | See [API errors and rate limits](https://feedbackpulse.com/help/developers/api.md#errors) or [download the OpenAPI contract](https://feedbackpulse.com/help/developers/api/openapi-v1.yaml). --- # Get an employee > Read one employee by ID with the FeedbackPulse REST API. GET `/v1/employees/{employee}` Returns one employee in your workspace by the public employee `id`. Requires a [workspace API-client key](https://feedbackpulse.com/help/developers/api.md#authentication) with the `employees:read` scope. ## Example request [Section titled “Example request”](#example-request) This example reads one employee. It does not change any records. Replace the ID with an `id` from [List employees](https://feedbackpulse.com/help/developers/api/reference/list-employees.md) or from the result of a [sync](https://feedbackpulse.com/help/developers/api/reference/sync-employees.md). ```bash curl --request GET 'https://api.feedbackpulse.com/v1/employees/emp_01J9EXAMPLE' \ --header "Authorization: Bearer $FEEDBACKPULSE_API_KEY" \ --header 'Accept: application/json' ``` ## Example response [Section titled “Example response”](#example-response) HTTP `200 OK` ```json { "data": { "id": "emp_01J9EXAMPLE", "name": "Alex Example", "email": "alex@example.com", "job_title": "Product Designer", "department": null, "employee_number": null, "type": "full-time", "employment_status": "active", "account_status": "not-invited", "access_status": "enabled", "is_manager": false, "hire_date": null, "termination_date": null, "created_at": "2026-11-02T09:00:00+00:00", "updated_at": "2026-11-02T09:00:00+00:00", "manager": null } } ``` ## Request [Section titled “Request”](#request) Put the employee `id` in the path. The request has no body and no query parameters. ### Headers [Section titled “Headers”](#headers) | Header | Required | Description | | --------------- | -------- | -------------------------------------------- | | `Authorization` | Yes | Bearer API-client key with `employees:read`. | ### Path parameters [Section titled “Path parameters”](#path-parameters) | Parameter | Type | Required | Description | | ---------- | ------ | -------- | --------------------------------------------------------------- | | `employee` | string | Yes | Canonical public employee identifier, for example `emp_01H...`. | ## Response [Section titled “Response”](#response) A `200` response contains the employee in `data`. A `404` response means that no employee with this `id` exists in the workspace of the API key. | Field | Type | Required | Description | | ------------------------ | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `data` | object | Yes | | | `data.id` | string | Yes | Canonical public employee identifier, for example `emp_01H...`. | | `data.name` | string | Yes | | | `data.email` | string | Yes | Format: `email`. | | `data.job_title` | string or null | No | | | `data.department` | string or null | No | | | `data.employee_number` | string or null | No | | | `data.type` | string or null | No | | | `data.employment_status` | string | Yes | Values: `active`, `terminated`. | | `data.account_status` | string or null | Yes | Null means activation history is unknown for a legacy terminated employee. Values: `not-invited`, `invited`, `active`, `null`. | | `data.access_status` | string | Yes | Values: `enabled`, `disabled`. | | `data.is_manager` | boolean | Yes | | | `data.hire_date` | string or null | No | Format: `date`. | | `data.termination_date` | string or null | No | Format: `date`. | | `data.created_at` | string | Yes | Format: `date-time`. | | `data.updated_at` | string | Yes | Format: `date-time`. | | `data.manager` | object or null | No | | | `data.manager.id` | string | No | Canonical public employee identifier, for example `emp_01H...`. | | `data.manager.name` | string | No | | | `meta` | object | No | | | `meta.warnings` | array | No | | ## Status codes [Section titled “Status codes”](#status-codes) | HTTP status | Meaning | | ----------- | ------------------------------------------------------- | | `200` | Employee found | | `401` | Missing or invalid bearer token | | `403` | Authenticated but lacking the required API client scope | | `404` | Resource not found in the API client’s tenant scope | | `429` | Rate limit exceeded | See [API errors and rate limits](https://feedbackpulse.com/help/developers/api.md#errors) or [download the OpenAPI contract](https://feedbackpulse.com/help/developers/api/openapi-v1.yaml). --- # List employees > List the employees in a workspace with the FeedbackPulse REST API, one page at a time and sorted by name. GET `/v1/employees` Returns the employees in your workspace, one page at a time, sorted by name. The list includes terminated employees. It does not include deleted employees. Requires a [workspace API-client key](https://feedbackpulse.com/help/developers/api.md#authentication) with the `employees:read` scope. ## Example request [Section titled “Example request”](#example-request) This example reads the first page of up to 25 employees. It does not change any records. ```bash curl --request GET 'https://api.feedbackpulse.com/v1/employees?page=1&per_page=25' \ --header "Authorization: Bearer $FEEDBACKPULSE_API_KEY" \ --header 'Accept: application/json' ``` ## Example response [Section titled “Example response”](#example-response) HTTP `200 OK` ```json { "data": [ { "id": "emp_01J9EXAMPLE", "name": "Alex Example", "email": "alex@example.com", "job_title": "Product Designer", "department": null, "employee_number": null, "type": "full-time", "employment_status": "active", "account_status": "not-invited", "access_status": "enabled", "is_manager": false, "hire_date": null, "termination_date": null, "created_at": "2026-11-02T09:00:00+00:00", "updated_at": "2026-11-02T09:00:00+00:00", "manager": null } ], "links": { "first": "https://api.feedbackpulse.com/v1/employees?page=1", "last": "https://api.feedbackpulse.com/v1/employees?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "path": "https://api.feedbackpulse.com/v1/employees", "per_page": 25, "to": 1, "total": 1 } } ``` ## Request [Section titled “Request”](#request) Send the parameters in the query string. To read every employee, keep the same `per_page` and increase `page` by 1 until `page` equals `meta.last_page`. ### Headers [Section titled “Headers”](#headers) | Header | Required | Description | | --------------- | -------- | -------------------------------------------- | | `Authorization` | Yes | Bearer API-client key with `employees:read`. | ### Query parameters [Section titled “Query parameters”](#query-parameters) | Parameter | Type | Required | Description | | ---------- | ------- | -------- | ---------------------------------------------------------- | | `page` | integer | No | Page number to return, starting at 1. Default: `1`. | | `per_page` | integer | No | Number of employees per page. Range: 1–100. Default: `25`. | ## Response [Section titled “Response”](#response) A `200` response contains up to `per_page` employees in `data`. `meta.total` counts the employees on all pages. Use an employee `id` as the `manager_id` when you [create an employee](https://feedbackpulse.com/help/developers/api/reference/create-employee.md). | Field | Type | Required | Description | | -------------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `data` | array | Yes | | | `data[].id` | string | Yes | Canonical public employee identifier, for example `emp_01H...`. | | `data[].name` | string | Yes | | | `data[].email` | string | Yes | Format: `email`. | | `data[].job_title` | string or null | No | | | `data[].department` | string or null | No | | | `data[].employee_number` | string or null | No | | | `data[].type` | string or null | No | | | `data[].employment_status` | string | Yes | Values: `active`, `terminated`. | | `data[].account_status` | string or null | Yes | Null means activation history is unknown for a legacy terminated employee. Values: `not-invited`, `invited`, `active`, `null`. | | `data[].access_status` | string | Yes | Values: `enabled`, `disabled`. | | `data[].is_manager` | boolean | Yes | | | `data[].hire_date` | string or null | No | Format: `date`. | | `data[].termination_date` | string or null | No | Format: `date`. | | `data[].created_at` | string | Yes | Format: `date-time`. | | `data[].updated_at` | string | Yes | Format: `date-time`. | | `data[].manager` | object or null | No | | | `data[].manager.id` | string | No | Canonical public employee identifier, for example `emp_01H...`. | | `data[].manager.name` | string | No | | | `meta` | object | Yes | | | `meta.current_page` | integer | No | | | `meta.from` | integer or null | No | | | `meta.last_page` | integer | No | | | `meta.path` | string | No | | | `meta.per_page` | integer | No | | | `meta.to` | integer or null | No | | | `meta.total` | integer | No | | | `links` | object | No | | ## Status codes [Section titled “Status codes”](#status-codes) | HTTP status | Meaning | | ----------- | ------------------------------------------------------- | | `200` | Paginated employee list | | `401` | Missing or invalid bearer token | | `403` | Authenticated but lacking the required API client scope | | `429` | Rate limit exceeded | See [API errors and rate limits](https://feedbackpulse.com/help/developers/api.md#errors) or [download the OpenAPI contract](https://feedbackpulse.com/help/developers/api/openapi-v1.yaml). --- # Sync employees > Create or update employees in a batch with the FeedbackPulse REST API. Check the result for each employee. POST `/v1/employees/sync` Synchronously creates or updates employees from a canonical batch payload. The response contains per-row actions, warnings, and summarized totals. A row that would terminate the last active admin of the workspace is not applied. It is reported as `errored` with the code `last_active_admin` in `errors`, and the request still answers 200. A batch that terminates every admin therefore keeps one of them active. A refused row is stored with the rest of the response: a retry with the same Idempotency-Key replays it even after another admin exists, so retry with a new key. Requires a [workspace API-client key](https://feedbackpulse.com/help/developers/api.md#authentication) with the `employees:sync` scope. ## Example request [Section titled “Example request”](#example-request) Run this example in a test workspace. It creates or updates a record. Use a distinct idempotency key for each new sync and keep it the same when retrying that sync. ```bash curl --request POST 'https://api.feedbackpulse.com/v1/employees/sync' \ --header "Authorization: Bearer $FEEDBACKPULSE_API_KEY" \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: example-hr:event-123' \ --data '{ "source": "example-hr", "employees": [ { "external_id": "hr-123", "email": "alex@example.com", "name": "Alex Example" } ] }' ``` ## Example response [Section titled “Example response”](#example-response) HTTP `200 OK` ```json { "summary": { "total": 1, "created": 1, "updated": 0, "skipped": 0, "errored": 0 }, "results": [ { "row": 1, "action": "created", "employee_id": "emp_01J9EXAMPLE", "email": "alex@example.com", "warnings": [] } ], "errors": [] } ``` ## Request [Section titled “Request”](#request) Send a JSON object. Use the same `source` and `external_id` for the same employee across requests. A manager reference can use an external ID in the same source or a work email. ### Headers [Section titled “Headers”](#headers) | Header | Required | Description | | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Authorization` | Yes | Bearer API-client key with `employees:sync`. | | `Content-Type` | Yes | `application/json` | | `Idempotency-Key` | No | Replays the original response when the same API client sends the same key and same request fingerprint to the same POST route. Rate-limited (429) and server error (5xx) responses are not stored, so retry them with the same key. A key whose request never finished returns 409 `idempotency_key_in_progress` for 10 minutes; after that, the next request with the same key and payload runs again. | ### JSON body [Section titled “JSON body”](#json-body) | Field | Type | Required | Description | | --------------------------------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `source` | string or null | No | Required when any employee row or manager reference uses `external_id`. | | `employees` | array | Yes | 1–100 items. | | `employees[].external_id` | string or null | No | | | `employees[].email` | string | Yes | Format: `email`. | | `employees[].name` | string or null | No | | | `employees[].employee_number` | string or null | No | | | `employees[].job_title` | string or null | No | | | `employees[].department` | string or null | No | | | `employees[].type` | string | No | Values: `full-time`, `part-time`, `contractor`. | | `employees[].employment_status` | string | No | Rehire never restores access or sends invitations. `terminated` is reported as an `errored` row with the code `last_active_admin` for the last active admin. Values: `active`, `terminated`. | | `employees[].send_invitation` | boolean | No | Explicit invitation command, rejected while access is disabled or account is activated. Default: `false`. | | `employees[].hire_date` | string or null | No | Format: `date`. | | `employees[].termination_date` | string or null | No | Format: `date`. | | `employees[].is_manager` | boolean | No | | | `employees[].manager` | null or object | No | Requires `external_id` or `email`. | | `employees[].manager.external_id` | string or null | No | | | `employees[].manager.email` | string or null | No | Format: `email`. | ## Response [Section titled “Response”](#response) A `200` response can contain skipped or failed rows. Check each `results[].action` and match entries in `errors` using the one-based row number. | Field | Type | Required | Description | | ----------------------- | -------------- | -------- | ----------------------------------------------------------------- | | `summary` | object | Yes | | | `summary.total` | integer | Yes | | | `summary.created` | integer | Yes | | | `summary.updated` | integer | Yes | | | `summary.skipped` | integer | Yes | | | `summary.errored` | integer | Yes | | | `results` | array | Yes | | | `results[].row` | integer | Yes | | | `results[].action` | string | Yes | Values: `created`, `updated`, `skipped`, `errored`. | | `results[].employee_id` | string or null | No | | | `results[].email` | string | Yes | Format: `email`. | | `results[].warnings` | array | Yes | | | `errors` | array | Yes | | | `errors[].row` | integer | Yes | | | `errors[].code` | string | Yes | Machine-readable row error code, for example `last_active_admin`. | | `errors[].message` | string | Yes | | ## Status codes [Section titled “Status codes”](#status-codes) | HTTP status | Meaning | | ----------- | ---------------------------------------------------------------------------- | | `200` | Sync completed | | `401` | Missing or invalid bearer token | | `403` | Authenticated but lacking the required API client scope | | `409` | Idempotency key reused with a different request payload or still in progress | | `422` | Validation failed or the idempotency key is invalid | | `429` | Rate limit exceeded | See [API errors and rate limits](https://feedbackpulse.com/help/developers/api.md#errors) or [download the OpenAPI contract](https://feedbackpulse.com/help/developers/api/openapi-v1.yaml). --- # FeedbackPulse MCP > Connect to FeedbackPulse MCP servers and look up OAuth discovery URLs, scopes, tools, prompts, and role requirements. FeedbackPulse provides a workspace MCP server for HR workflows and an Employee Surveys server for designing surveys. For client setup, see [AI Assistants & MCP](https://feedbackpulse.com/help/integrations/mcp-overview.md). ## Server URLs and OAuth [Section titled “Server URLs and OAuth”](#server-urls-and-oauth) | Server | Endpoint | OAuth protected resource metadata | | ---------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | FeedbackPulse | `https://app.feedbackpulse.com/mcp` | [Discovery document](https://app.feedbackpulse.com/.well-known/oauth-protected-resource/mcp) | | Employee Surveys | `https://app.feedbackpulse.com/mcp/employee-surveys` | [Discovery document](https://app.feedbackpulse.com/.well-known/oauth-protected-resource/mcp/employee-surveys) | Use the authorization server advertised in the discovery document. Both servers use authorization code with PKCE (`S256`). * **FeedbackPulse workspace server.** OAuth grants `mcp:use`. Admin write tools require a [personal MCP token](https://feedbackpulse.com/help/integrations/token-management.md) with `mcp:write`. Tool access also depends on the user’s role and the organization’s MCP settings. * **Employee Surveys server.** Preview a survey design before signing in. Saving an approved survey template or unlaunched draft requires OAuth with `survey-design:persist`. Use `tools/list` to retrieve the server’s current input schemas. The tool tables below describe workflows and access requirements. ## Employee Surveys design tools [Section titled “Employee Surveys design tools”](#employee-surveys-design-tools) | Tool | When to call it | | --------------------- | ------------------------------------------------------------------------------------------------------------ | | `preview_survey` | Validate a complete English survey proposal and return the preview for the user to review. | | `prepare_survey_save` | Request a save receipt after the user approves the exact preview and chooses a template or unlaunched draft. | | `save_survey` | Save the approved design using the receipt after the user signs in and authorizes the connection. | The remaining tools and guided prompts are for the FeedbackPulse workspace server. ## Survey tools [Section titled “Survey tools”](#survey-tools) Note Surveys are report-gated in FeedbackPulse: only Admins can view survey reports through MCP. Managers do not have survey reporting access through MCP at all, even for their own direct or indirect reports. | Tool | What it returns | Scope | Role | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- | | `list_surveys` | Surveys with status, response rate, and schedule. Filters: `status` (active, completed, expired, scheduled, draft, cancelled, archived). Cursor pagination. | `mcp:use` | Admin only | | `get_survey_detail` | Metadata for one survey: status, anonymity, response rate, template type, AI summary availability. Requires `survey_id`. | `mcp:use` | Admin only | | `get_survey_results` | Per-question aggregates: Likert averages, eNPS scores with promoter/passive/detractor breakdown, benchmark context, previous/year-ago eNPS deltas when available, yes/no percentages, text responses (up to 50). Anonymous surveys suppress text responses below the privacy threshold. | `mcp:use` | Admin only | | `get_survey_summary` | AI-generated summary with themes and insights from text responses. Requires `survey_id`. | `mcp:use` | Admin only | | `create_survey_draft` | Creates a real, unlaunched draft survey from an existing template and returns a dashboard edit link. Does not launch the survey, finalize scheduling, snapshot questions, or notify employees. Requires `template_id` and `name`. | `mcp:write` | Admin only | | `list_survey_templates` | Templates with name, type, and question count. Filter by `type`. Cursor pagination. | `mcp:use` | Admin only | | `get_survey_template` | Full template including all questions, types, and display options. Use before updating. Requires `survey_template_id`. | `mcp:use` | Admin only | | `create_survey_template` | Creates a new template. Supports question types: `likert`, `yes_no`, `text`, `enps`. Template types: pulse, onboarding, exit_interview, enps, leadership, engagement, custom. No survey is launched. | `mcp:write` | Admin only | | `update_survey_template` | Updates a template’s name, description, anonymity, type, or questions. Providing a `questions` array replaces all existing questions. Previously launched surveys are not affected. | `mcp:write` | Admin only | ## Review tools [Section titled “Review tools”](#review-tools) | Tool | What it returns | Scope | Role | Plan | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------------- | ---- | | `list_review_cycles` | Review cycles with completion statistics for performance and peer reviews. Use to find cycle IDs. | `mcp:use` | Admin, Manager | Any | | `get_review_cycle_summary` | Department-by-department breakdown: completed, in-progress, not-started, and overdue counts. Requires `review_cycle_id`. | `mcp:use` | Admin, Manager | Any | | `list_perf_reviews` | Per-employee performance review status. Defaults to the active cycle. Filters: `status` (completed, in_progress, not_started, overdue), `department`, `search`, `employee_id`. Managers see their reports only. | `mcp:use` | Admin, Manager | Paid | | `list_peer_reviews` | Peer reviews with status. Anonymous reviewers hidden. Filters: `review_cycle_id`, `status`. Cursor pagination. | `mcp:use` | Admin, Manager | Any | | `get_peer_review_stats` | Aggregate stats: completion rate, average ratings, overdue count. Requires `review_cycle_id`. | `mcp:use` | Admin, Manager | Any | Note `list_perf_reviews` returns an error if performance reviews are not enabled on your plan. ## Recognition tools [Section titled “Recognition tools”](#recognition-tools) Note Recognitions are also report-gated: only Admins can view recognition data through MCP. Managers do not have recognition reporting access through MCP at all. | Tool | What it returns | Scope | Role | Plan | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ---------- | ---- | | `get_recognition_stats` | Aggregate metrics: total count, this-month count, kudos vs constructive breakdown, top 5 recipients. Filters: `type` (kudos, constructive), `department`, `period` (today, 7days, 30days, quarter) or custom `from`/`to` dates, `recipient_id`. | `mcp:use` | Admin only | Paid | | `list_recognitions` | Individual recognition records with feedback text, including pending recognitions. Anonymous submitters hidden. Same filters as `get_recognition_stats`. Cursor pagination. | `mcp:use` | Admin only | Paid | | `get_recognition` | Full plain text for one recognition. Requires the `id` returned by `list_recognitions`. | `mcp:use` | Admin only | Paid | Note Recognition tools require the Recognition feature on your plan. ## Employee tools [Section titled “Employee tools”](#employee-tools) | Tool | What it returns | Scope | Role | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------------- | | `list_employees` | Employees with name, email, job title, department, status, and manager. Filters: `status` (active, terminated, invited, not-invited), `department` (exact match), `search` (name, email, or title partial match). Managers see direct and indirect reports only. Cursor pagination. | `mcp:use` | Admin, Manager | ## Administration tools [Section titled “Administration tools”](#administration-tools) These tools audit MCP usage itself and are available to Admins only. | Tool | What it returns | Scope | Role | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ---------- | | `list_tokens` | The organisation’s MCP personal API tokens: name, owner, last four characters, and last-used/created timestamps, for the 100 most recent tokens. Token secrets are never returned. Read-only; tokens are created or revoked in **Settings > Integrations**. | `mcp:use` | Admin only | | `get_activity_log` | The organisation’s MCP audit trail: tool name, arguments, calling user, response status, duration, and timestamp, newest first. Includes the calling Admin’s own tool calls. Optional `user_id` filter. Cursor pagination. | `mcp:use` | Admin only | ## Guided prompts [Section titled “Guided prompts”](#guided-prompts) Guided prompts provide structured, multi-step workflows. To run a prompt, ask your AI assistant by name, for example: *“Run the team pulse for the Engineering department.”* ### `analyze_survey_results` [Section titled “analyze_survey_results”](#analyze_survey_results) Analyses recent surveys for a team or the whole organisation. Retrieves results and AI summaries, identifies low-scoring questions, and produces actionable recommendations. | Argument | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------ | | `survey_id` | No | Analyse a specific survey. If provided, `department` and `period` are ignored. | | `department` | No | Filter to a specific department. | | `period` | No | Look-back window, e.g. “last 90 days”. Defaults to last 90 days. | ### `engagement_health_check` [Section titled “engagement_health_check”](#engagement_health_check) Full engagement snapshot combining survey scores and recognition activity. Flags low-response or high-concern areas and recommends next actions. | Argument | Required | Description | | ------------ | -------- | ------------------------------------------------- | | `department` | No | Scope to one department. | | `period` | No | Time window to analyse. Defaults to last 90 days. | ### `performance_review_prep` [Section titled “performance_review_prep”](#performance_review_prep) Pre-review compilation: cycle completion status, peer feedback stats, and calibration notes. Requires performance reviews to be enabled on your plan. | Argument | Required | Description | | --------------- | -------- | -------------------------------------------------------------------- | | `review_cycle` | Yes | Cycle name or ID. Use `list_review_cycles` to find available cycles. | | `employee_name` | No | Narrow the prep to a single employee. | ### `team_pulse` [Section titled “team_pulse”](#team_pulse) Quick health check on a team’s survey participation and recognition frequency. Works by department or manager name. | Argument | Required | Description | | -------------- | -------- | ------------------------------------------------- | | `department` | No | Department name. | | `manager_name` | No | Manager name to scope the check to their team. | | `period` | No | Time window to analyse. Defaults to last 90 days. | ## Permissions summary [Section titled “Permissions summary”](#permissions-summary) | Role | Surveys | Reviews | Recognitions | Employees | Template/draft write | Token & activity admin | | -------- | ------------ | ----------------------- | ----------------------- | ----------------------- | -------------------- | ---------------------- | | Admin | All org data | All reviews | All (including pending) | All employees | Yes (`mcp:write`) | Yes | | Manager | No access | Direct/indirect reports | No access | Direct/indirect reports | No | No | | Employee | No access | No access | No access | No access | No | No | Caution Managers have **no** access to survey or recognition data through MCP, regardless of team. This is a hard denial in FeedbackPulse’s reporting permissions, not a scoped or filtered view. Review and employee data remain scoped to a Manager’s direct and indirect reports as shown above. *** [← Back to MCP Overview](https://feedbackpulse.com/help/integrations/mcp-overview.md) --- # FeedbackPulse for Zapier > Connect FeedbackPulse to Zapier with a workspace API key, then create or update employees from an HR system or another app. Use the FeedbackPulse Zapier connector to create or update employee records when something happens in another app, such as a new hire in an HR system. ## Connect a workspace [Section titled “Connect a workspace”](#connect-a-workspace) 1. A workspace Admin opens **Settings > Integrations > API Clients** in FeedbackPulse, creates an API client, and selects `employees:read`, `employees:write`, and `employees:sync`. 2. In Zapier, add a FeedbackPulse action to a Zap and connect an account. 3. In **API key**, paste the key without the `Bearer` prefix. MCP tokens do not work. 4. In **Workspace label**, enter a name to recognize this connection, such as Example Workspace. Zapier uses the read scope to test the connection, to fill the **Manager** dropdown, and to read the saved employee after **Create or Update Employee**. ## Choose an employee action [Section titled “Choose an employee action”](#choose-an-employee-action) | Action | Use it for | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Create or Update Employee** | Create or update an employee profile from an HR system, matched by **HR system source** and **HR system employee reference**. This action preserves existing account status and does not send invitations. | | **Create Employee** | Create an employee, or restore a deleted employee with the same email. Optionally assign a manager and send an account invitation. | When your trigger supplies a stable event ID, map it to **Event key** so retries of that event use the same idempotency key. ## Create or Update Employee fields [Section titled “Create or Update Employee fields”](#create-or-update-employee-fields) | Field | Required | Help text | | -------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **HR system source** | Yes | Stable source/account namespace, for example bamboohr-example. Keep this unchanged across Zaps for the same HR account. | | **HR system employee reference** | Yes | The employee’s unique identifier in your HR system. Map it from your HR system’s trigger. FeedbackPulse uses it with **HR system source** to find the same employee on later runs. Do not map an event ID here. | | **Email** | Yes | | | **Name** | No | | | **Employment type** | No | Leave blank to preserve an existing value. New employees default to Full time. | | **Job title** | No | | | **Department** | No | | | **Employee number** | No | | | **Hire date** | No | Use YYYY-MM-DD. | | **Event key** | No | Map the ID of the event that triggered this Zap, with a prefix unique to this step, so FeedbackPulse can recognise a repeat of the same event. Leave blank for no duplicate protection. | **Employment type** offers **Full time**, **Part time**, and **Contractor**. The step returns the employee: **Employee ID**, **Name**, **Email**, **Job Title**, **Department**, **Employee Number**, **Hire Date**, **Employment Type**, **Employment Status**, **Account Status**, **Access Status**, **Is Manager**, **Termination Date**, **Created At**, **Updated At**, **Manager ID**, and **Manager Name**. It also returns **Sync Result**, **Employee Link**, **Warnings**, and **Has Warnings**. **Sync Result** is `created` or `updated`. If FeedbackPulse does not save the employee, the step fails with the reason. For example, a change that would terminate the last active admin of the workspace fails with the code `last_active_admin`. After the save, the step reads the employee back to fill these fields. If FeedbackPulse limits the request rate or is briefly unavailable during that read, the step fails and Zapier runs it again. Repeating the update is safe. If the read fails for another reason, the step still succeeds and the employee is saved: **Employee ID**, **Email**, **Sync Result**, and **Employee Link** are filled, the other employee fields are empty on that run, **Warnings** contains `employee_read_failed`, and **Has Warnings** is true. ## Create Employee fields [Section titled “Create Employee fields”](#create-employee-fields) | Field | Required | Help text | | --------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | Yes | | | **Email** | Yes | | | **Employment type** | Yes | | | **Job title** | No | | | **Department** | No | | | **Employee number** | No | | | **Hire date** | No | Use YYYY-MM-DD. | | **Manager** | No | Select an employee in this workspace or map their public Employee ID. | | **Send account invitation** | No | Sends an account setup email. Does not invite to or launch a survey. Check output warnings for delivery failures. | | **Event key** | No | Map the ID of the event that triggered this Zap, with a prefix unique to this step, so FeedbackPulse can recognise a repeat of the same event. Leave blank for no duplicate protection. | **Employment type** offers **Full time**, **Part time**, and **Contractor**, and starts at **Full time**. The step returns the employee: **Employee ID**, **Name**, **Email**, **Job Title**, **Department**, **Employee Number**, **Hire Date**, **Employment Type**, **Employment Status**, **Account Status**, **Access Status**, **Is Manager**, **Termination Date**, **Created At**, **Updated At**, **Manager ID**, and **Manager Name**. It also returns **Employee Link**, **Warnings**, and **Has Warnings**. ## API operations behind the connector [Section titled “API operations behind the connector”](#api-operations-behind-the-connector) Each Zapier step calls one REST API operation. The reference pages list the fields, responses, and errors for each one. | Zapier step | API operation | Scope | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------- | | Connection test and **Manager** dropdown | [List employees](https://feedbackpulse.com/help/developers/api/reference/list-employees.md) (`GET /v1/employees`) | `employees:read` | | **Create or Update Employee**, read of the saved employee | [Get an employee](https://feedbackpulse.com/help/developers/api/reference/get-employee.md) (`GET /v1/employees/{employee}`) | `employees:read` | | **Create Employee** | [Create an employee](https://feedbackpulse.com/help/developers/api/reference/create-employee.md) (`POST /v1/employees`) | `employees:write` | | **Create or Update Employee** | [Sync employees](https://feedbackpulse.com/help/developers/api/reference/sync-employees.md) (`POST /v1/employees/sync`) | `employees:sync` | If you have questions about the connector, [contact support](https://feedbackpulse.com/help/troubleshooting/contact-support.md).