canonical: https://jentic.com/apis/macorva.com/macorva

# Macorva CX API

Jentic publishes the only available OpenAPI specification for Macorva CX API, keeping it validated and agent-ready. Macorva CX is a customer experience feedback platform exposing endpoints for surveys, categories, feedback requests, and webhook subscriptions. The API supports retrieving institution-level survey configurations, sending feedback requests to customers via the deliver endpoint, polling response results, and registering webhooks for real-time event delivery.

## For AI agents

Send customer feedback requests, retrieve survey results, and register webhooks for real-time CX events through Macorva's eight feedback endpoints.

## Scope

Does not handle email campaign authoring, contact-list segmentation, or CRM record management - use for CX feedback request delivery and response retrieval only.

## Capabilities

- List configured surveys for an institution via GET `/customer/surveys`
- Retrieve all feedback categories defined for an institution through GET `/customer/categories`
- Create a feedback request and dispatch it to customers via POST `/customer/feedback-requests/deliver`
- Poll feedback request results to retrieve completed responses using GET `/customer/feedback-requests/{feedbackRequestId}`
- Register webhook subscriptions to receive new-response events through POST `/customer/hooks`
- Poll recent webhook events as a fallback or replay mechanism via GET `/customer/events`

## Use cases

### Post-Support Feedback Collection

Trigger a CX survey to a customer immediately after a support interaction closes. The flow calls POST `/customer/feedback-requests` to register the request, then POST `/customer/feedback-requests/deliver` to send it. The agent can later poll GET `/customer/feedback-requests/{feedbackRequestId}` for completed responses or rely on a webhook for push delivery.

Example prompt: POST to `/customer/feedback-requests` for a closed ticket then POST `/customer/feedback-requests/deliver` to email the survey to the customer

### Real-Time CX Event Routing

Wire Macorva responses straight into a downstream CRM, Slack channel or analytics warehouse. POST `/customer/hooks` registers a subscription URL, and the spec also exposes PUT `/customer/hooks/{id}` for updates and DELETE `/customer/hooks/{id}` for cleanup. If a webhook delivery is missed, GET `/customer/events` polls the recent event buffer for replay.

Example prompt: POST `/customer/hooks` with the team's intake URL and event filter to receive new-response notifications, then poll `/customer/events` as a backup

### Survey and Category Administration

Audit and align the surveys and category taxonomy across the institution. GET `/customer/surveys` lists every active survey configuration and GET `/customer/categories` returns the taxonomy used to tag responses. Useful for ops teams reconciling survey design across regions or rolling out a new category structure before a quarterly review.

Example prompt: Call GET `/customer/surveys` and GET `/customer/categories` and produce a reconciliation report of the current survey-to-category mapping

### AI Agent Customer Health Monitoring

Let an AI agent watch customer health indicators by subscribing to Macorva feedback events and triggering follow-up actions. Through Jentic, the agent registers a webhook with POST `/customer/hooks`, listens for low-score responses, and on receipt calls a downstream CRM API to log a follow-up task. Credentials are brokered by your Jentic One instance throughout.

Example prompt: Search Jentic for 'subscribe to feedback events', register a webhook via POST `/customer/hooks`, and on a low score response create a CRM follow-up task

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/customer/feedback-requests` | Create a feedback request |
| POST | `/customer/feedback-requests/deliver` | Deliver a feedback request to customers |
| GET | `/customer/feedback-requests/{feedbackRequestId}` | Retrieve feedback request results |
| GET | `/customer/surveys` | List configured surveys |
| GET | `/customer/categories` | List feedback categories |
| POST | `/customer/hooks` | Create a webhook subscription |
| GET | `/customer/events` | Poll recent webhook events |

## Key resources

- **Surveys** — List institution surveys via `/customer/surveys`
- **Categories** — Retrieve feedback category taxonomy via `/customer/categories`
- **Feedback Requests** — Create, deliver and read feedback requests via `/customer/feedback-requests` endpoints
- **Webhooks** — Manage webhook subscriptions via `/customer/hooks`
- **Events** — Poll recent events via `/customer/events`

## Why Jentic

- **Setup:** Wiring the Macorva CX API by hand means encoding basic-auth credentials on every request and coordinating them across feedback-request creation, delivery, survey, and webhook paths. Through Jentic you install once, import the Macorva CX API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** You choose which Macorva operations the agent may call, so you can limit it to the ones it needs, such as creating a feedback request and registering a response webhook, and leave out others like delivering requests to customers unless you add them. The agent only reaches the operations in the set you allow.
- **Credential handling:** Your Macorva credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a feedback request' or 'register a webhook for new responses', and Jentic returns the matching Macorva operation with its input schema so the agent calls the right endpoint directly.

## Related APIs

- **Qualtrics API** — Enterprise CX research platform with deep panel and analytics tooling
- **SurveyMonkey API** — Mainstream survey tooling with broad templates and integrations
- **Retently NPS API** — Lightweight NPS and CSAT tooling focused on transactional surveys
- **HubSpot CRM Contacts API** — Persists CX scores and feedback events onto contact records

## FAQ

### Why is there no official OpenAPI spec for Macorva CX API?

Macorva does not publish an OpenAPI specification on its public developer pages. Jentic generates and maintains this spec so AI agents and developers can call the Macorva CX API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Macorva CX API use?

The API uses HTTP Basic authentication with an institution key and secret (the basicAuth scheme in the spec). Through Jentic the credential is held encrypted in your Jentic One instance, so an agent calls `/customer/feedback-requests/deliver` with a scoped token rather than embedding the basic-auth pair.

### Can I trigger a feedback request to a customer via the Macorva API?

Yes. POST `/customer/feedback-requests` creates the request record and POST `/customer/feedback-requests/deliver` dispatches it to the configured channel. Both run on the https://app.macorva.com/api base URL.

### What are the rate limits for the Macorva CX API?

Per-endpoint rate limits are not defined in the OpenAPI spec; Macorva typically applies institution-level fair-use limits agreed at contract level. Coordinate with your Macorva account team for production volume needs.

### How do I receive new-response events from Macorva through Jentic?

Run pip install jentic, search for 'register a webhook for feedback responses', and Jentic surfaces POST `/customer/hooks` with its input schema. Submit the receiver URL and event filter, then verify by polling GET `/customer/events` for the replay buffer.

### Can the Macorva CX API list completed feedback responses?

Yes. GET `/customer/feedback-requests/{feedbackRequestId}` returns the response payload for a specific request, and GET `/customer/events` surfaces recent webhook deliveries that include response payloads. Use the feedbackRequestId returned from the create call as the path parameter.

### Can I limit what my agent is allowed to do with the Macorva CX API?

Yes. Because Jentic One is self-hosted, your own rules decide which Macorva operations and credentials the agent may use. You can allow it to only create a feedback request with POST `/customer/feedback-requests` and register a response webhook with POST `/customer/hooks`, while leaving out operations like POST `/customer/feedback-requests/deliver` that email customers directly. The agent can reach only the operations in the set you approve.